Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
[platform/adaptation/renesas_rcar/renesas_kernel.git] / Documentation / parport-lowlevel.txt
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 \f
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 \f
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 \f
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 \f
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 This function will register three callbacks into your driver:
343 'preempt', 'wakeup' and 'irq'.  Each of these may be NULL in order to
344 indicate that you do not want a callback.
345
346 When the 'preempt' function is called, it is because another driver
347 wishes to use the parallel port.  The 'preempt' function should return
348 non-zero if the parallel port cannot be released yet -- if zero is
349 returned, the port is lost to another driver and the port must be
350 re-claimed before use.
351
352 The 'wakeup' function is called once another driver has released the
353 port and no other driver has yet claimed it.  You can claim the
354 parallel port from within the 'wakeup' function (in which case the
355 claim is guaranteed to succeed), or choose not to if you don't need it
356 now.
357
358 If an interrupt occurs on the parallel port your driver has claimed,
359 the 'irq' function will be called. (Write something about shared
360 interrupts here.)
361
362 The 'handle' is a pointer to driver-specific data, and is passed to
363 the callback functions.
364
365 'flags' may be a bitwise combination of the following flags:
366
367         Flag            Meaning
368   PARPORT_DEV_EXCL      The device cannot share the parallel port at all.
369                         Use this only when absolutely necessary.
370
371 The typedefs are not actually defined -- they are only shown in order
372 to make the function prototype more readable.
373
374 The visible parts of the returned 'struct pardevice' are:
375
376 struct pardevice {
377         struct parport *port;   /* Associated port */
378         void *private;          /* Device driver's 'handle' */
379         ...
380 };
381
382 RETURN VALUE
383
384 A 'struct pardevice *': a handle to the registered parallel port
385 device that can be used for parport_claim, parport_release, etc.
386
387 ERRORS
388
389 A return value of NULL indicates that there was a problem registering
390 a device on that port.
391
392 EXAMPLE
393
394 static int preempt (void *handle)
395 {
396         if (busy_right_now)
397                 return 1;
398
399         must_reclaim_port = 1;
400         return 0;
401 }
402
403 static void wakeup (void *handle)
404 {
405         struct toaster *private = handle;
406         struct pardevice *dev = private->dev;
407         if (!dev) return; /* avoid races */
408
409         if (want_port)
410                 parport_claim (dev);
411 }
412
413 static int toaster_detect (struct toaster *private, struct parport *port)
414 {
415         private->dev = parport_register_device (port, "toaster", preempt,
416                                                 wakeup, NULL, 0,
417                                                 private);
418         if (!private->dev)
419                 /* Couldn't register with parport. */
420                 return -EIO;
421
422         must_reclaim_port = 0;
423         busy_right_now = 1;
424         parport_claim_or_block (private->dev);
425         ...
426         /* Don't need the port while the toaster warms up. */
427         busy_right_now = 0;
428         ...
429         busy_right_now = 1;
430         if (must_reclaim_port) {
431                 parport_claim_or_block (private->dev);
432                 must_reclaim_port = 0;
433         }
434         ...
435 }
436
437 SEE ALSO
438
439 parport_unregister_device, parport_claim
440 \f
441 parport_unregister_device - finish using a port
442 -------------------------
443
444 SYNPOPSIS
445
446 #include <linux/parport.h>
447
448 void parport_unregister_device (struct pardevice *dev);
449
450 DESCRIPTION
451
452 This function is the opposite of parport_register_device.  After using
453 parport_unregister_device, 'dev' is no longer a valid device handle.
454
455 You should not unregister a device that is currently claimed, although
456 if you do it will be released automatically.
457
458 EXAMPLE
459
460         ...
461         kfree (dev->private); /* before we lose the pointer */
462         parport_unregister_device (dev);
463         ...
464
465 SEE ALSO
466
467 parport_unregister_driver
468 \f
469 parport_claim, parport_claim_or_block - claim the parallel port for a device
470 -------------------------------------
471
472 SYNOPSIS
473
474 #include <linux/parport.h>
475
476 int parport_claim (struct pardevice *dev);
477 int parport_claim_or_block (struct pardevice *dev);
478
479 DESCRIPTION
480
481 These functions attempt to gain control of the parallel port on which
482 'dev' is registered.  'parport_claim' does not block, but
483 'parport_claim_or_block' may do. (Put something here about blocking
484 interruptibly or non-interruptibly.)
485
486 You should not try to claim a port that you have already claimed.
487
488 RETURN VALUE
489
490 A return value of zero indicates that the port was successfully
491 claimed, and the caller now has possession of the parallel port.
492
493 If 'parport_claim_or_block' blocks before returning successfully, the
494 return value is positive.
495
496 ERRORS
497
498   -EAGAIN  The port is unavailable at the moment, but another attempt
499            to claim it may succeed.
500
501 SEE ALSO
502
503 parport_release
504 \f
505 parport_release - release the parallel port
506 ---------------
507
508 SYNOPSIS
509
510 #include <linux/parport.h>
511
512 void parport_release (struct pardevice *dev);
513
514 DESCRIPTION
515
516 Once a parallel port device has been claimed, it can be released using
517 'parport_release'.  It cannot fail, but you should not release a
518 device that you do not have possession of.
519
520 EXAMPLE
521
522 static size_t write (struct pardevice *dev, const void *buf,
523                      size_t len)
524 {
525         ...
526         written = dev->port->ops->write_ecp_data (dev->port, buf,
527                                                   len);
528         parport_release (dev);
529         ...
530 }
531
532
533 SEE ALSO
534
535 change_mode, parport_claim, parport_claim_or_block, parport_yield
536 \f
537 parport_yield, parport_yield_blocking - temporarily release a parallel port
538 -------------------------------------
539
540 SYNOPSIS
541
542 #include <linux/parport.h>
543
544 int parport_yield (struct pardevice *dev)
545 int parport_yield_blocking (struct pardevice *dev);
546
547 DESCRIPTION
548
549 When a driver has control of a parallel port, it may allow another
550 driver to temporarily 'borrow' it.  'parport_yield' does not block;
551 'parport_yield_blocking' may do.
552
553 RETURN VALUE
554
555 A return value of zero indicates that the caller still owns the port
556 and the call did not block.
557
558 A positive return value from 'parport_yield_blocking' indicates that
559 the caller still owns the port and the call blocked.
560
561 A return value of -EAGAIN indicates that the caller no longer owns the
562 port, and it must be re-claimed before use.
563
564 ERRORS
565
566   -EAGAIN  Ownership of the parallel port was given away.
567
568 SEE ALSO
569
570 parport_release
571 \f
572 parport_wait_peripheral - wait for status lines, up to 35ms
573 -----------------------
574
575 SYNOPSIS
576
577 #include <linux/parport.h>
578
579 int parport_wait_peripheral (struct parport *port,
580                              unsigned char mask,
581                              unsigned char val);
582
583 DESCRIPTION
584
585 Wait for the status lines in mask to match the values in val.
586
587 RETURN VALUE
588
589  -EINTR  a signal is pending
590       0  the status lines in mask have values in val
591       1  timed out while waiting (35ms elapsed)
592
593 SEE ALSO
594
595 parport_poll_peripheral
596 \f
597 parport_poll_peripheral - wait for status lines, in usec
598 -----------------------
599
600 SYNOPSIS
601
602 #include <linux/parport.h>
603
604 int parport_poll_peripheral (struct parport *port,
605                              unsigned char mask,
606                              unsigned char val,
607                              int usec);
608
609 DESCRIPTION
610
611 Wait for the status lines in mask to match the values in val.
612
613 RETURN VALUE
614
615  -EINTR  a signal is pending
616       0  the status lines in mask have values in val
617       1  timed out while waiting (usec microseconds have elapsed)
618
619 SEE ALSO
620
621 parport_wait_peripheral
622 \f
623 parport_wait_event - wait for an event on a port
624 ------------------
625
626 SYNOPSIS
627
628 #include <linux/parport.h>
629
630 int parport_wait_event (struct parport *port, signed long timeout)
631
632 DESCRIPTION
633
634 Wait for an event (e.g. interrupt) on a port.  The timeout is in
635 jiffies.
636
637 RETURN VALUE
638
639       0  success
640      <0  error (exit as soon as possible)
641      >0  timed out
642 \f
643 parport_negotiate - perform IEEE 1284 negotiation
644 -----------------
645
646 SYNOPSIS
647
648 #include <linux/parport.h>
649
650 int parport_negotiate (struct parport *, int mode);
651
652 DESCRIPTION
653
654 Perform IEEE 1284 negotiation.
655
656 RETURN VALUE
657
658      0  handshake OK; IEEE 1284 peripheral and mode available
659     -1  handshake failed; peripheral not compliant (or none present)
660      1  handshake OK; IEEE 1284 peripheral present but mode not
661         available
662
663 SEE ALSO
664
665 parport_read, parport_write
666 \f
667 parport_read - read data from device
668 ------------
669
670 SYNOPSIS
671
672 #include <linux/parport.h>
673
674 ssize_t parport_read (struct parport *, void *buf, size_t len);
675
676 DESCRIPTION
677
678 Read data from device in current IEEE 1284 transfer mode.  This only
679 works for modes that support reverse data transfer.
680
681 RETURN VALUE
682
683 If negative, an error code; otherwise the number of bytes transferred.
684
685 SEE ALSO
686
687 parport_write, parport_negotiate
688 \f
689 parport_write - write data to device
690 -------------
691
692 SYNOPSIS
693
694 #include <linux/parport.h>
695
696 ssize_t parport_write (struct parport *, const void *buf, size_t len);
697
698 DESCRIPTION
699
700 Write data to device in current IEEE 1284 transfer mode.  This only
701 works for modes that support forward data transfer.
702
703 RETURN VALUE
704
705 If negative, an error code; otherwise the number of bytes transferred.
706
707 SEE ALSO
708
709 parport_read, parport_negotiate
710 \f
711 parport_open - register device for particular device number
712 ------------
713
714 SYNOPSIS
715
716 #include <linux/parport.h>
717
718 struct pardevice *parport_open (int devnum, const char *name,
719                                 int (*pf) (void *),
720                                 void (*kf) (void *),
721                                 void (*irqf) (int, void *,
722                                               struct pt_regs *),
723                                 int flags, void *handle);
724
725 DESCRIPTION
726
727 This is like parport_register_device but takes a device number instead
728 of a pointer to a struct parport.
729
730 RETURN VALUE
731
732 See parport_register_device.  If no device is associated with devnum,
733 NULL is returned.
734
735 SEE ALSO
736
737 parport_register_device
738 \f
739 parport_close - unregister device for particular device number
740 -------------
741
742 SYNOPSIS
743
744 #include <linux/parport.h>
745
746 void parport_close (struct pardevice *dev);
747
748 DESCRIPTION
749
750 This is the equivalent of parport_unregister_device for parport_open.
751
752 SEE ALSO
753
754 parport_unregister_device, parport_open
755 \f
756 parport_device_id - obtain IEEE 1284 Device ID
757 -----------------
758
759 SYNOPSIS
760
761 #include <linux/parport.h>
762
763 ssize_t parport_device_id (int devnum, char *buffer, size_t len);
764
765 DESCRIPTION
766
767 Obtains the IEEE 1284 Device ID associated with a given device.
768
769 RETURN VALUE
770
771 If negative, an error code; otherwise, the number of bytes of buffer
772 that contain the device ID.  The format of the device ID is as
773 follows:
774
775 [length][ID]
776
777 The first two bytes indicate the inclusive length of the entire Device
778 ID, and are in big-endian order.  The ID is a sequence of pairs of the
779 form:
780
781 key:value;
782
783 NOTES
784
785 Many devices have ill-formed IEEE 1284 Device IDs.
786
787 SEE ALSO
788
789 parport_find_class, parport_find_device
790 \f
791 parport_device_coords - convert device number to device coordinates
792 ------------------
793
794 SYNOPSIS
795
796 #include <linux/parport.h>
797
798 int parport_device_coords (int devnum, int *parport, int *mux,
799                            int *daisy);
800
801 DESCRIPTION
802
803 Convert between device number (zero-based) and device coordinates
804 (port, multiplexor, daisy chain address).
805
806 RETURN VALUE
807
808 Zero on success, in which case the coordinates are (*parport, *mux,
809 *daisy).
810
811 SEE ALSO
812
813 parport_open, parport_device_id
814 \f
815 parport_find_class - find a device by its class
816 ------------------
817
818 SYNOPSIS
819
820 #include <linux/parport.h>
821
822 typedef enum {
823         PARPORT_CLASS_LEGACY = 0,       /* Non-IEEE1284 device */
824         PARPORT_CLASS_PRINTER,
825         PARPORT_CLASS_MODEM,
826         PARPORT_CLASS_NET,
827         PARPORT_CLASS_HDC,              /* Hard disk controller */
828         PARPORT_CLASS_PCMCIA,
829         PARPORT_CLASS_MEDIA,            /* Multimedia device */
830         PARPORT_CLASS_FDC,              /* Floppy disk controller */
831         PARPORT_CLASS_PORTS,
832         PARPORT_CLASS_SCANNER,
833         PARPORT_CLASS_DIGCAM,
834         PARPORT_CLASS_OTHER,            /* Anything else */
835         PARPORT_CLASS_UNSPEC,           /* No CLS field in ID */
836         PARPORT_CLASS_SCSIADAPTER
837 } parport_device_class;
838
839 int parport_find_class (parport_device_class cls, int from);
840
841 DESCRIPTION
842
843 Find a device by class.  The search starts from device number from+1.
844
845 RETURN VALUE
846
847 The device number of the next device in that class, or -1 if no such
848 device exists.
849
850 NOTES
851
852 Example usage:
853
854 int devnum = -1;
855 while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM, devnum)) != -1) {
856     struct pardevice *dev = parport_open (devnum, ...);
857     ...
858 }
859
860 SEE ALSO
861
862 parport_find_device, parport_open, parport_device_id
863 \f
864 parport_find_device - find a device by its class
865 ------------------
866
867 SYNOPSIS
868
869 #include <linux/parport.h>
870
871 int parport_find_device (const char *mfg, const char *mdl, int from);
872
873 DESCRIPTION
874
875 Find a device by vendor and model.  The search starts from device
876 number from+1.
877
878 RETURN VALUE
879
880 The device number of the next device matching the specifications, or
881 -1 if no such device exists.
882
883 NOTES
884
885 Example usage:
886
887 int devnum = -1;
888 while ((devnum = parport_find_device ("IOMEGA", "ZIP+", devnum)) != -1) {
889     struct pardevice *dev = parport_open (devnum, ...);
890     ...
891 }
892
893 SEE ALSO
894
895 parport_find_class, parport_open, parport_device_id
896 \f
897 parport_set_timeout - set the inactivity timeout
898 -------------------
899
900 SYNOPSIS
901
902 #include <linux/parport.h>
903
904 long parport_set_timeout (struct pardevice *dev, long inactivity);
905
906 DESCRIPTION
907
908 Set the inactivity timeout, in jiffies, for a registered device.  The
909 previous timeout is returned.
910
911 RETURN VALUE
912
913 The previous timeout, in jiffies.
914
915 NOTES
916
917 Some of the port->ops functions for a parport may take time, owing to
918 delays at the peripheral.  After the peripheral has not responded for
919 'inactivity' jiffies, a timeout will occur and the blocking function
920 will return.
921
922 A timeout of 0 jiffies is a special case: the function must do as much
923 as it can without blocking or leaving the hardware in an unknown
924 state.  If port operations are performed from within an interrupt
925 handler, for instance, a timeout of 0 jiffies should be used.
926
927 Once set for a registered device, the timeout will remain at the set
928 value until set again.
929
930 SEE ALSO
931
932 port->ops->xxx_read/write_yyy
933 \f
934 PORT FUNCTIONS
935 --------------
936
937 The functions in the port->ops structure (struct parport_operations)
938 are provided by the low-level driver responsible for that port.
939
940 port->ops->read_data - read the data register
941 --------------------
942
943 SYNOPSIS
944
945 #include <linux/parport.h>
946
947 struct parport_operations {
948         ...
949         unsigned char (*read_data) (struct parport *port);
950         ...
951 };
952
953 DESCRIPTION
954
955 If port->modes contains the PARPORT_MODE_TRISTATE flag and the
956 PARPORT_CONTROL_DIRECTION bit in the control register is set, this
957 returns the value on the data pins.  If port->modes contains the
958 PARPORT_MODE_TRISTATE flag and the PARPORT_CONTROL_DIRECTION bit is
959 not set, the return value _may_ be the last value written to the data
960 register.  Otherwise the return value is undefined.
961
962 SEE ALSO
963
964 write_data, read_status, write_control
965 \f
966 port->ops->write_data - write the data register
967 ---------------------
968
969 SYNOPSIS
970
971 #include <linux/parport.h>
972
973 struct parport_operations {
974         ...
975         void (*write_data) (struct parport *port, unsigned char d);
976         ...
977 };
978
979 DESCRIPTION
980
981 Writes to the data register.  May have side-effects (a STROBE pulse,
982 for instance).
983
984 SEE ALSO
985
986 read_data, read_status, write_control
987 \f
988 port->ops->read_status - read the status register
989 ----------------------
990
991 SYNOPSIS
992
993 #include <linux/parport.h>
994
995 struct parport_operations {
996         ...
997         unsigned char (*read_status) (struct parport *port);
998         ...
999 };
1000
1001 DESCRIPTION
1002
1003 Reads from the status register.  This is a bitmask:
1004
1005 - PARPORT_STATUS_ERROR (printer fault, "nFault")
1006 - PARPORT_STATUS_SELECT (on-line, "Select")
1007 - PARPORT_STATUS_PAPEROUT (no paper, "PError")
1008 - PARPORT_STATUS_ACK (handshake, "nAck")
1009 - PARPORT_STATUS_BUSY (busy, "Busy")
1010
1011 There may be other bits set.
1012
1013 SEE ALSO
1014
1015 read_data, write_data, write_control
1016 \f
1017 port->ops->read_control - read the control register
1018 -----------------------
1019
1020 SYNOPSIS
1021
1022 #include <linux/parport.h>
1023
1024 struct parport_operations {
1025         ...
1026         unsigned char (*read_control) (struct parport *port);
1027         ...
1028 };
1029
1030 DESCRIPTION
1031
1032 Returns the last value written to the control register (either from
1033 write_control or frob_control).  No port access is performed.
1034
1035 SEE ALSO
1036
1037 read_data, write_data, read_status, write_control
1038 \f
1039 port->ops->write_control - write the control register
1040 ------------------------
1041
1042 SYNOPSIS
1043
1044 #include <linux/parport.h>
1045
1046 struct parport_operations {
1047         ...
1048         void (*write_control) (struct parport *port, unsigned char s);
1049         ...
1050 };
1051
1052 DESCRIPTION
1053
1054 Writes to the control register. This is a bitmask:
1055                           _______
1056 - PARPORT_CONTROL_STROBE (nStrobe)
1057                           _______
1058 - PARPORT_CONTROL_AUTOFD (nAutoFd)
1059                         _____
1060 - PARPORT_CONTROL_INIT (nInit)
1061                           _________
1062 - PARPORT_CONTROL_SELECT (nSelectIn)
1063
1064 SEE ALSO
1065
1066 read_data, write_data, read_status, frob_control
1067 \f
1068 port->ops->frob_control - write control register bits
1069 -----------------------
1070
1071 SYNOPSIS
1072
1073 #include <linux/parport.h>
1074
1075 struct parport_operations {
1076         ...
1077         unsigned char (*frob_control) (struct parport *port,
1078                                        unsigned char mask,
1079                                        unsigned char val);
1080         ...
1081 };
1082
1083 DESCRIPTION
1084
1085 This is equivalent to reading from the control register, masking out
1086 the bits in mask, exclusive-or'ing with the bits in val, and writing
1087 the result to the control register.
1088
1089 As some ports don't allow reads from the control port, a software copy
1090 of its contents is maintained, so frob_control is in fact only one
1091 port access.
1092
1093 SEE ALSO
1094
1095 read_data, write_data, read_status, write_control
1096 \f
1097 port->ops->enable_irq - enable interrupt generation
1098 ---------------------
1099
1100 SYNOPSIS
1101
1102 #include <linux/parport.h>
1103
1104 struct parport_operations {
1105         ...
1106         void (*enable_irq) (struct parport *port);
1107         ...
1108 };
1109
1110 DESCRIPTION
1111
1112 The parallel port hardware is instructed to generate interrupts at
1113 appropriate moments, although those moments are
1114 architecture-specific.  For the PC architecture, interrupts are
1115 commonly generated on the rising edge of nAck.
1116
1117 SEE ALSO
1118
1119 disable_irq
1120 \f
1121 port->ops->disable_irq - disable interrupt generation
1122 ----------------------
1123
1124 SYNOPSIS
1125
1126 #include <linux/parport.h>
1127
1128 struct parport_operations {
1129         ...
1130         void (*disable_irq) (struct parport *port);
1131         ...
1132 };
1133
1134 DESCRIPTION
1135
1136 The parallel port hardware is instructed not to generate interrupts.
1137 The interrupt itself is not masked.
1138
1139 SEE ALSO
1140
1141 enable_irq
1142 \f
1143 port->ops->data_forward - enable data drivers
1144 -----------------------
1145
1146 SYNOPSIS
1147
1148 #include <linux/parport.h>
1149
1150 struct parport_operations {
1151         ...
1152         void (*data_forward) (struct parport *port);
1153         ...
1154 };
1155
1156 DESCRIPTION
1157
1158 Enables the data line drivers, for 8-bit host-to-peripheral
1159 communications.
1160
1161 SEE ALSO
1162
1163 data_reverse
1164 \f
1165 port->ops->data_reverse - tristate the buffer
1166 -----------------------
1167
1168 SYNOPSIS
1169
1170 #include <linux/parport.h>
1171
1172 struct parport_operations {
1173         ...
1174         void (*data_reverse) (struct parport *port);
1175         ...
1176 };
1177
1178 DESCRIPTION
1179
1180 Places the data bus in a high impedance state, if port->modes has the
1181 PARPORT_MODE_TRISTATE bit set.
1182
1183 SEE ALSO
1184
1185 data_forward
1186 \f
1187 port->ops->epp_write_data - write EPP data
1188 -------------------------
1189
1190 SYNOPSIS
1191
1192 #include <linux/parport.h>
1193
1194 struct parport_operations {
1195         ...
1196         size_t (*epp_write_data) (struct parport *port, const void *buf,
1197                                   size_t len, int flags);
1198         ...
1199 };
1200
1201 DESCRIPTION
1202
1203 Writes data in EPP mode, and returns the number of bytes written.
1204
1205 The 'flags' parameter may be one or more of the following,
1206 bitwise-or'ed together:
1207
1208 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1209                         32-bit registers.  However, if a transfer
1210                         times out, the return value may be unreliable.
1211
1212 SEE ALSO
1213
1214 epp_read_data, epp_write_addr, epp_read_addr
1215 \f
1216 port->ops->epp_read_data - read EPP data
1217 ------------------------
1218
1219 SYNOPSIS
1220
1221 #include <linux/parport.h>
1222
1223 struct parport_operations {
1224         ...
1225         size_t (*epp_read_data) (struct parport *port, void *buf,
1226                                  size_t len, int flags);
1227         ...
1228 };
1229
1230 DESCRIPTION
1231
1232 Reads data in EPP mode, and returns the number of bytes read.
1233
1234 The 'flags' parameter may be one or more of the following,
1235 bitwise-or'ed together:
1236
1237 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1238                         32-bit registers.  However, if a transfer
1239                         times out, the return value may be unreliable.
1240
1241 SEE ALSO
1242
1243 epp_write_data, epp_write_addr, epp_read_addr
1244 \f
1245 port->ops->epp_write_addr - write EPP address
1246 -------------------------
1247
1248 SYNOPSIS
1249
1250 #include <linux/parport.h>
1251
1252 struct parport_operations {
1253         ...
1254         size_t (*epp_write_addr) (struct parport *port,
1255                                   const void *buf, size_t len, int flags);
1256         ...
1257 };
1258
1259 DESCRIPTION
1260
1261 Writes EPP addresses (8 bits each), and returns the number written.
1262
1263 The 'flags' parameter may be one or more of the following,
1264 bitwise-or'ed together:
1265
1266 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1267                         32-bit registers.  However, if a transfer
1268                         times out, the return value may be unreliable.
1269
1270 (Does PARPORT_EPP_FAST make sense for this function?)
1271
1272 SEE ALSO
1273
1274 epp_write_data, epp_read_data, epp_read_addr
1275 \f
1276 port->ops->epp_read_addr - read EPP address
1277 ------------------------
1278
1279 SYNOPSIS
1280
1281 #include <linux/parport.h>
1282
1283 struct parport_operations {
1284         ...
1285         size_t (*epp_read_addr) (struct parport *port, void *buf,
1286                                  size_t len, int flags);
1287         ...
1288 };
1289
1290 DESCRIPTION
1291
1292 Reads EPP addresses (8 bits each), and returns the number read.
1293
1294 The 'flags' parameter may be one or more of the following,
1295 bitwise-or'ed together:
1296
1297 PARPORT_EPP_FAST        Use fast transfers. Some chips provide 16-bit and
1298                         32-bit registers.  However, if a transfer
1299                         times out, the return value may be unreliable.
1300
1301 (Does PARPORT_EPP_FAST make sense for this function?)
1302
1303 SEE ALSO
1304
1305 epp_write_data, epp_read_data, epp_write_addr
1306 \f
1307 port->ops->ecp_write_data - write a block of ECP data
1308 -------------------------
1309
1310 SYNOPSIS
1311
1312 #include <linux/parport.h>
1313
1314 struct parport_operations {
1315         ...
1316         size_t (*ecp_write_data) (struct parport *port,
1317                                   const void *buf, size_t len, int flags);
1318         ...
1319 };
1320
1321 DESCRIPTION
1322
1323 Writes a block of ECP data.  The 'flags' parameter is ignored.
1324
1325 RETURN VALUE
1326
1327 The number of bytes written.
1328
1329 SEE ALSO
1330
1331 ecp_read_data, ecp_write_addr
1332 \f
1333 port->ops->ecp_read_data - read a block of ECP data
1334 ------------------------
1335
1336 SYNOPSIS
1337
1338 #include <linux/parport.h>
1339
1340 struct parport_operations {
1341         ...
1342         size_t (*ecp_read_data) (struct parport *port,
1343                                  void *buf, size_t len, int flags);
1344         ...
1345 };
1346
1347 DESCRIPTION
1348
1349 Reads a block of ECP data.  The 'flags' parameter is ignored.
1350
1351 RETURN VALUE
1352
1353 The number of bytes read.  NB. There may be more unread data in a
1354 FIFO.  Is there a way of stunning the FIFO to prevent this?
1355
1356 SEE ALSO
1357
1358 ecp_write_block, ecp_write_addr
1359 \f
1360 port->ops->ecp_write_addr - write a block of ECP addresses
1361 -------------------------
1362
1363 SYNOPSIS
1364
1365 #include <linux/parport.h>
1366
1367 struct parport_operations {
1368         ...
1369         size_t (*ecp_write_addr) (struct parport *port,
1370                                   const void *buf, size_t len, int flags);
1371         ...
1372 };
1373
1374 DESCRIPTION
1375
1376 Writes a block of ECP addresses.  The 'flags' parameter is ignored.
1377
1378 RETURN VALUE
1379
1380 The number of bytes written.
1381
1382 NOTES
1383
1384 This may use a FIFO, and if so shall not return until the FIFO is empty.
1385
1386 SEE ALSO
1387
1388 ecp_read_data, ecp_write_data
1389 \f
1390 port->ops->nibble_read_data - read a block of data in nibble mode
1391 ---------------------------
1392
1393 SYNOPSIS
1394
1395 #include <linux/parport.h>
1396
1397 struct parport_operations {
1398         ...
1399         size_t (*nibble_read_data) (struct parport *port,
1400                                     void *buf, size_t len, int flags);
1401         ...
1402 };
1403
1404 DESCRIPTION
1405
1406 Reads a block of data in nibble mode.  The 'flags' parameter is ignored.
1407
1408 RETURN VALUE
1409
1410 The number of whole bytes read.
1411
1412 SEE ALSO
1413
1414 byte_read_data, compat_write_data
1415 \f
1416 port->ops->byte_read_data - read a block of data in byte mode
1417 -------------------------
1418
1419 SYNOPSIS
1420
1421 #include <linux/parport.h>
1422
1423 struct parport_operations {
1424         ...
1425         size_t (*byte_read_data) (struct parport *port,
1426                                   void *buf, size_t len, int flags);
1427         ...
1428 };
1429
1430 DESCRIPTION
1431
1432 Reads a block of data in byte mode.  The 'flags' parameter is ignored.
1433
1434 RETURN VALUE
1435
1436 The number of bytes read.
1437
1438 SEE ALSO
1439
1440 nibble_read_data, compat_write_data
1441 \f
1442 port->ops->compat_write_data - write a block of data in compatibility mode
1443 ----------------------------
1444
1445 SYNOPSIS
1446
1447 #include <linux/parport.h>
1448
1449 struct parport_operations {
1450         ...
1451         size_t (*compat_write_data) (struct parport *port,
1452                                      const void *buf, size_t len, int flags);
1453         ...
1454 };
1455
1456 DESCRIPTION
1457
1458 Writes a block of data in compatibility mode.  The 'flags' parameter
1459 is ignored.
1460
1461 RETURN VALUE
1462
1463 The number of bytes written.
1464
1465 SEE ALSO
1466
1467 nibble_read_data, byte_read_data