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