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