About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / parport-lowlevel.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.