Root/Documentation/parport-lowlevel.txt

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

Archive Download this file



interactive