2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[]>
4 <book id="ParportGuide">
6 <title>The Linux 2.4 Parallel Port Subsystem</title>
10 <firstname>Tim</firstname>
11 <surname>Waugh</surname>
14 <email>twaugh@redhat.com</email>
21 <year>1999-2000</year>
22 <holder>Tim Waugh</holder>
27 Permission is granted to copy, distribute and/or modify this
28 document under the terms of the GNU Free Documentation License,
29 Version 1.1 or any later version published by the Free Software
30 Foundation; with no Invariant Sections, with no Front-Cover Texts,
31 and with no Back-Cover Texts. A copy of the license is included
32 in the section entitled "GNU Free Documentation License".
40 <title>Design goals</title>
43 <title>The problems</title>
46 The first parallel port support for Linux came with the line
47 printer driver, <literal>lp</literal>. The printer driver is a
48 character special device, and (in Linux 2.0) had support for
49 writing, via <function>write</function>, and configuration and
50 statistics reporting via <function>ioctl</function>.
54 The printer driver could be used on any computer that had an IBM
55 PC-compatible parallel port. Because some architectures have
56 parallel ports that aren't really the same as PC-style ports,
57 other variants of the printer driver were written in order to
58 support Amiga and Atari parallel ports.
62 When the Iomega Zip drive was released, and a driver written for
63 it, a problem became apparent. The Zip drive is a parallel port
64 device that provides a parallel port of its own---it is designed
65 to sit between a computer and an attached printer, with the
66 printer plugged into the Zip drive, and the Zip drive plugged into
71 The problem was that, although printers and Zip drives were both
72 supported, for any given port only one could be used at a time.
73 Only one of the two drivers could be present in the kernel at
74 once. This was because of the fact that both drivers wanted to
75 drive the same hardware---the parallel port. When the printer
76 driver initialised, it would call the
77 <function>check_region</function> function to make sure that the
78 IO region associated with the parallel port was free, and then it
79 would call <function>request_region</function> to allocate it.
80 The Zip drive used the same mechanism. Whichever driver
81 initialised first would gain exclusive control of the parallel
86 The only way around this problem at the time was to make sure that
87 both drivers were available as loadable kernel modules. To use
88 the printer, load the printer driver module; then for the Zip
89 drive, unload the printer driver module and load the Zip driver
94 The net effect was that printing a document that was stored on a
95 Zip drive was a bit of an ordeal, at least if the Zip drive and
96 printer shared a parallel port. A better solution was
101 Zip drives are not the only devices that presented problems for
102 Linux. There are other devices with pass-through ports, for
103 example parallel port CD-ROM drives. There are also printers that
104 report their status textually rather than using simple error pins:
105 sending a command to the printer can cause it to report the number
106 of pages that it has ever printed, or how much free memory it has,
107 or whether it is running out of toner, and so on. The printer
108 driver didn't originally offer any facility for reading back this
109 information (although Carsten Gross added nibble mode readback
110 support for kernel 2.2).
114 The IEEE has issued a standards document called IEEE 1284, which
115 documents existing practice for parallel port communications in a
116 variety of modes. Those modes are: <quote>compatibility</quote>,
117 reverse nibble, reverse byte, ECP and EPP. Newer devices often
118 use the more advanced modes of transfer (ECP and EPP). In Linux
119 2.0, the printer driver only supported <quote>compatibility
120 mode</quote> (i.e. normal printer protocol) and reverse nibble
127 <title>The solutions</title>
129 <!-- How they are addressed
131 - overview of structure (i.e. port drivers) in 2.2 and 2.3.
133 - whether or not 'platform independence' goal was met
137 The <literal>parport</literal> code in Linux 2.2 was designed to
138 meet these problems of architectural differences in parallel
139 ports, of port-sharing between devices with pass-through ports,
140 and of lack of support for IEEE 1284 transfer modes.
143 <!-- platform differences -->
146 There are two layers to the <literal>parport</literal>
147 subsystem, only one of which deals directly with the hardware.
148 The other layer deals with sharing and IEEE 1284 transfer modes.
149 In this way, parallel support for a particular architecture comes
150 in the form of a module which registers itself with the generic
154 <!-- sharing model -->
157 The sharing model provided by the <literal>parport</literal>
158 subsystem is one of exclusive access. A device driver, such as
159 the printer driver, must ask the <literal>parport</literal>
160 layer for access to the port, and can only use the port once
161 access has been granted. When it has finished a
162 <quote>transaction</quote>, it can tell the
163 <literal>parport</literal> layer that it may release the port
164 for other device drivers to use.
167 <!-- talk a bit about how drivers can share devices on the same port -->
170 Devices with pass-through ports all manage to share a parallel
171 port with other devices in generally the same way. The device has
172 a latch for each of the pins on its pass-through port. The normal
173 state of affairs is pass-through mode, with the device copying the
174 signal lines between its host port and its pass-through port.
175 When the device sees a special signal from the host port, it
176 latches the pass-through port so that devices further downstream
177 don't get confused by the pass-through device's conversation with
178 the host parallel port: the device connected to the pass-through
179 port (and any devices connected in turn to it) are effectively cut
180 off from the computer. When the pass-through device has completed
181 its transaction with the computer, it enables the pass-through
187 <imagedata fileref="parport-share" format="eps">
190 <imagedata fileref="parport-share.png" format="png">
195 This technique relies on certain <quote>special signals</quote>
196 being invisible to devices that aren't watching for them. This
197 tends to mean only changing the data signals and leaving the
198 control signals alone. IEEE 1284.3 documents a standard protocol
199 for daisy-chaining devices together with parallel ports.
202 <!-- transfer modes -->
205 Support for standard transfer modes are provided as operations
206 that can be performed on a port, along with operations for setting
207 the data lines, or the control lines, or reading the status lines.
208 These operations appear to the device driver as function pointers;
216 <chapter id="transfermodes">
217 <title>Standard transfer modes</title>
219 <!-- Defined by IEEE, but in common use (even though there are widely -->
220 <!-- varying implementations). -->
223 The <quote>standard</quote> transfer modes in use over the parallel
224 port are <quote>defined</quote> by a document called IEEE 1284. It
225 really just codifies existing practice and documents protocols (and
226 variations on protocols) that have been in common use for quite
231 The original definitions of which pin did what were set out by
232 Centronics Data Computer Corporation, but only the printer-side
233 interface signals were specified.
237 By the early 1980s, IBM's host-side implementation had become the
238 most widely used. New printers emerged that claimed Centronics
239 compatibility, but although compatible with Centronics they
240 differed from one another in a number of ways.
244 As a result of this, when IEEE 1284 was published in 1994, all that
245 it could really do was document the various protocols that are used
246 for printers (there are about six variations on a theme).
250 In addition to the protocol used to talk to Centronics-compatible
251 printers, IEEE 1284 defined other protocols that are used for
252 unidirectional peripheral-to-host transfers (reverse nibble and
253 reverse byte) and for fast bidirectional transfers (ECP and
259 <chapter id="structure">
260 <title>Structure</title>
264 - parports and their IEEE 1284 overrides
265 - IEEE 1284 transfer modes for generic ports
266 - maybe mention muxes here
273 <imagedata fileref="parport-structure" format="eps">
276 <imagedata fileref="parport-structure.png" format="png">
281 <title>Sharing core</title>
284 At the core of the <literal>parport</literal> subsystem is the
285 sharing mechanism (see
286 <filename>drivers/parport/share.c</filename>). This module,
287 <literal>parport</literal>, is responsible for keeping track of
288 which ports there are in the system, which device drivers might be
289 interested in new ports, and whether or not each port is available
290 for use (or if not, which driver is currently using it).
296 <title>Parports and their overrides</title>
299 The generic <literal>parport</literal> sharing code doesn't
300 directly handle the parallel port hardware. That is done instead
301 by <quote>low-level</quote> <literal>parport</literal> drivers.
302 The function of a low-level <literal>parport</literal> driver is
303 to detect parallel ports, register them with the sharing code, and
304 provide a list of access functions for each port.
308 The most basic access functions that must be provided are ones for
309 examining the status lines, for setting the control lines, and for
310 setting the data lines. There are also access functions for
311 setting the direction of the data lines; normally they are in the
312 <quote>forward</quote> direction (that is, the computer drives
313 them), but some ports allow switching to <quote>reverse</quote>
314 mode (driven by the peripheral). There is an access function for
315 examining the data lines once in reverse mode.
321 <title>IEEE 1284 transfer modes</title>
324 Stacked on top of the sharing mechanism, but still in the
325 <literal>parport</literal> module, are functions for
326 transferring data. They are provided for the device drivers to
327 use, and are very much like library routines. Since these
328 transfer functions are provided by the generic
329 <literal>parport</literal> core they must use the <quote>lowest
330 common denominator</quote> set of access functions: they can set
331 the control lines, examine the status lines, and use the data
332 lines. With some parallel ports the data lines can only be set
333 and not examined, and with other ports accessing the data register
334 causes control line activity; with these types of situations, the
335 IEEE 1284 transfer functions make a best effort attempt to do the
336 right thing. In some cases, it is not physically possible to use
337 particular IEEE 1284 transfer modes.
341 The low-level <literal>parport</literal> drivers also provide
342 IEEE 1284 transfer functions, as names in the access function
343 list. The low-level driver can just name the generic IEEE 1284
344 transfer functions for this. Some parallel ports can do IEEE 1284
345 transfers in hardware; for those ports, the low-level driver can
346 provide functions to utilise that feature.
354 <title>Pardevices and parport_drivers</title>
357 When a parallel port device driver (such as
358 <literal>lp</literal>) initialises it tells the sharing layer
359 about itself using <function>parport_register_driver</function>.
360 The information is put into a <structname>struct
361 parport_driver</structname>, which is put into a linked list. The
362 information in a <structname>struct parport_driver</structname>
363 really just amounts to some function pointers to callbacks in the
364 parallel port device driver.
368 During its initialisation, a low-level port driver tells the
369 sharing layer about all the ports that it has found (using
370 <function>parport_register_port</function>), and the sharing layer
371 creates a <structname>struct parport</structname> for each of
372 them. Each <structname>struct parport</structname> contains
373 (among other things) a pointer to a <structname>struct
374 parport_operations</structname>, which is a list of function
375 pointers for the various operations that can be performed on a
376 port. You can think of a <structname>struct parport</structname>
377 as a parallel port <quote>object</quote>, if
378 <quote>object-orientated</quote> programming is your thing. The
379 <structname>parport</structname> structures are chained in a
380 linked list, whose head is <varname>portlist</varname> (in
381 <filename>drivers/parport/share.c</filename>).
385 Once the port has been registered, the low-level port driver
386 announces it. The <function>parport_announce_port</function>
387 function walks down the list of parallel port device drivers
388 (<structname>struct parport_driver</structname>s) calling the
389 <function>attach</function> function of each (which may block).
393 Similarly, a low-level port driver can undo the effect of
394 registering a port with the
395 <function>parport_unregister_port</function> function, and device
396 drivers are notified using the <function>detach</function>
397 callback (which may not block).
401 Device drivers can undo the effect of registering themselves with
402 the <function>parport_unregister_driver</function>
408 <!-- IEEE 1284.3 API -->
411 <title>The IEEE 1284.3 API</title>
414 The ability to daisy-chain devices is very useful, but if every
415 device does it in a different way it could lead to lots of
416 complications for device driver writers. Fortunately, the IEEE
417 are standardising it in IEEE 1284.3, which covers daisy-chain
418 devices and port multiplexors.
422 At the time of writing, IEEE 1284.3 has not been published, but
423 the draft specifies the on-the-wire protocol for daisy-chaining
424 and multiplexing, and also suggests a programming interface for
425 using it. That interface (or most of it) has been implemented in
426 the <literal>parport</literal> code in Linux.
430 At initialisation of the parallel port <quote>bus</quote>,
431 daisy-chained devices are assigned addresses starting from zero.
432 There can only be four devices with daisy-chain addresses, plus
433 one device on the end that doesn't know about daisy-chaining and
434 thinks it's connected directly to a computer.
438 Another way of connecting more parallel port devices is to use a
439 multiplexor. The idea is to have a device that is connected
440 directly to a parallel port on a computer, but has a number of
441 parallel ports on the other side for other peripherals to connect
442 to (two or four ports are allowed). The multiplexor switches
443 control to different ports under software control---it is, in
444 effect, a programmable printer switch.
448 Combining the ability of daisy-chaining five devices together with
449 the ability to multiplex one parallel port between four gives the
450 potential to have twenty peripherals connected to the same
455 In addition, of course, a single computer can have multiple
456 parallel ports. So, each parallel port peripheral in the system
457 can be identified with three numbers, or co-ordinates: the
458 parallel port, the multiplexed port, and the daisy-chain
464 <imagedata fileref="parport-multi" format="eps">
467 <imagedata fileref="parport-multi.png" format="png">
472 Each device in the system is numbered at initialisation (by
473 <function>parport_daisy_init</function>). You can convert between
474 this device number and its co-ordinates with
475 <function>parport_device_num</function> and
476 <function>parport_device_coords</function>.
481 #include <parport.h>
484 <funcdef>int <function>parport_device_num</function></funcdef>
485 <paramdef>int <parameter>parport</parameter></paramdef>
486 <paramdef>int <parameter>mux</parameter></paramdef>
487 <paramdef>int <parameter>daisy</parameter></paramdef>
493 <funcdef>int <function>parport_device_coords</function></funcdef>
494 <paramdef>int <parameter>devnum</parameter></paramdef>
495 <paramdef>int *<parameter>parport</parameter></paramdef>
496 <paramdef>int *<parameter>mux</parameter></paramdef>
497 <paramdef>int *<parameter>daisy</parameter></paramdef>
502 Any parallel port peripheral will be connected directly or
503 indirectly to a parallel port on the system, but it won't have a
504 daisy-chain address if it does not know about daisy-chaining, and
505 it won't be connected through a multiplexor port if there is no
506 multiplexor. The special co-ordinate value
507 <constant>-1</constant> is used to indicate these cases.
511 Two functions are provided for finding devices based on their IEEE
512 1284 Device ID: <function>parport_find_device</function> and
513 <function>parport_find_class</function>.
518 #include <parport.h>
521 <funcdef>int <function>parport_find_device</function></funcdef>
522 <paramdef>const char *<parameter>mfg</parameter></paramdef>
523 <paramdef>const char *<parameter>mdl</parameter></paramdef>
524 <paramdef>int <parameter>from</parameter></paramdef>
530 <funcdef>int <function>parport_find_class</function></funcdef>
531 <paramdef>parport_device_class <parameter>cls</parameter></paramdef>
532 <paramdef>int <parameter>from</parameter></paramdef>
537 These functions take a device number (in addition to some other
538 things), and return another device number. They walk through the
539 list of detected devices until they find one that matches the
540 requirements, and then return that device number (or
541 <constant>-1</constant> if there are no more such devices). They
542 start their search at the device after the one in the list with
543 the number given (at <parameter>from</parameter>+1, in other
551 <chapter id="drivers">
552 <title>Device driver's view</title>
555 - sharing interface, preemption, interrupts, wakeups...
556 - IEEE 1284.3 interface
558 - why can read data but ctr is faked, etc.
561 <!-- I should take a look at the kernel hackers' guide bit I wrote, -->
562 <!-- as that deals with a lot of this. The main complaint with it -->
563 <!-- was that there weren't enough examples, but 'The printer -->
564 <!-- driver' should deal with that later; might be worth mentioning -->
565 <!-- in the text. -->
568 This section is written from the point of view of the device driver
569 programmer, who might be writing a driver for a printer or a
570 scanner or else anything that plugs into the parallel port. It
571 explains how to use the <literal>parport</literal> interface to
572 find parallel ports, use them, and share them with other device
577 We'll start out with a description of the various functions that
578 can be called, and then look at a reasonably simple example of
579 their use: the printer driver.
583 The interactions between the device driver and the
584 <literal>parport</literal> layer are as follows. First, the
585 device driver registers its existence with
586 <literal>parport</literal>, in order to get told about any
587 parallel ports that have been (or will be) detected. When it gets
588 told about a parallel port, it then tells
589 <literal>parport</literal> that it wants to drive a device on
590 that port. Thereafter it can claim exclusive access to the port in
591 order to talk to its device.
595 So, the first thing for the device driver to do is tell
596 <literal>parport</literal> that it wants to know what parallel
597 ports are on the system. To do this, it uses the
598 <function>parport_register_driver</function> function:
603 #include <parport.h>
605 struct parport_driver {
607 void (*attach) (struct parport *);
608 void (*detach) (struct parport *);
609 struct parport_driver *next;
614 <funcdef>int <function>parport_register_driver</function></funcdef>
615 <paramdef>struct parport_driver *<parameter>driver</parameter></paramdef>
620 In other words, the device driver passes pointers to a couple of
621 functions to <literal>parport</literal>, and
622 <literal>parport</literal> calls <function>attach</function> for
623 each port that's detected (and <function>detach</function> for each
624 port that disappears---yes, this can happen).
628 The next thing that happens is that the device driver tells
629 <literal>parport</literal> that it thinks there's a device on the
630 port that it can drive. This typically will happen in the driver's
631 <function>attach</function> function, and is done with
632 <function>parport_register_device</function>:
637 #include <parport.h>
640 <funcdef>struct pardevice *<function>parport_register_device</function></funcdef>
641 <paramdef>struct parport *<parameter>port</parameter></paramdef>
642 <paramdef>const char *<parameter>name</parameter></paramdef>
643 <paramdef>int <parameter>(*pf)</parameter>
644 <funcparams>void *</funcparams></paramdef>
645 <paramdef>void <parameter>(*kf)</parameter>
646 <funcparams>void *</funcparams></paramdef>
647 <paramdef>void <parameter>(*irq_func)</parameter>
648 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
649 <paramdef>int <parameter>flags</parameter></paramdef>
650 <paramdef>void *<parameter>handle</parameter></paramdef>
655 The <parameter>port</parameter> comes from the parameter supplied
656 to the <function>attach</function> function when it is called, or
657 alternatively can be found from the list of detected parallel ports
658 directly with the (now deprecated)
659 <function>parport_enumerate</function> function. A better way of
660 doing this is with <function>parport_find_number</function> or
661 <function>parport_find_base</function> functions, which find ports
662 by number and by base I/O address respectively.
667 #include <parport.h>
670 <funcdef>struct parport *<function>parport_find_number</function></funcdef>
671 <paramdef>int <parameter>number</parameter></paramdef>
676 #include <parport.h>
679 <funcdef>struct parport *<function>parport_find_base</function></funcdef>
680 <paramdef>unsigned long <parameter>base</parameter></paramdef>
685 The next three parameters, <parameter>pf</parameter>,
686 <parameter>kf</parameter>, and <parameter>irq_func</parameter>, are
687 more function pointers. These callback functions get called under
688 various circumstances, and are always given the
689 <parameter>handle</parameter> as one of their parameters.
693 The preemption callback, <parameter>pf</parameter>, is called when
694 the driver has claimed access to the port but another device driver
695 wants access. If the driver is willing to let the port go, it
696 should return zero and the port will be released on its behalf.
697 There is no need to call <function>parport_release</function>. If
698 <parameter>pf</parameter> gets called at a bad time for letting the
699 port go, it should return non-zero and no action will be taken. It
700 is good manners for the driver to try to release the port at the
701 earliest opportunity after its preemption callback is
706 The <quote>kick</quote> callback, <parameter>kf</parameter>, is
707 called when the port can be claimed for exclusive access; that is,
708 <function>parport_claim</function> is guaranteed to succeed inside
709 the <quote>kick</quote> callback. If the driver wants to claim the
710 port it should do so; otherwise, it need not take any
715 The <parameter>irq_func</parameter> callback is called,
716 predictably, when a parallel port interrupt is generated. But it
717 is not the only code that hooks on the interrupt. The sequence is
718 this: the lowlevel driver is the one that has done
719 <function>request_irq</function>; it then does whatever
720 hardware-specific things it needs to do to the parallel port
721 hardware (for PC-style ports, there is nothing special to do); it
722 then tells the IEEE 1284 code about the interrupt, which may
723 involve reacting to an IEEE 1284 event, depending on the current
724 IEEE 1284 phase; and finally the <parameter>irq_func</parameter>
729 None of the callback functions are allowed to block.
733 The <parameter>flags</parameter> are for telling
734 <literal>parport</literal> any requirements or hints that are
735 useful. The only useful value here (other than
736 <constant>0</constant>, which is the usual value) is
737 <constant>PARPORT_DEV_EXCL</constant>. The point of that flag is
738 to request exclusive access at all times---once a driver has
739 successfully called <function>parport_register_device</function>
740 with that flag, no other device drivers will be able to register
741 devices on that port (until the successful driver deregisters its
746 The <constant>PARPORT_DEV_EXCL</constant> flag is for preventing
747 port sharing, and so should only be used when sharing the port with
748 other device drivers is impossible and would lead to incorrect
749 behaviour. Use it sparingly!
753 Devices can also be registered by device drivers based on their
754 device numbers (the same device numbers as in the previous
759 The <function>parport_open</function> function is similar to
760 <function>parport_register_device</function>, and
761 <function>parport_close</function> is the equivalent of
762 <function>parport_unregister_device</function>. The difference is
763 that <function>parport_open</function> takes a device number rather
764 than a pointer to a <structname>struct parport</structname>.
769 #include <parport.h>
772 <funcdef>struct pardevice *<function>parport_open</function></funcdef>
773 <paramdef>int <parameter>devnum</parameter></paramdef>
774 <paramdef>const char *<parameter>name</parameter></paramdef>
775 <paramdef>int <parameter>(*pf)</parameter>
776 <funcparams>void *</funcparams></paramdef>
777 <paramdef>int <parameter>(*kf)</parameter>
778 <funcparams>void *</funcparams></paramdef>
779 <paramdef>int <parameter>(*irqf)</parameter>
780 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
781 <paramdef>int <parameter>flags</parameter></paramdef>
782 <paramdef>void *<parameter>handle</parameter></paramdef>
788 <funcdef>void <function>parport_close</function></funcdef>
789 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
795 <funcdef>struct pardevice *<function>parport_register_device</function></funcdef>
796 <paramdef>struct parport *<parameter>port</parameter></paramdef>
797 <paramdef>const char *<parameter>name</parameter></paramdef>
798 <paramdef>int <parameter>(*pf)</parameter>
799 <funcparams>void *</funcparams></paramdef>
800 <paramdef>int <parameter>(*kf)</parameter>
801 <funcparams>void *</funcparams></paramdef>
802 <paramdef>int <parameter>(*irqf)</parameter>
803 <funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
804 <paramdef>int <parameter>flags</parameter></paramdef>
805 <paramdef>void *<parameter>handle</parameter></paramdef>
811 <funcdef>void <function>parport_unregister_device</function></funcdef>
812 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
817 The intended use of these functions is during driver initialisation
818 while the driver looks for devices that it supports, as
819 demonstrated by the following code fragment:
825 while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM,
827 struct pardevice *dev = parport_open (devnum, ...);
833 Once your device driver has registered its device and been handed a
834 pointer to a <structname>struct pardevice</structname>, the next
835 thing you are likely to want to do is communicate with the device
836 you think is there. To do that you'll need to claim access to the
842 #include <parport.h>
845 <funcdef>int <function>parport_claim</function></funcdef>
846 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
852 <funcdef>int <function>parport_claim_or_block</function></funcdef>
853 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
859 <funcdef>void <function>parport_release</function></funcdef>
860 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
865 To claim access to the port, use <function>parport_claim</function>
866 or <function>parport_claim_or_block</function>. The first of these
867 will not block, and so can be used from interrupt context. If
868 <function>parport_claim</function> succeeds it will return zero and
869 the port is available to use. It may fail (returning non-zero) if
870 the port is in use by another driver and that driver is not willing
871 to relinquish control of the port.
875 The other function, <function>parport_claim_or_block</function>,
876 will block if necessary to wait for the port to be free. If it
877 slept, it returns <constant>1</constant>; if it succeeded without
878 needing to sleep it returns <constant>0</constant>. If it fails it
879 will return a negative error code.
883 When you have finished communicating with the device, you can give
884 up access to the port so that other drivers can communicate with
885 their devices. The <function>parport_release</function> function
886 cannot fail, but it should not be called without the port claimed.
887 Similarly, you should not try to claim the port if you already have
892 You may find that although there are convenient points for your
893 driver to relinquish the parallel port and allow other drivers to
894 talk to their devices, it would be preferable to keep hold of the
895 port. The printer driver only needs the port when there is data to
896 print, for example, but a network driver (such as PLIP) could be
897 sent a remote packet at any time. With PLIP, it is no huge
898 catastrophe if a network packet is dropped, since it will likely be
899 sent again, so it is possible for that kind of driver to share the
900 port with other (pass-through) devices.
904 The <function>parport_yield</function> and
905 <function>parport_yield_blocking</function> functions are for
906 marking points in the driver at which other drivers may claim the
907 port and use their devices. Yielding the port is similar to
908 releasing it and reclaiming it, but is more efficient because
909 nothing is done if there are no other devices needing the port. In
910 fact, nothing is done even if there are other devices waiting but
911 the current device is still within its <quote>timeslice</quote>.
912 The default timeslice is half a second, but it can be adjusted via
913 a <filename>/proc</filename> entry.
918 #include <parport.h>
921 <funcdef>int <function>parport_yield</function></funcdef>
922 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
928 <funcdef>int <function>parport_yield_blocking</function></funcdef>
929 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
934 The first of these, <function>parport_yield</function>, will not
935 block but as a result may fail. The return value for
936 <function>parport_yield</function> is the same as for
937 <function>parport_claim</function>. The blocking version,
938 <function>parport_yield_blocking</function>, has the same return
939 code as <function>parport_claim_or_block</function>.
943 Once the port has been claimed, the device driver can use the
944 functions in the <structname>struct parport_operations</structname>
945 pointer in the <structname>struct parport</structname> it has a
946 pointer to. For example:
951 port->ops->write_data (port, d);
955 Some of these operations have <quote>shortcuts</quote>. For
956 instance, <function>parport_write_data</function> is equivalent to
957 the above, but may be a little bit faster (it's a macro that in
958 some cases can avoid needing to indirect through
959 <varname>port</varname> and <varname>ops</varname>).
964 <chapter id="portdrivers">
965 <title>Port drivers</title>
967 <!-- What port drivers are for (i.e. implementing parport objects). -->
970 To recap, then:</para>
972 <itemizedlist spacing=compact>
976 The device driver registers itself with <literal>parport</literal>.
982 A low-level driver finds a parallel port and registers it with
983 <literal>parport</literal> (these first two things can happen
984 in either order). This registration creates a <structname>struct
985 parport</structname> which is linked onto a list of known ports.
991 <literal>parport</literal> calls the
992 <function>attach</function> function of each registered device
993 driver, passing it the pointer to the new <structname>struct
994 parport</structname>.
1000 The device driver gets a handle from
1001 <literal>parport</literal>, for use with
1002 <function>parport_claim</function>/<function>release</function>.
1003 This handle takes the form of a pointer to a <structname>struct
1004 pardevice</structname>, representing a particular device on the
1005 parallel port, and is acquired using
1006 <function>parport_register_device</function>.
1012 The device driver claims the port using
1013 <function>parport_claim</function> (or
1014 <function>function_claim_or_block</function>).
1020 Then it goes ahead and uses the port. When finished it releases
1028 The purpose of the low-level drivers, then, is to detect parallel
1029 ports and provide methods of accessing them (i.e. implementing the
1030 operations in <structname>struct
1031 parport_operations</structname>).
1034 <!-- Should DocBookise this -->
1036 A more complete description of which operation is supposed to do
1037 what is available in
1038 <filename>Documentation/parport-lowlevel.txt</filename>.
1044 <title>The printer driver</title>
1046 <!-- Talk the reader through the printer driver. -->
1047 <!-- Could even talk about parallel port console here. -->
1050 The printer driver, <literal>lp</literal> is a character special
1051 device driver and a <literal>parport</literal> client. As a
1052 character special device driver it registers a <structname>struct
1053 file_operations</structname> using
1054 <function>register_chrdev</function>, with pointers filled in for
1055 <structfield>write</structfield>, <structfield>ioctl</structfield>,
1056 <structfield>open</structfield> and
1057 <structfield>release</structfield>. As a client of
1058 <literal>parport</literal>, it registers a <structname>struct
1059 parport_driver</structname> using
1060 <function>parport_register_driver</function>, so that
1061 <literal>parport</literal> knows to call
1062 <function>lp_attach</function> when a new parallel port is
1063 discovered (and <function>lp_detach</function> when it goes
1068 The parallel port console functionality is also implemented in
1069 <filename>drivers/char/lp.c</filename>, but that won't be covered
1070 here (it's quite simple though).
1074 The initialisation of the driver is quite easy to understand (see
1075 <function>lp_init</function>). The <varname>lp_table</varname> is
1076 an array of structures that contain information about a specific
1077 device (the <structname>struct pardevice</structname> associated
1078 with it, for example). That array is initialised to sensible
1079 values first of all.
1083 Next, the printer driver calls <function>register_chrdev</function>
1084 passing it a pointer to <varname>lp_fops</varname>, which contains
1085 function pointers for the printer driver's implementation of
1086 <function>open</function>, <function>write</function>, and so on.
1087 This part is the same as for any character special device
1092 After successfully registering itself as a character special device
1093 driver, the printer driver registers itself as a
1094 <literal>parport</literal> client using
1095 <function>parport_register_driver</function>. It passes a pointer
1101 static struct parport_driver lp_driver = {
1107 ]]></programlisting>
1110 The <function>lp_detach</function> function is not very interesting
1111 (it does nothing); the interesting bit is
1112 <function>lp_attach</function>. What goes on here depends on
1113 whether the user supplied any parameters. The possibilities are:
1114 no parameters supplied, in which case the printer driver uses every
1115 port that is detected; the user supplied the parameter
1116 <quote>auto</quote>, in which case only ports on which the device
1117 ID string indicates a printer is present are used; or the user
1118 supplied a list of parallel port numbers to try, in which case only
1123 For each port that the printer driver wants to use (see
1124 <function>lp_register</function>), it calls
1125 <function>parport_register_device</function> and stores the
1126 resulting <structname>struct pardevice</structname> pointer in the
1127 <varname>lp_table</varname>. If the user told it to do so, it then
1132 The other interesting piece of the printer driver, from the point
1133 of view of <literal>parport</literal>, is
1134 <function>lp_write</function>. In this function, the user space
1135 process has data that it wants printed, and the printer driver
1136 hands it off to the <literal>parport</literal> code to deal with.
1140 The <literal>parport</literal> functions it uses that we have not
1141 seen yet are <function>parport_negotiate</function>,
1142 <function>parport_set_timeout</function>, and
1143 <function>parport_write</function>. These functions are part of
1144 the IEEE 1284 implementation.
1148 The way the IEEE 1284 protocol works is that the host tells the
1149 peripheral what transfer mode it would like to use, and the
1150 peripheral either accepts that mode or rejects it; if the mode is
1151 rejected, the host can try again with a different mode. This is
1152 the negotiation phase. Once the peripheral has accepted a
1153 particular transfer mode, data transfer can begin that mode.
1157 The particular transfer mode that the printer driver wants to use
1158 is named in IEEE 1284 as <quote>compatibility</quote> mode, and the
1159 function to request a particular mode is called
1160 <function>parport_negotiate</function>.
1165 #include <parport.h>
1168 <funcdef>int <function>parport_negotiate</function></funcdef>
1169 <paramdef>struct parport *<parameter>port</parameter></paramdef>
1170 <paramdef>int <parameter>mode</parameter></paramdef>
1175 The <parameter>modes</parameter> parameter is a symbolic constant
1176 representing an IEEE 1284 mode; in this instance, it is
1177 <constant>IEEE1284_MODE_COMPAT</constant>. (Compatibility mode is
1178 slightly different to the other modes---rather than being
1179 specifically requested, it is the default until another mode is
1184 Back to <function>lp_write</function> then. First, access to the
1185 parallel port is secured with
1186 <function>parport_claim_or_block</function>. At this point the
1187 driver might sleep, waiting for another driver (perhaps a Zip drive
1188 driver, for instance) to let the port go. Next, it goes to
1189 compatibility mode using <function>parport_negotiate</function>.
1193 The main work is done in the write-loop. In particular, the line
1194 that hands the data over to <literal>parport</literal> reads:
1199 written = parport_write (port, kbuf, copy_size);
1200 ]]></programlisting>
1203 The <function>parport_write</function> function writes data to the
1204 peripheral using the currently selected transfer mode
1205 (compatibility mode, in this case). It returns the number of bytes
1206 successfully written:
1211 #include <parport.h>
1214 <funcdef>ssize_t <function>parport_write</function></funcdef>
1215 <paramdef>struct parport *<parameter>port</parameter></paramdef>
1216 <paramdef>const void *<parameter>buf</parameter></paramdef>
1217 <paramdef>size_t <parameter>len</parameter></paramdef>
1223 <funcdef>ssize_t <function>parport_read</function></funcdef>
1224 <paramdef>struct parport *<parameter>port</parameter></paramdef>
1225 <paramdef>void *<parameter>buf</parameter></paramdef>
1226 <paramdef>size_t <parameter>len</parameter></paramdef>
1231 (<function>parport_read</function> does what it sounds like, but
1232 only works for modes in which reverse transfer is possible. Of
1233 course, <function>parport_write</function> only works in modes in
1234 which forward transfer is possible, too.)
1238 The <parameter>buf</parameter> pointer should be to kernel space
1239 memory, and obviously the <parameter>len</parameter> parameter
1240 specifies the amount of data to transfer.
1244 In fact what <function>parport_write</function> does is call the
1245 appropriate block transfer function from the <structname>struct
1246 parport_operations</structname>:
1251 struct parport_operations {
1254 /* Block read/write */
1255 size_t (*epp_write_data) (struct parport *port,
1257 size_t len, int flags);
1258 size_t (*epp_read_data) (struct parport *port,
1259 void *buf, size_t len,
1261 size_t (*epp_write_addr) (struct parport *port,
1263 size_t len, int flags);
1264 size_t (*epp_read_addr) (struct parport *port,
1265 void *buf, size_t len,
1268 size_t (*ecp_write_data) (struct parport *port,
1270 size_t len, int flags);
1271 size_t (*ecp_read_data) (struct parport *port,
1272 void *buf, size_t len,
1274 size_t (*ecp_write_addr) (struct parport *port,
1276 size_t len, int flags);
1278 size_t (*compat_write_data) (struct parport *port,
1280 size_t len, int flags);
1281 size_t (*nibble_read_data) (struct parport *port,
1282 void *buf, size_t len,
1284 size_t (*byte_read_data) (struct parport *port,
1285 void *buf, size_t len,
1288 ]]></programlisting>
1291 The transfer code in <literal>parport</literal> will tolerate a
1292 data transfer stall only for so long, and this timeout can be
1293 specified with <function>parport_set_timeout</function>, which
1294 returns the previous timeout:
1299 #include <parport.h>
1302 <funcdef>long <function>parport_set_timeout</function></funcdef>
1303 <paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
1304 <paramdef>long <parameter>inactivity</parameter></paramdef>
1309 This timeout is specific to the device, and is restored on
1310 <function>parport_claim</function>.
1314 The next function to look at is the one that allows processes to
1315 read from <filename>/dev/lp0</filename>:
1316 <function>lp_read</function>. It's short, like
1317 <function>lp_write</function>.
1321 The semantics of reading from a line printer device are as follows:
1327 Switch to reverse nibble mode.
1333 Try to read data from the peripheral using reverse nibble mode,
1334 until either the user-provided buffer is full or the peripheral
1335 indicates that there is no more data.
1341 If there was data, stop, and return it.
1347 Otherwise, we tried to read data and there was none. If the user
1348 opened the device node with the <constant>O_NONBLOCK</constant>
1349 flag, return. Otherwise wait until an interrupt occurs on the
1350 port (or a timeout elapses).
1357 <chapter id="ppdev">
1358 <title>User-level device drivers</title>
1362 <title>Introduction to ppdev</title>
1365 The printer is accessible through <filename>/dev/lp0</filename>;
1366 in the same way, the parallel port itself is accessible through
1367 <filename>/dev/parport0</filename>. The difference is in the
1368 level of control that you have over the wires in the parallel port
1373 With the printer driver, a user-space program (such as the printer
1374 spooler) can send bytes in <quote>printer protocol</quote>.
1375 Briefly, this means that for each byte, the eight data lines are
1376 set up, then a <quote>strobe</quote> line tells the printer to
1377 look at the data lines, and the printer sets an
1378 <quote>acknowledgement</quote> line to say that it got the byte.
1379 The printer driver also allows the user-space program to read
1380 bytes in <quote>nibble mode</quote>, which is a way of
1381 transferring data from the peripheral to the computer half a byte
1382 at a time (and so it's quite slow).
1386 In contrast, the <literal>ppdev</literal> driver (accessed via
1387 <filename>/dev/parport0</filename>) allows you to:
1390 <itemizedlist spacing=compact>
1394 examine status lines,
1406 set/examine data lines (and control the direction of the data
1413 wait for an interrupt (triggered by one of the status lines),
1419 find out how many new interrupts have occurred,
1425 set up a response to an interrupt,
1431 use IEEE 1284 negotiation (for telling peripheral which transfer
1438 transfer data using a specified IEEE 1284 mode.
1447 <title>User-level or kernel-level driver?</title>
1450 The decision of whether to choose to write a kernel-level device
1451 driver or a user-level device driver depends on several factors.
1452 One of the main ones from a practical point of view is speed:
1453 kernel-level device drivers get to run faster because they are not
1454 preemptable, unlike user-level applications.
1458 Another factor is ease of development. It is in general easier to
1459 write a user-level driver because (a) one wrong move does not
1460 result in a crashed machine, (b) you have access to user libraries
1461 (such as the C library), and (c) debugging is easier.
1467 <title>Programming interface</title>
1470 The <literal>ppdev</literal> interface is largely the same as that
1471 of other character special devices, in that it supports
1472 <function>open</function>, <function>close</function>,
1473 <function>read</function>, <function>write</function>, and
1474 <function>ioctl</function>. The constants for the
1475 <function>ioctl</function> commands are in
1476 <filename>include/linux/ppdev.h</filename>.
1481 Starting and stopping: <function>open</function> and
1482 <function>close</function>
1486 The device node <filename>/dev/parport0</filename> represents any
1487 device that is connected to <filename>parport0</filename>, the
1488 first parallel port in the system. Each time the device node is
1489 opened, it represents (to the process doing the opening) a
1490 different device. It can be opened more than once, but only one
1491 instance can actually be in control of the parallel port at any
1492 time. A process that has opened
1493 <filename>/dev/parport0</filename> shares the parallel port in
1494 the same way as any other device driver. A user-land driver may
1495 be sharing the parallel port with in-kernel device drivers as
1496 well as other user-land drivers.
1501 <title>Control: <function>ioctl</function></title>
1504 Most of the control is done, naturally enough, via the
1505 <function>ioctl</function> call. Using
1506 <function>ioctl</function>, the user-land driver can control both
1507 the <literal>ppdev</literal> driver in the kernel and the
1508 physical parallel port itself. The <function>ioctl</function>
1509 call takes as parameters a file descriptor (the one returned from
1510 opening the device node), a command, and optionally (a pointer
1515 <varlistentry><term><constant>PPCLAIM</constant></term>
1519 Claims access to the port. As a user-land device driver
1520 writer, you will need to do this before you are able to
1521 actually change the state of the parallel port in any way.
1522 Note that some operations only affect the
1523 <literal>ppdev</literal> driver and not the port, such as
1524 <constant>PPSETMODE</constant>; they can be performed while
1525 access to the port is not claimed.
1528 </listitem></varlistentry>
1530 <varlistentry><term><constant>PPEXCL</constant></term>
1534 Instructs the kernel driver to forbid any sharing of the port
1535 with other drivers, i.e. it requests exclusivity. The
1536 <constant>PPEXCL</constant> command is only valid when the
1537 port is not already claimed for use, and it may mean that the
1538 next <constant>PPCLAIM</constant> <function>ioctl</function>
1539 will fail: some other driver may already have registered
1540 itself on that port.
1544 Most device drivers don't need exclusive access to the port.
1545 It's only provided in case it is really needed, for example
1546 for devices where access to the port is required for extensive
1547 periods of time (many seconds).
1551 Note that the <constant>PPEXCL</constant>
1552 <function>ioctl</function> doesn't actually claim the port
1553 there and then---action is deferred until the
1554 <constant>PPCLAIM</constant> <function>ioctl</function> is
1558 </listitem></varlistentry>
1560 <varlistentry><term><constant>PPRELEASE</constant></term>
1564 Releases the port. Releasing the port undoes the effect of
1565 claiming the port. It allows other device drivers to talk to
1566 their devices (assuming that there are any).
1569 </listitem></varlistentry>
1571 <varlistentry><term><constant>PPYIELD</constant></term>
1575 Yields the port to another driver. This
1576 <function>ioctl</function> is a kind of short-hand for
1577 releasing the port and immediately reclaiming it. It gives
1578 other drivers a chance to talk to their devices, but
1579 afterwards claims the port back. An example of using this
1580 would be in a user-land printer driver: once a few characters
1581 have been written we could give the port to another device
1582 driver for a while, but if we still have characters to send to
1583 the printer we would want the port back as soon as possible.
1587 It is important not to claim the parallel port for too long,
1588 as other device drivers will have no time to service their
1589 devices. If your device does not allow for parallel port
1590 sharing at all, it is better to claim the parallel port
1591 exclusively (see <constant>PPEXCL</constant>).
1594 </listitem></varlistentry>
1596 <varlistentry><term><constant>PPNEGOT</constant></term>
1600 Performs IEEE 1284 negotiation into a particular mode.
1601 Briefly, negotiation is the method by which the host and the
1602 peripheral decide on a protocol to use when transferring data.
1606 An IEEE 1284 compliant device will start out in compatibility
1607 mode, and then the host can negotiate to another mode (such as
1612 The <function>ioctl</function> parameter should be a pointer
1613 to an <type>int</type>; values for this are in
1614 <filename>incluce/linux/parport.h</filename> and include:
1617 <itemizedlist spacing=compact>
1619 <constant>IEEE1284_MODE_COMPAT</constant></para></listitem>
1621 <constant>IEEE1284_MODE_NIBBLE</constant></para></listitem>
1623 <constant>IEEE1284_MODE_BYTE</constant></para></listitem>
1625 <constant>IEEE1284_MODE_EPP</constant></para></listitem>
1627 <constant>IEEE1284_MODE_ECP</constant></para></listitem>
1631 The <constant>PPNEGOT</constant> <function>ioctl</function>
1632 actually does two things: it performs the on-the-wire
1633 negotiation, and it sets the behaviour of subsequent
1634 <function>read</function>/<function>write</function> calls so
1635 that they use that mode (but see
1636 <constant>PPSETMODE</constant>).
1639 </listitem></varlistentry>
1641 <varlistentry><term><constant>PPSETMODE</constant></term>
1645 Sets which IEEE 1284 protocol to use for the
1646 <function>read</function> and <function>write</function>
1651 The <function>ioctl</function> parameter should be a pointer
1652 to an <type>int</type>.
1655 </listitem></varlistentry>
1657 <varlistentry><term><constant>PPGETMODE</constant></term>
1661 Retrieves the current IEEE 1284 mode to use for
1662 <function>read</function> and <function>write</function>.
1665 </listitem></varlistentry>
1667 <varlistentry><term><constant>PPGETTIME</constant></term>
1671 Retrieves the time-out value. The <function>read</function>
1672 and <function>write</function> calls will time out if the
1673 peripheral doesn't respond quickly enough. The
1674 <constant>PPGETTIME</constant> <function>ioctl</function>
1675 retrieves the length of time that the peripheral is allowed to
1676 have before giving up.
1680 The <function>ioctl</function> parameter should be a pointer
1681 to a <structname>struct timeval</structname>.
1684 </listitem></varlistentry>
1686 <varlistentry><term><constant>PPSETTIME</constant></term>
1690 Sets the time-out. The <function>ioctl</function> parameter
1691 should be a pointer to a <structname>struct
1692 timeval</structname>.
1695 </listitem></varlistentry>
1697 <varlistentry><term><constant>PPGETMODES</constant></term>
1701 Retrieves the capabilities of the hardware (i.e. the
1702 <structfield>modes</structfield> field of the
1703 <structname>parport</structname> structure).
1706 </listitem></varlistentry>
1708 <varlistentry><term><constant>PPSETFLAGS</constant></term>
1712 Sets flags on the <literal>ppdev</literal> device which can
1713 affect future I/O operations. Available flags are:
1716 <itemizedlist spacing=compact>
1718 <constant>PP_FASTWRITE</constant></para></listitem>
1720 <constant>PP_FASTREAD</constant></para></listitem>
1722 <constant>PP_W91284PIC</constant></para></listitem>
1725 </listitem></varlistentry>
1727 <varlistentry><term><constant>PPWCONTROL</constant></term>
1731 Sets the control lines. The <function>ioctl</function>
1732 parameter is a pointer to an <type>unsigned char</type>, the
1733 bitwise OR of the control line values in
1734 <filename>include/linux/parport.h</filename>.
1737 </listitem></varlistentry>
1739 <varlistentry><term><constant>PPRCONTROL</constant></term>
1743 Returns the last value written to the control register, in the
1744 form of an <type>unsigned char</type>: each bit corresponds to
1745 a control line (although some are unused). The
1746 <function>ioctl</function> parameter should be a pointer to an
1747 <type>unsigned char</type>.
1751 This doesn't actually touch the hardware; the last value
1752 written is remembered in software. This is because some
1753 parallel port hardware does not offer read access to the
1758 The control lines bits are defined in
1759 <filename>include/linux/parport.h</filename>:
1762 <itemizedlist spacing=compact>
1764 <constant>PARPORT_CONTROL_STROBE</constant></para></listitem>
1766 <constant>PARPORT_CONTROL_AUTOFD</constant></para></listitem>
1768 <constant>PARPORT_CONTROL_SELECT</constant></para></listitem>
1770 <constant>PARPORT_CONTROL_INIT</constant></para></listitem>
1773 </listitem></varlistentry>
1775 <varlistentry><term><constant>PPFCONTROL</constant></term>
1779 Frobs the control lines. Since a common operation is to
1780 change one of the control signals while leaving the others
1781 alone, it would be quite inefficient for the user-land driver
1782 to have to use <constant>PPRCONTROL</constant>, make the
1783 change, and then use <constant>PPWCONTROL</constant>. Of
1784 course, each driver could remember what state the control
1785 lines are supposed to be in (they are never changed by
1786 anything else), but in order to provide
1787 <constant>PPRCONTROL</constant>, <literal>ppdev</literal>
1788 must remember the state of the control lines anyway.
1792 The <constant>PPFCONTROL</constant> <function>ioctl</function>
1793 is for <quote>frobbing</quote> control lines, and is like
1794 <constant>PPWCONTROL</constant> but acts on a restricted set
1795 of control lines. The <function>ioctl</function> parameter is
1796 a pointer to a <structname>struct
1797 ppdev_frob_struct</structname>:
1802 struct ppdev_frob_struct {
1810 The <structfield>mask</structfield> and
1811 <structfield>val</structfield> fields are bitwise ORs of
1812 control line names (such as in
1813 <constant>PPWCONTROL</constant>). The operation performed by
1814 <constant>PPFCONTROL</constant> is:
1819 new_ctr = (old_ctr & ~mask) | val;]]>
1823 In other words, the signals named in
1824 <structfield>mask</structfield> are set to the values in
1825 <structfield>val</structfield>.
1828 </listitem></varlistentry>
1830 <varlistentry><term><constant>PPRSTATUS</constant></term>
1834 Returns an <type>unsigned char</type> containing bits set for
1835 each status line that is set (for instance,
1836 <constant>PARPORT_STATUS_BUSY</constant>). The
1837 <function>ioctl</function> parameter should be a pointer to an
1838 <type>unsigned char</type>.
1841 </listitem></varlistentry>
1843 <varlistentry><term><constant>PPDATADIR</constant></term>
1847 Controls the data line drivers. Normally the computer's
1848 parallel port will drive the data lines, but for byte-wide
1849 transfers from the peripheral to the host it is useful to turn
1850 off those drivers and let the peripheral drive the
1851 signals. (If the drivers on the computer's parallel port are
1852 left on when this happens, the port might be damaged.)
1856 This is only needed in conjunction with
1857 <constant>PPWDATA</constant> or
1858 <constant>PPRDATA</constant>.
1862 The <function>ioctl</function> parameter is a pointer to an
1863 <type>int</type>. If the <type>int</type> is zero, the
1864 drivers are turned on (forward direction); if non-zero, the
1865 drivers are turned off (reverse direction).
1868 </listitem></varlistentry>
1870 <varlistentry><term><constant>PPWDATA</constant></term>
1874 Sets the data lines (if in forward mode). The
1875 <function>ioctl</function> parameter is a pointer to an
1876 <type>unsigned char</type>.
1879 </listitem></varlistentry>
1881 <varlistentry><term><constant>PPRDATA</constant></term>
1885 Reads the data lines (if in reverse mode). The
1886 <function>ioctl</function> parameter is a pointer to an
1887 <type>unsigned char</type>.
1890 </listitem></varlistentry>
1892 <varlistentry><term><constant>PPCLRIRQ</constant></term>
1896 Clears the interrupt count. The <literal>ppdev</literal>
1897 driver keeps a count of interrupts as they are triggered.
1898 <constant>PPCLRIRQ</constant> stores this count in an
1899 <type>int</type>, a pointer to which is passed in as the
1900 <function>ioctl</function> parameter.
1904 In addition, the interrupt count is reset to zero.
1907 </listitem></varlistentry>
1909 <varlistentry><term><constant>PPWCTLONIRQ</constant></term>
1913 Set a trigger response. Afterwards when an interrupt is
1914 triggered, the interrupt handler will set the control lines as
1915 requested. The <function>ioctl</function> parameter is a
1916 pointer to an <type>unsigned char</type>, which is interpreted
1917 in the same way as for <constant>PPWCONTROL</constant>.
1921 The reason for this <function>ioctl</function> is simply
1922 speed. Without this <function>ioctl</function>, responding to
1923 an interrupt would start in the interrupt handler, switch
1924 context to the user-land driver via <function>poll</function>
1925 or <function>select</function>, and then switch context back
1926 to the kernel in order to handle
1927 <constant>PPWCONTROL</constant>. Doing the whole lot in the
1928 interrupt handler is a lot faster.
1931 </listitem></varlistentry>
1933 <!-- PPSETPHASE? -->
1940 <title>Transferring data: <function>read</function> and
1941 <function>write</function></title>
1944 Transferring data using <function>read</function> and
1945 <function>write</function> is straightforward. The data is
1946 transferring using the current IEEE 1284 mode (see the
1947 <constant>PPSETMODE</constant> <function>ioctl</function>). For
1948 modes which can only transfer data in one direction, only the
1949 appropriate function will work, of course.
1954 <title>Waiting for events: <function>poll</function> and
1955 <function>select</function></title>
1958 The <literal>ppdev</literal> driver provides user-land device
1959 drivers with the ability to wait for interrupts, and this is done
1960 using <function>poll</function> (and <function>select</function>,
1961 which is implemented in terms of <function>poll</function>).
1965 When a user-land device driver wants to wait for an interrupt, it
1966 sleeps with <function>poll</function>. When the interrupt
1967 arrives, <literal>ppdev</literal> wakes it up (with a
1968 <quote>read</quote> event, although strictly speaking there is
1969 nothing to actually <function>read</function>).
1977 <title>Examples</title>
1980 Presented here are two demonstrations of how to write a simple
1981 printer driver for <literal>ppdev</literal>. Firstly we will
1982 use the <function>write</function> function, and after that we
1983 will drive the control and data lines directly.
1987 The first thing to do is to actually open the device.
1990 <programlisting><![CDATA[
1991 int drive_printer (const char *name)
1994 int mode; /* We'll need this later. */
1996 fd = open (name, O_RDWR);
2001 ]]></programlisting>
2004 Here <varname>name</varname> should be something along the lines
2005 of <filename>"/dev/parport0"</filename>. (If you don't have any
2006 <filename>/dev/parport</filename> files, you can make them with
2007 <command>mknod</command>; they are character special device nodes
2012 In order to do anything with the port we need to claim access to
2016 <programlisting><![CDATA[
2017 if (ioctl (fd, PPCLAIM)) {
2022 ]]></programlisting>
2025 Our printer driver will copy its input (from
2026 <varname>stdin</varname>) to the printer, and it can do that it
2027 one of two ways. The first way is to hand it all off to the
2028 kernel driver, with the knowledge that the protocol that the
2029 printer speaks is IEEE 1284's <quote>compatibility</quote>
2033 <programlisting><![CDATA[
2034 /* Switch to compatibility mode. (In fact we don't need
2035 * to do this, since we start off in compatibility mode
2036 * anyway, but this demonstrates PPNEGOT.)
2037 mode = IEEE1284_MODE_COMPAT;
2038 if (ioctl (fd, PPNEGOT, &mode)) {
2049 got = read (0 /* stdin */, buffer, 1000);
2061 int written = write_printer (fd, ptr, got);
2073 ]]></programlisting>
2076 The <function>write_printer</function> function is not pictured
2077 above. This is because the main loop that is shown can be used
2078 for both methods of driving the printer. Here is one
2079 implementation of <function>write_printer</function>:
2082 <programlisting><![CDATA[
2083 ssize_t write_printer (int fd, const void *ptr, size_t count)
2085 return write (fd, ptr, count);
2087 ]]></programlisting>
2090 We hand the data to the kernel-level driver (using
2091 <function>write</function>) and it handles the printer
2096 Now let's do it the hard way! In this particular example there is
2097 no practical reason to do anything other than just call
2098 <function>write</function>, because we know that the printer talks
2099 an IEEE 1284 protocol. On the other hand, this particular example
2100 does not even need a user-land driver since there is already a
2101 kernel-level one; for the purpose of this discussion, try to
2102 imagine that the printer speaks a protocol that is not already
2103 implemented under Linux.
2107 So, here is the alternative implementation of
2108 <function>write_printer</function> (for brevity, error checking
2112 <programlisting><![CDATA[
2113 ssize_t write_printer (int fd, const void *ptr, size_t count)
2117 while (wrote < count) {
2118 unsigned char status, control, data;
2119 unsigned char mask = (PARPORT_STATUS_ERROR
2120 | PARPORT_STATUS_BUSY);
2121 unsigned char val = (PARPORT_STATUS_ERROR
2122 | PARPORT_STATUS_BUSY);
2123 struct ppdev_frob_struct frob;
2126 /* Wait for printer to be ready */
2128 ioctl (fd, PPRSTATUS, &status);
2130 if ((status & mask) == val)
2133 ioctl (fd, PPRELEASE);
2135 ioctl (fd, PPCLAIM);
2138 /* Set the data lines */
2139 data = * ((char *) ptr)++;
2140 ioctl (fd, PPWDATA, &data);
2142 /* Delay for a bit */
2145 nanosleep (&ts, NULL);
2148 frob.mask = PARPORT_CONTROL_STROBE;
2149 frob.val = PARPORT_CONTROL_STROBE;
2150 ioctl (fd, PPFCONTROL, &frob);
2151 nanosleep (&ts, NULL);
2155 ioctl (fd, PPFCONTROL, &frob);
2156 nanosleep (&ts, NULL);
2163 ]]></programlisting>
2166 To show a bit more of the <literal>ppdev</literal> interface,
2167 here is a small piece of code that is intended to mimic the
2168 printer's side of printer protocol.
2171 <programlisting><![CDATA[
2175 int busy = nAck | nFault;
2176 int acking = nFault;
2177 int ready = Busy | nAck | nFault;
2180 /* Set up the control lines when an interrupt happens. */
2181 ioctl (fd, PPWCTLONIRQ, &busy);
2183 /* Now we're ready. */
2184 ioctl (fd, PPWCONTROL, &ready);
2186 /* Wait for an interrupt. */
2191 if (!select (fd + 1, &rfds, NULL, NULL, NULL))
2192 /* Caught a signal? */
2196 /* We are now marked as busy. */
2198 /* Fetch the data. */
2199 ioctl (fd, PPRDATA, &ch);
2201 /* Clear the interrupt. */
2202 ioctl (fd, PPCLRIRQ, &irqc);
2204 fprintf (stderr, "Arghh! Missed %d interrupt%s!\n",
2205 irqc - 1, irqc == 2 ? "s" : "");
2208 ioctl (fd, PPWCONTROL, &acking);
2210 ioctl (fd, PPWCONTROL, &busy);
2214 ]]></programlisting>
2217 And here is an example (with no error checking at all) to show how
2218 to read data from the port, using ECP mode, with optional
2219 negotiation to ECP mode first.
2222 <programlisting><![CDATA[
2225 fd = open ("/dev/parport0", O_RDONLY | O_NOCTTY);
2226 ioctl (fd, PPCLAIM);
2227 mode = IEEE1284_MODE_ECP;
2228 if (negotiate_first) {
2229 ioctl (fd, PPNEGOT, &mode);
2230 /* no need for PPSETMODE */
2232 ioctl (fd, PPSETMODE, &mode);
2235 /* Now do whatever we want with fd */
2240 execlp ("cat", "cat", NULL);
2247 /* Okay, finished */
2248 ioctl (fd, PPRELEASE);
2251 ]]></programlisting>
2259 Linux parallel port driver API reference
2262 !Fdrivers/parport/daisy.c parport_device_num
2263 !Fdrivers/parport/daisy.c parport_device_coords
2264 !Fdrivers/parport/daisy.c parport_find_device
2265 !Fdrivers/parport/daisy.c parport_find_class
2266 !Fdrivers/parport/share.c parport_register_driver
2267 !Fdrivers/parport/share.c parport_unregister_driver
2268 !Fdrivers/parport/share.c parport_get_port
2269 !Fdrivers/parport/share.c parport_put_port
2270 !Fdrivers/parport/share.c parport_find_number parport_find_base
2271 !Fdrivers/parport/share.c parport_register_device
2272 !Fdrivers/parport/share.c parport_unregister_device
2273 !Fdrivers/parport/daisy.c parport_open
2274 !Fdrivers/parport/daisy.c parport_close
2275 !Fdrivers/parport/share.c parport_claim
2276 !Fdrivers/parport/share.c parport_claim_or_block
2277 !Fdrivers/parport/share.c parport_release
2278 !Finclude/linux/parport.h parport_yield
2279 !Finclude/linux/parport.h parport_yield_blocking
2280 !Fdrivers/parport/ieee1284.c parport_negotiate
2281 !Fdrivers/parport/ieee1284.c parport_write
2282 !Fdrivers/parport/ieee1284.c parport_read
2283 !Fdrivers/parport/ieee1284.c parport_set_timeout
2289 The Linux 2.2 Parallel Port Subsystem
2293 Although the interface described in this document is largely new
2294 with the 2.4 kernel, the sharing mechanism is available in the 2.2
2295 kernel as well. The functions available in 2.2 are:
2301 <function>parport_register_device</function>
2307 <function>parport_unregister_device</function>
2313 <function>parport_claim</function>
2319 <function>parport_claim_or_block</function>
2325 <function>parport_release</function>
2331 <function>parport_yield</function>
2337 <function>parport_yield_blocking</function>
2343 In addition, negotiation to reverse nibble mode is supported:
2348 <funcdef>int <function>parport_ieee1284_nibble_mode_ok</function></funcdef>
2349 <paramdef>struct parport *<parameter>port</parameter></paramdef>
2350 <paramdef>unsigned char <parameter>mode</parameter></paramdef>
2355 The only valid values for <parameter>mode</parameter> are 0 (for
2356 reverse nibble mode) and 4 (for Device ID in reverse nibble mode).
2360 This function is obsoleted by
2361 <function>parport_negotiate</function> in Linux 2.4, and has been
2368 GNU Free Documentation License
2371 <literallayout class="monospaced">
2372 GNU Free Documentation License
2373 Version 1.1, March 2000
2375 Copyright (C) 2000 Free Software Foundation, Inc.
2376 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2377 Everyone is permitted to copy and distribute verbatim copies
2378 of this license document, but changing it is not allowed.
2383 The purpose of this License is to make a manual, textbook, or other
2384 written document "free" in the sense of freedom: to assure everyone
2385 the effective freedom to copy and redistribute it, with or without
2386 modifying it, either commercially or noncommercially. Secondarily,
2387 this License preserves for the author and publisher a way to get
2388 credit for their work, while not being considered responsible for
2389 modifications made by others.
2391 This License is a kind of "copyleft", which means that derivative
2392 works of the document must themselves be free in the same sense. It
2393 complements the GNU General Public License, which is a copyleft
2394 license designed for free software.
2396 We have designed this License in order to use it for manuals for free
2397 software, because free software needs free documentation: a free
2398 program should come with manuals providing the same freedoms that the
2399 software does. But this License is not limited to software manuals;
2400 it can be used for any textual work, regardless of subject matter or
2401 whether it is published as a printed book. We recommend this License
2402 principally for works whose purpose is instruction or reference.
2405 1. APPLICABILITY AND DEFINITIONS
2407 This License applies to any manual or other work that contains a
2408 notice placed by the copyright holder saying it can be distributed
2409 under the terms of this License. The "Document", below, refers to any
2410 such manual or work. Any member of the public is a licensee, and is
2413 A "Modified Version" of the Document means any work containing the
2414 Document or a portion of it, either copied verbatim, or with
2415 modifications and/or translated into another language.
2417 A "Secondary Section" is a named appendix or a front-matter section of
2418 the Document that deals exclusively with the relationship of the
2419 publishers or authors of the Document to the Document's overall subject
2420 (or to related matters) and contains nothing that could fall directly
2421 within that overall subject. (For example, if the Document is in part a
2422 textbook of mathematics, a Secondary Section may not explain any
2423 mathematics.) The relationship could be a matter of historical
2424 connection with the subject or with related matters, or of legal,
2425 commercial, philosophical, ethical or political position regarding
2428 The "Invariant Sections" are certain Secondary Sections whose titles
2429 are designated, as being those of Invariant Sections, in the notice
2430 that says that the Document is released under this License.
2432 The "Cover Texts" are certain short passages of text that are listed,
2433 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
2434 the Document is released under this License.
2436 A "Transparent" copy of the Document means a machine-readable copy,
2437 represented in a format whose specification is available to the
2438 general public, whose contents can be viewed and edited directly and
2439 straightforwardly with generic text editors or (for images composed of
2440 pixels) generic paint programs or (for drawings) some widely available
2441 drawing editor, and that is suitable for input to text formatters or
2442 for automatic translation to a variety of formats suitable for input
2443 to text formatters. A copy made in an otherwise Transparent file
2444 format whose markup has been designed to thwart or discourage
2445 subsequent modification by readers is not Transparent. A copy that is
2446 not "Transparent" is called "Opaque".
2448 Examples of suitable formats for Transparent copies include plain
2449 ASCII without markup, Texinfo input format, LaTeX input format, SGML
2450 or XML using a publicly available DTD, and standard-conforming simple
2451 HTML designed for human modification. Opaque formats include
2452 PostScript, PDF, proprietary formats that can be read and edited only
2453 by proprietary word processors, SGML or XML for which the DTD and/or
2454 processing tools are not generally available, and the
2455 machine-generated HTML produced by some word processors for output
2458 The "Title Page" means, for a printed book, the title page itself,
2459 plus such following pages as are needed to hold, legibly, the material
2460 this License requires to appear in the title page. For works in
2461 formats which do not have any title page as such, "Title Page" means
2462 the text near the most prominent appearance of the work's title,
2463 preceding the beginning of the body of the text.
2468 You may copy and distribute the Document in any medium, either
2469 commercially or noncommercially, provided that this License, the
2470 copyright notices, and the license notice saying this License applies
2471 to the Document are reproduced in all copies, and that you add no other
2472 conditions whatsoever to those of this License. You may not use
2473 technical measures to obstruct or control the reading or further
2474 copying of the copies you make or distribute. However, you may accept
2475 compensation in exchange for copies. If you distribute a large enough
2476 number of copies you must also follow the conditions in section 3.
2478 You may also lend copies, under the same conditions stated above, and
2479 you may publicly display copies.
2482 3. COPYING IN QUANTITY
2484 If you publish printed copies of the Document numbering more than 100,
2485 and the Document's license notice requires Cover Texts, you must enclose
2486 the copies in covers that carry, clearly and legibly, all these Cover
2487 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
2488 the back cover. Both covers must also clearly and legibly identify
2489 you as the publisher of these copies. The front cover must present
2490 the full title with all words of the title equally prominent and
2491 visible. You may add other material on the covers in addition.
2492 Copying with changes limited to the covers, as long as they preserve
2493 the title of the Document and satisfy these conditions, can be treated
2494 as verbatim copying in other respects.
2496 If the required texts for either cover are too voluminous to fit
2497 legibly, you should put the first ones listed (as many as fit
2498 reasonably) on the actual cover, and continue the rest onto adjacent
2501 If you publish or distribute Opaque copies of the Document numbering
2502 more than 100, you must either include a machine-readable Transparent
2503 copy along with each Opaque copy, or state in or with each Opaque copy
2504 a publicly-accessible computer-network location containing a complete
2505 Transparent copy of the Document, free of added material, which the
2506 general network-using public has access to download anonymously at no
2507 charge using public-standard network protocols. If you use the latter
2508 option, you must take reasonably prudent steps, when you begin
2509 distribution of Opaque copies in quantity, to ensure that this
2510 Transparent copy will remain thus accessible at the stated location
2511 until at least one year after the last time you distribute an Opaque
2512 copy (directly or through your agents or retailers) of that edition to
2515 It is requested, but not required, that you contact the authors of the
2516 Document well before redistributing any large number of copies, to give
2517 them a chance to provide you with an updated version of the Document.
2522 You may copy and distribute a Modified Version of the Document under
2523 the conditions of sections 2 and 3 above, provided that you release
2524 the Modified Version under precisely this License, with the Modified
2525 Version filling the role of the Document, thus licensing distribution
2526 and modification of the Modified Version to whoever possesses a copy
2527 of it. In addition, you must do these things in the Modified Version:
2529 A. Use in the Title Page (and on the covers, if any) a title distinct
2530 from that of the Document, and from those of previous versions
2531 (which should, if there were any, be listed in the History section
2532 of the Document). You may use the same title as a previous version
2533 if the original publisher of that version gives permission.
2534 B. List on the Title Page, as authors, one or more persons or entities
2535 responsible for authorship of the modifications in the Modified
2536 Version, together with at least five of the principal authors of the
2537 Document (all of its principal authors, if it has less than five).
2538 C. State on the Title page the name of the publisher of the
2539 Modified Version, as the publisher.
2540 D. Preserve all the copyright notices of the Document.
2541 E. Add an appropriate copyright notice for your modifications
2542 adjacent to the other copyright notices.
2543 F. Include, immediately after the copyright notices, a license notice
2544 giving the public permission to use the Modified Version under the
2545 terms of this License, in the form shown in the Addendum below.
2546 G. Preserve in that license notice the full lists of Invariant Sections
2547 and required Cover Texts given in the Document's license notice.
2548 H. Include an unaltered copy of this License.
2549 I. Preserve the section entitled "History", and its title, and add to
2550 it an item stating at least the title, year, new authors, and
2551 publisher of the Modified Version as given on the Title Page. If
2552 there is no section entitled "History" in the Document, create one
2553 stating the title, year, authors, and publisher of the Document as
2554 given on its Title Page, then add an item describing the Modified
2555 Version as stated in the previous sentence.
2556 J. Preserve the network location, if any, given in the Document for
2557 public access to a Transparent copy of the Document, and likewise
2558 the network locations given in the Document for previous versions
2559 it was based on. These may be placed in the "History" section.
2560 You may omit a network location for a work that was published at
2561 least four years before the Document itself, or if the original
2562 publisher of the version it refers to gives permission.
2563 K. In any section entitled "Acknowledgements" or "Dedications",
2564 preserve the section's title, and preserve in the section all the
2565 substance and tone of each of the contributor acknowledgements
2566 and/or dedications given therein.
2567 L. Preserve all the Invariant Sections of the Document,
2568 unaltered in their text and in their titles. Section numbers
2569 or the equivalent are not considered part of the section titles.
2570 M. Delete any section entitled "Endorsements". Such a section
2571 may not be included in the Modified Version.
2572 N. Do not retitle any existing section as "Endorsements"
2573 or to conflict in title with any Invariant Section.
2575 If the Modified Version includes new front-matter sections or
2576 appendices that qualify as Secondary Sections and contain no material
2577 copied from the Document, you may at your option designate some or all
2578 of these sections as invariant. To do this, add their titles to the
2579 list of Invariant Sections in the Modified Version's license notice.
2580 These titles must be distinct from any other section titles.
2582 You may add a section entitled "Endorsements", provided it contains
2583 nothing but endorsements of your Modified Version by various
2584 parties--for example, statements of peer review or that the text has
2585 been approved by an organization as the authoritative definition of a
2588 You may add a passage of up to five words as a Front-Cover Text, and a
2589 passage of up to 25 words as a Back-Cover Text, to the end of the list
2590 of Cover Texts in the Modified Version. Only one passage of
2591 Front-Cover Text and one of Back-Cover Text may be added by (or
2592 through arrangements made by) any one entity. If the Document already
2593 includes a cover text for the same cover, previously added by you or
2594 by arrangement made by the same entity you are acting on behalf of,
2595 you may not add another; but you may replace the old one, on explicit
2596 permission from the previous publisher that added the old one.
2598 The author(s) and publisher(s) of the Document do not by this License
2599 give permission to use their names for publicity for or to assert or
2600 imply endorsement of any Modified Version.
2603 5. COMBINING DOCUMENTS
2605 You may combine the Document with other documents released under this
2606 License, under the terms defined in section 4 above for modified
2607 versions, provided that you include in the combination all of the
2608 Invariant Sections of all of the original documents, unmodified, and
2609 list them all as Invariant Sections of your combined work in its
2612 The combined work need only contain one copy of this License, and
2613 multiple identical Invariant Sections may be replaced with a single
2614 copy. If there are multiple Invariant Sections with the same name but
2615 different contents, make the title of each such section unique by
2616 adding at the end of it, in parentheses, the name of the original
2617 author or publisher of that section if known, or else a unique number.
2618 Make the same adjustment to the section titles in the list of
2619 Invariant Sections in the license notice of the combined work.
2621 In the combination, you must combine any sections entitled "History"
2622 in the various original documents, forming one section entitled
2623 "History"; likewise combine any sections entitled "Acknowledgements",
2624 and any sections entitled "Dedications". You must delete all sections
2625 entitled "Endorsements."
2628 6. COLLECTIONS OF DOCUMENTS
2630 You may make a collection consisting of the Document and other documents
2631 released under this License, and replace the individual copies of this
2632 License in the various documents with a single copy that is included in
2633 the collection, provided that you follow the rules of this License for
2634 verbatim copying of each of the documents in all other respects.
2636 You may extract a single document from such a collection, and distribute
2637 it individually under this License, provided you insert a copy of this
2638 License into the extracted document, and follow this License in all
2639 other respects regarding verbatim copying of that document.
2643 7. AGGREGATION WITH INDEPENDENT WORKS
2645 A compilation of the Document or its derivatives with other separate
2646 and independent documents or works, in or on a volume of a storage or
2647 distribution medium, does not as a whole count as a Modified Version
2648 of the Document, provided no compilation copyright is claimed for the
2649 compilation. Such a compilation is called an "aggregate", and this
2650 License does not apply to the other self-contained works thus compiled
2651 with the Document, on account of their being thus compiled, if they
2652 are not themselves derivative works of the Document.
2654 If the Cover Text requirement of section 3 is applicable to these
2655 copies of the Document, then if the Document is less than one quarter
2656 of the entire aggregate, the Document's Cover Texts may be placed on
2657 covers that surround only the Document within the aggregate.
2658 Otherwise they must appear on covers around the whole aggregate.
2663 Translation is considered a kind of modification, so you may
2664 distribute translations of the Document under the terms of section 4.
2665 Replacing Invariant Sections with translations requires special
2666 permission from their copyright holders, but you may include
2667 translations of some or all Invariant Sections in addition to the
2668 original versions of these Invariant Sections. You may include a
2669 translation of this License provided that you also include the
2670 original English version of this License. In case of a disagreement
2671 between the translation and the original English version of this
2672 License, the original English version will prevail.
2677 You may not copy, modify, sublicense, or distribute the Document except
2678 as expressly provided for under this License. Any other attempt to
2679 copy, modify, sublicense or distribute the Document is void, and will
2680 automatically terminate your rights under this License. However,
2681 parties who have received copies, or rights, from you under this
2682 License will not have their licenses terminated so long as such
2683 parties remain in full compliance.
2686 10. FUTURE REVISIONS OF THIS LICENSE
2688 The Free Software Foundation may publish new, revised versions
2689 of the GNU Free Documentation License from time to time. Such new
2690 versions will be similar in spirit to the present version, but may
2691 differ in detail to address new problems or concerns. See
2692 http:///www.gnu.org/copyleft/.
2694 Each version of the License is given a distinguishing version number.
2695 If the Document specifies that a particular numbered version of this
2696 License "or any later version" applies to it, you have the option of
2697 following the terms and conditions either of that specified version or
2698 of any later version that has been published (not as a draft) by the
2699 Free Software Foundation. If the Document does not specify a version
2700 number of this License, you may choose any version ever published (not
2701 as a draft) by the Free Software Foundation.
2704 ADDENDUM: How to use this License for your documents
2706 To use this License in a document you have written, include a copy of
2707 the License in the document and put the following copyright and
2708 license notices just after the title page:
2710 Copyright (c) YEAR YOUR NAME.
2711 Permission is granted to copy, distribute and/or modify this document
2712 under the terms of the GNU Free Documentation License, Version 1.1
2713 or any later version published by the Free Software Foundation;
2714 with the Invariant Sections being LIST THEIR TITLES, with the
2715 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
2716 A copy of the license is included in the section entitled "GNU
2717 Free Documentation License".
2719 If you have no Invariant Sections, write "with no Invariant Sections"
2720 instead of saying which ones are invariant. If you have no
2721 Front-Cover Texts, write "no Front-Cover Texts" instead of
2722 "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
2724 If your document contains nontrivial examples of program code, we
2725 recommend releasing these examples in parallel under your choice of
2726 free software license, such as the GNU General Public License,
2727 to permit their use in free software.
2732 <!-- Additional function to be documented:
2733 !Ddrivers/parport/init.c
2735 <!-- Local Variables: -->
2736 <!-- sgml-indent-step: 1 -->
2737 <!-- sgml-indent-data: 1 -->