About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / parport-lowlevel.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	===============================
2	PARPORT interface documentation
3	===============================
4	
5	:Time-stamp: <2000-02-24 13:30:20 twaugh>
6	
7	Described here are the following functions:
8	
9	Global functions::
10	  parport_register_driver
11	  parport_unregister_driver
12	  parport_enumerate
13	  parport_register_device
14	  parport_unregister_device
15	  parport_claim
16	  parport_claim_or_block
17	  parport_release
18	  parport_yield
19	  parport_yield_blocking
20	  parport_wait_peripheral
21	  parport_poll_peripheral
22	  parport_wait_event
23	  parport_negotiate
24	  parport_read
25	  parport_write
26	  parport_open
27	  parport_close
28	  parport_device_id
29	  parport_device_coords
30	  parport_find_class
31	  parport_find_device
32	  parport_set_timeout
33	
34	Port functions (can be overridden by low-level drivers):
35	
36	  SPP::
37	    port->ops->read_data
38	    port->ops->write_data
39	    port->ops->read_status
40	    port->ops->read_control
41	    port->ops->write_control
42	    port->ops->frob_control
43	    port->ops->enable_irq
44	    port->ops->disable_irq
45	    port->ops->data_forward
46	    port->ops->data_reverse
47	
48	  EPP::
49	    port->ops->epp_write_data
50	    port->ops->epp_read_data
51	    port->ops->epp_write_addr
52	    port->ops->epp_read_addr
53	
54	  ECP::
55	    port->ops->ecp_write_data
56	    port->ops->ecp_read_data
57	    port->ops->ecp_write_addr
58	
59	  Other::
60	    port->ops->nibble_read_data
61	    port->ops->byte_read_data
62	    port->ops->compat_write_data
63	
64	The parport subsystem comprises ``parport`` (the core port-sharing
65	code), and a variety of low-level drivers that actually do the port
66	accesses.  Each low-level driver handles a particular style of port
67	(PC, Amiga, and so on).
68	
69	The parport interface to the device driver author can be broken down
70	into global functions and port functions.
71	
72	The global functions are mostly for communicating between the device
73	driver and the parport subsystem: acquiring a list of available ports,
74	claiming a port for exclusive use, and so on.  They also include
75	``generic`` functions for doing standard things that will work on any
76	IEEE 1284-capable architecture.
77	
78	The port functions are provided by the low-level drivers, although the
79	core parport module provides generic ``defaults`` for some routines.
80	The port functions can be split into three groups: SPP, EPP, and ECP.
81	
82	SPP (Standard Parallel Port) functions modify so-called ``SPP``
83	registers: data, status, and control.  The hardware may not actually
84	have registers exactly like that, but the PC does and this interface is
85	modelled after common PC implementations.  Other low-level drivers may
86	be able to emulate most of the functionality.
87	
88	EPP (Enhanced Parallel Port) functions are provided for reading and
89	writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)
90	functions are used for IEEE 1284 ECP mode. (What about BECP? Does
91	anyone care?)
92	
93	Hardware assistance for EPP and/or ECP transfers may or may not be
94	available, and if it is available it may or may not be used.  If
95	hardware is not used, the transfer will be software-driven.  In order
96	to cope with peripherals that only tenuously support IEEE 1284, a
97	low-level driver specific function is provided, for altering 'fudge
98	factors'.
99	
100	Global functions
101	================
102	
103	parport_register_driver - register a device driver with parport
104	---------------------------------------------------------------
105	
106	SYNOPSIS
107	^^^^^^^^
108	
109	::
110	
111		#include <linux/parport.h>
112	
113		struct parport_driver {
114			const char *name;
115			void (*attach) (struct parport *);
116			void (*detach) (struct parport *);
117			struct parport_driver *next;
118		};
119		int parport_register_driver (struct parport_driver *driver);
120	
121	DESCRIPTION
122	^^^^^^^^^^^
123	
124	In order to be notified about parallel ports when they are detected,
125	parport_register_driver should be called.  Your driver will
126	immediately be notified of all ports that have already been detected,
127	and of each new port as low-level drivers are loaded.
128	
129	A ``struct parport_driver`` contains the textual name of your driver,
130	a pointer to a function to handle new ports, and a pointer to a
131	function to handle ports going away due to a low-level driver
132	unloading.  Ports will only be detached if they are not being used
133	(i.e. there are no devices registered on them).
134	
135	The visible parts of the ``struct parport *`` argument given to
136	attach/detach are::
137	
138		struct parport
139		{
140			struct parport *next; /* next parport in list */
141			const char *name;     /* port's name */
142			unsigned int modes;   /* bitfield of hardware modes */
143			struct parport_device_info probe_info;
144					/* IEEE1284 info */
145			int number;           /* parport index */
146			struct parport_operations *ops;
147			...
148		};
149	
150	There are other members of the structure, but they should not be
151	touched.
152	
153	The ``modes`` member summarises the capabilities of the underlying
154	hardware.  It consists of flags which may be bitwise-ored together:
155	
156	  ============================= ===============================================
157	  PARPORT_MODE_PCSPP		IBM PC registers are available,
158					i.e. functions that act on data,
159					control and status registers are
160					probably writing directly to the
161					hardware.
162	  PARPORT_MODE_TRISTATE		The data drivers may be turned off.
163					This allows the data lines to be used
164					for reverse (peripheral to host)
165					transfers.
166	  PARPORT_MODE_COMPAT		The hardware can assist with
167					compatibility-mode (printer)
168					transfers, i.e. compat_write_block.
169	  PARPORT_MODE_EPP		The hardware can assist with EPP
170					transfers.
171	  PARPORT_MODE_ECP		The hardware can assist with ECP
172					transfers.
173	  PARPORT_MODE_DMA		The hardware can use DMA, so you might
174					want to pass ISA DMA-able memory
175					(i.e. memory allocated using the
176					GFP_DMA flag with kmalloc) to the
177					low-level driver in order to take
178					advantage of it.
179	  ============================= ===============================================
180	
181	There may be other flags in ``modes`` as well.
182	
183	The contents of ``modes`` is advisory only.  For example, if the
184	hardware is capable of DMA, and PARPORT_MODE_DMA is in ``modes``, it
185	doesn't necessarily mean that DMA will always be used when possible.
186	Similarly, hardware that is capable of assisting ECP transfers won't
187	necessarily be used.
188	
189	RETURN VALUE
190	^^^^^^^^^^^^
191	
192	Zero on success, otherwise an error code.
193	
194	ERRORS
195	^^^^^^
196	
197	None. (Can it fail? Why return int?)
198	
199	EXAMPLE
200	^^^^^^^
201	
202	::
203	
204		static void lp_attach (struct parport *port)
205		{
206			...
207			private = kmalloc (...);
208			dev[count++] = parport_register_device (...);
209			...
210		}
211	
212		static void lp_detach (struct parport *port)
213		{
214			...
215		}
216	
217		static struct parport_driver lp_driver = {
218			"lp",
219			lp_attach,
220			lp_detach,
221			NULL /* always put NULL here */
222		};
223	
224		int lp_init (void)
225		{
226			...
227			if (parport_register_driver (&lp_driver)) {
228				/* Failed; nothing we can do. */
229				return -EIO;
230			}
231			...
232		}
233	
234	
235	SEE ALSO
236	^^^^^^^^
237	
238	parport_unregister_driver, parport_register_device, parport_enumerate
239	
240	
241	
242	parport_unregister_driver - tell parport to forget about this driver
243	--------------------------------------------------------------------
244	
245	SYNOPSIS
246	^^^^^^^^
247	
248	::
249	
250		#include <linux/parport.h>
251	
252		struct parport_driver {
253			const char *name;
254			void (*attach) (struct parport *);
255			void (*detach) (struct parport *);
256			struct parport_driver *next;
257		};
258		void parport_unregister_driver (struct parport_driver *driver);
259	
260	DESCRIPTION
261	^^^^^^^^^^^
262	
263	This tells parport not to notify the device driver of new ports or of
264	ports going away.  Registered devices belonging to that driver are NOT
265	unregistered: parport_unregister_device must be used for each one.
266	
267	EXAMPLE
268	^^^^^^^
269	
270	::
271	
272		void cleanup_module (void)
273		{
274			...
275			/* Stop notifications. */
276			parport_unregister_driver (&lp_driver);
277	
278			/* Unregister devices. */
279			for (i = 0; i < NUM_DEVS; i++)
280				parport_unregister_device (dev[i]);
281			...
282		}
283	
284	SEE ALSO
285	^^^^^^^^
286	
287	parport_register_driver, parport_enumerate
288	
289	
290	
291	parport_enumerate - retrieve a list of parallel ports (DEPRECATED)
292	------------------------------------------------------------------
293	
294	SYNOPSIS
295	^^^^^^^^
296	
297	::
298	
299		#include <linux/parport.h>
300	
301		struct parport *parport_enumerate (void);
302	
303	DESCRIPTION
304	^^^^^^^^^^^
305	
306	Retrieve the first of a list of valid parallel ports for this machine.
307	Successive parallel ports can be found using the ``struct parport
308	*next`` element of the ``struct parport *`` that is returned.  If ``next``
309	is NULL, there are no more parallel ports in the list.  The number of
310	ports in the list will not exceed PARPORT_MAX.
311	
312	RETURN VALUE
313	^^^^^^^^^^^^
314	
315	A ``struct parport *`` describing a valid parallel port for the machine,
316	or NULL if there are none.
317	
318	ERRORS
319	^^^^^^
320	
321	This function can return NULL to indicate that there are no parallel
322	ports to use.
323	
324	EXAMPLE
325	^^^^^^^
326	
327	::
328	
329		int detect_device (void)
330		{
331			struct parport *port;
332	
333			for (port = parport_enumerate ();
334			port != NULL;
335			port = port->next) {
336				/* Try to detect a device on the port... */
337				...
338			}
339			}
340	
341			...
342		}
343	
344	NOTES
345	^^^^^
346	
347	parport_enumerate is deprecated; parport_register_driver should be
348	used instead.
349	
350	SEE ALSO
351	^^^^^^^^
352	
353	parport_register_driver, parport_unregister_driver
354	
355	
356	
357	parport_register_device - register to use a port
358	------------------------------------------------
359	
360	SYNOPSIS
361	^^^^^^^^
362	
363	::
364	
365		#include <linux/parport.h>
366	
367		typedef int (*preempt_func) (void *handle);
368		typedef void (*wakeup_func) (void *handle);
369		typedef int (*irq_func) (int irq, void *handle, struct pt_regs *);
370	
371		struct pardevice *parport_register_device(struct parport *port,
372							  const char *name,
373							  preempt_func preempt,
374							  wakeup_func wakeup,
375							  irq_func irq,
376							  int flags,
377							  void *handle);
378	
379	DESCRIPTION
380	^^^^^^^^^^^
381	
382	Use this function to register your device driver on a parallel port
383	(``port``).  Once you have done that, you will be able to use
384	parport_claim and parport_release in order to use the port.
385	
386	The (``name``) argument is the name of the device that appears in /proc
387	filesystem. The string must be valid for the whole lifetime of the
388	device (until parport_unregister_device is called).
389	
390	This function will register three callbacks into your driver:
391	``preempt``, ``wakeup`` and ``irq``.  Each of these may be NULL in order to
392	indicate that you do not want a callback.
393	
394	When the ``preempt`` function is called, it is because another driver
395	wishes to use the parallel port.  The ``preempt`` function should return
396	non-zero if the parallel port cannot be released yet -- if zero is
397	returned, the port is lost to another driver and the port must be
398	re-claimed before use.
399	
400	The ``wakeup`` function is called once another driver has released the
401	port and no other driver has yet claimed it.  You can claim the
402	parallel port from within the ``wakeup`` function (in which case the
403	claim is guaranteed to succeed), or choose not to if you don't need it
404	now.
405	
406	If an interrupt occurs on the parallel port your driver has claimed,
407	the ``irq`` function will be called. (Write something about shared
408	interrupts here.)
409	
410	The ``handle`` is a pointer to driver-specific data, and is passed to
411	the callback functions.
412	
413	``flags`` may be a bitwise combination of the following flags:
414	
415	  ===================== =================================================
416	        Flag            Meaning
417	  ===================== =================================================
418	  PARPORT_DEV_EXCL	The device cannot share the parallel port at all.
419				Use this only when absolutely necessary.
420	  ===================== =================================================
421	
422	The typedefs are not actually defined -- they are only shown in order
423	to make the function prototype more readable.
424	
425	The visible parts of the returned ``struct pardevice`` are::
426	
427		struct pardevice {
428			struct parport *port;	/* Associated port */
429			void *private;		/* Device driver's 'handle' */
430			...
431		};
432	
433	RETURN VALUE
434	^^^^^^^^^^^^
435	
436	A ``struct pardevice *``: a handle to the registered parallel port
437	device that can be used for parport_claim, parport_release, etc.
438	
439	ERRORS
440	^^^^^^
441	
442	A return value of NULL indicates that there was a problem registering
443	a device on that port.
444	
445	EXAMPLE
446	^^^^^^^
447	
448	::
449	
450		static int preempt (void *handle)
451		{
452			if (busy_right_now)
453				return 1;
454	
455			must_reclaim_port = 1;
456			return 0;
457		}
458	
459		static void wakeup (void *handle)
460		{
461			struct toaster *private = handle;
462			struct pardevice *dev = private->dev;
463			if (!dev) return; /* avoid races */
464	
465			if (want_port)
466				parport_claim (dev);
467		}
468	
469		static int toaster_detect (struct toaster *private, struct parport *port)
470		{
471			private->dev = parport_register_device (port, "toaster", preempt,
472								wakeup, NULL, 0,
473								private);
474			if (!private->dev)
475				/* Couldn't register with parport. */
476				return -EIO;
477	
478			must_reclaim_port = 0;
479			busy_right_now = 1;
480			parport_claim_or_block (private->dev);
481			...
482			/* Don't need the port while the toaster warms up. */
483			busy_right_now = 0;
484			...
485			busy_right_now = 1;
486			if (must_reclaim_port) {
487				parport_claim_or_block (private->dev);
488				must_reclaim_port = 0;
489			}
490			...
491		}
492	
493	SEE ALSO
494	^^^^^^^^
495	
496	parport_unregister_device, parport_claim
497	
498	
499	
500	parport_unregister_device - finish using a port
501	-----------------------------------------------
502	
503	SYNPOPSIS
504	
505	::
506	
507		#include <linux/parport.h>
508	
509		void parport_unregister_device (struct pardevice *dev);
510	
511	DESCRIPTION
512	^^^^^^^^^^^
513	
514	This function is the opposite of parport_register_device.  After using
515	parport_unregister_device, ``dev`` is no longer a valid device handle.
516	
517	You should not unregister a device that is currently claimed, although
518	if you do it will be released automatically.
519	
520	EXAMPLE
521	^^^^^^^
522	
523	::
524	
525		...
526		kfree (dev->private); /* before we lose the pointer */
527		parport_unregister_device (dev);
528		...
529	
530	SEE ALSO
531	^^^^^^^^
532	
533	
534	parport_unregister_driver
535	
536	parport_claim, parport_claim_or_block - claim the parallel port for a device
537	----------------------------------------------------------------------------
538	
539	SYNOPSIS
540	^^^^^^^^
541	
542	::
543	
544		#include <linux/parport.h>
545	
546		int parport_claim (struct pardevice *dev);
547		int parport_claim_or_block (struct pardevice *dev);
548	
549	DESCRIPTION
550	^^^^^^^^^^^
551	
552	These functions attempt to gain control of the parallel port on which
553	``dev`` is registered.  ``parport_claim`` does not block, but
554	``parport_claim_or_block`` may do. (Put something here about blocking
555	interruptibly or non-interruptibly.)
556	
557	You should not try to claim a port that you have already claimed.
558	
559	RETURN VALUE
560	^^^^^^^^^^^^
561	
562	A return value of zero indicates that the port was successfully
563	claimed, and the caller now has possession of the parallel port.
564	
565	If ``parport_claim_or_block`` blocks before returning successfully, the
566	return value is positive.
567	
568	ERRORS
569	^^^^^^
570	
571	========== ==========================================================
572	  -EAGAIN  The port is unavailable at the moment, but another attempt
573	           to claim it may succeed.
574	========== ==========================================================
575	
576	SEE ALSO
577	^^^^^^^^
578	
579	
580	parport_release
581	
582	parport_release - release the parallel port
583	-------------------------------------------
584	
585	SYNOPSIS
586	^^^^^^^^
587	
588	::
589	
590		#include <linux/parport.h>
591	
592		void parport_release (struct pardevice *dev);
593	
594	DESCRIPTION
595	^^^^^^^^^^^
596	
597	Once a parallel port device has been claimed, it can be released using
598	``parport_release``.  It cannot fail, but you should not release a
599	device that you do not have possession of.
600	
601	EXAMPLE
602	^^^^^^^
603	
604	::
605	
606		static size_t write (struct pardevice *dev, const void *buf,
607				size_t len)
608		{
609			...
610			written = dev->port->ops->write_ecp_data (dev->port, buf,
611								len);
612			parport_release (dev);
613			...
614		}
615	
616	
617	SEE ALSO
618	^^^^^^^^
619	
620	change_mode, parport_claim, parport_claim_or_block, parport_yield
621	
622	
623	
624	parport_yield, parport_yield_blocking - temporarily release a parallel port
625	---------------------------------------------------------------------------
626	
627	SYNOPSIS
628	^^^^^^^^
629	
630	::
631	
632		#include <linux/parport.h>
633	
634		int parport_yield (struct pardevice *dev)
635		int parport_yield_blocking (struct pardevice *dev);
636	
637	DESCRIPTION
638	^^^^^^^^^^^
639	
640	When a driver has control of a parallel port, it may allow another
641	driver to temporarily ``borrow`` it.  ``parport_yield`` does not block;
642	``parport_yield_blocking`` may do.
643	
644	RETURN VALUE
645	^^^^^^^^^^^^
646	
647	A return value of zero indicates that the caller still owns the port
648	and the call did not block.
649	
650	A positive return value from ``parport_yield_blocking`` indicates that
651	the caller still owns the port and the call blocked.
652	
653	A return value of -EAGAIN indicates that the caller no longer owns the
654	port, and it must be re-claimed before use.
655	
656	ERRORS
657	^^^^^^
658	
659	========= ==========================================================
660	  -EAGAIN  Ownership of the parallel port was given away.
661	========= ==========================================================
662	
663	SEE ALSO
664	^^^^^^^^
665	
666	parport_release
667	
668	
669	
670	parport_wait_peripheral - wait for status lines, up to 35ms
671	-----------------------------------------------------------
672	
673	SYNOPSIS
674	^^^^^^^^
675	
676	::
677	
678		#include <linux/parport.h>
679	
680		int parport_wait_peripheral (struct parport *port,
681					     unsigned char mask,
682					     unsigned char val);
683	
684	DESCRIPTION
685	^^^^^^^^^^^
686	
687	Wait for the status lines in mask to match the values in val.
688	
689	RETURN VALUE
690	^^^^^^^^^^^^
691	
692	======== ==========================================================
693	 -EINTR  a signal is pending
694	      0  the status lines in mask have values in val
695	      1  timed out while waiting (35ms elapsed)
696	======== ==========================================================
697	
698	SEE ALSO
699	^^^^^^^^
700	
701	parport_poll_peripheral
702	
703	
704	
705	parport_poll_peripheral - wait for status lines, in usec
706	--------------------------------------------------------
707	
708	SYNOPSIS
709	^^^^^^^^
710	
711	::
712	
713		#include <linux/parport.h>
714	
715		int parport_poll_peripheral (struct parport *port,
716					     unsigned char mask,
717					     unsigned char val,
718					     int usec);
719	
720	DESCRIPTION
721	^^^^^^^^^^^
722	
723	Wait for the status lines in mask to match the values in val.
724	
725	RETURN VALUE
726	^^^^^^^^^^^^
727	
728	======== ==========================================================
729	 -EINTR  a signal is pending
730	      0  the status lines in mask have values in val
731	      1  timed out while waiting (usec microseconds have elapsed)
732	======== ==========================================================
733	
734	SEE ALSO
735	^^^^^^^^
736	
737	parport_wait_peripheral
738	
739	
740	
741	parport_wait_event - wait for an event on a port
742	------------------------------------------------
743	
744	SYNOPSIS
745	^^^^^^^^
746	
747	::
748	
749		#include <linux/parport.h>
750	
751		int parport_wait_event (struct parport *port, signed long timeout)
752	
753	DESCRIPTION
754	^^^^^^^^^^^
755	
756	Wait for an event (e.g. interrupt) on a port.  The timeout is in
757	jiffies.
758	
759	RETURN VALUE
760	^^^^^^^^^^^^
761	
762	======= ==========================================================
763	      0  success
764	     <0  error (exit as soon as possible)
765	     >0  timed out
766	======= ==========================================================
767	
768	parport_negotiate - perform IEEE 1284 negotiation
769	-------------------------------------------------
770	
771	SYNOPSIS
772	^^^^^^^^
773	
774	::
775	
776		#include <linux/parport.h>
777	
778		int parport_negotiate (struct parport *, int mode);
779	
780	DESCRIPTION
781	^^^^^^^^^^^
782	
783	Perform IEEE 1284 negotiation.
784	
785	RETURN VALUE
786	^^^^^^^^^^^^
787	
788	======= ==========================================================
789	     0  handshake OK; IEEE 1284 peripheral and mode available
790	    -1  handshake failed; peripheral not compliant (or none present)
791	     1  handshake OK; IEEE 1284 peripheral present but mode not
792	        available
793	======= ==========================================================
794	
795	SEE ALSO
796	^^^^^^^^
797	
798	parport_read, parport_write
799	
800	
801	
802	parport_read - read data from device
803	------------------------------------
804	
805	SYNOPSIS
806	^^^^^^^^
807	
808	::
809	
810		#include <linux/parport.h>
811	
812		ssize_t parport_read (struct parport *, void *buf, size_t len);
813	
814	DESCRIPTION
815	^^^^^^^^^^^
816	
817	Read data from device in current IEEE 1284 transfer mode.  This only
818	works for modes that support reverse data transfer.
819	
820	RETURN VALUE
821	^^^^^^^^^^^^
822	
823	If negative, an error code; otherwise the number of bytes transferred.
824	
825	SEE ALSO
826	^^^^^^^^
827	
828	parport_write, parport_negotiate
829	
830	
831	
832	parport_write - write data to device
833	------------------------------------
834	
835	SYNOPSIS
836	^^^^^^^^
837	
838	::
839	
840		#include <linux/parport.h>
841	
842		ssize_t parport_write (struct parport *, const void *buf, size_t len);
843	
844	DESCRIPTION
845	^^^^^^^^^^^
846	
847	Write data to device in current IEEE 1284 transfer mode.  This only
848	works for modes that support forward data transfer.
849	
850	RETURN VALUE
851	^^^^^^^^^^^^
852	
853	If negative, an error code; otherwise the number of bytes transferred.
854	
855	SEE ALSO
856	^^^^^^^^
857	
858	parport_read, parport_negotiate
859	
860	
861	
862	parport_open - register device for particular device number
863	-----------------------------------------------------------
864	
865	SYNOPSIS
866	^^^^^^^^
867	
868	::
869	
870		#include <linux/parport.h>
871	
872		struct pardevice *parport_open (int devnum, const char *name,
873					        int (*pf) (void *),
874						void (*kf) (void *),
875						void (*irqf) (int, void *,
876							      struct pt_regs *),
877						int flags, void *handle);
878	
879	DESCRIPTION
880	^^^^^^^^^^^
881	
882	This is like parport_register_device but takes a device number instead
883	of a pointer to a struct parport.
884	
885	RETURN VALUE
886	^^^^^^^^^^^^
887	
888	See parport_register_device.  If no device is associated with devnum,
889	NULL is returned.
890	
891	SEE ALSO
892	^^^^^^^^
893	
894	parport_register_device
895	
896	
897	
898	parport_close - unregister device for particular device number
899	--------------------------------------------------------------
900	
901	SYNOPSIS
902	^^^^^^^^
903	
904	::
905	
906		#include <linux/parport.h>
907	
908		void parport_close (struct pardevice *dev);
909	
910	DESCRIPTION
911	^^^^^^^^^^^
912	
913	This is the equivalent of parport_unregister_device for parport_open.
914	
915	SEE ALSO
916	^^^^^^^^
917	
918	parport_unregister_device, parport_open
919	
920	
921	
922	parport_device_id - obtain IEEE 1284 Device ID
923	----------------------------------------------
924	
925	SYNOPSIS
926	^^^^^^^^
927	
928	::
929	
930		#include <linux/parport.h>
931	
932		ssize_t parport_device_id (int devnum, char *buffer, size_t len);
933	
934	DESCRIPTION
935	^^^^^^^^^^^
936	
937	Obtains the IEEE 1284 Device ID associated with a given device.
938	
939	RETURN VALUE
940	^^^^^^^^^^^^
941	
942	If negative, an error code; otherwise, the number of bytes of buffer
943	that contain the device ID.  The format of the device ID is as
944	follows::
945	
946		[length][ID]
947	
948	The first two bytes indicate the inclusive length of the entire Device
949	ID, and are in big-endian order.  The ID is a sequence of pairs of the
950	form::
951	
952		key:value;
953	
954	NOTES
955	^^^^^
956	
957	Many devices have ill-formed IEEE 1284 Device IDs.
958	
959	SEE ALSO
960	^^^^^^^^
961	
962	parport_find_class, parport_find_device
963	
964	
965	
966	parport_device_coords - convert device number to device coordinates
967	-------------------------------------------------------------------
968	
969	SYNOPSIS
970	^^^^^^^^
971	
972	::
973	
974		#include <linux/parport.h>
975	
976		int parport_device_coords (int devnum, int *parport, int *mux,
977					   int *daisy);
978	
979	DESCRIPTION
980	^^^^^^^^^^^
981	
982	Convert between device number (zero-based) and device coordinates
983	(port, multiplexor, daisy chain address).
984	
985	RETURN VALUE
986	^^^^^^^^^^^^
987	
988	Zero on success, in which case the coordinates are (``*parport``, ``*mux``,
989	``*daisy``).
990	
991	SEE ALSO
992	^^^^^^^^
993	
994	parport_open, parport_device_id
995	
996	
997	
998	parport_find_class - find a device by its class
999	-----------------------------------------------
1000	
1001	SYNOPSIS
1002	^^^^^^^^
1003	
1004	::
1005	
1006		#include <linux/parport.h>
1007	
1008		typedef enum {
1009			PARPORT_CLASS_LEGACY = 0,       /* Non-IEEE1284 device */
1010			PARPORT_CLASS_PRINTER,
1011			PARPORT_CLASS_MODEM,
1012			PARPORT_CLASS_NET,
1013			PARPORT_CLASS_HDC,              /* Hard disk controller */
1014			PARPORT_CLASS_PCMCIA,
1015			PARPORT_CLASS_MEDIA,            /* Multimedia device */
1016			PARPORT_CLASS_FDC,              /* Floppy disk controller */
1017			PARPORT_CLASS_PORTS,
1018			PARPORT_CLASS_SCANNER,
1019			PARPORT_CLASS_DIGCAM,
1020			PARPORT_CLASS_OTHER,            /* Anything else */
1021			PARPORT_CLASS_UNSPEC,           /* No CLS field in ID */
1022			PARPORT_CLASS_SCSIADAPTER
1023		} parport_device_class;
1024	
1025		int parport_find_class (parport_device_class cls, int from);
1026	
1027	DESCRIPTION
1028	^^^^^^^^^^^
1029	
1030	Find a device by class.  The search starts from device number from+1.
1031	
1032	RETURN VALUE
1033	^^^^^^^^^^^^
1034	
1035	The device number of the next device in that class, or -1 if no such
1036	device exists.
1037	
1038	NOTES
1039	^^^^^
1040	
1041	Example usage::
1042	
1043		int devnum = -1;
1044		while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, devnum)) != -1) {
1045			struct pardevice *dev = parport_open (devnum, ...);
1046			...
1047		}
1048	
1049	SEE ALSO
1050	^^^^^^^^
1051	
1052	parport_find_device, parport_open, parport_device_id
1053	
1054	
1055	
1056	parport_find_device - find a device by its class
1057	------------------------------------------------
1058	
1059	SYNOPSIS
1060	^^^^^^^^
1061	
1062	::
1063	
1064		#include <linux/parport.h>
1065	
1066		int parport_find_device (const char *mfg, const char *mdl, int from);
1067	
1068	DESCRIPTION
1069	^^^^^^^^^^^
1070	
1071	Find a device by vendor and model.  The search starts from device
1072	number from+1.
1073	
1074	RETURN VALUE
1075	^^^^^^^^^^^^
1076	
1077	The device number of the next device matching the specifications, or
1078	-1 if no such device exists.
1079	
1080	NOTES
1081	^^^^^
1082	
1083	Example usage::
1084	
1085		int devnum = -1;
1086		while ((devnum = parport_find_device ("IOMEGA", "ZIP+", devnum)) != -1) {
1087			struct pardevice *dev = parport_open (devnum, ...);
1088			...
1089		}
1090	
1091	SEE ALSO
1092	^^^^^^^^
1093	
1094	parport_find_class, parport_open, parport_device_id
1095	
1096	
1097	
1098	parport_set_timeout - set the inactivity timeout
1099	------------------------------------------------
1100	
1101	SYNOPSIS
1102	^^^^^^^^
1103	
1104	::
1105	
1106		#include <linux/parport.h>
1107	
1108		long parport_set_timeout (struct pardevice *dev, long inactivity);
1109	
1110	DESCRIPTION
1111	^^^^^^^^^^^
1112	
1113	Set the inactivity timeout, in jiffies, for a registered device.  The
1114	previous timeout is returned.
1115	
1116	RETURN VALUE
1117	^^^^^^^^^^^^
1118	
1119	The previous timeout, in jiffies.
1120	
1121	NOTES
1122	^^^^^
1123	
1124	Some of the port->ops functions for a parport may take time, owing to
1125	delays at the peripheral.  After the peripheral has not responded for
1126	``inactivity`` jiffies, a timeout will occur and the blocking function
1127	will return.
1128	
1129	A timeout of 0 jiffies is a special case: the function must do as much
1130	as it can without blocking or leaving the hardware in an unknown
1131	state.  If port operations are performed from within an interrupt
1132	handler, for instance, a timeout of 0 jiffies should be used.
1133	
1134	Once set for a registered device, the timeout will remain at the set
1135	value until set again.
1136	
1137	SEE ALSO
1138	^^^^^^^^
1139	
1140	port->ops->xxx_read/write_yyy
1141	
1142	
1143	
1144	
1145	PORT FUNCTIONS
1146	==============
1147	
1148	The functions in the port->ops structure (struct parport_operations)
1149	are provided by the low-level driver responsible for that port.
1150	
1151	port->ops->read_data - read the data register
1152	---------------------------------------------
1153	
1154	SYNOPSIS
1155	^^^^^^^^
1156	
1157	::
1158	
1159		#include <linux/parport.h>
1160	
1161		struct parport_operations {
1162			...
1163			unsigned char (*read_data) (struct parport *port);
1164			...
1165		};
1166	
1167	DESCRIPTION
1168	^^^^^^^^^^^
1169	
1170	If port->modes contains the PARPORT_MODE_TRISTATE flag and the
1171	PARPORT_CONTROL_DIRECTION bit in the control register is set, this
1172	returns the value on the data pins.  If port->modes contains the
1173	PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is
1174	not set, the return value _may_ be the last value written to the data
1175	register.  Otherwise the return value is undefined.
1176	
1177	SEE ALSO
1178	^^^^^^^^
1179	
1180	write_data, read_status, write_control
1181	
1182	
1183	
1184	port->ops->write_data - write the data register
1185	-----------------------------------------------
1186	
1187	SYNOPSIS
1188	^^^^^^^^
1189	
1190	::
1191	
1192		#include <linux/parport.h>
1193	
1194		struct parport_operations {
1195			...
1196			void (*write_data) (struct parport *port, unsigned char d);
1197			...
1198		};
1199	
1200	DESCRIPTION
1201	^^^^^^^^^^^
1202	
1203	Writes to the data register.  May have side-effects (a STROBE pulse,
1204	for instance).
1205	
1206	SEE ALSO
1207	^^^^^^^^
1208	
1209	read_data, read_status, write_control
1210	
1211	
1212	
1213	port->ops->read_status - read the status register
1214	-------------------------------------------------
1215	
1216	SYNOPSIS
1217	^^^^^^^^
1218	
1219	::
1220	
1221		#include <linux/parport.h>
1222	
1223		struct parport_operations {
1224			...
1225			unsigned char (*read_status) (struct parport *port);
1226			...
1227		};
1228	
1229	DESCRIPTION
1230	^^^^^^^^^^^
1231	
1232	Reads from the status register.  This is a bitmask:
1233	
1234	- PARPORT_STATUS_ERROR (printer fault, "nFault")
1235	- PARPORT_STATUS_SELECT (on-line, "Select")
1236	- PARPORT_STATUS_PAPEROUT (no paper, "PError")
1237	- PARPORT_STATUS_ACK (handshake, "nAck")
1238	- PARPORT_STATUS_BUSY (busy, "Busy")
1239	
1240	There may be other bits set.
1241	
1242	SEE ALSO
1243	^^^^^^^^
1244	
1245	read_data, write_data, write_control
1246	
1247	
1248	
1249	port->ops->read_control - read the control register
1250	---------------------------------------------------
1251	
1252	SYNOPSIS
1253	^^^^^^^^
1254	
1255	::
1256	
1257		#include <linux/parport.h>
1258	
1259		struct parport_operations {
1260			...
1261			unsigned char (*read_control) (struct parport *port);
1262			...
1263		};
1264	
1265	DESCRIPTION
1266	^^^^^^^^^^^
1267	
1268	Returns the last value written to the control register (either from
1269	write_control or frob_control).  No port access is performed.
1270	
1271	SEE ALSO
1272	^^^^^^^^
1273	
1274	read_data, write_data, read_status, write_control
1275	
1276	
1277	
1278	port->ops->write_control - write the control register
1279	-----------------------------------------------------
1280	
1281	SYNOPSIS
1282	^^^^^^^^
1283	
1284	::
1285	
1286		#include <linux/parport.h>
1287	
1288		struct parport_operations {
1289			...
1290			void (*write_control) (struct parport *port, unsigned char s);
1291			...
1292		};
1293	
1294	DESCRIPTION
1295	^^^^^^^^^^^
1296	
1297	Writes to the control register. This is a bitmask::
1298	
1299					  _______
1300		- PARPORT_CONTROL_STROBE (nStrobe)
1301					  _______
1302		- PARPORT_CONTROL_AUTOFD (nAutoFd)
1303					_____
1304		- PARPORT_CONTROL_INIT (nInit)
1305					  _________
1306		- PARPORT_CONTROL_SELECT (nSelectIn)
1307	
1308	SEE ALSO
1309	^^^^^^^^
1310	
1311	read_data, write_data, read_status, frob_control
1312	
1313	
1314	
1315	port->ops->frob_control - write control register bits
1316	-----------------------------------------------------
1317	
1318	SYNOPSIS
1319	^^^^^^^^
1320	
1321	::
1322	
1323		#include <linux/parport.h>
1324	
1325		struct parport_operations {
1326			...
1327			unsigned char (*frob_control) (struct parport *port,
1328						unsigned char mask,
1329						unsigned char val);
1330			...
1331		};
1332	
1333	DESCRIPTION
1334	^^^^^^^^^^^
1335	
1336	This is equivalent to reading from the control register, masking out
1337	the bits in mask, exclusive-or'ing with the bits in val, and writing
1338	the result to the control register.
1339	
1340	As some ports don't allow reads from the control port, a software copy
1341	of its contents is maintained, so frob_control is in fact only one
1342	port access.
1343	
1344	SEE ALSO
1345	^^^^^^^^
1346	
1347	read_data, write_data, read_status, write_control
1348	
1349	
1350	
1351	port->ops->enable_irq - enable interrupt generation
1352	---------------------------------------------------
1353	
1354	SYNOPSIS
1355	^^^^^^^^
1356	
1357	::
1358	
1359		#include <linux/parport.h>
1360	
1361		struct parport_operations {
1362			...
1363			void (*enable_irq) (struct parport *port);
1364			...
1365		};
1366	
1367	DESCRIPTION
1368	^^^^^^^^^^^
1369	
1370	The parallel port hardware is instructed to generate interrupts at
1371	appropriate moments, although those moments are
1372	architecture-specific.  For the PC architecture, interrupts are
1373	commonly generated on the rising edge of nAck.
1374	
1375	SEE ALSO
1376	^^^^^^^^
1377	
1378	disable_irq
1379	
1380	
1381	
1382	port->ops->disable_irq - disable interrupt generation
1383	-----------------------------------------------------
1384	
1385	SYNOPSIS
1386	^^^^^^^^
1387	
1388	::
1389	
1390		#include <linux/parport.h>
1391	
1392		struct parport_operations {
1393			...
1394			void (*disable_irq) (struct parport *port);
1395			...
1396		};
1397	
1398	DESCRIPTION
1399	^^^^^^^^^^^
1400	
1401	The parallel port hardware is instructed not to generate interrupts.
1402	The interrupt itself is not masked.
1403	
1404	SEE ALSO
1405	^^^^^^^^
1406	
1407	enable_irq
1408	
1409	
1410	
1411	port->ops->data_forward - enable data drivers
1412	---------------------------------------------
1413	
1414	SYNOPSIS
1415	^^^^^^^^
1416	
1417	::
1418	
1419		#include <linux/parport.h>
1420	
1421		struct parport_operations {
1422			...
1423			void (*data_forward) (struct parport *port);
1424			...
1425		};
1426	
1427	DESCRIPTION
1428	^^^^^^^^^^^
1429	
1430	Enables the data line drivers, for 8-bit host-to-peripheral
1431	communications.
1432	
1433	SEE ALSO
1434	^^^^^^^^
1435	
1436	data_reverse
1437	
1438	
1439	
1440	port->ops->data_reverse - tristate the buffer
1441	---------------------------------------------
1442	
1443	SYNOPSIS
1444	^^^^^^^^
1445	
1446	::
1447	
1448		#include <linux/parport.h>
1449	
1450		struct parport_operations {
1451			...
1452			void (*data_reverse) (struct parport *port);
1453			...
1454		};
1455	
1456	DESCRIPTION
1457	^^^^^^^^^^^
1458	
1459	Places the data bus in a high impedance state, if port->modes has the
1460	PARPORT_MODE_TRISTATE bit set.
1461	
1462	SEE ALSO
1463	^^^^^^^^
1464	
1465	data_forward
1466	
1467	
1468	
1469	port->ops->epp_write_data - write EPP data
1470	------------------------------------------
1471	
1472	SYNOPSIS
1473	^^^^^^^^
1474	
1475	::
1476	
1477		#include <linux/parport.h>
1478	
1479		struct parport_operations {
1480			...
1481			size_t (*epp_write_data) (struct parport *port, const void *buf,
1482						size_t len, int flags);
1483			...
1484		};
1485	
1486	DESCRIPTION
1487	^^^^^^^^^^^
1488	
1489	Writes data in EPP mode, and returns the number of bytes written.
1490	
1491	The ``flags`` parameter may be one or more of the following,
1492	bitwise-or'ed together:
1493	
1494	======================= =================================================
1495	PARPORT_EPP_FAST	Use fast transfers. Some chips provide 16-bit and
1496				32-bit registers.  However, if a transfer
1497				times out, the return value may be unreliable.
1498	======================= =================================================
1499	
1500	SEE ALSO
1501	^^^^^^^^
1502	
1503	epp_read_data, epp_write_addr, epp_read_addr
1504	
1505	
1506	
1507	port->ops->epp_read_data - read EPP data
1508	----------------------------------------
1509	
1510	SYNOPSIS
1511	^^^^^^^^
1512	
1513	::
1514	
1515		#include <linux/parport.h>
1516	
1517		struct parport_operations {
1518			...
1519			size_t (*epp_read_data) (struct parport *port, void *buf,
1520						size_t len, int flags);
1521			...
1522		};
1523	
1524	DESCRIPTION
1525	^^^^^^^^^^^
1526	
1527	Reads data in EPP mode, and returns the number of bytes read.
1528	
1529	The ``flags`` parameter may be one or more of the following,
1530	bitwise-or'ed together:
1531	
1532	======================= =================================================
1533	PARPORT_EPP_FAST	Use fast transfers. Some chips provide 16-bit and
1534				32-bit registers.  However, if a transfer
1535				times out, the return value may be unreliable.
1536	======================= =================================================
1537	
1538	SEE ALSO
1539	^^^^^^^^
1540	
1541	epp_write_data, epp_write_addr, epp_read_addr
1542	
1543	
1544	
1545	port->ops->epp_write_addr - write EPP address
1546	---------------------------------------------
1547	
1548	SYNOPSIS
1549	^^^^^^^^
1550	
1551	::
1552	
1553		#include <linux/parport.h>
1554	
1555		struct parport_operations {
1556			...
1557			size_t (*epp_write_addr) (struct parport *port,
1558						const void *buf, size_t len, int flags);
1559			...
1560		};
1561	
1562	DESCRIPTION
1563	^^^^^^^^^^^
1564	
1565	Writes EPP addresses (8 bits each), and returns the number written.
1566	
1567	The ``flags`` parameter may be one or more of the following,
1568	bitwise-or'ed together:
1569	
1570	======================= =================================================
1571	PARPORT_EPP_FAST	Use fast transfers. Some chips provide 16-bit and
1572				32-bit registers.  However, if a transfer
1573				times out, the return value may be unreliable.
1574	======================= =================================================
1575	
1576	(Does PARPORT_EPP_FAST make sense for this function?)
1577	
1578	SEE ALSO
1579	^^^^^^^^
1580	
1581	epp_write_data, epp_read_data, epp_read_addr
1582	
1583	
1584	
1585	port->ops->epp_read_addr - read EPP address
1586	-------------------------------------------
1587	
1588	SYNOPSIS
1589	^^^^^^^^
1590	
1591	::
1592	
1593		#include <linux/parport.h>
1594	
1595		struct parport_operations {
1596			...
1597			size_t (*epp_read_addr) (struct parport *port, void *buf,
1598						size_t len, int flags);
1599			...
1600		};
1601	
1602	DESCRIPTION
1603	^^^^^^^^^^^
1604	
1605	Reads EPP addresses (8 bits each), and returns the number read.
1606	
1607	The ``flags`` parameter may be one or more of the following,
1608	bitwise-or'ed together:
1609	
1610	======================= =================================================
1611	PARPORT_EPP_FAST	Use fast transfers. Some chips provide 16-bit and
1612				32-bit registers.  However, if a transfer
1613				times out, the return value may be unreliable.
1614	======================= =================================================
1615	
1616	(Does PARPORT_EPP_FAST make sense for this function?)
1617	
1618	SEE ALSO
1619	^^^^^^^^
1620	
1621	epp_write_data, epp_read_data, epp_write_addr
1622	
1623	
1624	
1625	port->ops->ecp_write_data - write a block of ECP data
1626	-----------------------------------------------------
1627	
1628	SYNOPSIS
1629	^^^^^^^^
1630	
1631	::
1632	
1633		#include <linux/parport.h>
1634	
1635		struct parport_operations {
1636			...
1637			size_t (*ecp_write_data) (struct parport *port,
1638						const void *buf, size_t len, int flags);
1639			...
1640		};
1641	
1642	DESCRIPTION
1643	^^^^^^^^^^^
1644	
1645	Writes a block of ECP data.  The ``flags`` parameter is ignored.
1646	
1647	RETURN VALUE
1648	^^^^^^^^^^^^
1649	
1650	The number of bytes written.
1651	
1652	SEE ALSO
1653	^^^^^^^^
1654	
1655	ecp_read_data, ecp_write_addr
1656	
1657	
1658	
1659	port->ops->ecp_read_data - read a block of ECP data
1660	---------------------------------------------------
1661	
1662	SYNOPSIS
1663	^^^^^^^^
1664	
1665	::
1666	
1667		#include <linux/parport.h>
1668	
1669		struct parport_operations {
1670			...
1671			size_t (*ecp_read_data) (struct parport *port,
1672						void *buf, size_t len, int flags);
1673			...
1674		};
1675	
1676	DESCRIPTION
1677	^^^^^^^^^^^
1678	
1679	Reads a block of ECP data.  The ``flags`` parameter is ignored.
1680	
1681	RETURN VALUE
1682	^^^^^^^^^^^^
1683	
1684	The number of bytes read.  NB. There may be more unread data in a
1685	FIFO.  Is there a way of stunning the FIFO to prevent this?
1686	
1687	SEE ALSO
1688	^^^^^^^^
1689	
1690	ecp_write_block, ecp_write_addr
1691	
1692	
1693	
1694	port->ops->ecp_write_addr - write a block of ECP addresses
1695	----------------------------------------------------------
1696	
1697	SYNOPSIS
1698	^^^^^^^^
1699	
1700	::
1701	
1702		#include <linux/parport.h>
1703	
1704		struct parport_operations {
1705			...
1706			size_t (*ecp_write_addr) (struct parport *port,
1707						const void *buf, size_t len, int flags);
1708			...
1709		};
1710	
1711	DESCRIPTION
1712	^^^^^^^^^^^
1713	
1714	Writes a block of ECP addresses.  The ``flags`` parameter is ignored.
1715	
1716	RETURN VALUE
1717	^^^^^^^^^^^^
1718	
1719	The number of bytes written.
1720	
1721	NOTES
1722	^^^^^
1723	
1724	This may use a FIFO, and if so shall not return until the FIFO is empty.
1725	
1726	SEE ALSO
1727	^^^^^^^^
1728	
1729	ecp_read_data, ecp_write_data
1730	
1731	
1732	
1733	port->ops->nibble_read_data - read a block of data in nibble mode
1734	-----------------------------------------------------------------
1735	
1736	SYNOPSIS
1737	^^^^^^^^
1738	
1739	::
1740	
1741		#include <linux/parport.h>
1742	
1743		struct parport_operations {
1744			...
1745			size_t (*nibble_read_data) (struct parport *port,
1746						void *buf, size_t len, int flags);
1747			...
1748		};
1749	
1750	DESCRIPTION
1751	^^^^^^^^^^^
1752	
1753	Reads a block of data in nibble mode.  The ``flags`` parameter is ignored.
1754	
1755	RETURN VALUE
1756	^^^^^^^^^^^^
1757	
1758	The number of whole bytes read.
1759	
1760	SEE ALSO
1761	^^^^^^^^
1762	
1763	byte_read_data, compat_write_data
1764	
1765	
1766	
1767	port->ops->byte_read_data - read a block of data in byte mode
1768	-------------------------------------------------------------
1769	
1770	SYNOPSIS
1771	^^^^^^^^
1772	
1773	::
1774	
1775		#include <linux/parport.h>
1776	
1777		struct parport_operations {
1778			...
1779			size_t (*byte_read_data) (struct parport *port,
1780						void *buf, size_t len, int flags);
1781			...
1782		};
1783	
1784	DESCRIPTION
1785	^^^^^^^^^^^
1786	
1787	Reads a block of data in byte mode.  The ``flags`` parameter is ignored.
1788	
1789	RETURN VALUE
1790	^^^^^^^^^^^^
1791	
1792	The number of bytes read.
1793	
1794	SEE ALSO
1795	^^^^^^^^
1796	
1797	nibble_read_data, compat_write_data
1798	
1799	
1800	
1801	port->ops->compat_write_data - write a block of data in compatibility mode
1802	--------------------------------------------------------------------------
1803	
1804	SYNOPSIS
1805	^^^^^^^^
1806	
1807	::
1808	
1809		#include <linux/parport.h>
1810	
1811		struct parport_operations {
1812			...
1813			size_t (*compat_write_data) (struct parport *port,
1814						const void *buf, size_t len, int flags);
1815			...
1816		};
1817	
1818	DESCRIPTION
1819	^^^^^^^^^^^
1820	
1821	Writes a block of data in compatibility mode.  The ``flags`` parameter
1822	is ignored.
1823	
1824	RETURN VALUE
1825	^^^^^^^^^^^^
1826	
1827	The number of bytes written.
1828	
1829	SEE ALSO
1830	^^^^^^^^
1831	
1832	nibble_read_data, byte_read_data
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog