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