From: Christoph Hellwig The partportbook is licensed under the GFDL and Linus agreed to remove all GFDL licensed files in http://www.ussg.iu.edu/hypermail/linux/kernel/0306.1/1968.html. I pinged the author the first time on the 2nd of april but still didn't get a reply, then send a patch to Linus to remove it last week but linus ignored it. Here's the patch again: --- 25-akpm/Documentation/DocBook/Makefile | 21 25-akpm/Documentation/DocBook/parport-multi.fig | 51 25-akpm/Documentation/DocBook/parport-share.fig | 142 - 25-akpm/Documentation/DocBook/parport-structure.fig | 54 25-akpm/Documentation/DocBook/parportbook.tmpl | 2735 -------------------- 5 files changed, 4 insertions(+), 2999 deletions(-) diff -puN Documentation/DocBook/Makefile~remove-documentation-docbook-parportbooktmpl Documentation/DocBook/Makefile --- 25/Documentation/DocBook/Makefile~remove-documentation-docbook-parportbooktmpl 2004-04-25 21:44:32.643437400 -0700 +++ 25-akpm/Documentation/DocBook/Makefile 2004-04-25 21:44:32.652436032 -0700 @@ -7,11 +7,10 @@ # list of DOCBOOKS. DOCBOOKS := wanbook.sgml z8530book.sgml mcabook.sgml videobook.sgml \ - parportbook.sgml kernel-hacking.sgml \ - kernel-locking.sgml via-audio.sgml mousedrivers.sgml \ - deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \ - writing_usb_driver.sgml scsidrivers.sgml sis900.sgml \ - kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml \ + kernel-hacking.sgml kernel-locking.sgml via-audio.sgml \ + mousedrivers.sgml deviceiobook.sgml procfs-guide.sgml \ + tulip-user.sgml writing_usb_driver.sgml scsidrivers.sgml \ + sis900.sgml kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml \ gadget.sgml libata.sgml ### @@ -93,16 +92,6 @@ C-procfs-example2 = $(addprefix $(obj)/, $(obj)/procfs-guide.sgml: $(C-procfs-example2) ### -# The parportbook includes a few images. -# Force them to be build before the books -IMG-parportbook := parport-share.fig parport-multi.fig parport-structure.fig -IMG-parportbook2 := $(addprefix $(obj)/,$(IMG-parportbook)) -EPS-parportbook := $(patsubst %.fig,%.eps, $(IMG-parportbook2)) -PNG-parportbook := $(patsubst %.fig,%.png, $(IMG-parportbook2)) -$(obj)/parportbook.html: $(PNG-parportbook) -$(obj)/parportbook.ps $(obj)/parportbook.pdf: $(EPS-parportbook) $(PNG-parportbook) - -### # Rules to generate postscript, PDF and HTML # db2html creates a directory. Generate a html file used for timestamp @@ -194,8 +183,6 @@ clean-files := $(DOCBOOKS) \ $(patsubst %.sgml, %.pdf, $(DOCBOOKS)) \ $(patsubst %.sgml, %.html, $(DOCBOOKS)) \ $(patsubst %.sgml, %.9, $(DOCBOOKS)) \ - $(patsubst %.fig,%.eps, $(IMG-parportbook)) \ - $(patsubst %.fig,%.png, $(IMG-parportbook)) \ $(C-procfs-example) ifneq ($(wildcard $(patsubst %.html,%,$(HTML))),) diff -puN Documentation/DocBook/parportbook.tmpl~remove-documentation-docbook-parportbooktmpl Documentation/DocBook/parportbook.tmpl --- 25/Documentation/DocBook/parportbook.tmpl~remove-documentation-docbook-parportbooktmpl 2004-04-25 21:44:32.645437096 -0700 +++ 25-akpm/Documentation/DocBook/parportbook.tmpl 2004-04-25 21:44:32.668433600 -0700 @@ -1,2735 +0,0 @@ - - - - - - The Linux 2.4 Parallel Port Subsystem - - - - Tim - Waugh - -
- twaugh@redhat.com -
- - - - - - 1999-2000 - Tim Waugh - - - - - 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". - - - - - - - - Design goals - - - The problems - - - The first parallel port support for Linux came with the line - printer driver, lp. The printer driver is a - character special device, and (in Linux 2.0) had support for - writing, via write, and configuration and - statistics reporting via ioctl. - - - - 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. - - - - 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. - - - - 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 - check_region function to make sure that the - IO region associated with the parallel port was free, and then it - would call request_region to allocate it. - The Zip drive used the same mechanism. Whichever driver - initialised first would gain exclusive control of the parallel - port. - - - - 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. - - - - 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. - - - - 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). - - - - 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: compatibility, - 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 compatibility - mode (i.e. normal printer protocol) and reverse nibble - mode. - - - - - - The solutions - - - - - The parport 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. - - - - - - There are two layers to the parport - 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. - - - - - - The sharing model provided by the parport - subsystem is one of exclusive access. A device driver, such as - the printer driver, must ask the parport - layer for access to the port, and can only use the port once - access has been granted. When it has finished a - transaction, it can tell the - parport layer that it may release the port - for other device drivers to use. - - - - - - 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. - - - - - - - - - - - - - This technique relies on certain special signals - 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. - - - - - - 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. - - - - - - - - Standard transfer modes - - - - - - The standard transfer modes in use over the parallel - port are defined 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. - - - - 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. - - - - 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. - - - - 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). - - - - 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). - - - - - - Structure - - - - - - - - - - - - - - Sharing core - - - At the core of the parport subsystem is the - sharing mechanism (see - drivers/parport/share.c). This module, - parport, 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). - - - - - - Parports and their overrides - - - The generic parport sharing code doesn't - directly handle the parallel port hardware. That is done instead - by low-level parport drivers. - The function of a low-level parport driver is - to detect parallel ports, register them with the sharing code, and - provide a list of access functions for each port. - - - - 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 - forward direction (that is, the computer drives - them), but some ports allow switching to reverse - mode (driven by the peripheral). There is an access function for - examining the data lines once in reverse mode. - - - - - - IEEE 1284 transfer modes - - - Stacked on top of the sharing mechanism, but still in the - parport 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 - parport core they must use the lowest - common denominator 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. - - - - The low-level parport 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. - - - - - - - - Pardevices and parport_drivers - - - When a parallel port device driver (such as - lp) initialises it tells the sharing layer - about itself using parport_register_driver. - The information is put into a struct - parport_driver, which is put into a linked list. The - information in a struct parport_driver - really just amounts to some function pointers to callbacks in the - parallel port device driver. - - - - During its initialisation, a low-level port driver tells the - sharing layer about all the ports that it has found (using - parport_register_port), and the sharing layer - creates a struct parport for each of - them. Each struct parport contains - (among other things) a pointer to a struct - parport_operations, which is a list of function - pointers for the various operations that can be performed on a - port. You can think of a struct parport - as a parallel port object, if - object-orientated programming is your thing. The - parport structures are chained in a - linked list, whose head is portlist (in - drivers/parport/share.c). - - - - Once the port has been registered, the low-level port driver - announces it. The parport_announce_port - function walks down the list of parallel port device drivers - (struct parport_drivers) calling the - attach function of each (which may block). - - - - Similarly, a low-level port driver can undo the effect of - registering a port with the - parport_unregister_port function, and device - drivers are notified using the detach - callback (which may not block). - - - - Device drivers can undo the effect of registering themselves with - the parport_unregister_driver - function. - - - - - - - - The IEEE 1284.3 API - - - 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. - - - - 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 parport code in Linux. - - - - At initialisation of the parallel port bus, - 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. - - - - 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. - - - - 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! - - - - 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. - - - - - - - - - - - - - Each device in the system is numbered at initialisation (by - parport_daisy_init). You can convert between - this device number and its co-ordinates with - parport_device_num and - parport_device_coords. - - - - -#include <parport.h> - - - int parport_device_num - int parport - int mux - int daisy - - - - - - int parport_device_coords - int devnum - int *parport - int *mux - int *daisy - - - - - 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 - -1 is used to indicate these cases. - - - - Two functions are provided for finding devices based on their IEEE - 1284 Device ID: parport_find_device and - parport_find_class. - - - - -#include <parport.h> - - - int parport_find_device - const char *mfg - const char *mdl - int from - - - - - - int parport_find_class - parport_device_class cls - int from - - - - - 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 - -1 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 from+1, in other - words). - - - - - - - - Device driver's view - - - - - - - - - - - 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 parport interface to - find parallel ports, use them, and share them with other device - drivers. - - - - 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. - - - - The interactions between the device driver and the - parport layer are as follows. First, the - device driver registers its existence with - parport, 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 - parport 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. - - - - So, the first thing for the device driver to do is tell - parport that it wants to know what parallel - ports are on the system. To do this, it uses the - parport_register_driver function: - - - - -#include <parport.h> - -struct parport_driver { - const char *name; - void (*attach) (struct parport *); - void (*detach) (struct parport *); - struct parport_driver *next; -}; - - - - int parport_register_driver - struct parport_driver *driver - - - - - In other words, the device driver passes pointers to a couple of - functions to parport, and - parport calls attach for - each port that's detected (and detach for each - port that disappears---yes, this can happen). - - - - The next thing that happens is that the device driver tells - parport that it thinks there's a device on the - port that it can drive. This typically will happen in the driver's - attach function, and is done with - parport_register_device: - - - - -#include <parport.h> - - - struct pardevice *parport_register_device - struct parport *port - const char *name - int (*pf) - void * - void (*kf) - void * - void (*irq_func) - int, void *, struct pt_regs * - int flags - void *handle - - - - - The port comes from the parameter supplied - to the attach function when it is called, or - alternatively can be found from the list of detected parallel ports - directly with the (now deprecated) - parport_enumerate function. A better way of - doing this is with parport_find_number or - parport_find_base functions, which find ports - by number and by base I/O address respectively. - - - - -#include <parport.h> - - - struct parport *parport_find_number - int number - - - - -#include <parport.h> - - - struct parport *parport_find_base - unsigned long base - - - - - The next three parameters, pf, - kf, and irq_func, are - more function pointers. These callback functions get called under - various circumstances, and are always given the - handle as one of their parameters. - - - - The preemption callback, pf, 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 parport_release. If - pf 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. - - - - The kick callback, kf, is - called when the port can be claimed for exclusive access; that is, - parport_claim is guaranteed to succeed inside - the kick callback. If the driver wants to claim the - port it should do so; otherwise, it need not take any - action. - - - - The irq_func 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 - request_irq; 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 irq_func - function is called. - - - - None of the callback functions are allowed to block. - - - - The flags are for telling - parport any requirements or hints that are - useful. The only useful value here (other than - 0, which is the usual value) is - PARPORT_DEV_EXCL. The point of that flag is - to request exclusive access at all times---once a driver has - successfully called parport_register_device - 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). - - - - The PARPORT_DEV_EXCL 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! - - - - Devices can also be registered by device drivers based on their - device numbers (the same device numbers as in the previous - section). - - - - The parport_open function is similar to - parport_register_device, and - parport_close is the equivalent of - parport_unregister_device. The difference is - that parport_open takes a device number rather - than a pointer to a struct parport. - - - - -#include <parport.h> - - - struct pardevice *parport_open - int devnum - const char *name - int (*pf) - void * - int (*kf) - void * - int (*irqf) - int, void *, struct pt_regs * - int flags - void *handle - - - - - - void parport_close - struct pardevice *dev - - - - - - struct pardevice *parport_register_device - struct parport *port - const char *name - int (*pf) - void * - int (*kf) - void * - int (*irqf) - int, void *, struct pt_regs * - int flags - void *handle - - - - - - void parport_unregister_device - struct pardevice *dev - - - - - 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: - - - - - - - Once your device driver has registered its device and been handed a - pointer to a struct pardevice, 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. - - - - -#include <parport.h> - - - int parport_claim - struct pardevice *dev - - - - - - int parport_claim_or_block - struct pardevice *dev - - - - - - void parport_release - struct pardevice *dev - - - - - To claim access to the port, use parport_claim - or parport_claim_or_block. The first of these - will not block, and so can be used from interrupt context. If - parport_claim 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. - - - - The other function, parport_claim_or_block, - will block if necessary to wait for the port to be free. If it - slept, it returns 1; if it succeeded without - needing to sleep it returns 0. If it fails it - will return a negative error code. - - - - 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 parport_release 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. - - - - 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. - - - - The parport_yield and - parport_yield_blocking 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 timeslice. - The default timeslice is half a second, but it can be adjusted via - a /proc entry. - - - - -#include <parport.h> - - - int parport_yield - struct pardevice *dev - - - - - - int parport_yield_blocking - struct pardevice *dev - - - - - The first of these, parport_yield, will not - block but as a result may fail. The return value for - parport_yield is the same as for - parport_claim. The blocking version, - parport_yield_blocking, has the same return - code as parport_claim_or_block. - - - - Once the port has been claimed, the device driver can use the - functions in the struct parport_operations - pointer in the struct parport it has a - pointer to. For example: - - - - ops->write_data (port, d); - ]]> - - - Some of these operations have shortcuts. For - instance, parport_write_data 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 - port and ops). - - - - - - Port drivers - - - - - To recap, then: - - - - - - The device driver registers itself with parport. - - - - - - A low-level driver finds a parallel port and registers it with - parport (these first two things can happen - in either order). This registration creates a struct - parport which is linked onto a list of known ports. - - - - - - parport calls the - attach function of each registered device - driver, passing it the pointer to the new struct - parport. - - - - - - The device driver gets a handle from - parport, for use with - parport_claim/release. - This handle takes the form of a pointer to a struct - pardevice, representing a particular device on the - parallel port, and is acquired using - parport_register_device. - - - - - - The device driver claims the port using - parport_claim (or - function_claim_or_block). - - - - - - Then it goes ahead and uses the port. When finished it releases - the port. - - - - - - - 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 struct - parport_operations). - - - - - A more complete description of which operation is supposed to do - what is available in - Documentation/parport-lowlevel.txt. - - - - - - The printer driver - - - - - - The printer driver, lp is a character special - device driver and a parport client. As a - character special device driver it registers a struct - file_operations using - register_chrdev, with pointers filled in for - write, ioctl, - open and - release. As a client of - parport, it registers a struct - parport_driver using - parport_register_driver, so that - parport knows to call - lp_attach when a new parallel port is - discovered (and lp_detach when it goes - away). - - - - The parallel port console functionality is also implemented in - drivers/char/lp.c, but that won't be covered - here (it's quite simple though). - - - - The initialisation of the driver is quite easy to understand (see - lp_init). The lp_table is - an array of structures that contain information about a specific - device (the struct pardevice associated - with it, for example). That array is initialised to sensible - values first of all. - - - - Next, the printer driver calls register_chrdev - passing it a pointer to lp_fops, which contains - function pointers for the printer driver's implementation of - open, write, and so on. - This part is the same as for any character special device - driver. - - - - After successfully registering itself as a character special device - driver, the printer driver registers itself as a - parport client using - parport_register_driver. It passes a pointer - to this structure: - - - - - - - The lp_detach function is not very interesting - (it does nothing); the interesting bit is - lp_attach. 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 - auto, 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. - - - - For each port that the printer driver wants to use (see - lp_register), it calls - parport_register_device and stores the - resulting struct pardevice pointer in the - lp_table. If the user told it to do so, it then - resets the printer. - - - - The other interesting piece of the printer driver, from the point - of view of parport, is - lp_write. In this function, the user space - process has data that it wants printed, and the printer driver - hands it off to the parport code to deal with. - - - - The parport functions it uses that we have not - seen yet are parport_negotiate, - parport_set_timeout, and - parport_write. These functions are part of - the IEEE 1284 implementation. - - - - 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 negotiation phase. Once the peripheral has accepted a - particular transfer mode, data transfer can begin that mode. - - - - The particular transfer mode that the printer driver wants to use - is named in IEEE 1284 as compatibility mode, and the - function to request a particular mode is called - parport_negotiate. - - - - -#include <parport.h> - - - int parport_negotiate - struct parport *port - int mode - - - - - The modes parameter is a symbolic constant - representing an IEEE 1284 mode; in this instance, it is - IEEE1284_MODE_COMPAT. (Compatibility mode is - slightly different to the other modes---rather than being - specifically requested, it is the default until another mode is - selected.) - - - - Back to lp_write then. First, access to the - parallel port is secured with - parport_claim_or_block. 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 parport_negotiate. - - - - The main work is done in the write-loop. In particular, the line - that hands the data over to parport reads: - - - - - - - The parport_write 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: - - - - -#include <parport.h> - - - ssize_t parport_write - struct parport *port - const void *buf - size_t len - - - - - - ssize_t parport_read - struct parport *port - void *buf - size_t len - - - - - (parport_read does what it sounds like, but - only works for modes in which reverse transfer is possible. Of - course, parport_write only works in modes in - which forward transfer is possible, too.) - - - - The buf pointer should be to kernel space - memory, and obviously the len parameter - specifies the amount of data to transfer. - - - - In fact what parport_write does is call the - appropriate block transfer function from the struct - parport_operations: - - - - - - - The transfer code in parport will tolerate a - data transfer stall only for so long, and this timeout can be - specified with parport_set_timeout, which - returns the previous timeout: - - - - -#include <parport.h> - - - long parport_set_timeout - struct pardevice *dev - long inactivity - - - - - This timeout is specific to the device, and is restored on - parport_claim. - - - - The next function to look at is the one that allows processes to - read from /dev/lp0: - lp_read. It's short, like - lp_write. - - - - The semantics of reading from a line printer device are as follows: - - - - - - Switch to reverse nibble mode. - - - - - - 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. - - - - - - If there was data, stop, and return it. - - - - - - Otherwise, we tried to read data and there was none. If the user - opened the device node with the O_NONBLOCK - flag, return. Otherwise wait until an interrupt occurs on the - port (or a timeout elapses). - - - - - - - - User-level device drivers - - - - Introduction to ppdev - - - The printer is accessible through /dev/lp0; - in the same way, the parallel port itself is accessible through - /dev/parport0. The difference is in the - level of control that you have over the wires in the parallel port - cable. - - - - With the printer driver, a user-space program (such as the printer - spooler) can send bytes in printer protocol. - Briefly, this means that for each byte, the eight data lines are - set up, then a strobe line tells the printer to - look at the data lines, and the printer sets an - acknowledgement line to say that it got the byte. - The printer driver also allows the user-space program to read - bytes in nibble mode, 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). - - - - In contrast, the ppdev driver (accessed via - /dev/parport0) allows you to: - - - - - - - examine status lines, - - - - - - set control lines, - - - - - - set/examine data lines (and control the direction of the data - lines), - - - - - - wait for an interrupt (triggered by one of the status lines), - - - - - - find out how many new interrupts have occurred, - - - - - - set up a response to an interrupt, - - - - - - use IEEE 1284 negotiation (for telling peripheral which transfer - mode, to use) - - - - - - transfer data using a specified IEEE 1284 mode. - - - - - - - - - User-level or kernel-level driver? - - - 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. - - - - 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. - - - - - - Programming interface - - - The ppdev interface is largely the same as that - of other character special devices, in that it supports - open, close, - read, write, and - ioctl. The constants for the - ioctl commands are in - include/linux/ppdev.h. - - - - - Starting and stopping: <function>open</function> and - <function>close</function> - - - - The device node /dev/parport0 represents any - device that is connected to parport0, 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 - /dev/parport0 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. - - - - - Control: <function>ioctl</function> - - - Most of the control is done, naturally enough, via the - ioctl call. Using - ioctl, the user-land driver can control both - the ppdev driver in the kernel and the - physical parallel port itself. The ioctl - call takes as parameters a file descriptor (the one returned from - opening the device node), a command, and optionally (a pointer - to) some data. - - - - PPCLAIM - - - - 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 - ppdev driver and not the port, such as - PPSETMODE; they can be performed while - access to the port is not claimed. - - - - - PPEXCL - - - - Instructs the kernel driver to forbid any sharing of the port - with other drivers, i.e. it requests exclusivity. The - PPEXCL command is only valid when the - port is not already claimed for use, and it may mean that the - next PPCLAIM ioctl - will fail: some other driver may already have registered - itself on that port. - - - - 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). - - - - Note that the PPEXCL - ioctl doesn't actually claim the port - there and then---action is deferred until the - PPCLAIM ioctl is - performed. - - - - - PPRELEASE - - - - 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). - - - - - PPYIELD - - - - Yields the port to another driver. This - ioctl 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. - - - - 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 PPEXCL). - - - - - PPNEGOT - - - - 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. - - - - An IEEE 1284 compliant device will start out in compatibility - mode, and then the host can negotiate to another mode (such as - ECP). - - - - The ioctl parameter should be a pointer - to an int; values for this are in - incluce/linux/parport.h and include: - - - - - IEEE1284_MODE_COMPAT - - IEEE1284_MODE_NIBBLE - - IEEE1284_MODE_BYTE - - IEEE1284_MODE_EPP - - IEEE1284_MODE_ECP - - - - The PPNEGOT ioctl - actually does two things: it performs the on-the-wire - negotiation, and it sets the behaviour of subsequent - read/write calls so - that they use that mode (but see - PPSETMODE). - - - - - PPSETMODE - - - - Sets which IEEE 1284 protocol to use for the - read and write - calls. - - - - The ioctl parameter should be a pointer - to an int. - - - - - PPGETMODE - - - - Retrieves the current IEEE 1284 mode to use for - read and write. - - - - - PPGETTIME - - - - Retrieves the time-out value. The read - and write calls will time out if the - peripheral doesn't respond quickly enough. The - PPGETTIME ioctl - retrieves the length of time that the peripheral is allowed to - have before giving up. - - - - The ioctl parameter should be a pointer - to a struct timeval. - - - - - PPSETTIME - - - - Sets the time-out. The ioctl parameter - should be a pointer to a struct - timeval. - - - - - PPGETMODES - - - - Retrieves the capabilities of the hardware (i.e. the - modes field of the - parport structure). - - - - - PPSETFLAGS - - - - Sets flags on the ppdev device which can - affect future I/O operations. Available flags are: - - - - - PP_FASTWRITE - - PP_FASTREAD - - PP_W91284PIC - - - - - PPWCONTROL - - - - Sets the control lines. The ioctl - parameter is a pointer to an unsigned char, the - bitwise OR of the control line values in - include/linux/parport.h. - - - - - PPRCONTROL - - - - Returns the last value written to the control register, in the - form of an unsigned char: each bit corresponds to - a control line (although some are unused). The - ioctl parameter should be a pointer to an - unsigned char. - - - - 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. - - - - The control lines bits are defined in - include/linux/parport.h: - - - - - PARPORT_CONTROL_STROBE - - PARPORT_CONTROL_AUTOFD - - PARPORT_CONTROL_SELECT - - PARPORT_CONTROL_INIT - - - - - PPFCONTROL - - - - 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 PPRCONTROL, make the - change, and then use PPWCONTROL. 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 - PPRCONTROL, ppdev - must remember the state of the control lines anyway. - - - - The PPFCONTROL ioctl - is for frobbing control lines, and is like - PPWCONTROL but acts on a restricted set - of control lines. The ioctl parameter is - a pointer to a struct - ppdev_frob_struct: - - - - - - - - The mask and - val fields are bitwise ORs of - control line names (such as in - PPWCONTROL). The operation performed by - PPFCONTROL is: - - - - - - - - In other words, the signals named in - mask are set to the values in - val. - - - - - PPRSTATUS - - - - Returns an unsigned char containing bits set for - each status line that is set (for instance, - PARPORT_STATUS_BUSY). The - ioctl parameter should be a pointer to an - unsigned char. - - - - - PPDATADIR - - - - 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.) - - - - This is only needed in conjunction with - PPWDATA or - PPRDATA. - - - - The ioctl parameter is a pointer to an - int. If the int is zero, the - drivers are turned on (forward direction); if non-zero, the - drivers are turned off (reverse direction). - - - - - PPWDATA - - - - Sets the data lines (if in forward mode). The - ioctl parameter is a pointer to an - unsigned char. - - - - - PPRDATA - - - - Reads the data lines (if in reverse mode). The - ioctl parameter is a pointer to an - unsigned char. - - - - - PPCLRIRQ - - - - Clears the interrupt count. The ppdev - driver keeps a count of interrupts as they are triggered. - PPCLRIRQ stores this count in an - int, a pointer to which is passed in as the - ioctl parameter. - - - - In addition, the interrupt count is reset to zero. - - - - - PPWCTLONIRQ - - - - Set a trigger response. Afterwards when an interrupt is - triggered, the interrupt handler will set the control lines as - requested. The ioctl parameter is a - pointer to an unsigned char, which is interpreted - in the same way as for PPWCONTROL. - - - - The reason for this ioctl is simply - speed. Without this ioctl, responding to - an interrupt would start in the interrupt handler, switch - context to the user-land driver via poll - or select, and then switch context back - to the kernel in order to handle - PPWCONTROL. Doing the whole lot in the - interrupt handler is a lot faster. - - - - - - - - - - - - Transferring data: <function>read</function> and - <function>write</function> - - - Transferring data using read and - write is straightforward. The data is - transferring using the current IEEE 1284 mode (see the - PPSETMODE ioctl). For - modes which can only transfer data in one direction, only the - appropriate function will work, of course. - - - - - Waiting for events: <function>poll</function> and - <function>select</function> - - - The ppdev driver provides user-land device - drivers with the ability to wait for interrupts, and this is done - using poll (and select, - which is implemented in terms of poll). - - - - When a user-land device driver wants to wait for an interrupt, it - sleeps with poll. When the interrupt - arrives, ppdev wakes it up (with a - read event, although strictly speaking there is - nothing to actually read). - - - - - - - - Examples - - - Presented here are two demonstrations of how to write a simple - printer driver for ppdev. Firstly we will - use the write function, and after that we - will drive the control and data lines directly. - - - - The first thing to do is to actually open the device. - - - - - - Here name should be something along the lines - of "/dev/parport0". (If you don't have any - /dev/parport files, you can make them with - mknod; they are character special device nodes - with major 99.) - - - - In order to do anything with the port we need to claim access to - it. - - - - - - Our printer driver will copy its input (from - stdin) 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 compatibility - mode. - - - 0) { - int written = write_printer (fd, ptr, got); - - if (written < 0) { - perror ("write"); - close (fd); - return 1; - } - - ptr += written; - got -= written; - } - } - ]]> - - - The write_printer 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 write_printer: - - - - - - We hand the data to the kernel-level driver (using - write) and it handles the printer - protocol. - - - - Now let's do it the hard way! In this particular example there is - no practical reason to do anything other than just call - write, 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. - - - - So, here is the alternative implementation of - write_printer (for brevity, error checking - has been omitted): - - - - - - To show a bit more of the ppdev interface, - here is a small piece of code that is intended to mimic the - printer's side of printer protocol. - - - 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); - } - ]]> - - - 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. - - - - - - - - - - - Linux parallel port driver API reference - - -!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 - - - - - - The Linux 2.2 Parallel Port Subsystem - - - - 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: - - - - - - parport_register_device - - - - - - parport_unregister_device - - - - - - parport_claim - - - - - - parport_claim_or_block - - - - - - parport_release - - - - - - parport_yield - - - - - - parport_yield_blocking - - - - - - In addition, negotiation to reverse nibble mode is supported: - - - - - int parport_ieee1284_nibble_mode_ok - struct parport *port - unsigned char mode - - - - - The only valid values for mode are 0 (for - reverse nibble mode) and 4 (for Device ID in reverse nibble mode). - - - - This function is obsoleted by - parport_negotiate in Linux 2.4, and has been - removed. - - - - - - GNU Free Documentation License - - - - 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. - - - - - - - - diff -puN Documentation/DocBook/parport-multi.fig~remove-documentation-docbook-parportbooktmpl Documentation/DocBook/parport-multi.fig --- 25/Documentation/DocBook/parport-multi.fig~remove-documentation-docbook-parportbooktmpl 2004-04-25 21:44:32.646436944 -0700 +++ 25-akpm/Documentation/DocBook/parport-multi.fig 2004-04-25 21:44:32.652436032 -0700 @@ -1,59 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -6 1425 4350 5175 5475 -6 3450 5100 4425 5475 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 4425 5475 4425 5100 3450 5100 3450 5475 4425 5475 -4 0 0 50 0 0 12 0.0000 4 135 510 3600 5400 Printer\001 --6 -6 3375 4350 5175 4725 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 5175 4725 5175 4350 3375 4350 3375 4725 5175 4725 -4 0 0 50 0 0 12 0.0000 4 180 870 3825 4650 Multiplexor\001 --6 -6 1425 4650 2775 5475 -6 1425 4650 2775 5475 -2 4 0 1 0 7 50 0 -1 0.000 0 0 6 0 0 5 - 2757 5475 2757 4650 1425 4650 1425 5475 2757 5475 -4 0 0 50 0 0 12 0.0000 4 180 735 1725 5100 Computer\001 --6 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2775 4875 2700 4875 2700 5025 2775 5025 2775 4875 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2775 5175 2700 5175 2700 5325 2775 5325 2775 5175 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 2775 4950 3600 4725 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 2775 5250 3450 5325 --6 -6 3150 2625 4125 3525 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 4125 3075 4125 2625 3150 2625 3150 3075 4125 3075 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 3675 3075 3675 3525 -4 0 0 50 0 0 12 0.0000 4 135 510 3300 2925 Printer\001 --6 -6 4275 3450 5250 4350 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 5250 3900 5250 3450 4275 3450 4275 3900 5250 3900 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 4800 3900 4800 4350 -4 0 0 50 0 0 12 0.0000 4 135 510 4425 3750 Printer\001 --6 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 3900 4050 3900 3525 3375 3525 3375 4050 3900 4050 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 3675 4050 3675 4350 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3600 4350 3750 4350 3750 4425 3600 4425 3600 4350 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4725 4350 4875 4350 4875 4425 4725 4425 4725 4350 -4 0 0 50 0 0 12 0.0000 4 135 285 3450 3900 ZIP\001 diff -puN Documentation/DocBook/parport-share.fig~remove-documentation-docbook-parportbooktmpl Documentation/DocBook/parport-share.fig --- 25/Documentation/DocBook/parport-share.fig~remove-documentation-docbook-parportbooktmpl 2004-04-25 21:44:32.647436792 -0700 +++ 25-akpm/Documentation/DocBook/parport-share.fig 2004-04-25 21:44:32.653435880 -0700 @@ -1,154 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #8e8e8e -0 33 #8e8e8e -0 34 #aeaaae -0 35 #515551 -0 36 #414141 -0 37 #868286 -0 38 #8e8e8e -0 39 #414141 -0 40 #868286 -0 41 #c7c3c7 -0 42 #e7e3e7 -0 43 #414141 -0 44 #868286 -0 45 #c7c3c7 -0 46 #e7e3e7 -0 47 #868286 -0 48 #c7c3c7 -0 49 #e7e3e7 -6 1200 3000 2250 4950 -6 1275 3150 2175 3675 -6 1312 3487 1837 3637 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 5 - 1312 3562 1312 3524 1474 3524 1474 3487 1675 3487 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 3 - 1474 3637 1474 3562 1675 3562 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 2 - 1675 3524 1837 3524 -2 1 0 1 7 -1 19 0 -1 0.000 2 0 -1 0 0 2 - 1675 3487 1675 3524 -2 1 0 1 7 -1 19 0 -1 0.000 2 0 -1 0 0 2 - 1312 3562 1474 3562 -2 1 0 1 7 -1 19 0 -1 0.000 2 0 -1 0 0 5 - 1474 3637 1675 3637 1675 3562 1837 3562 1837 3524 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 3 - 1716 3637 1797 3637 1797 3600 -2 1 0 1 7 -1 19 0 -1 0.000 2 0 -1 0 0 3 - 1716 3637 1716 3600 1797 3600 --6 -6 1413 3345 2070 3397 -6 1994 3352 2070 3390 -2 1 0 1 7 40 19 0 -1 0.000 2 0 -1 0 0 3 - 1994 3390 1994 3352 2070 3352 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 3 - 1994 3390 2070 3390 2070 3352 --6 -6 1531 3353 1643 3389 -2 2 0 0 40 41 19 0 20 0.000 2 0 -1 0 0 5 - 1568 3353 1606 3353 1606 3389 1568 3389 1568 3353 -2 2 0 0 40 39 19 0 20 0.000 2 0 -1 0 0 5 - 1606 3353 1643 3353 1643 3389 1606 3389 1606 3353 -2 2 0 0 40 41 19 0 20 0.000 2 0 -1 0 0 5 - 1568 3353 1531 3353 1531 3389 1568 3389 1568 3353 --6 -6 1413 3345 1465 3397 -1 3 0 0 0 39 18 0 20 0.000 1 0.0000 1439 3371 26 26 1439 3371 1439 3397 -1 3 0 0 40 41 18 0 20 0.000 1 0.0000 1439 3371 15 15 1439 3371 1443 3385 --6 -2 2 0 0 40 7 19 0 20 0.000 2 0 -1 0 0 3 - 1950 3371 1875 3371 1950 3371 -2 2 0 0 40 41 19 0 20 0.000 2 0 -1 0 0 5 - 1945 3384 1896 3384 1896 3357 1945 3357 1945 3384 --6 -6 1350 3183 2100 3300 -2 1 0 1 7 40 19 0 -1 0.000 2 0 -1 0 0 3 - 1350 3300 1350 3183 2100 3183 -2 1 0 1 40 -1 19 0 -1 0.000 2 0 -1 0 0 3 - 1350 3300 2100 3300 2100 3183 --6 -2 1 0 1 7 7 19 0 -1 0.000 2 0 -1 0 0 5 - 1275 3675 1875 3675 1875 3450 2175 3450 2175 3150 -2 1 0 1 40 7 19 0 -1 0.000 2 0 -1 0 0 3 - 1275 3675 1275 3150 2175 3150 --6 -6 1950 3750 2175 3975 -5 1 0 1 7 7 19 0 -1 0.000 0 0 0 0 2038.000 3900.000 1985 3953 1985 3847 2091 3847 -5 1 0 1 40 7 19 0 -1 0.000 0 1 0 0 2038.000 3900.000 1985 3953 2091 3953 2091 3847 --6 -6 1200 4050 1800 4800 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4125 1725 4125 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4200 1725 4200 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4275 1725 4275 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4350 1725 4350 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4425 1725 4425 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4500 1725 4500 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4575 1725 4575 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4650 1725 4650 -2 1 0 2 40 7 19 0 -1 0.000 2 1 -1 0 0 2 - 1275 4725 1725 4725 --6 -2 2 0 1 0 39 20 0 20 0.000 2 0 -1 0 0 5 - 1200 4950 1425 4950 1425 4911 1200 4911 1200 4950 -2 2 0 1 0 39 20 0 20 0.000 2 0 -1 0 0 5 - 2025 4950 2250 4950 2250 4911 2025 4911 2025 4950 -2 2 0 1 0 42 20 0 20 0.000 2 0 -1 0 0 5 - 1200 4907 2250 4907 2250 3000 1200 3000 1200 4907 --6 -6 2374 3225 3375 4050 -3 2 0 1 0 37 50 0 -1 0.000 0 0 0 3 - 2374 3402 3139 3402 3257 4050 - 0.000 -1.000 0.000 -3 2 0 1 0 37 50 0 -1 0.000 0 0 0 3 - 2374 3461 3096 3437 3198 4050 - 0.000 -1.000 0.000 --6 -2 2 0 1 0 1 50 0 20 0.000 0 0 -1 0 0 5 - 2925 4575 4050 4575 4050 4875 2925 4875 2925 4575 -2 3 0 1 0 32 50 0 20 0.000 0 0 -1 0 0 5 - 1200 3000 1575 2475 2400 2475 2250 3000 1200 3000 -2 3 0 1 0 8 50 0 20 0.000 0 0 -1 0 0 5 - 2925 4575 3000 4200 4050 4200 4050 4575 2925 4575 -2 2 0 1 0 0 50 0 20 0.000 0 0 -1 0 0 5 - 3075 4725 3900 4725 3900 4800 3075 4800 3075 4725 -2 2 0 1 0 46 50 0 20 0.000 0 0 -1 0 0 5 - 4800 3975 6450 3975 6450 4875 4800 4875 4800 3975 -2 2 0 1 0 36 50 0 20 0.000 0 0 -1 0 0 5 - 5025 4575 6225 4575 6225 4725 5025 4725 5025 4575 -2 2 0 1 0 36 50 0 20 0.000 0 0 -1 0 0 5 - 5025 3975 6225 3975 6225 3300 5025 3300 5025 3975 -2 3 0 1 0 37 50 0 20 0.000 0 0 -1 0 0 5 - 4800 3975 4800 3825 5025 3825 5025 3975 4800 3975 -2 3 0 1 0 37 50 0 20 0.000 0 0 -1 0 0 5 - 6225 3825 6375 3825 6450 3975 6225 3975 6225 3825 -2 3 0 1 0 32 50 0 20 0.000 0 0 -1 0 0 5 - 2400 2475 2250 3000 2250 4875 2400 4350 2400 2475 -2 3 0 1 0 37 50 0 -1 0.000 0 0 -1 0 0 6 - 3075 4200 3075 4050 3300 4050 3375 4050 3375 4200 3075 4200 -2 3 0 1 0 37 50 0 -1 0.000 0 0 -1 0 0 6 - 3900 4200 3900 4050 3675 4050 3600 4050 3600 4200 3900 4200 -3 2 0 1 0 37 50 0 -1 0.000 0 0 0 5 - 3705 4050 3825 3675 4185 3390 4590 3615 4800 4035 - 0.000 -1.000 -1.000 -1.000 0.000 -3 2 0 1 0 37 50 0 -1 0.000 0 0 0 5 - 3765 4050 3874 3708 4202 3449 4571 3654 4800 4185 - 0.000 -1.000 -1.000 -1.000 0.000 -4 0 0 50 0 0 12 0.0000 4 180 735 1350 5400 Computer\001 -4 0 0 50 0 0 12 0.0000 4 180 675 3150 5400 Zip drive\001 -4 0 0 50 0 0 12 0.0000 4 135 510 5325 5400 Printer\001 diff -puN Documentation/DocBook/parport-structure.fig~remove-documentation-docbook-parportbooktmpl Documentation/DocBook/parport-structure.fig --- 25/Documentation/DocBook/parport-structure.fig~remove-documentation-docbook-parportbooktmpl 2004-04-25 21:44:32.648436640 -0700 +++ 25-akpm/Documentation/DocBook/parport-structure.fig 2004-04-25 21:44:32.654435728 -0700 @@ -1,60 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #414541 -0 33 #8e8e8e -0 34 #414541 -0 35 #8e8e8e -0 36 #414541 -0 37 #8e8e8e -0 38 #414541 -0 39 #8e8e8e -0 40 #414541 -0 41 #8e8e8e -0 42 #414541 -0 43 #8e8e8e -0 44 #414141 -0 45 #868286 -0 46 #c7c3c7 -0 47 #8e8e8e -0 48 #414141 -0 49 #868286 -0 50 #c7c3c7 -0 51 #e7e3e7 -6 2025 1800 3075 2250 -2 4 0 1 0 7 50 0 -1 0.000 0 0 3 0 0 5 - 3045 2250 3045 1800 2025 1800 2025 2250 3045 2250 -4 0 0 50 0 14 12 0.0000 4 180 210 2400 2100 lp\001 --6 -6 4125 1800 5175 2250 -2 4 0 1 0 7 50 0 -1 0.000 0 0 3 0 0 5 - 5145 2250 5145 1800 4125 1800 4125 2250 5145 2250 -4 0 0 50 0 14 12 0.0000 4 135 315 4425 2100 ppa\001 --6 -6 3225 3075 4275 3525 -6 3375 3225 4125 3450 -4 0 0 50 0 14 12 0.0000 4 165 735 3375 3375 parport\001 --6 -2 4 0 1 0 7 50 0 -1 0.000 0 0 3 0 0 5 - 4245 3525 4245 3075 3225 3075 3225 3525 4245 3525 --6 -6 3000 4350 4500 4800 -2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5 - 4500 4800 4500 4350 3000 4350 3000 4800 4500 4800 -4 0 0 50 0 14 12 0.0000 4 165 1050 3225 4650 parport_pc\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 2550 2250 3600 3075 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4650 2250 3825 3075 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3750 3525 3750 4350 _