<!-- -*- sgml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[]>
<book id="ParportGuide">
<bookinfo>
<title>The Linux 2.4 Parallel Port Subsystem</title>
<authorgroup>
<author>
<firstname>Tim</firstname>
<surname>Waugh</surname>
<affiliation>
<address>
<email>twaugh@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>1999-2000</year>
<holder>Tim Waugh</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included
in the section entitled "GNU Free Documentation License".
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="design">
<title>Design goals</title>
<sect1>
<title>The problems</title>
<para>
The first parallel port support for Linux came with the line
printer driver, <literal>lp</literal>. The printer driver is a
character special device, and (in Linux 2.0) had support for
writing, via <function>write</function>, and configuration and
statistics reporting via <function>ioctl</function>.
</para>
<para>
The printer driver could be used on any computer that had an IBM
PC-compatible parallel port. Because some architectures have
parallel ports that aren't really the same as PC-style ports,
other variants of the printer driver were written in order to
support Amiga and Atari parallel ports.
</para>
<para>
When the Iomega Zip drive was released, and a driver written for
it, a problem became apparent. The Zip drive is a parallel port
device that provides a parallel port of its own---it is designed
to sit between a computer and an attached printer, with the
printer plugged into the Zip drive, and the Zip drive plugged into
the computer.
</para>
<para>
The problem was that, although printers and Zip drives were both
supported, for any given port only one could be used at a time.
Only one of the two drivers could be present in the kernel at
once. This was because of the fact that both drivers wanted to
drive the same hardware---the parallel port. When the printer
driver initialised, it would call the
<function>check_region</function> function to make sure that the
IO region associated with the parallel port was free, and then it
would call <function>request_region</function> to allocate it.
The Zip drive used the same mechanism. Whichever driver
initialised first would gain exclusive control of the parallel
port.
</para>
<para>
The only way around this problem at the time was to make sure that
both drivers were available as loadable kernel modules. To use
the printer, load the printer driver module; then for the Zip
drive, unload the printer driver module and load the Zip driver
module.
</para>
<para>
The net effect was that printing a document that was stored on a
Zip drive was a bit of an ordeal, at least if the Zip drive and
printer shared a parallel port. A better solution was
needed.
</para>
<para>
Zip drives are not the only devices that presented problems for
Linux. There are other devices with pass-through ports, for
example parallel port CD-ROM drives. There are also printers that
report their status textually rather than using simple error pins:
sending a command to the printer can cause it to report the number
of pages that it has ever printed, or how much free memory it has,
or whether it is running out of toner, and so on. The printer
driver didn't originally offer any facility for reading back this
information (although Carsten Gross added nibble mode readback
support for kernel 2.2).
</para>
<para>
The IEEE has issued a standards document called IEEE 1284, which
documents existing practice for parallel port communications in a
variety of modes. Those modes are: <quote>compatibility</quote>,
reverse nibble, reverse byte, ECP and EPP. Newer devices often
use the more advanced modes of transfer (ECP and EPP). In Linux
2.0, the printer driver only supported <quote>compatibility
mode</quote> (i.e. normal printer protocol) and reverse nibble
mode.
</para>
</sect1>
<sect1>
<title>The solutions</title>
<!-- How they are addressed
- sharing model
- overview of structure (i.e. port drivers) in 2.2 and 2.3.
- IEEE 1284 stuff
- whether or not 'platform independence' goal was met
-->
<para>
The <literal>parport</literal> code in Linux 2.2 was designed to
meet these problems of architectural differences in parallel
ports, of port-sharing between devices with pass-through ports,
and of lack of support for IEEE 1284 transfer modes.
</para>
<!-- platform differences -->
<para>
There are two layers to the <literal>parport</literal>
subsystem, only one of which deals directly with the hardware.
The other layer deals with sharing and IEEE 1284 transfer modes.
In this way, parallel support for a particular architecture comes
in the form of a module which registers itself with the generic
sharing layer.
</para>
<!-- sharing model -->
<para>
The sharing model provided by the <literal>parport</literal>
subsystem is one of exclusive access. A device driver, such as
the printer driver, must ask the <literal>parport</literal>
layer for access to the port, and can only use the port once
access has been granted. When it has finished a
<quote>transaction</quote>, it can tell the
<literal>parport</literal> layer that it may release the port
for other device drivers to use.
</para>
<!-- talk a bit about how drivers can share devices on the same port -->
<para>
Devices with pass-through ports all manage to share a parallel
port with other devices in generally the same way. The device has
a latch for each of the pins on its pass-through port. The normal
state of affairs is pass-through mode, with the device copying the
signal lines between its host port and its pass-through port.
When the device sees a special signal from the host port, it
latches the pass-through port so that devices further downstream
don't get confused by the pass-through device's conversation with
the host parallel port: the device connected to the pass-through
port (and any devices connected in turn to it) are effectively cut
off from the computer. When the pass-through device has completed
its transaction with the computer, it enables the pass-through
port again.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="parport-share" format="eps">
</imageobject>
<imageobject>
<imagedata fileref="parport-share.png" format="png">
</imageobject>
</mediaobject>
<para>
This technique relies on certain <quote>special signals</quote>
being invisible to devices that aren't watching for them. This
tends to mean only changing the data signals and leaving the
control signals alone. IEEE 1284.3 documents a standard protocol
for daisy-chaining devices together with parallel ports.
</para>
<!-- transfer modes -->
<para>
Support for standard transfer modes are provided as operations
that can be performed on a port, along with operations for setting
the data lines, or the control lines, or reading the status lines.
These operations appear to the device driver as function pointers;
more later.
</para>
</sect1>
</chapter>
<chapter id="transfermodes">
<title>Standard transfer modes</title>
<!-- Defined by IEEE, but in common use (even though there are widely -->
<!-- varying implementations). -->
<para>
The <quote>standard</quote> transfer modes in use over the parallel
port are <quote>defined</quote> by a document called IEEE 1284. It
really just codifies existing practice and documents protocols (and
variations on protocols) that have been in common use for quite
some time.
</para>
<para>
The original definitions of which pin did what were set out by
Centronics Data Computer Corporation, but only the printer-side
interface signals were specified.
</para>
<para>
By the early 1980s, IBM's host-side implementation had become the
most widely used. New printers emerged that claimed Centronics
compatibility, but although compatible with Centronics they
differed from one another in a number of ways.
</para>
<para>
As a result of this, when IEEE 1284 was published in 1994, all that
it could really do was document the various protocols that are used
for printers (there are about six variations on a theme).
</para>
<para>
In addition to the protocol used to talk to Centronics-compatible
printers, IEEE 1284 defined other protocols that are used for
unidirectional peripheral-to-host transfers (reverse nibble and
reverse byte) and for fast bidirectional transfers (ECP and
EPP).
</para>
</chapter>
<chapter id="structure">
<title>Structure</title>
<!-- Main structure
- sharing core
- parports and their IEEE 1284 overrides
- IEEE 1284 transfer modes for generic ports
- maybe mention muxes here
- pardevices
- IEEE 1284.3 API
-->
<mediaobject>
<imageobject>
<imagedata fileref="parport-structure" format="eps">
</imageobject>
<imageobject>
<imagedata fileref="parport-structure.png" format="png">
</imageobject>
</mediaobject>
<sect1>
<title>Sharing core</title>
<para>
At the core of the <literal>parport</literal> subsystem is the
sharing mechanism (see
<filename>drivers/parport/share.c</filename>). This module,
<literal>parport</literal>, is responsible for keeping track of
which ports there are in the system, which device drivers might be
interested in new ports, and whether or not each port is available
for use (or if not, which driver is currently using it).
</para>
</sect1>
<sect1>
<title>Parports and their overrides</title>
<para>
The generic <literal>parport</literal> sharing code doesn't
directly handle the parallel port hardware. That is done instead
by <quote>low-level</quote> <literal>parport</literal> drivers.
The function of a low-level <literal>parport</literal> driver is
to detect parallel ports, register them with the sharing code, and
provide a list of access functions for each port.
</para>
<para>
The most basic access functions that must be provided are ones for
examining the status lines, for setting the control lines, and for
setting the data lines. There are also access functions for
setting the direction of the data lines; normally they are in the
<quote>forward</quote> direction (that is, the computer drives
them), but some ports allow switching to <quote>reverse</quote>
mode (driven by the peripheral). There is an access function for
examining the data lines once in reverse mode.
</para>
</sect1>
<sect1>
<title>IEEE 1284 transfer modes</title>
<para>
Stacked on top of the sharing mechanism, but still in the
<literal>parport</literal> module, are functions for
transferring data. They are provided for the device drivers to
use, and are very much like library routines. Since these
transfer functions are provided by the generic
<literal>parport</literal> core they must use the <quote>lowest
common denominator</quote> set of access functions: they can set
the control lines, examine the status lines, and use the data
lines. With some parallel ports the data lines can only be set
and not examined, and with other ports accessing the data register
causes control line activity; with these types of situations, the
IEEE 1284 transfer functions make a best effort attempt to do the
right thing. In some cases, it is not physically possible to use
particular IEEE 1284 transfer modes.
</para>
<para>
The low-level <literal>parport</literal> drivers also provide
IEEE 1284 transfer functions, as names in the access function
list. The low-level driver can just name the generic IEEE 1284
transfer functions for this. Some parallel ports can do IEEE 1284
transfers in hardware; for those ports, the low-level driver can
provide functions to utilise that feature.
</para>
</sect1>
<!-- muxes? -->
<sect1>
<title>Pardevices and parport_drivers</title>
<para>
When a parallel port device driver (such as
<literal>lp</literal>) initialises it tells the sharing layer
about itself using <function>parport_register_driver</function>.
The information is put into a <structname>struct
parport_driver</structname>, which is put into a linked list. The
information in a <structname>struct parport_driver</structname>
really just amounts to some function pointers to callbacks in the
parallel port device driver.
</para>
<para>
During its initialisation, a low-level port driver tells the
sharing layer about all the ports that it has found (using
<function>parport_register_port</function>), and the sharing layer
creates a <structname>struct parport</structname> for each of
them. Each <structname>struct parport</structname> contains
(among other things) a pointer to a <structname>struct
parport_operations</structname>, which is a list of function
pointers for the various operations that can be performed on a
port. You can think of a <structname>struct parport</structname>
as a parallel port <quote>object</quote>, if
<quote>object-orientated</quote> programming is your thing. The
<structname>parport</structname> structures are chained in a
linked list, whose head is <varname>portlist</varname> (in
<filename>drivers/parport/share.c</filename>).
</para>
<para>
Once the port has been registered, the low-level port driver
announces it. The <function>parport_announce_port</function>
function walks down the list of parallel port device drivers
(<structname>struct parport_driver</structname>s) calling the
<function>attach</function> function of each (which may block).
</para>
<para>
Similarly, a low-level port driver can undo the effect of
registering a port with the
<function>parport_unregister_port</function> function, and device
drivers are notified using the <function>detach</function>
callback (which may not block).
</para>
<para>
Device drivers can undo the effect of registering themselves with
the <function>parport_unregister_driver</function>
function.
</para>
</sect1>
<!-- IEEE 1284.3 API -->
<sect1>
<title>The IEEE 1284.3 API</title>
<para>
The ability to daisy-chain devices is very useful, but if every
device does it in a different way it could lead to lots of
complications for device driver writers. Fortunately, the IEEE
are standardising it in IEEE 1284.3, which covers daisy-chain
devices and port multiplexors.
</para>
<para>
At the time of writing, IEEE 1284.3 has not been published, but
the draft specifies the on-the-wire protocol for daisy-chaining
and multiplexing, and also suggests a programming interface for
using it. That interface (or most of it) has been implemented in
the <literal>parport</literal> code in Linux.
</para>
<para>
At initialisation of the parallel port <quote>bus</quote>,
daisy-chained devices are assigned addresses starting from zero.
There can only be four devices with daisy-chain addresses, plus
one device on the end that doesn't know about daisy-chaining and
thinks it's connected directly to a computer.
</para>
<para>
Another way of connecting more parallel port devices is to use a
multiplexor. The idea is to have a device that is connected
directly to a parallel port on a computer, but has a number of
parallel ports on the other side for other peripherals to connect
to (two or four ports are allowed). The multiplexor switches
control to different ports under software control---it is, in
effect, a programmable printer switch.
</para>
<para>
Combining the ability of daisy-chaining five devices together with
the ability to multiplex one parallel port between four gives the
potential to have twenty peripherals connected to the same
parallel port!
</para>
<para>
In addition, of course, a single computer can have multiple
parallel ports. So, each parallel port peripheral in the system
can be identified with three numbers, or co-ordinates: the
parallel port, the multiplexed port, and the daisy-chain
address.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="parport-multi" format="eps">
</imageobject>
<imageobject>
<imagedata fileref="parport-multi.png" format="png">
</imageobject>
</mediaobject>
<para>
Each device in the system is numbered at initialisation (by
<function>parport_daisy_init</function>). You can convert between
this device number and its co-ordinates with
<function>parport_device_num</function> and
<function>parport_device_coords</function>.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_device_num</function></funcdef>
<paramdef>int <parameter>parport</parameter></paramdef>
<paramdef>int <parameter>mux</parameter></paramdef>
<paramdef>int <parameter>daisy</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_device_coords</function></funcdef>
<paramdef>int <parameter>devnum</parameter></paramdef>
<paramdef>int *<parameter>parport</parameter></paramdef>
<paramdef>int *<parameter>mux</parameter></paramdef>
<paramdef>int *<parameter>daisy</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Any parallel port peripheral will be connected directly or
indirectly to a parallel port on the system, but it won't have a
daisy-chain address if it does not know about daisy-chaining, and
it won't be connected through a multiplexor port if there is no
multiplexor. The special co-ordinate value
<constant>-1</constant> is used to indicate these cases.
</para>
<para>
Two functions are provided for finding devices based on their IEEE
1284 Device ID: <function>parport_find_device</function> and
<function>parport_find_class</function>.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_find_device</function></funcdef>
<paramdef>const char *<parameter>mfg</parameter></paramdef>
<paramdef>const char *<parameter>mdl</parameter></paramdef>
<paramdef>int <parameter>from</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_find_class</function></funcdef>
<paramdef>parport_device_class <parameter>cls</parameter></paramdef>
<paramdef>int <parameter>from</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
These functions take a device number (in addition to some other
things), and return another device number. They walk through the
list of detected devices until they find one that matches the
requirements, and then return that device number (or
<constant>-1</constant> if there are no more such devices). They
start their search at the device after the one in the list with
the number given (at <parameter>from</parameter>+1, in other
words).
</para>
</sect1>
</chapter>
<chapter id="drivers">
<title>Device driver's view</title>
<!-- Cover:
- sharing interface, preemption, interrupts, wakeups...
- IEEE 1284.3 interface
- port operations
- why can read data but ctr is faked, etc.
-->
<!-- I should take a look at the kernel hackers' guide bit I wrote, -->
<!-- as that deals with a lot of this. The main complaint with it -->
<!-- was that there weren't enough examples, but 'The printer -->
<!-- driver' should deal with that later; might be worth mentioning -->
<!-- in the text. -->
<para>
This section is written from the point of view of the device driver
programmer, who might be writing a driver for a printer or a
scanner or else anything that plugs into the parallel port. It
explains how to use the <literal>parport</literal> interface to
find parallel ports, use them, and share them with other device
drivers.
</para>
<para>
We'll start out with a description of the various functions that
can be called, and then look at a reasonably simple example of
their use: the printer driver.
</para>
<para>
The interactions between the device driver and the
<literal>parport</literal> layer are as follows. First, the
device driver registers its existence with
<literal>parport</literal>, in order to get told about any
parallel ports that have been (or will be) detected. When it gets
told about a parallel port, it then tells
<literal>parport</literal> that it wants to drive a device on
that port. Thereafter it can claim exclusive access to the port in
order to talk to its device.
</para>
<para>
So, the first thing for the device driver to do is tell
<literal>parport</literal> that it wants to know what parallel
ports are on the system. To do this, it uses the
<function>parport_register_device</function> function:
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
struct parport_driver {
const char *name;
void (*attach) (struct parport *);
void (*detach) (struct parport *);
struct parport_driver *next;
};
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_register_driver</function></funcdef>
<paramdef>struct parport_driver *<parameter>driver</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
In other words, the device driver passes pointers to a couple of
functions to <literal>parport</literal>, and
<literal>parport</literal> calls <function>attach</function> for
each port that's detected (and <function>detach</function> for each
port that disappears---yes, this can happen).
</para>
<para>
The next thing that happens is that the device driver tells
<literal>parport</literal> that it thinks there's a device on the
port that it can drive. This typically will happen in the driver's
<function>attach</function> function, and is done with
<function>parport_register_device</function>:
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>struct pardevice *<function>parport_register_device</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>(*pf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>void <parameter>(*kf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>void <parameter>(*irq_func)</parameter>
<funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>handle</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <parameter>port</parameter> comes from the parameter supplied
to the <function>attach</function> function when it is called, or
alternatively can be found from the list of detected parallel ports
directly with the (now deprecated)
<function>parport_enumerate</function> function. A better way of
doing this is with <function>parport_find_number</function> or
<function>parport_find_base</function> functions, which find ports
by number and by base I/O address respectively.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>struct parport *<function>parport_find_number</function></funcdef>
<paramdef>int <parameter>number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>struct parport *<function>parport_find_base</function></funcdef>
<paramdef>unsigned long <parameter>base</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The next three parameters, <parameter>pf</parameter>,
<parameter>kf</parameter>, and <parameter>irq_func</parameter>, are
more function pointers. These callback functions get called under
various circumstances, and are always given the
<parameter>handle</parameter> as one of their parameters.
</para>
<para>
The preemption callback, <parameter>pf</parameter>, is called when
the driver has claimed access to the port but another device driver
wants access. If the driver is willing to let the port go, it
should return zero and the port will be released on its behalf.
There is no need to call <function>parport_release</function>. If
<parameter>pf</parameter> gets called at a bad time for letting the
port go, it should return non-zero and no action will be taken. It
is good manners for the driver to try to release the port at the
earliest opportunity after its preemption callback is
called.
</para>
<para>
The <quote>kick</quote> callback, <parameter>kf</parameter>, is
called when the port can be claimed for exclusive access; that is,
<function>parport_claim</function> is guaranteed to succeed inside
the <quote>kick</quote> callback. If the driver wants to claim the
port it should do so; otherwise, it need not take any
action.
</para>
<para>
The <parameter>irq_func</parameter> callback is called,
predictably, when a parallel port interrupt is generated. But it
is not the only code that hooks on the interrupt. The sequence is
this: the lowlevel driver is the one that has done
<function>request_irq</function>; it then does whatever
hardware-specific things it needs to do to the parallel port
hardware (for PC-style ports, there is nothing special to do); it
then tells the IEEE 1284 code about the interrupt, which may
involve reacting to an IEEE 1284 event, depending on the current
IEEE 1284 phase; and finally the <parameter>irq_func</parameter>
function is called.
</para>
<para>
None of the callback functions are allowed to block.
</para>
<para>
The <parameter>flags</parameter> are for telling
<literal>parport</literal> any requirements or hints that are
useful. The only useful value here (other than
<constant>0</constant>, which is the usual value) is
<constant>PARPORT_DEV_EXCL</constant>. The point of that flag is
to request exclusive access at all times---once a driver has
successfully called <function>parport_register_device</function>
with that flag, no other device drivers will be able to register
devices on that port (until the successful driver deregisters its
device, of course).
</para>
<para>
The <constant>PARPORT_DEV_EXCL</constant> flag is for preventing
port sharing, and so should only be used when sharing the port with
other device drivers is impossible and would lead to incorrect
behaviour. Use it sparingly!
</para>
<para>
Devices can also be registered by device drivers based on their
device numbers (the same device numbers as in the previous
section).
</para>
<para>
The <function>parport_open</function> function is similar to
<function>parport_register_device</function>, and
<function>parport_close</function> is the equivalent of
<function>parport_unregister_device</function>. The difference is
that <function>parport_open</function> takes a device number rather
than a pointer to a <structname>struct parport</structname>.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>struct pardevice *<function>parport_open</function></funcdef>
<paramdef>int <parameter>devnum</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>(*pf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>int <parameter>(*kf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>int <parameter>(*irqf)</parameter>
<funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>handle</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>parport_close</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>struct pardevice *<function>parport_register_device</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>(*pf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>int <parameter>(*kf)</parameter>
<funcparams>void *</funcparams></paramdef>
<paramdef>int <parameter>(*irqf)</parameter>
<funcparams>int, void *, struct pt_regs *</funcparams></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>handle</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>parport_unregister_device</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The intended use of these functions is during driver initialisation
while the driver looks for devices that it supports, as
demonstrated by the following code fragment:
</para>
<programlisting>
<![CDATA[
int devnum = -1;
while ((devnum = parport_find_class (PARPORT_CLASS_DIGCAM,
devnum)) != -1) {
struct pardevice *dev = parport_open (devnum, ...);
...
}
]]></programlisting>
<para>
Once your device driver has registered its device and been handed a
pointer to a <structname>struct pardevice</structname>, the next
thing you are likely to want to do is communicate with the device
you think is there. To do that you'll need to claim access to the
port.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_claim</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_claim_or_block</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>parport_release</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
To claim access to the port, use <function>parport_claim</function>
or <function>parport_claim_or_block</function>. The first of these
will not block, and so can be used from interrupt context. If
<function>parport_claim</function> succeeds it will return zero and
the port is available to use. It may fail (returning non-zero) if
the port is in use by another driver and that driver is not willing
to relinquish control of the port.
</para>
<para>
The other function, <function>parport_claim_or_block</function>,
will block if necessary to wait for the port to be free. If it
slept, it returns <constant>1</constant>; if it succeeded without
needing to sleep it returns <constant>0</constant>. If it fails it
will return a negative error code.
</para>
<para>
When you have finished communicating with the device, you can give
up access to the port so that other drivers can communicate with
their devices. The <function>parport_release</function> function
cannot fail, but it should not be called without the port claimed.
Similarly, you should not try to claim the port if you already have
it claimed.
</para>
<para>
You may find that although there are convenient points for your
driver to relinquish the parallel port and allow other drivers to
talk to their devices, it would be preferable to keep hold of the
port. The printer driver only needs the port when there is data to
print, for example, but a network driver (such as PLIP) could be
sent a remote packet at any time. With PLIP, it is no huge
catastrophe if a network packet is dropped, since it will likely be
sent again, so it is possible for that kind of driver to share the
port with other (pass-through) devices.
</para>
<para>
The <function>parport_yield</function> and
<function>parport_yield_blocking</function> functions are for
marking points in the driver at which other drivers may claim the
port and use their devices. Yielding the port is similar to
releasing it and reclaiming it, but is more efficient because
nothing is done if there are no other devices needing the port. In
fact, nothing is done even if there are other devices waiting but
the current device is still within its <quote>timeslice</quote>.
The default timeslice is half a second, but it can be adjusted via
a <filename>/proc</filename> entry.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_yield</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_yield_blocking</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The first of these, <function>parport_yield</function>, will not
block but as a result may fail. The return value for
<function>parport_yield</function> is the same as for
<function>parport_claim</function>. The blocking version,
<function>parport_yield_blocking</function>, has the same return
code as <function>parport_claim_or_block</function>.
</para>
<para>
Once the port has been claimed, the device driver can use the
functions in the <structname>struct parport_operations</structname>
pointer in the <structname>struct parport</structname> it has a
pointer to. For example:
</para>
<programlisting>
<![CDATA[
port->ops->write_data (port, d);
]]></programlisting>
<para>
Some of these operations have <quote>shortcuts</quote>. For
instance, <function>parport_write_data</function> is equivalent to
the above, but may be a little bit faster (it's a macro that in
some cases can avoid needing to indirect through
<varname>port</varname> and <varname>ops</varname>).
</para>
</chapter>
<chapter id="portdrivers">
<title>Port drivers</title>
<!-- What port drivers are for (i.e. implementing parport objects). -->
<para>
To recap, then:</para>
<itemizedlist spacing=compact>
<listitem>
<para>
The device driver registers itself with <literal>parport</literal>.
</para>
</listitem>
<listitem>
<para>
A low-level driver finds a parallel port and registers it with
<literal>parport</literal> (these first two things can happen
in either order). This registration creates a <structname>struct
parport</structname> which is linked onto a list of known ports.
</para>
</listitem>
<listitem>
<para>
<literal>parport</literal> calls the
<function>attach</function> function of each registered device
driver, passing it the pointer to the new <structname>struct
parport</structname>.
</para>
</listitem>
<listitem>
<para>
The device driver gets a handle from
<literal>parport</literal>, for use with
<function>parport_claim</function>/<function>release</function>.
This handle takes the form of a pointer to a <structname>struct
pardevice</structname>, representing a particular device on the
parallel port, and is acquired using
<function>parport_register_device</function>.
</para>
</listitem>
<listitem>
<para>
The device driver claims the port using
<function>parport_claim</function> (or
<function>function_claim_or_block</function>).
</para>
</listitem>
<listitem>
<para>
Then it goes ahead and uses the port. When finished it releases
the port.
</para>
</listitem>
</itemizedlist>
<para>
The purpose of the low-level drivers, then, is to detect parallel
ports and provide methods of accessing them (i.e. implementing the
operations in <structname>struct
parport_operations</structname>).
</para>
<!-- Should DocBookise this -->
<para>
A more complete description of which operation is supposed to do
what is available in
<filename>Documentation/parport-lowlevel.txt</filename>.
</para>
</chapter>
<chapter id="lp">
<title>The printer driver</title>
<!-- Talk the reader through the printer driver. -->
<!-- Could even talk about parallel port console here. -->
<para>
The printer driver, <literal>lp</literal> is a character special
device driver and a <literal>parport</literal> client. As a
character special device driver it registers a <structname>struct
file_operations</structname> using
<function>register_chrdev</function>, with pointers filled in for
<structfield>write</structfield>, <structfield>ioctl</structfield>,
<structfield>open</structfield> and
<structfield>release</structfield>. As a client of
<literal>parport</literal>, it registers a <structname>struct
parport_driver</structname> using
<function>parport_register_driver</function>, so that
<literal>parport</literal> knows to call
<function>lp_attach</function> when a new parallel port is
discovered (and <function>lp_detach</function> when it goes
away).
</para>
<para>
The parallel port console functionality is also implemented in
<filename>drivers/char/lp.c</filename>, but that won't be covered
here (it's quite simple though).
</para>
<para>
The initialisation of the driver is quite easy to understand (see
<function>lp_init</function>). The <varname>lp_table</varname> is
an array of structures that contain information about a specific
device (the <structname>struct pardevice</structname> associated
with it, for example). That array is initialised to sensible
values first of all.
</para>
<para>
Next, the printer driver calls <function>register_chrdev</function>
passing it a pointer to <varname>lp_fops</varname>, which contains
function pointers for the printer driver's implementation of
<function>open</function>, <function>write</function>, and so on.
This part is the same as for any character special device
driver.
</para>
<para>
After successfully registering itself as a character special device
driver, the printer driver registers itself as a
<literal>parport</literal> client using
<function>parport_register_driver</function>. It passes a pointer
to this structure:
</para>
<programlisting>
<![CDATA[
static struct parport_driver lp_driver = {
"lp",
lp_attach,
lp_detach,
NULL
};
]]></programlisting>
<para>
The <function>lp_detach</function> function is not very interesting
(it does nothing); the interesting bit is
<function>lp_attach</function>. What goes on here depends on
whether the user supplied any parameters. The possibilities are:
no parameters supplied, in which case the printer driver uses every
port that is detected; the user supplied the parameter
<quote>auto</quote>, in which case only ports on which the device
ID string indicates a printer is present are used; or the user
supplied a list of parallel port numbers to try, in which case only
those are used.
</para>
<para>
For each port that the printer driver wants to use (see
<function>lp_register</function>), it calls
<function>parport_register_device</function> and stores the
resulting <structname>struct pardevice</structname> pointer in the
<varname>lp_table</varname>. If the user told it to do so, it then
resets the printer.
</para>
<para>
The other interesting piece of the printer driver, from the point
of view of <literal>parport</literal>, is
<function>lp_write</function>. In this function, the user space
process has data that it wants printed, and the printer driver
hands it off to the <literal>parport</literal> code to deal with.
</para>
<para>
The <literal>parport</literal> functions it uses that we have not
seen yet are <function>parport_negotiate</function>,
<function>parport_set_timeout</function>, and
<function>parport_write</function>. These functions are part of
the IEEE 1284 implementation.
</para>
<para>
The way the IEEE 1284 protocol works is that the host tells the
peripheral what transfer mode it would like to use, and the
peripheral either accepts that mode or rejects it; if the mode is
rejected, the host can try again with a different mode. This is
the negotation phase. Once the peripheral has accepted a
particular transfer mode, data transfer can begin that mode.
</para>
<para>
The particular transfer mode that the printer driver wants to use
is named in IEEE 1284 as <quote>compatibility</quote> mode, and the
function to request a particular mode is called
<function>parport_negotiate</function>.
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_negotiate</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <parameter>modes</parameter> parameter is a symbolic constant
representing an IEEE 1284 mode; in this instance, it is
<constant>IEEE1284_MODE_COMPAT</constant>. (Compatibility mode is
slightly different to the other modes---rather than being
specifically requested, it is the default until another mode is
selected.)
</para>
<para>
Back to <function>lp_write</function> then. First, access to the
parallel port is secured with
<function>parport_claim_or_block</function>. At this point the
driver might sleep, waiting for another driver (perhaps a Zip drive
driver, for instance) to let the port go. Next, it goes to
compatibility mode using <function>parport_negotiate</function>.
</para>
<para>
The main work is done in the write-loop. In particular, the line
that hands the data over to <literal>parport</literal> reads:
</para>
<programlisting>
<![CDATA[
written = parport_write (port, kbuf, copy_size);
]]></programlisting>
<para>
The <function>parport_write</function> function writes data to the
peripheral using the currently selected transfer mode
(compatibility mode, in this case). It returns the number of bytes
successfully written:
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t <function>parport_write</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>const void *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>ssize_t <function>parport_read</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>void *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
(<function>parport_read</function> does what it sounds like, but
only works for modes in which reverse transfer is possible. Of
course, <function>parport_write</function> only works in modes in
which forward transfer is possible, too.)
</para>
<para>
The <parameter>buf</parameter> pointer should be to kernel space
memory, and obviously the <parameter>len</parameter> parameter
specifies the amount of data to transfer.
</para>
<para>
In fact what <function>parport_write</function> does is call the
appropriate block transfer function from the <structname>struct
parport_operations</structname>:
</para>
<programlisting>
<![CDATA[
struct parport_operations {
[...]
/* Block read/write */
size_t (*epp_write_data) (struct parport *port,
const void *buf,
size_t len, int flags);
size_t (*epp_read_data) (struct parport *port,
void *buf, size_t len,
int flags);
size_t (*epp_write_addr) (struct parport *port,
const void *buf,
size_t len, int flags);
size_t (*epp_read_addr) (struct parport *port,
void *buf, size_t len,
int flags);
size_t (*ecp_write_data) (struct parport *port,
const void *buf,
size_t len, int flags);
size_t (*ecp_read_data) (struct parport *port,
void *buf, size_t len,
int flags);
size_t (*ecp_write_addr) (struct parport *port,
const void *buf,
size_t len, int flags);
size_t (*compat_write_data) (struct parport *port,
const void *buf,
size_t len, int flags);
size_t (*nibble_read_data) (struct parport *port,
void *buf, size_t len,
int flags);
size_t (*byte_read_data) (struct parport *port,
void *buf, size_t len,
int flags);
};
]]></programlisting>
<para>
The transfer code in <literal>parport</literal> will tolerate a
data transfer stall only for so long, and this timeout can be
specified with <function>parport_set_timeout</function>, which
returns the previous timeout:
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>long <function>parport_set_timeout</function></funcdef>
<paramdef>struct pardevice *<parameter>dev</parameter></paramdef>
<paramdef>long <parameter>inactivity</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This timeout is specific to the device, and is restored on
<function>parport_claim</function>.
</para>
<para>
The next function to look at is the one that allows processes to
read from <filename>/dev/lp0</filename>:
<function>lp_read</function>. It's short, like
<function>lp_write</function>.
</para>
<para>
The semantics of reading from a line printer device are as follows:
</para>
<itemizedlist>
<listitem>
<para>
Switch to reverse nibble mode.
</para>
</listitem>
<listitem>
<para>
Try to read data from the peripheral using reverse nibble mode,
until either the user-provided buffer is full or the peripheral
indicates that there is no more data.
</para>
</listitem>
<listitem>
<para>
If there was data, stop, and return it.
</para>
</listitem>
<listitem>
<para>
Otherwise, we tried to read data and there was none. If the user
opened the device node with the <constant>O_NONBLOCK</constant>
flag, return. Otherwise wait until an interrupt occurs on the
port (or a timeout elapses).
</para>
</listitem>
</itemizedlist>
</chapter>
<chapter id="ppdev">
<title>User-level device drivers</title>
<!-- ppdev -->
<sect1>
<title>Introduction to ppdev</title>
<para>
The printer is accessible through <filename>/dev/lp0</filename>;
in the same way, the parallel port itself is accessible through
<filename>/dev/parport0</filename>. The difference is in the
level of control that you have over the wires in the parallel port
cable.
</para>
<para>
With the printer driver, a user-space program (such as the printer
spooler) can send bytes in <quote>printer protocol</quote>.
Briefly, this means that for each byte, the eight data lines are
set up, then a <quote>strobe</quote> line tells the printer to
look at the data lines, and the printer sets an
<quote>acknowledgement</quote> line to say that it got the byte.
The printer driver also allows the user-space program to read
bytes in <quote>nibble mode</quote>, which is a way of
transferring data from the peripheral to the computer half a byte
at a time (and so it's quite slow).
</para>
<para>
In contrast, the <literal>ppdev</literal> driver (accessed via
<filename>/dev/parport0</filename>) allows you to:
</para>
<itemizedlist spacing=compact>
<listitem>
<para>
examine status lines,
</para>
</listitem>
<listitem>
<para>
set control lines,
</para>
</listitem>
<listitem>
<para>
set/examine data lines (and control the direction of the data
lines),
</para>
</listitem>
<listitem>
<para>
wait for an interrupt (triggered by one of the status lines),
</para>
</listitem>
<listitem>
<para>
find out how many new interrupts have occurred,
</para>
</listitem>
<listitem>
<para>
set up a response to an interrupt,
</para>
</listitem>
<listitem>
<para>
use IEEE 1284 negotiation (for telling peripheral which transfer
mode, to use)
</para>
</listitem>
<listitem>
<para>
transfer data using a specified IEEE 1284 mode.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>User-level or kernel-level driver?</title>
<para>
The decision of whether to choose to write a kernel-level device
driver or a user-level device driver depends on several factors.
One of the main ones from a practical point of view is speed:
kernel-level device drivers get to run faster because they are not
preemptable, unlike user-level applications.
</para>
<para>
Another factor is ease of development. It is in general easier to
write a user-level driver because (a) one wrong move does not
result in a crashed machine, (b) you have access to user libraries
(such as the C library), and (c) debugging is easier.
</para>
</sect1>
<sect1>
<title>Programming interface</title>
<para>
The <literal>ppdev</literal> interface is largely the same as that
of other character special devices, in that it supports
<function>open</function>, <function>close</function>,
<function>read</function>, <function>write</function>, and
<function>ioctl</function>. The constants for the
<function>ioctl</function> commands are in
<filename>include/linux/ppdev.h</filename>.
</para>
<sect2>
<title>
Starting and stopping: <function>open</function> and
<function>close</function>
</title>
<para>
The device node <filename>/dev/parport0</filename> represents any
device that is connected to <filename>parport0</filename>, the
first parallel port in the system. Each time the device node is
opened, it represents (to the process doing the opening) a
different device. It can be opened more than once, but only one
instance can actually be in control of the parallel port at any
time. A process that has opened
<filename>/dev/parport0</filename> shares the parallel port in
the same way as any other device driver. A user-land driver may
be sharing the parallel port with in-kernel device drivers as
well as other user-land drivers.
</para>
</sect2>
<sect2>
<title>Control: <function>ioctl</function></title>
<para>
Most of the control is done, naturally enough, via the
<function>ioctl</function> call. Using
<function>ioctl</function>, the user-land driver can control both
the <literal>ppdev</literal> driver in the kernel and the
physical parallel port itself. The <function>ioctl</function>
call takes as parameters a file descriptor (the one returned from
opening the device node), a command, and optionally (a pointer
to) some data.
</para>
<variablelist>
<varlistentry><term><constant>PPCLAIM</constant></term>
<listitem>
<para>
Claims access to the port. As a user-land device driver
writer, you will need to do this before you are able to
actually change the state of the parallel port in any way.
Note that some operations only affect the
<literal>ppdev</literal> driver and not the port, such as
<constant>PPSETMODE</constant>; they can be performed while
access to the port is not claimed.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPEXCL</constant></term>
<listitem>
<para>
Instructs the kernel driver to forbid any sharing of the port
with other drivers, i.e. it requests exclusivity. The
<constant>PPEXCL</constant> command is only valid when the
port is not already claimed for use, and it may mean that the
next <constant>PPCLAIM</constant> <function>ioctl</function>
will fail: some other driver may already have registered
itself on that port.
</para>
<para>
Most device drivers don't need exclusive access to the port.
It's only provided in case it is really needed, for example
for devices where access to the port is required for extensive
periods of time (many seconds).
</para>
<para>
Note that the <constant>PPEXCL</constant>
<function>ioctl</function> doesn't actually claim the port
there and then---action is deferred until the
<constant>PPCLAIM</constant> <function>ioctl</function> is
performed.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPRELEASE</constant></term>
<listitem>
<para>
Releases the port. Releasing the port undoes the effect of
claiming the port. It allows other device drivers to talk to
their devices (assuming that there are any).
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPYIELD</constant></term>
<listitem>
<para>
Yields the port to another driver. This
<function>ioctl</function> is a kind of short-hand for
releasing the port and immediately reclaiming it. It gives
other drivers a chance to talk to their devices, but
afterwards claims the port back. An example of using this
would be in a user-land printer driver: once a few characters
have been written we could give the port to another device
driver for a while, but if we still have characters to send to
the printer we would want the port back as soon as possible.
</para>
<para>
It is important not to claim the parallel port for too long,
as other device drivers will have no time to service their
devices. If your device does not allow for parallel port
sharing at all, it is better to claim the parallel port
exclusively (see <constant>PPEXCL</constant>).
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPNEGOT</constant></term>
<listitem>
<para>
Performs IEEE 1284 negotiation into a particular mode.
Briefly, negotiation is the method by which the host and the
peripheral decide on a protocol to use when transferring data.
</para>
<para>
An IEEE 1284 compliant device will start out in compatibility
mode, and then the host can negotiate to another mode (such as
ECP).
</para>
<para>
The <function>ioctl</function> parameter should be a pointer
to an <type>int</type>; values for this are in
<filename>incluce/linux/parport.h</filename> and include:
</para>
<itemizedlist spacing=compact>
<listitem><para>
<constant>IEEE1284_MODE_COMPAT</constant></para></listitem>
<listitem><para>
<constant>IEEE1284_MODE_NIBBLE</constant></para></listitem>
<listitem><para>
<constant>IEEE1284_MODE_BYTE</constant></para></listitem>
<listitem><para>
<constant>IEEE1284_MODE_EPP</constant></para></listitem>
<listitem><para>
<constant>IEEE1284_MODE_ECP</constant></para></listitem>
</itemizedlist>
<para>
The <constant>PPNEGOT</constant> <function>ioctl</function>
actually does two things: it performs the on-the-wire
negotiation, and it sets the behaviour of subsequent
<function>read</function>/<function>write</function> calls so
that they use that mode (but see
<constant>PPSETMODE</constant>).
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPSETMODE</constant></term>
<listitem>
<para>
Sets which IEEE 1284 protocol to use for the
<function>read</function> and <function>write</function>
calls.
</para>
<para>
The <function>ioctl</function> parameter should be a pointer
to an <type>int</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPGETMODE</constant></term>
<listitem>
<para>
Retrieves the current IEEE 1284 mode to use for
<function>read</function> and <function>write</function>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPGETTIME</constant></term>
<listitem>
<para>
Retrieves the time-out value. The <function>read</function>
and <function>write</function> calls will time out if the
peripheral doesn't respond quickly enough. The
<constant>PPGETTIME</constant> <function>ioctl</function>
retrieves the length of time that the peripheral is allowed to
have before giving up.
</para>
<para>
The <function>ioctl</function> parameter should be a pointer
to a <structname>struct timeval</structname>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPSETTIME</constant></term>
<listitem>
<para>
Sets the time-out. The <function>ioctl</function> parameter
should be a pointer to a <structname>struct
timeval</structname>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPGETMODES</constant></term>
<listitem>
<para>
Retrieves the capabilities of the hardware (i.e. the
<structfield>modes</structfield> field of the
<structname>parport</structname> structure).
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPSETFLAGS</constant></term>
<listitem>
<para>
Sets flags on the <literal>ppdev</literal> device which can
affect future I/O operations. Available flags are:
</para>
<itemizedlist spacing=compact>
<listitem><para>
<constant>PP_FASTWRITE</constant></para></listitem>
<listitem><para>
<constant>PP_FASTREAD</constant></para></listitem>
<listitem><para>
<constant>PP_W91284PIC</constant></para></listitem>
</itemizedlist>
</listitem></varlistentry>
<varlistentry><term><constant>PPWCONTROL</constant></term>
<listitem>
<para>
Sets the control lines. The <function>ioctl</function>
parameter is a pointer to an <type>unsigned char</type>, the
bitwise OR of the control line values in
<filename>include/linux/parport.h</filename>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPRCONTROL</constant></term>
<listitem>
<para>
Returns the last value written to the control register, in the
form of an <type>unsigned char</type>: each bit corresponds to
a control line (although some are unused). The
<function>ioctl</function> parameter should be a pointer to an
<type>unsigned char</type>.
</para>
<para>
This doesn't actually touch the hardware; the last value
written is remembered in software. This is because some
parallel port hardware does not offer read access to the
control register.
</para>
<para>
The control lines bits are defined in
<filename>include/linux/parport.h</filename>:
</para>
<itemizedlist spacing=compact>
<listitem><para>
<constant>PARPORT_CONTROL_STROBE</constant></para></listitem>
<listitem><para>
<constant>PARPORT_CONTROL_AUTOFD</constant></para></listitem>
<listitem><para>
<constant>PARPORT_CONTROL_SELECT</constant></para></listitem>
<listitem><para>
<constant>PARPORT_CONTROL_INIT</constant></para></listitem>
</itemizedlist>
</listitem></varlistentry>
<varlistentry><term><constant>PPFCONTROL</constant></term>
<listitem>
<para>
Frobs the control lines. Since a common operation is to
change one of the control signals while leaving the others
alone, it would be quite inefficient for the user-land driver
to have to use <constant>PPRCONTROL</constant>, make the
change, and then use <constant>PPWCONTROL</constant>. Of
course, each driver could remember what state the control
lines are supposed to be in (they are never changed by
anything else), but in order to provide
<constant>PPRCONTROL</constant>, <literal>ppdev</literal>
must remember the state of the control lines anyway.
</para>
<para>
The <constant>PPFCONTROL</constant> <function>ioctl</function>
is for <quote>frobbing</quote> control lines, and is like
<constant>PPWCONTROL</constant> but acts on a restricted set
of control lines. The <function>ioctl</function> parameter is
a pointer to a <structname>struct
ppdev_frob_struct</structname>:
</para>
<programlisting>
<![CDATA[
struct ppdev_frob_struct {
unsigned char mask;
unsigned char val;
};
]]>
</programlisting>
<para>
The <structfield>mask</structfield> and
<structfield>val</structfield> fields are bitwise ORs of
control line names (such as in
<constant>PPWCONTROL</constant>). The operation performed by
<constant>PPFCONTROL</constant> is:
</para>
<programlisting>
<![CDATA[
new_ctr = (old_ctr & ~mask) | val;]]>
</programlisting>
<para>
In other words, the signals named in
<structfield>mask</structfield> are set to the values in
<structfield>val</structfield>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPRSTATUS</constant></term>
<listitem>
<para>
Returns an <type>unsigned char</type> containing bits set for
each status line that is set (for instance,
<constant>PARPORT_STATUS_BUSY</constant>). The
<function>ioctl</function> parameter should be a pointer to an
<type>unsigned char</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPDATADIR</constant></term>
<listitem>
<para>
Controls the data line drivers. Normally the computer's
parallel port will drive the data lines, but for byte-wide
transfers from the peripheral to the host it is useful to turn
off those drivers and let the peripheral drive the
signals. (If the drivers on the computer's parallel port are
left on when this happens, the port might be damaged.)
</para>
<para>
This is only needed in conjunction with
<constant>PPWDATA</constant> or
<constant>PPRDATA</constant>.
</para>
<para>
The <function>ioctl</function> parameter is a pointer to an
<type>int</type>. If the <type>int</type> is zero, the
drivers are turned on (forward direction); if non-zero, the
drivers are turned off (reverse direction).
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPWDATA</constant></term>
<listitem>
<para>
Sets the data lines (if in forward mode). The
<function>ioctl</function> parameter is a pointer to an
<type>unsigned char</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPRDATA</constant></term>
<listitem>
<para>
Reads the data lines (if in reverse mode). The
<function>ioctl</function> parameter is a pointer to an
<type>unsigned char</type>.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPCLRIRQ</constant></term>
<listitem>
<para>
Clears the interrupt count. The <literal>ppdev</literal>
driver keeps a count of interrupts as they are triggered.
<constant>PPCLRIRQ</constant> stores this count in an
<type>int</type>, a pointer to which is passed in as the
<function>ioctl</function> parameter.
</para>
<para>
In addition, the interrupt count is reset to zero.
</para>
</listitem></varlistentry>
<varlistentry><term><constant>PPWCTLONIRQ</constant></term>
<listitem>
<para>
Set a trigger response. Afterwards when an interrupt is
triggered, the interrupt handler will set the control lines as
requested. The <function>ioctl</function> parameter is a
pointer to an <type>unsigned char</type>, which is interpreted
in the same way as for <constant>PPWCONTROL</constant>.
</para>
<para>
The reason for this <function>ioctl</function> is simply
speed. Without this <function>ioctl</function>, responding to
an interrupt would start in the interrupt handler, switch
context to the user-land driver via <function>poll</function>
or <function>select</function>, and then switch context back
to the kernel in order to handle
<constant>PPWCONTROL</constant>. Doing the whole lot in the
interrupt handler is a lot faster.
</para>
</listitem></varlistentry>
<!-- PPSETPHASE? -->
</variablelist>
</sect2>
<sect2>
<title>Transferring data: <function>read</function> and
<function>write</function></title>
<para>
Transferring data using <function>read</function> and
<function>write</function> is straightforward. The data is
transferring using the current IEEE 1284 mode (see the
<constant>PPSETMODE</constant> <function>ioctl</function>). For
modes which can only transfer data in one direction, only the
appropriate function will work, of course.
</para>
</sect2>
<sect2>
<title>Waiting for events: <function>poll</function> and
<function>select</function></title>
<para>
The <literal>ppdev</literal> driver provides user-land device
drivers with the ability to wait for interrupts, and this is done
using <function>poll</function> (and <function>select</function>,
which is implemented in terms of <function>poll</function>).
</para>
<para>
When a user-land device driver wants to wait for an interrupt, it
sleeps with <function>poll</function>. When the interrupt
arrives, <literal>ppdev</literal> wakes it up (with a
<quote>read</quote> event, although strictly speaking there is
nothing to actually <function>read</function>).
</para>
</sect2>
</sect1>
<sect1>
<title>Examples</title>
<para>
Presented here are two demonstrations of how to write a simple
printer driver for <literal>ppdev</literal>. Firstly we will
use the <function>write</function> function, and after that we
will drive the control and data lines directly.
</para>
<para>
The first thing to do is to actually open the device.
</para>
<programlisting><![CDATA[
int drive_printer (const char *name)
{
int fd;
int mode; /* We'll need this later. */
fd = open (name, O_RDWR);
if (fd == -1) {
perror ("open");
return 1;
}
]]></programlisting>
<para>
Here <varname>name</varname> should be something along the lines
of <filename>"/dev/parport0"</filename>. (If you don't have any
<filename>/dev/parport</filename> files, you can make them with
<command>mknod</command>; they are character special device nodes
with major 99.)
</para>
<para>
In order to do anything with the port we need to claim access to
it.
</para>
<programlisting><![CDATA[
if (ioctl (fd, PPCLAIM)) {
perror ("PPCLAIM");
close (fd);
return 1;
}
]]></programlisting>
<para>
Our printer driver will copy its input (from
<varname>stdin</varname>) to the printer, and it can do that it
one of two ways. The first way is to hand it all off to the
kernel driver, with the knowledge that the protocol that the
printer speaks is IEEE 1284's <quote>compatibility</quote>
mode.
</para>
<programlisting><![CDATA[
/* Switch to compatibility mode. (In fact we don't need
* to do this, since we start off in compatibility mode
* anyway, but this demonstrates PPNEGOT.)
mode = IEEE1284_MODE_COMPAT;
if (ioctl (fd, PPNEGOT, &mode)) {
perror ("PPNEGOT");
close (fd);
return 1;
}
for (;;) {
char buffer[1000];
char *ptr = buffer;
size_t got;
got = read (0 /* stdin */, buffer, 1000);
if (got < 0) {
perror ("read");
close (fd);
return 1;
}
if (got == 0)
/* End of input */
break;
while (got > 0) {
int written = write_printer (fd, ptr, got);
if (written < 0) {
perror ("write");
close (fd);
return 1;
}
ptr += written;
got -= written;
}
}
]]></programlisting>
<para>
The <function>write_printer</function> function is not pictured
above. This is because the main loop that is shown can be used
for both methods of driving the printer. Here is one
implementation of <function>write_printer</function>:
</para>
<programlisting><![CDATA[
ssize_t write_printer (int fd, const void *ptr, size_t count)
{
return write (fd, ptr, count);
}
]]></programlisting>
<para>
We hand the data to the kernel-level driver (using
<function>write</function>) and it handles the printer
protocol.
</para>
<para>
Now let's do it the hard way! In this particular example there is
no practical reason to do anything other than just call
<function>write</function>, because we know that the printer talks
an IEEE 1284 protocol. On the other hand, this particular example
does not even need a user-land driver since there is already a
kernel-level one; for the purpose of this discussion, try to
imagine that the printer speaks a protocol that is not already
implemented under Linux.
</para>
<para>
So, here is the alternative implementation of
<function>write_printer</function> (for brevity, error checking
has been omitted):
</para>
<programlisting><![CDATA[
ssize_t write_printer (int fd, const void *ptr, size_t count)
{
ssize_t wrote = 0;
while (wrote < count) {
unsigned char status, control, data;
unsigned char mask = (PARPORT_STATUS_ERROR
| PARPORT_STATUS_BUSY);
unsigned char val = (PARPORT_STATUS_ERROR
| PARPORT_STATUS_BUSY);
struct ppdev_frob_struct frob;
struct timespec ts;
/* Wait for printer to be ready */
for (;;) {
ioctl (fd, PPRSTATUS, &status);
if ((status & mask) == val)
break;
ioctl (fd, PPRELEASE);
sleep (1);
ioctl (fd, PPCLAIM);
}
/* Set the data lines */
data = * ((char *) ptr)++;
ioctl (fd, PPWDATA, &data);
/* Delay for a bit */
ts.tv_sec = 0;
ts.tv_nsec = 1000;
nanosleep (&ts, NULL);
/* Pulse strobe */
frob.mask = PARPORT_CONTROL_STROBE;
frob.val = PARPORT_CONTROL_STROBE;
ioctl (fd, PPFCONTROL, &frob);
nanosleep (&ts, NULL);
/* End the pulse */
frob.val = 0;
ioctl (fd, PPFCONTROL, &frob);
nanosleep (&ts, NULL);
wrote++;
}
return wrote;
}
]]></programlisting>
<para>
To show a bit more of the <literal>ppdev</literal> interface,
here is a small piece of code that is intended to mimic the
printer's side of printer protocol.
</para>
<programlisting><![CDATA[
for (;;)
{
int irqc;
int busy = nAck | nFault;
int acking = nFault;
int ready = Busy | nAck | nFault;
char ch;
/* Set up the control lines when an interrupt happens. */
ioctl (fd, PPWCTLONIRQ, &busy);
/* Now we're ready. */
ioctl (fd, PPWCONTROL, &ready);
/* Wait for an interrupt. */
{
fd_set rfds;
FD_ZERO (&rfds);
FD_SET (fd, &rfds);
if (!select (fd + 1, &rfds, NULL, NULL, NULL))
/* Caught a signal? */
continue;
}
/* We are now marked as busy. */
/* Fetch the data. */
ioctl (fd, PPRDATA, &ch);
/* Clear the interrupt. */
ioctl (fd, PPCLRIRQ, &irqc);
if (irqc > 1)
fprintf (stderr, "Arghh! Missed %d interrupt%s!\n",
irqc - 1, irqc == 2 ? "s" : "");
/* Ack it. */
ioctl (fd, PPWCONTROL, &acking);
usleep (2);
ioctl (fd, PPWCONTROL, &busy);
putchar (ch);
}
]]></programlisting>
<para>
And here is an example (with no error checking at all) to show how
to read data from the port, using ECP mode, with optional
negotiation to ECP mode first.
</para>
<programlisting><![CDATA[
{
int fd, mode;
fd = open ("/dev/parport0", O_RDONLY | O_NOCTTY);
ioctl (fd, PPCLAIM);
mode = IEEE1284_MODE_ECP;
if (negotiate_first) {
ioctl (fd, PPNEGOT, &mode);
/* no need for PPSETMODE */
} else {
ioctl (fd, PPSETMODE, &mode);
}
/* Now do whatever we want with fd */
close (0);
dup2 (fd, 0);
if (!fork()) {
/* child */
execlp ("cat", "cat", NULL);
exit (1);
} else {
/* parent */
wait (NULL);
}
/* Okay, finished */
ioctl (fd, PPRELEASE);
close (fd);
}
]]></programlisting>
</sect1>
</chapter>
<appendix id="api">
<title>
Linux parallel port driver API reference
</title>
!Fdrivers/parport/daisy.c parport_device_num
!Fdrivers/parport/daisy.c parport_device_coords
!Fdrivers/parport/daisy.c parport_find_device
!Fdrivers/parport/daisy.c parport_find_class
!Fdrivers/parport/share.c parport_register_driver
!Fdrivers/parport/share.c parport_unregister_driver
!Fdrivers/parport/share.c parport_get_port
!Fdrivers/parport/share.c parport_put_port
!Fdrivers/parport/share.c parport_find_number parport_find_base
!Fdrivers/parport/share.c parport_register_device
!Fdrivers/parport/share.c parport_unregister_device
!Fdrivers/parport/daisy.c parport_open
!Fdrivers/parport/daisy.c parport_close
!Fdrivers/parport/share.c parport_claim
!Fdrivers/parport/share.c parport_claim_or_block
!Fdrivers/parport/share.c parport_release
!Finclude/linux/parport.h parport_yield
!Finclude/linux/parport.h parport_yield_blocking
!Fdrivers/parport/ieee1284.c parport_negotiate
!Fdrivers/parport/ieee1284.c parport_write
!Fdrivers/parport/ieee1284.c parport_read
!Fdrivers/parport/ieee1284.c parport_set_timeout
</appendix>
<appendix>
<title>
The Linux 2.2 Parallel Port Subsystem
</title>
<para>
Although the interface described in this document is largely new
with the 2.4 kernel, the sharing mechanism is available in the 2.2
kernel as well. The functions available in 2.2 are:
</para>
<itemizedlist>
<listitem>
<para>
<function>parport_register_device</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_unregister_device</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_claim</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_claim_or_block</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_release</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_yield</function>
</para>
</listitem>
<listitem>
<para>
<function>parport_yield_blocking</function>
</para>
</listitem>
</itemizedlist>
<para>
In addition, negotiation to reverse nibble mode is supported:
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_ieee1284_nibble_mode_ok</function></funcdef>
<paramdef>struct parport *<parameter>port</parameter></paramdef>
<paramdef>unsigned char <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The only valid values for <parameter>mode</parameter> are 0 (for
reverse nibble mode) and 4 (for Device ID in reverse nibble mode).
</para>
<para>
This function is obsoleted by
<function>parport_negotiate</function> in Linux 2.4, and has been
removed.
</para>
</appendix>
<appendix id="fdl">
<title>
GNU Free Documentation License
</title>
<literallayout class="monospaced">
GNU Free Documentation License
Version 1.1, March 2000
Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The "Document", below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as "you".
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML designed for human modification. Opaque formats include
PostScript, PDF, proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output
purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications",
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements"
or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications". You must delete all sections
entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http:///www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
</literallayout>
</appendix>
</book>
<!-- Local Variables: -->
<!-- sgml-indent-step: 1 -->
<!-- sgml-indent-data: 1 -->
<!-- End: -->