NetBSD/share/man/man4/ppbus.4

.\" $NetBSD: ppbus.4,v 1.15 2009/08/19 23:17:25 wiz Exp $
.\"
.\" Copyright (c) 1998, 1999 Nicolas Souchu
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man4/ppbus.4,v 1.14.2.5 2001/08/17 13:08:39 ru Exp $
.\"
.Dd August 19, 2009
.Dt PPBUS 4
.Os
.Sh NAME
.Nm ppbus
.Nd Parallel Port Bus system with GPIO
.Sh SYNOPSIS
.Cd "ppbus* at atppc?"
.Cd "options PPBUS_VERBOSE"
.Cd "options PPBUS_DEBUG"
.Cd "options DEBUG_1284"
.Pp
.Cd "gpio* at ppbus?"
.Cd "lpt* at ppbus?"
.Cd "plip* at ppbus?"
.Cd "pps* at ppbus?"
.\" Cd "lpbb* at ppbus?"
.\" Cd "vpo* at ppbus?"
.Sh DESCRIPTION
The
.Nm
system provides a uniform, modular, and architecture-independent
system for the implementation of drivers to control various parallel
devices, and to use different parallel port chip sets.
.Sh DEVICE DRIVERS
In order to write new drivers or port existing drivers, the
.Nm
system provides the following facilities:
.Bl -bullet -offset indent
.It
architecture-independent macros or functions to access parallel ports
.It
mechanism to allow various devices to share the same parallel port
.It
a
.Xr gpio 4
interface to access the individual pins
.It
a user interface named
.Xr ppi 4
that allows parallel port access from outside the kernel without
conflicting with kernel-in drivers.
.El
.Ss Developing new drivers
The
.Nm
system has been designed to support the development of standard
and non-standard software:
.Pp
.Bl -column "Driver" -compact
.It Em Driver Ta Em Description
.\" It Sy vpo Ta "VPI0 parallel to Adaptec AIC-7110 SCSI controller driver" .
It uses standard and non-standard parallel port accesses.
.It Sy ppi Ta "Parallel port interface for general I/O"
.It Sy pps Ta "Pulse per second Timing Interface"
.\" It Sy lpbb Ta "Philips official parallel port I2C bit-banging interface"
.El
.Ss Porting existing drivers
Another approach to the
.Nm
system is to port existing drivers.
Various drivers have already been ported:
.Pp
.Bl -column "Driver" -compact
.It Em Driver Ta Em Description
.It Sy lpt Ta "lpt printer driver"
.It Sy lp Ta "plip network interface driver"
.El
.Pp
.Nm
should let you port any other software even from other operating
systems that provide similar services.
.Sh PARALLEL PORT CHIP SETS
Parallel port chip set support is provided by
.Xr atppc 4 .
.Pp
The
.Nm
system provides functions and macros to request service from the
.Nm
including reads, writes, setting of parameters, and bus requests/releases.
.Pp
.Xr atppc 4
detects chip set and capabilities and sets up interrupt handling.
It makes
methods available for use to the
.Nm
system.
.Sh PARALLEL PORT MODEL
The logical parallel port model chosen for the
.Nm
system is the AT
parallel port model.
Consequently, for the
.Em atppc
implementation of
.Nm ,
most of the services provided by
.Nm
will
translate into I/O instructions on actual registers.
However, other parallel port implementations may require more than
one I/O instruction to do a single logical register operation on
data, status and control virtual registers.
.Ss Description
The parallel port may operate in the following modes:
.Bl -bullet -offset indent
.It
Compatible (Centronics -- the standard parallel port mode) mode,
output byte
.It
Nibble mode, input 4-bits
.It
Byte (PS/2) mode, input byte
.It
Extended Capability Port (ECP) mode, bidirectional byte
.It
Enhanced Parallel Port (EPP) mode, bidirectional byte
.El
.Ss Compatible mode
This mode defines the protocol used by most PCs to transfer data
to a printer.
In this mode, data is placed on the port's data lines, the printer
status is checked for no errors and that it is not busy, and then
a data Strobe is generated by the software to clock the data to
the printer.
.Pp
Many I/O controllers have implemented a mode that uses a FIFO buffer
to transfer data with the Compatibility mode protocol.
This mode is referred to as
.Dq Fast Centronics
or
.Dq Parallel Port FIFO mode .
.Ss Nibble mode
The Nibble mode is the most common way to get reverse channel data
from a printer or peripheral.
When combined with the standard host to printer mode, a bidirectional
data channel is created.
Inputs are accomplished by reading 4 of the 8 bits of the status
register.
.Ss Byte mode
In this mode, the data register is used either for outputs and inputs.
All transfers are 8-bits long.
Channel direction must be negotiated when doing
.Tn IEEE 1248
compliant operations.
.Ss Extended Capability Port mode
The ECP protocol was proposed as an advanced mode for communication
with printer and scanner type peripherals.
Like the EPP protocol, ECP mode provides for a high performance
bidirectional communication path between the host adapter and the
peripheral.
.Pp
ECP protocol features include:
.Bl -item -offset indent
.It
Run_Length_Encoding (RLE) data compression for host adapters (not
supported in these drivers)
.It
FIFO's for both the forward and reverse channels
.It
DMA or programmed I/O for the host register interface.
.El
.Ss Enhanced Parallel Port mode
The EPP protocol was originally developed as a means to provide a
high performance parallel port link that would still be compatible
with the standard parallel port.
.Pp
The EPP mode has two types of cycle: address and data.
What makes the difference at hardware level is the strobe of the
byte placed on the data lines.
Data are strobed with nAutofeed, addresses are strobed with nSelectin
signals.
.Pp
A particularity of the ISA implementation of the EPP protocol is
that an EPP cycle fits in an ISA cycle.
In this fashion, parallel port peripherals can operate at close to
the same performance levels as an equivalent ISA plug-in card.
.Pp
At software level, you may implement the protocol you wish, using
data and address cycles as you want.
This is for the
.Tn IEEE 1284
compatible part.
Peripheral vendors may implement protocol handshake with the
following status lines: PError, nFault and Select.
Try to know how these lines toggle with your peripheral, allowing
the peripheral to request more data, stop the transfer and so on.
.Pp
At any time, the peripheral may interrupt the host with the nAck
signal without disturbing the current transfer.
.Ss Mixed modes
Some manufacturers, like SMC, have implemented chip sets that
support mixed modes.
With such chip sets, mode switching is available at any time by
accessing the extended control register.
All ECP-capable chip sets can switch between standard, byte, fast
centronics, and ECP modes.
Some ECP chip sets also support switching to EPP mode.
.Sh IEEE 1284 1994 Standard
.Ss Background
This standard is also named
.Do
IEEE Standard Signaling Method for a Bidirectional Parallel Peripheral
Interface for Personal Computers
.Dc .
It defines a signaling method for asynchronous, fully interlocked,
bidirectional parallel communications between hosts and printers
or other peripherals.
It also specifies a format for a peripheral identification string
and a method of returning this string to the host.
.Pp
This standard is architecture independent and only specifies dialog
handshake at signal level.
One should refer to architecture specific documentation in order
to manipulate machine dependent registers, mapped memory or other
methods to control these signals.
.Pp
The
.Tn IEEE 1284
protocol is fully oriented with all supported parallel port modes.
The computer acts as master and the peripheral as slave.
.Pp
Any transfer is defined as a finite state automate.
It allows software to properly manage the fully interlocked scheme
of the signaling method.
The compatible mode is supported
.Dq as is
without any negotiation because it is the default, backward-compatible
transfer mode.
Any other mode must be firstly negotiated by the host to check it
is supported by the peripheral, then to enter one of the forward
idle states.
.Pp
At any time, the slave may want to send data to the host.
The host must negotiate to permit the peripheral to complete the
transfer.
Interrupt lines may be dedicated to the requesting signals
to prevent time consuming polling methods.
.Pp
If the host accepts the transfer, it must firstly negotiate the
reverse mode and then start the transfer.
At any time during reverse transfer, the host may terminate the
transfer or the slave may drive wires to signal that no more data
is available.
.Ss Implementation
.Tn IEEE 1284 Standard
support has been implemented at the top of the
.Nm
system as a set of procedures that perform high level functions
like negotiation, termination, transfer in any mode without bothering
you with low level characteristics of the standard.
.Pp
.Tn IEEE 1284
interacts with the
.Nm
system as little as possible.
That means you still have to request the
.Nm
when you want to access it, and of course, release it when finished.
.Sh ARCHITECTURE
.Ss Chip set, ppbus and device layers
First, there is the
.Em chip set
layer, the lowest of the
.Nm
system.
It provides chip set abstraction through a set of low level functions
that maps the logical model to the underlying hardware.
.Pp
Secondly, there is the
.Em ppbus
layer that provides functions to:
.Bl -enum -offset indent
.It
share the parallel port bus among the daisy-chain like connected
devices
.It
manage devices linked to
.Nm
.It
propose an arch-independent interface to access the hardware layer.
.El
.Pp
Finally, the
.Em device
layer represents the traditional device drivers such as
.Xr lpt 4
which now use an abstraction instead of real hardware.
.Ss Parallel port mode management
Operating modes are differentiated at various
.Nm
system layers.
There is a difference between a
.Em capability
and a
.Em mode .
A chip set may have a combination of capabilities, but at any one
time the
.Nm
system operates in a single mode.
.Pp
Nibble mode is a
.Em virtual
mode: the actual chip set would be in standard mode and the driver
would change its behavior to drive the right lines on the parallel
port.
.Pp
Each child device of
.Nm
must set its operating mode and other parameters whenever it requests
and gets access to its parent
.Nm .
.Sh FEATURES
.Ss The boot process
.Nm
attachment tries to detect any PnP parallel peripheral (according to
.%T "Plug and Play Parallel Port Devices" draft from (c)1993-4
.Tn Microsoft Corporation )
then probes and attaches known device drivers.
.Pp
During probe, device drivers should request the
.Nm
and try to determine if the right capabilities are present in the
system.
.Ss Bus request and interrupts
.Nm
reservation via a bus request is mandatory not to corrupt I/O of
other devices.
For example, when the
.Xr lpt 4
device is opened, the bus will be
.Dq allocated
to the device driver and attempts to reserve the bus for another
device will fail until the
.Xr lpt 4
driver releases the bus.
.Pp
Child devices can also register interrupt handlers to be called
when a hardware interrupt occurs.
In order to attach a handler, drivers must own the bus.
Drivers should have interrupt handlers that check to see if the
device still owns the bus when they are called and/or ensure that
these handlers are removed whenever the device does not own the
bus.
.Ss Micro-sequences
.Em Micro-sequences
are a general purpose mechanism to allow fast low-level manipulation
of the parallel port.
Micro-sequences may be used to do either standard (in
.Tn IEEE 1284
modes) or non-standard transfers.
The philosophy of micro-sequences is to avoid the overhead of the
.Nm
layer for a sequence of operations and do most of the job at the
chip set level.
.Pp
A micro-sequence is an array of opcodes and parameters.
Each opcode codes an operation (opcodes are described in
.Xr microseq 9 ) .
Standard I/O operations are implemented at ppbus level whereas
basic I/O operations and microseq language are coded at adapter
level for efficiency.
.\" .Pp
.\" As an example, the
.\" .Xr vpo 4
.\" driver uses micro-sequences to implement:
.\" .Bl -bullet -offset indent
.\" .It
.\" a modified version of the Nibble transfer mode
.\" .It
.\" various I/O sequences to initialize, select and allocate the
.\" peripheral
.\" .El
.Ss GPIO interface
Pins 1 through 17 of the parallel port can be controlled through the
.Xr gpio 4
interface, pins 18 through 25 are hardwired to ground.
Pins 10 through 13 and pin 15 are input pins, the others are output
pins.
Some of the pins are inverted by the hardware, the values read or
written are adjusted accordingly.
Note that the
.Xr gpio 4
interface starts at 0 when numbering pins.
.Sh SEE ALSO
.Xr atppc 4 ,
.Xr gpio 4 ,
.Xr lpt 4 ,
.Xr plip 4 ,
.Xr ppi 4 ,
.\" Xr vpo 4 ,
.Xr microseq 9
.Sh HISTORY
The
.Nm
system first appeared in
.Fx 3.0 .
.Sh AUTHORS
This manual page is based on the
.Fx
.Nm ppbus
manual page.
The information has been updated for the
.Nx
port by Gary Thorpe.
.Sh BUGS
The
.Nm
framework is still experimental and not enabled by default yet.