path: root/Documentation/parport-lowlevel.txt

PARPORT interface documentation
-------------------------------

Time-stamp: <2000-02-24 13:30:20 twaugh>

Described here are the following functions:

Global functions:
  parport_register_driver
  parport_unregister_driver
  parport_enumerate
  parport_register_device
  parport_unregister_device
  parport_claim
  parport_claim_or_block
  parport_release
  parport_yield
  parport_yield_blocking
  parport_wait_peripheral
  parport_poll_peripheral
  parport_wait_event
  parport_negotiate
  parport_read
  parport_write
  parport_open
  parport_close
  parport_device_id
  parport_device_coords
  parport_find_class
  parport_find_device
  parport_set_timeout

Port functions (can be overridden by low-level drivers):
  SPP:
    port->ops->read_data
    port->ops->write_data
    port->ops->read_status
    port->ops->read_control
    port->ops->write_control
    port->ops->frob_control
    port->ops->enable_irq
    port->ops->disable_irq
    port->ops->data_forward
    port->ops->data_reverse

  EPP:
    port->ops->epp_write_data
    port->ops->epp_read_data
    port->ops->epp_write_addr
    port->ops->epp_read_addr

  ECP:
    port->ops->ecp_write_data
    port->ops->ecp_read_data
    port->ops->ecp_write_addr

  Other:
    port->ops->nibble_read_data
    port->ops->byte_read_data
    port->ops->compat_write_data

The parport subsystem comprises 'parport' (the core port-sharing
code), and a variety of low-level drivers that actually do the port
accesses.  Each low-level driver handles a particular style of port
(PC, Amiga, and so on).

The parport interface to the device driver author can be broken down
into global functions and port functions.

The global functions are mostly for communicating between the device
driver and the parport subsystem: acquiring a list of available ports,
claiming a port for exclusive use, and so on.  They also include
'generic' functions for doing standard things that will work on any
IEEE 1284-capable architecture.

The port functions are provided by the low-level drivers, although the
core parport module provides generic 'defaults' for some routines.
The port functions can be split into three groups: SPP, EPP, and ECP.

SPP (Standard Parallel Port) functions modify so-called 'SPP'
registers: data, status, and control.  The hardware may not actually
have registers exactly like that, but the PC does and this interface is
modelled after common PC implementations.  Other low-level drivers may
be able to emulate most of the functionality.

EPP (Enhanced Parallel Port) functions are provided for reading and
writing in IEEE 1284 EPP mode, and ECP (Extended Capabilities Port)
functions are used for IEEE 1284 ECP mode. (What about BECP? Does
anyone care?)

Hardware assistance for EPP and/or ECP transfers may or may not be
available, and if it is available it may or may not be used.  If
hardware is not used, the transfer will be software-driven.  In order
to cope with peripherals that only tenuously support IEEE 1284, a
low-level driver specific function is provided, for altering 'fudge
factors'.

GLOBAL FUNCTIONS
----------------

parport_register_driver - register a device driver with parport
-----------------------

SYNOPSIS

#include <linux/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);

DESCRIPTION

In order to be notified about parallel ports when they are detected,
parport_register_driver should be called.  Your driver will
immediately be notified of all ports that have already been detected,
and of each new port as low-level drivers are loaded.

A 'struct parport_driver' contains the textual name of your driver,
a pointer to a function to handle new ports, and a pointer to a
function to handle ports going away due to a low-level driver
unloading.  Ports will only be detached if they are not being used
(i.e. there are no devices registered on them).

The visible parts of the 'struct parport *' argument given to
attach/detach are:

struct parport
{
	struct parport *next; /* next parport in list */
	const char *name;     /* port's name */
	unsigned int modes;   /* bitfield of hardware modes */
	struct parport_device_info probe_info;
			      /* IEEE1284 info */
	int number;           /* parport index */
	struct parport_operations *ops;
	...
};

There are other members of the structure, but they should not be
touched.

The 'modes' member summarises the capabilities of the underlying
hardware.  It consists of flags which may be bitwise-ored together:

  PARPORT_MODE_PCSPP		IBM PC registers are available,
				i.e. functions that act on data,
				control and status registers are
				probably writing directly to the
				hardware.
  PARPORT_MODE_TRISTATE		The data drivers may be turned off.
				This allows the data lines to be used
				for reverse (peripheral to host)
				transfers.
  PARPORT_MODE_COMPAT		The hardware can assist with
				compatibility-mode (printer)
				transfers, i.e. compat_write_block.
  PARPORT_MODE_EPP		The hardware can assist with EPP
				transfers.
  PARPORT_MODE_ECP		The hardware can assist with ECP
				transfers.
  PARPORT_MODE_DMA		The hardware can use DMA, so you might
				want to pass ISA DMA-able memory
				(i.e. memory allocated using the
				GFP_DMA flag with kmalloc) to the
				low-level driver in order to take
				advantage of it.

There may be other flags in 'modes' as well.

The contents of 'modes' is advisory only.  For example, if the
hardware is capable of DMA, and PARPORT_MODE_DMA is in 'modes', it
doesn't necessarily me