Ok. I didn't make 2.4.0 in 2000. Tough. I tried, but we had some
[davej-history.git] / Documentation / parport-lowlevel.txt
blob1d40008a1926f3ee112707476f2bb23fb4637120
1 PARPORT interface documentation
2 -------------------------------
4 Time-stamp: <2000-02-24 13:30:20 twaugh>
6 Described here are the following functions:
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_num
29   parport_device_coords
30   parport_find_class
31   parport_find_device
32   parport_set_timeout
34 Port functions (can be overridden by low-level drivers):
35   SPP:
36     port->ops->read_data
37     port->ops->write_data
38     port->ops->read_status
39     port->ops->read_control
40     port->ops->write_control
41     port->ops->frob_control
42     port->ops->enable_irq
43     port->ops->disable_irq
44     port->ops->data_forward
45     port->ops->data_reverse
47   EPP:
48     port->ops->epp_write_data
49     port->ops->epp_read_data
50     port->ops->epp_write_addr
51     port->ops->epp_read_addr
53   ECP:
54     port->ops->ecp_write_data
55     port->ops->ecp_read_data
56     port->ops->ecp_write_addr
58   Other:
59     port->ops->nibble_read_data
60     port->ops->byte_read_data
61     port->ops->compat_write_data
63 The parport subsystem comprises 'parport' (the core port-sharing
64 code), and a variety of low-level drivers that actually do the port
65 accesses.  Each low-level driver handles a particular style of port
66 (PC, Amiga, and so on).
68 The parport interface to the device driver author can be broken down
69 into global functions and port functions.
71 The global functions are mostly for communicating between the device
72 driver and the parport subsystem: acquiring a list of available ports,
73 claiming a port for exclusive use, and so on.  They also include
74 'generic' functions for doing standard things that will work on any
75 IEEE 1284-capable architecture.
77 The port functions are provided by the low-level drivers, although the
78 core parport module provides generic 'defaults' for some routines.
79 The port functions can be split into three groups: SPP, EPP, and ECP.
81 SPP (Standard Parallel Port) functions modify so-called 'SPP'
82 registers: data, status, and control.  The hardware may not actually
83 have registers exactly like that, but the PC does and this interface is
84 modelled after common PC implementations.  Other low-level drivers may
85 be able to emulate most of the functionality.
87 EPP (Enhanced Parallel Port) functions are provided for reading and
88 writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)
89 functions are used for IEEE 1284 ECP mode. (What about BECP? Does
90 anyone care?)
92 Hardware assistance for EPP and/or ECP transfers may or may not be
93 available, and if it is available it may or may not be used.  If
94 hardware is not used, the transfer will be software-driven.  In order
95 to cope with peripherals that only tenuously support IEEE 1284, a
96 low-level driver specific function is provided, for altering 'fudge
97 factors'.
99 GLOBAL FUNCTIONS
100 ----------------
102 parport_register_driver - register a device driver with parport
103 -----------------------
105 SYNOPSIS
107 #include <linux/parport.h>
109 struct parport_driver {
110         const char *name;
111         void (*attach) (struct parport *);
112         void (*detach) (struct parport *);
113         struct parport_driver *next;
115 int parport_register_driver (struct parport_driver *driver);
117 DESCRIPTION
119 In order to be notified about parallel ports when they are detected,
120 parport_register_driver should be called.  Your driver will
121 immediately be notified of all ports that have already been detected,
122 and of each new port as low-level drivers are loaded.
124 A 'struct parport_driver' contains the textual name of your driver,
125 a pointer to a function to handle new ports, and a pointer to a
126 function to handle ports going away due to a low-level driver
127 unloading.  Ports will only be detached if they are not being used
128 (i.e. there are no devices registered on them).
130 The visible parts of the 'struct parport *' argument given to
131 attach/detach are:
133 struct parport
135         struct parport *next; /* next parport in list */
136         const char *name;     /* port's name */
137         unsigned int modes;   /* bitfield of hardware modes */
138         struct parport_device_info probe_info;
139                               /* IEEE1284 info */
140         int number;           /* parport index */
141         struct parport_operations *ops;
142         ...
145 There are other members of the structure, but they should not be
146 touched.
148 The 'modes' member summarises the capabilities of the underlying
149 hardware.  It consists of flags which may be bitwise-ored together:
151   PARPORT_MODE_PCSPP            IBM PC registers are available,
152                                 i.e. functions that act on data,
153                                 control and status registers are
154                                 probably writing directly to the
155                                 hardware.
156   PARPORT_MODE_TRISTATE         The data drivers may be turned off.
157                                 This allows the data lines to be used
158                                 for reverse (peripheral to host)
159                                 transfers.
160   PARPORT_MODE_COMPAT           The hardware can assist with
161                                 compatibility-mode (printer)
162                                 transfers, i.e. compat_write_block.
163   PARPORT_MODE_EPP              The hardware can assist with EPP
164                                 transfers.
165   PARPORT_MODE_ECP              The hardware can assist with ECP
166                                 transfers.
167   PARPORT_MODE_DMA              The hardware can use DMA, so you might
168                                 want to pass ISA DMA-able memory
169                                 (i.e. memory allocated using the
170                                 GFP_DMA flag with kmalloc) to the
171                                 low-level driver in order to take
172                                 advantage of it.
174 There may be other flags in 'modes' as well.
176 The contents of 'modes' is advisory only.  For example, if the
177 hardware is capable of DMA, and PARPORT_MODE_DMA is in 'modes', it
178 doesn't necessarily mean that DMA will always be used when possible.
179 Similarly, hardware that is capable of assisting ECP transfers won't
180 necessarily be used.
182 RETURN VALUE
184 Zero on success, otherwise an error code.
186 ERRORS
188 None. (Can it fail? Why return int?)
190 EXAMPLE
192 static void lp_attach (struct parport *port)
194         ...
195         private = kmalloc (...);
196         dev[count++] = parport_register_device (...);
197         ...
200 static void lp_detach (struct parport *port)
202         ...
205 static struct parport_driver lp_driver = {
206         "lp",
207         lp_attach,
208         lp_detach,
209         NULL /* always put NULL here */
212 int lp_init (void)
214         ...
215         if (parport_register_driver (&lp_driver)) {
216                 /* Failed; nothing we can do. */
217                 return -EIO;
218         }
219         ...
222 SEE ALSO
224 parport_unregister_driver, parport_register_device, parport_enumerate
226 parport_unregister_driver - tell parport to forget about this driver
227 -------------------------
229 SYNOPSIS
231 #include <linux/parport.h>
233 struct parport_driver {
234         const char *name;
235         void (*attach) (struct parport *);
236         void (*detach) (struct parport *);
237         struct parport_driver *next;
239 void parport_unregister_driver (struct parport_driver *driver);
241 DESCRIPTION
243 This tells parport not to notify the device driver of new ports or of
244 ports going away.  Registered devices belonging to that driver are NOT
245 unregistered: parport_unregister_device must be used for each one.
247 EXAMPLE
249 void cleanup_module (void)
251         ...
252         /* Stop notifications. */
253         parport_unregister_driver (&lp_driver);
255         /* Unregister devices. */
256         for (i = 0; i < NUM_DEVS; i++)
257                 parport_unregister_device (dev[i]);
258         ...
261 SEE ALSO
263 parport_register_driver, parport_enumerate
265 parport_enumerate - retrieve a list of parallel ports (DEPRECATED)
266 -----------------
268 SYNOPSIS
270 #include <linux/parport.h>
272 struct parport *parport_enumerate (void);
274 DESCRIPTION
276 Retrieve the first of a list of valid parallel ports for this machine.
277 Successive parallel ports can be found using the 'struct parport
278 *next' element of the 'struct parport *' that is returned.  If 'next'
279 is NULL, there are no more parallel ports in the list.  The number of
280 ports in the list will not exceed PARPORT_MAX.
282 RETURN VALUE
284 A 'struct parport *' describing a valid parallel port for the machine,
285 or NULL if there are none.
287 ERRORS
289 This function can return NULL to indicate that there are no parallel
290 ports to use.
292 EXAMPLE
294 int detect_device (void)
296         struct parport *port;
298         for (port = parport_enumerate ();
299              port != NULL;
300              port = port->next) {
301                 /* Try to detect a device on the port... */
302                 ...
303              }
304         }
306         ...
309 NOTES
311 parport_enumerate is deprecated; parport_register_driver should be
312 used instead.
314 SEE ALSO
316 parport_register_driver, parport_unregister_driver
318 parport_register_device - register to use a port
319 -----------------------
321 SYNOPSIS
323 #include <linux/parport.h>
325 typedef int (*preempt_func) (void *handle);
326 typedef void (*wakeup_func) (void *handle);
327 typedef int (*irq_func) (int irq, void *handle, struct pt_regs *);
329 struct pardevice *parport_register_device(struct parport *port,
330                                           const char *name,
331                                           preempt_func preempt,
332                                           wakeup_func wakeup,
333                                           irq_func irq,
334                                           int flags,
335                                           void *handle);
337 DESCRIPTION
339 Use this function to register your device driver on a parallel port
340 ('port').  Once you have done that, you will be able to use
341 parport_claim and parport_release in order to use the port.
343 This function will register three callbacks into your driver:
344 'preempt', 'wakeup' and 'irq'.  Each of these may be NULL in order to
345 indicate that you do not want a callback.
347 When the 'preempt' function is called, it is because another driver
348 wishes to use the parallel port.  The 'preempt' function should return
349 non-zero if the parallel port cannot be released yet -- if zero is
350 returned, the port is lost to another driver and the port must be
351 re-claimed before use.
353 The 'wakeup' function is called once another driver has released the
354 port and no other driver has yet claimed it.  You can claim the
355 parallel port from within the 'wakeup' function (in which case the
356 claim is guaranteed to succeed), or choose not to if you don't need it
357 now.
359 If an interrupt occurs on the parallel port your driver has claimed,
360 the 'irq' function will be called. (Write something about shared
361 interrupts here.)
363 The 'handle' is a pointer to driver-specific data, and is passed to
364 the callback functions.
366 'flags' may be a bitwise combination of the following flags:
368         Flag            Meaning
369   PARPORT_DEV_EXCL      The device cannot share the parallel port at all.
370                         Use this only when absolutely necessary.
372 The typedefs are not actually defined -- they are only shown in order
373 to make the function prototype more readable.
375 The visible parts of the returned 'struct pardevice' are:
377 struct pardevice {
378         struct parport *port;   /* Associated port */
379         void *private;          /* Device driver's 'handle' */
380         ...
383 RETURN VALUE
385 A 'struct pardevice *': a handle to the registered parallel port
386 device that can be used for parport_claim, parport_release, etc.
388 ERRORS
390 A return value of NULL indicates that there was a problem registering
391 a device on that port.
393 EXAMPLE
395 static int preempt (void *handle)
397         if (busy_right_now)
398                 return 1;
400         must_reclaim_port = 1;
401         return 0;
404 static void wakeup (void *handle)
406         struct toaster *private = handle;
407         struct pardevice *dev = private->dev;
408         if (!dev) return; /* avoid races */
410         if (want_port)
411                 parport_claim (dev);
414 static int toaster_detect (struct toaster *private, struct parport *port)
416         private->dev = parport_register_device (port, "toaster", preempt,
417                                                 wakeup, NULL, 0,
418                                                 private);
419         if (!private->dev)
420                 /* Couldn't register with parport. */
421                 return -EIO;
423         must_reclaim_port = 0;
424         busy_right_now = 1;
425         parport_claim_or_block (private->dev);
426         ...
427         /* Don't need the port while the toaster warms up. */
428         busy_right_now = 0;
429         ...
430         busy_right_now = 1;
431         if (must_reclaim_port) {
432                 parport_claim_or_block (private->dev);
433                 must_reclaim_port = 0;
434         }
435         ...
438 SEE ALSO
440 parport_unregister_device, parport_claim
442 parport_unregister_device - finish using a port
443 -------------------------
445 SYNPOPSIS
447 #include <linux/parport.h>
449 void parport_unregister_device (struct pardevice *dev);
451 DESCRIPTION
453 This function is the opposite of parport_register_device.  After using
454 parport_unregister_device, 'dev' is no longer a valid device handle.
456 You should not unregister a device that is currently claimed, although
457 if you do it will be released automatically.
459 EXAMPLE
461         ...
462         kfree (dev->private); /* before we lose the pointer */
463         parport_unregister_device (dev);
464         ...
466 SEE ALSO
468 parport_unregister_driver
470 parport_claim, parport_claim_or_block - claim the parallel port for a device
471 -------------------------------------
473 SYNOPSIS
475 #include <linux/parport.h>
477 int parport_claim (struct pardevice *dev);
478 int parport_claim_or_block (struct pardevice *dev);
480 DESCRIPTION
482 These functions attempt to gain control of the parallel port on which
483 'dev' is registered.  'parport_claim' does not block, but
484 'parport_claim_or_block' may do. (Put something here about blocking
485 interruptibly or non-interruptibly.)
487 You should not try to claim a port that you have already claimed.
489 RETURN VALUE
491 A return value of zero indicates that the port was successfully
492 claimed, and the caller now has possession of the parallel port.
494 If 'parport_claim_or_block' blocks before returning successfully, the
495 return value is positive.
497 ERRORS
499   -EAGAIN  The port is unavailable at the moment, but another attempt
500            to claim it may succeed.
502 SEE ALSO
504 parport_release
506 parport_release - release the parallel port
507 ---------------
509 SYNOPSIS
511 #include <linux/parport.h>
513 void parport_release (struct pardevice *dev);
515 DESCRIPTION
517 Once a parallel port device has been claimed, it can be released using
518 'parport_release'.  It cannot fail, but you should not release a
519 device that you do not have possession of.
521 EXAMPLE
523 static size_t write (struct pardevice *dev, const void *buf,
524                      size_t len)
526         ...
527         written = dev->port->ops->write_ecp_data (dev->port, buf,
528                                                   len);
529         parport_release (dev);
530         ...
534 SEE ALSO
536 change_mode, parport_claim, parport_claim_or_block, parport_yield
538 parport_yield, parport_yield_blocking - temporarily release a parallel port
539 -------------------------------------
541 SYNOPSIS
543 #include <linux/parport.h>
545 int parport_yield (struct pardevice *dev)
546 int parport_yield_blocking (struct pardevice *dev);
548 DESCRIPTION
550 When a driver has control of a parallel port, it may allow another
551 driver to temporarily 'borrow' it.  'parport_yield' does not block;
552 'parport_yield_blocking' may do.
554 RETURN VALUE
556 A return value of zero indicates that the caller still owns the port
557 and the call did not block.
559 A positive return value from 'parport_yield_blocking' indicates that
560 the caller still owns the port and the call blocked.
562 A return value of -EAGAIN indicates that the caller no longer owns the
563 port, and it must be re-claimed before use.
565 ERRORS
567   -EAGAIN  Ownership of the parallel port was given away.
569 SEE ALSO
571 parport_release
573 parport_wait_peripheral - wait for status lines, up to 35ms
574 -----------------------
576 SYNOPSIS
578 #include <linux/parport.h>
580 int parport_wait_peripheral (struct parport *port,
581                              unsigned char mask,
582                              unsigned char val);
584 DESCRIPTION
586 Wait for the status lines in mask to match the values in val.
588 RETURN VALUE
590  -EINTR  a signal is pending
591       0  the status lines in mask have values in val
592       1  timed out while waiting (35ms elapsed)
594 SEE ALSO
596 parport_poll_peripheral
598 parport_poll_peripheral - wait for status lines, in usec
599 -----------------------
601 SYNOPSIS
603 #include <linux/parport.h>
605 int parport_poll_peripheral (struct parport *port,
606                              unsigned char mask,
607                              unsigned char val,
608                              int usec);
610 DESCRIPTION
612 Wait for the status lines in mask to match the values in val.
614 RETURN VALUE
616  -EINTR  a signal is pending
617       0  the status lines in mask have values in val
618       1  timed out while waiting (usec microseconds have elapsed)
620 SEE ALSO
622 parport_wait_peripheral
624 parport_wait_event - wait for an event on a port
625 ------------------
627 SYNOPSIS
629 #include <linux/parport.h>
631 int parport_wait_event (struct parport *port, signed long timeout)
633 DESCRIPTION
635 Wait for an event (e.g. interrupt) on a port.  The timeout is in
636 jiffies.
638 RETURN VALUE
640       0  success
641      <0  error (exit as soon as possible)
642      >0  timed out
644 parport_negotiate - perform IEEE 1284 negotiation
645 -----------------
647 SYNOPSIS
649 #include <linux/parport.h>
651 int parport_negotiate (struct parport *, int mode);
653 DESCRIPTION
655 Perform IEEE 1284 negotiation.
657 RETURN VALUE
659      0  handshake OK; IEEE 1284 peripheral and mode available
660     -1  handshake failed; peripheral not compliant (or none present)
661      1  handshake OK; IEEE 1284 peripheral present but mode not
662         available
664 SEE ALSO
666 parport_read, parport_write
668 parport_read - read data from device
669 ------------
671 SYNOPSIS
673 #include <linux/parport.h>
675 ssize_t parport_read (struct parport *, void *buf, size_t len);
677 DESCRIPTION
679 Read data from device in current IEEE 1284 transfer mode.  This only
680 works for modes that support reverse data transfer.
682 RETURN VALUE
684 If negative, an error code; otherwise the number of bytes transferred.
686 SEE ALSO
688 parport_write, parport_negotiate
690 parport_write - write data to device
691 -------------
693 SYNOPSIS
695 #include <linux/parport.h>
697 ssize_t parport_write (struct parport *, const void *buf, size_t len);
699 DESCRIPTION
701 Write data to device in current IEEE 1284 transfer mode.  This only
702 works for modes that support forward data transfer.
704 RETURN VALUE
706 If negative, an error code; otherwise the number of bytes transferred.
708 SEE ALSO
710 parport_read, parport_negotiate
712 parport_open - register device for particular device number
713 ------------
715 SYNOPSIS
717 #include <linux/parport.h>
719 struct pardevice *parport_open (int devnum, const char *name,
720                                 int (*pf) (void *),
721                                 void (*kf) (void *),
722                                 void (*irqf) (int, void *,
723                                               struct pt_regs *),
724                                 int flags, void *handle);
726 DESCRIPTION
728 This is like parport_register_device but takes a device number instead
729 of a pointer to a struct parport.
731 RETURN VALUE
733 See parport_register_device.  If no device is associated with devnum,
734 NULL is returned.
736 SEE ALSO
738 parport_register_device, parport_device_num
740 parport_close - unregister device for particular device number
741 -------------
743 SYNOPSIS
745 #include <linux/parport.h>
747 void parport_close (struct pardevice *dev);
749 DESCRIPTION
751 This is the equivalent of parport_unregister_device for parport_open.
753 SEE ALSO
755 parport_unregister_device, parport_open
757 parport_device_id - obtain IEEE 1284 Device ID
758 -----------------
760 SYNOPSIS
762 #include <linux/parport.h>
764 ssize_t parport_device_id (int devnum, char *buffer, size_t len);
766 DESCRIPTION
768 Obtains the IEEE 1284 Device ID associated with a given device.
770 RETURN VALUE
772 If negative, an error code; otherwise, the number of bytes of buffer
773 that contain the device ID.  The format of the device ID is as
774 follows:
776 [length][ID]
778 The first two bytes indicate the inclusive length of the entire Device
779 ID, and are in big-endian order.  The ID is a sequence of pairs of the
780 form:
782 key:value;
784 NOTES
786 Many devices have ill-formed IEEE 1284 Device IDs.
788 SEE ALSO
790 parport_find_class, parport_find_device, parport_device_num
792 parport_device_num - convert device coordinates to device number
793 ------------------
795 SYNOPSIS
797 #include <linux/parport.h>
799 int parport_device_num (int parport, int mux, int daisy);
801 DESCRIPTION
803 Convert between device coordinates (port, multiplexor, daisy chain
804 address) and device number (zero-based).
806 RETURN VALUE
808 Device number, or -1 if no device at given coordinates.
810 SEE ALSO
812 parport_device_coords, parport_open, parport_device_id
814 parport_device_coords - convert device number to device coordinates
815 ------------------
817 SYNOPSIS
819 #include <linux/parport.h>
821 int parport_device_coords (int devnum, int *parport, int *mux,
822                            int *daisy);
824 DESCRIPTION
826 Convert between device number (zero-based) and device coordinates
827 (port, multiplexor, daisy chain address).
829 RETURN VALUE
831 Zero on success, in which case the coordinates are (*parport, *mux,
832 *daisy).
834 SEE ALSO
836 parport_device_num, parport_open, parport_device_id
838 parport_find_class - find a device by its class
839 ------------------
841 SYNOPSIS
843 #include <linux/parport.h>
845 typedef enum {
846         PARPORT_CLASS_LEGACY = 0,       /* Non-IEEE1284 device */
847         PARPORT_CLASS_PRINTER,
848         PARPORT_CLASS_MODEM,
849         PARPORT_CLASS_NET,
850         PARPORT_CLASS_HDC,              /* Hard disk controller */
851         PARPORT_CLASS_PCMCIA,
852         PARPORT_CLASS_MEDIA,            /* Multimedia device */
853         PARPORT_CLASS_FDC,              /* Floppy disk controller */
854         PARPORT_CLASS_PORTS,
855         PARPORT_CLASS_SCANNER,
856         PARPORT_CLASS_DIGCAM,
857         PARPORT_CLASS_OTHER,            /* Anything else */
858         PARPORT_CLASS_UNSPEC,           /* No CLS field in ID */
859         PARPORT_CLASS_SCSIADAPTER
860 } parport_device_class;
862 int parport_find_class (parport_device_class cls, int from);
864 DESCRIPTION
866 Find a device by class.  The search starts from device number from+1.
868 RETURN VALUE
870 The device number of the next device in that class, or -1 if no such
871 device exists.
873 NOTES
875 Example usage:
877 int devnum = -1;
878 while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, devnum)) != -1) {
879     struct pardevice *dev = parport_open (devnum, ...);
880     ...
883 SEE ALSO
885 parport_find_device, parport_open, parport_device_id
887 parport_find_device - find a device by its class
888 ------------------
890 SYNOPSIS
892 #include <linux/parport.h>
894 int parport_find_device (const char *mfg, const char *mdl, int from);
896 DESCRIPTION
898 Find a device by vendor and model.  The search starts from device
899 number from+1.
901 RETURN VALUE
903 The device number of the next device matching the specifications, or
904 -1 if no such device exists.
906 NOTES
908 Example usage:
910 int devnum = -1;
911 while ((devnum = parport_find_device ("IOMEGA", "ZIP+", devnum)) != -1) {
912     struct pardevice *dev = parport_open (devnum, ...);
913     ...
916 SEE ALSO
918 parport_find_class, parport_open, parport_device_id
920 parport_set_timeout - set the inactivity timeout
921 -------------------
923 SYNOPSIS
925 #include <linux/parport.h>
927 long parport_set_timeout (struct pardevice *dev, long inactivity);
929 DESCRIPTION
931 Set the inactivity timeout, in jiffies, for a registered device.  The
932 previous timeout is returned.
934 RETURN VALUE
936 The previous timeout, in jiffies.
938 NOTES
940 Some of the port->ops functions for a parport may take time, owing to
941 delays at the peripheral.  After the peripheral has not responded for
942 'inactivity' jiffies, a timeout will occur and the blocking function
943 will return.
945 A timeout of 0 jiffies is a special case: the function must do as much
946 as it can without blocking or leaving the hardware in an unknown
947 state.  If port operations are performed from within an interrupt
948 handler, for instance, a timeout of 0 jiffies should be used.
950 Once set for a registered device, the timeout will remain at the set
951 value until set again.
953 SEE ALSO
955 port->ops->xxx_read/write_yyy
957 PORT FUNCTIONS
958 --------------
960 The functions in the port->ops structure (struct parport_operations)
961 are provided by the low-level driver responsible for that port.
963 port->ops->read_data - read the data register
964 --------------------
966 SYNOPSIS
968 #include <linux/parport.h>
970 struct parport_operations {
971         ...
972         unsigned char (*read_data) (struct parport *port);
973         ...
976 DESCRIPTION
978 If port->modes contains the PARPORT_MODE_TRISTATE flag and the
979 PARPORT_CONTROL_DIRECTION bit in the control register is set, this
980 returns the value on the data pins.  If port->modes contains the
981 PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is
982 not set, the return value _may_ be the last value written to the data
983 register.  Otherwise the return value is undefined.
985 SEE ALSO
987 write_data, read_status, write_control
989 port->ops->write_data - write the data register
990 ---------------------
992 SYNOPSIS
994 #include <linux/parport.h>
996 struct parport_operations {
997         ...
998         void (*write_data) (struct parport *port, unsigned char d);
999         ...
1002 DESCRIPTION
1004 Writes to the data register.  May have side-effects (a STROBE pulse,
1005 for instance).
1007 SEE ALSO
1009 read_data, read_status, write_control
1011 port->ops->read_status - read the status register
1012 ----------------------
1014 SYNOPSIS
1016 #include <linux/parport.h>
1018 struct parport_operations {
1019         ...
1020         unsigned char (*read_status) (struct parport *port);
1021         ...
1024 DESCRIPTION
1026 Reads from the status register.  This is a bitmask:
1028 - PARPORT_STATUS_ERROR (printer fault, "nFault")
1029 - PARPORT_STATUS_SELECT (on-line, "Select")
1030 - PARPORT_STATUS_PAPEROUT (no paper, "PError")
1031 - PARPORT_STATUS_ACK (handshake, "nAck")
1032 - PARPORT_STATUS_BUSY (busy, "Busy")
1034 There may be other bits set.
1036 SEE ALSO
1038 read_data, write_data, write_control
1040 port->ops->read_control - read the control register
1041 -----------------------
1043 SYNOPSIS
1045 #include <linux/parport.h>
1047 struct parport_operations {
1048         ...
1049         unsigned char (*read_control) (struct parport *port);
1050         ...
1053 DESCRIPTION
1055 Returns the last value written to the control register (either from
1056 write_control or frob_control).  No port access is performed.
1058 SEE ALSO
1060 read_data, write_data, read_status, write_control
1062 port->ops->write_control - write the control register
1063 ------------------------
1065 SYNOPSIS
1067 #include <linux/parport.h>
1069 struct parport_operations {
1070         ...
1071         void (*write_status) (struct parport *port, unsigned char s);
1072         ...
1075 DESCRIPTION
1077 Writes to the control register. This is a bitmask:
1078                           _______
1079 - PARPORT_CONTROL_STROBE (nStrobe)
1080                           _______
1081 - PARPORT_CONTROL_AUTOFD (nAutoFd)
1082                         _____
1083 - PARPORT_CONTROL_INIT (nInit)
1084                           _________
1085 - PARPORT_CONTROL_SELECT (nSelectIn)
1087 SEE ALSO
1089 read_data, write_data, read_status, frob_control
1091 port->ops->frob_control - write control register bits
1092 -----------------------
1094 SYNOPSIS
1096 #include <linux/parport.h>
1098 struct parport_operations {
1099         ...
1100         void (*frob_control) (struct parport *port,
1101                               unsigned char mask,
1102                               unsigned char val);
1103         ...
1106 DESCRIPTION
1108 This is equivalent to reading from the control register, masking out
1109 the bits in mask, exclusive-or'ing with the bits in val, and writing
1110 the result to the control register.
1112 As some ports don't allow reads from the control port, a software copy
1113 of its contents is maintained, so frob_control is in fact only one
1114 port access.
1116 SEE ALSO
1118 read_data, write_data, read_status, write_control
1120 port->ops->enable_irq - enable interrupt generation
1121 ---------------------
1123 SYNOPSIS
1125 #include <linux/parport.h>
1127 struct parport_operations {
1128         ...
1129         void (*enable_irq) (struct parport *port);
1130         ...
1133 DESCRIPTION
1135 The parallel port hardware is instructed to generate interrupts at
1136 appropriate moments, although those moments are
1137 architecture-specific.  For the PC architecture, interrupts are
1138 commonly generated on the rising edge of nAck.
1140 SEE ALSO
1142 disable_irq
1144 port->ops->disable_irq - disable interrupt generation
1145 ----------------------
1147 SYNOPSIS
1149 #include <linux/parport.h>
1151 struct parport_operations {
1152         ...
1153         void (*disable_irq) (struct parport *port);
1154         ...
1157 DESCRIPTION
1159 The parallel port hardware is instructed not to generate interrupts.
1160 The interrupt itself is not masked.
1162 SEE ALSO
1164 enable_irq
1166 port->ops->data_forward - enable data drivers
1167 -----------------------
1169 SYNOPSIS
1171 #include <linux/parport.h>
1173 struct parport_operations {
1174         ...
1175         void (*data_forward) (struct parport *port);
1176         ...
1179 DESCRIPTION
1181 Enables the data line drivers, for 8-bit host-to-peripheral
1182 communications.
1184 SEE ALSO
1186 data_reverse
1188 port->ops->data_reverse - tristate the buffer
1189 -----------------------
1191 SYNOPSIS
1193 #include <linux/parport.h>
1195 struct parport_operations {
1196         ...
1197         void (*data_reverse) (struct parport *port);
1198         ...
1201 DESCRIPTION
1203 Places the data bus in a high impedance state, if port->modes has the
1204 PARPORT_MODE_TRISTATE bit set.
1206 SEE ALSO
1208 data_forward
1210 port->ops->epp_write_data - write EPP data
1211 -------------------------
1213 SYNOPSIS
1215 #include <linux/parport.h>
1217 struct parport_operations {
1218         ...
1219         size_t (*epp_write_data) (struct parport *port, const void *buf,
1220                                   size_t len, int flags);
1221         ...
1224 DESCRIPTION
1226 Writes data in EPP mode, and returns the number of bytes written.
1228 The 'flags' parameter may be one or more of the following,
1229 bitwise-or'ed together:
1231 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1232                         32-bit registers.  However, if a transfer
1233                         times out, the return value may be unreliable.
1235 SEE ALSO
1237 epp_read_data, epp_write_addr, epp_read_addr
1239 port->ops->epp_read_data - read EPP data
1240 ------------------------
1242 SYNOPSIS
1244 #include <linux/parport.h>
1246 struct parport_operations {
1247         ...
1248         size_t (*epp_read_data) (struct parport *port, void *buf,
1249                                  size_t len, int flags);
1250         ...
1253 DESCRIPTION
1255 Reads data in EPP mode, and returns the number of bytes read.
1257 The 'flags' parameter may be one or more of the following,
1258 bitwise-or'ed together:
1260 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1261                         32-bit registers.  However, if a transfer
1262                         times out, the return value may be unreliable.
1264 SEE ALSO
1266 epp_write_data, epp_write_addr, epp_read_addr
1268 port->ops->epp_write_addr - write EPP address
1269 -------------------------
1271 SYNOPSIS
1273 #include <linux/parport.h>
1275 struct parport_operations {
1276         ...
1277         size_t (*epp_write_addr) (struct parport *port,
1278                                   const void *buf, size_t len, int flags);
1279         ...
1282 DESCRIPTION
1284 Writes EPP addresses (8 bits each), and returns the number written.
1286 The 'flags' parameter may be one or more of the following,
1287 bitwise-or'ed together:
1289 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1290                         32-bit registers.  However, if a transfer
1291                         times out, the return value may be unreliable.
1293 (Does PARPORT_EPP_FAST make sense for this function?)
1295 SEE ALSO
1297 epp_write_data, epp_read_data, epp_read_addr
1299 port->ops->epp_read_addr - read EPP address
1300 ------------------------
1302 SYNOPSIS
1304 #include <linux/parport.h>
1306 struct parport_operations {
1307         ...
1308         size_t (*epp_read_addr) (struct parport *port, void *buf,
1309                                  size_t len, int flags);
1310         ...
1313 DESCRIPTION
1315 Reads EPP addresses (8 bits each), and returns the number read.
1317 The 'flags' parameter may be one or more of the following,
1318 bitwise-or'ed together:
1320 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1321                         32-bit registers.  However, if a transfer
1322                         times out, the return value may be unreliable.
1324 (Does PARPORT_EPP_FAST make sense for this function?)
1326 SEE ALSO
1328 epp_write_data, epp_read_data, epp_write_addr
1330 port->ops->ecp_write_data - write a block of ECP data
1331 -------------------------
1333 SYNOPSIS
1335 #include <linux/parport.h>
1337 struct parport_operations {
1338         ...
1339         size_t (*ecp_write_data) (struct parport *port,
1340                                   const void *buf, size_t len, int flags);
1341         ...
1344 DESCRIPTION
1346 Writes a block of ECP data.  The 'flags' parameter is ignored.
1348 RETURN VALUE
1350 The number of bytes written.
1352 SEE ALSO
1354 ecp_read_data, ecp_write_addr
1356 port->ops->ecp_read_data - read a block of ECP data
1357 ------------------------
1359 SYNOPSIS
1361 #include <linux/parport.h>
1363 struct parport_operations {
1364         ...
1365         size_t (*ecp_read_data) (struct parport *port,
1366                                  void *buf, size_t len, int flags);
1367         ...
1370 DESCRIPTION
1372 Reads a block of ECP data.  The 'flags' parameter is ignored.
1374 RETURN VALUE
1376 The number of bytes read.  NB. There may be more unread data in a
1377 FIFO.  Is there a way of stunning the FIFO to prevent this?
1379 SEE ALSO
1381 ecp_write_block, ecp_write_addr
1383 port->ops->ecp_write_addr - write a block of ECP addresses
1384 -------------------------
1386 SYNOPSIS
1388 #include <linux/parport.h>
1390 struct parport_operations {
1391         ...
1392         size_t (*ecp_write_addr) (struct parport *port,
1393                                   const void *buf, size_t len, int flags);
1394         ...
1397 DESCRIPTION
1399 Writes a block of ECP addresses.  The 'flags' parameter is ignored.
1401 RETURN VALUE
1403 The number of bytes written.
1405 NOTES
1407 This may use a FIFO, and if so shall not return until the FIFO is empty.
1409 SEE ALSO
1411 ecp_read_data, ecp_write_data
1413 port->ops->nibble_read_data - read a block of data in nibble mode
1414 ---------------------------
1416 SYNOPSIS
1418 #include <linux/parport.h>
1420 struct parport_operations {
1421         ...
1422         size_t (*nibble_read_data) (struct parport *port,
1423                                     void *buf, size_t len, int flags);
1424         ...
1427 DESCRIPTION
1429 Reads a block of data in nibble mode.  The 'flags' parameter is ignored.
1431 RETURN VALUE
1433 The number of whole bytes read.
1435 SEE ALSO
1437 byte_read_data, compat_write_data
1439 port->ops->byte_read_data - read a block of data in byte mode
1440 -------------------------
1442 SYNOPSIS
1444 #include <linux/parport.h>
1446 struct parport_operations {
1447         ...
1448         size_t (*byte_read_data) (struct parport *port,
1449                                   void *buf, size_t len, int flags);
1450         ...
1453 DESCRIPTION
1455 Reads a block of data in byte mode.  The 'flags' parameter is ignored.
1457 RETURN VALUE
1459 The number of bytes read.
1461 SEE ALSO
1463 nibble_read_data, compat_write_data
1465 port->ops->compat_write_data - write a block of data in compatibility mode
1466 ----------------------------
1468 SYNOPSIS
1470 #include <linux/parport.h>
1472 struct parport_operations {
1473         ...
1474         size_t (*compat_write_data) (struct parport *port,
1475                                      const void *buf, size_t len, int flags);
1476         ...
1479 DESCRIPTION
1481 Writes a block of data in compatibility mode.  The 'flags' parameter
1482 is ignored.
1484 RETURN VALUE
1486 The number of bytes written.
1488 SEE ALSO
1490 nibble_read_data, byte_read_data