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