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