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