freebsd-dev/share/man/man4/ppbus.4

.\" Copyright (c) 1998, 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.
.\"
.\"
.Dd March 1, 1998
.Dt PPBUS 4
.Os FreeBSD
.Sh NAME
.Nm ppbus
.Nd
Parallel port bus system
.Sh SYNOPSIS
.Cd "controller ppbus0"
.Pp
.Cd "controller vpo0 at ppbus?"
.Pp
.Cd "device nlpt0 at ppbus?"
.Cd "device plip0 at ppbus?"
.Cd "device ppi0 at ppbus?"
.Sh DESCRIPTION
The
.Em ppbus
system provides a uniform, modular and architecture-independent
system for the implementation of drivers to control various parallel devices,
and to utilize different parallel port chipsets.
.Sh DEVICE DRIVERS
In order to write new drivers or port existing drivers, the ppbus system
provides the following facilities:
.Bl -bullet -item -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 user interface named
.Xr ppi 4
that allows parallel port access from outside the kernel without confliting
with kernel-in drivers.
.El
.Ss Developing new drivers
.Pp
The ppbus 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"
.El
.Ss Porting existing drivers
.Pp
Another approach to the ppbus 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 nlpt Ta "lpt printer driver"
.It Sy plip Ta "lp parallel network interface driver"
.El
.Pp
ppbus should let you port any other software even from other operating systems
that provide similar services.
.Sh PARALLEL PORT CHIPSETS
Parallel port chipset support is provided by
.Xr ppc 4 .
.Pp
The ppbus system provides functions and macros to allocate a new
parallel port bus, then initialize it and upper peripheral device drivers.
.Pp
ppc makes chipset detection and initialisation and then calls ppbus attach
functions to initialize the ppbus system.
.Sh PARALLEL PORT MODEL
The logical parallel port model chosen for the ppbus system is the PC's
parallel port model. Consequently, for the i386 implementation of ppbus,
most of the services provided by ppc are macros for inb()
and outb() calls. But, for an other architecture, accesses to one of our logical
registers (data, status, control...) may require more than one I/O access.
.Ss Description
The parallel port may operate in the following modes:
.Bl -bullet -item -offset indent
.It
compatible mode, also called Centronics mode
.It
bidirectional 8/4-bits mode, also called NIBBLE mode
.It
byte mode, also called PS/2 mode
.It
Extended Capability Port mode, ECP 
.It
Enhanced Parallel Port mode, EPP
.It
mixed ECP+EPP or ECP+PS/2 modes
.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 sofware 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
"Fast Centronics" or "Parallel Port FIFO mode".
.Ss Bidirectional mode
The NIBBLE mode is the most common way to get reverse channel data from a
printer or peripheral. Combined with the standard host to printer mode, it
provides a complete bidirectional channel.
.Pp
In this mode, outputs are 8-bits long. 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. Then,
any transfer is 8-bits long.
.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
.It
FIFOs for both the forward and reverse channels
.It
DMA as well as 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.
.Ss Mixed modes
Some manufacturers, like SMC, have implemented chipsets that support mixed
modes. With such chipsets, mode switching is available at any time by
accessing the extended control register.
.Sh ARCHITECTURE
.Ss adapter, ppbus and device layers
First, there is the
.Em adapter
layer, the lowest of the ppbus system. It provides
chipset abstraction throw 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 ppbus
.It
propose an arch-independent interface to access the hardware layer.
.El
.Pp
Finaly, the
.Em device
layer gathers the parallel peripheral device drivers.
.Pp
Each layer has its own C structure respectively ppb_adapter, ppb_data and 
ppb_device. The ppb_link structure gathers pointers to other structures and
info shared among different layers.
.Pp
See description of these structures in
.Xr ppbconf 9 .
.Ss Parallel modes managment
We have to differenciate operating modes at various ppbus system layers.
Actually, ppbus and adapter operating modes on one hands and for each
one, current and available modes are seperated.
.Pp
With this level of abstraction a particular chipset may commute from any
native mode the any other mode emulated with extended modes without
disturbing upper layers. For example, most chipsets support NIBBLE mode as
native and emulated with ECP and/or EPP.
.Pp
This achitecture should support IEEE1284-1994 modes.
.Sh FEATURES
.Ss The boot process
The boot process starts with the probe phasis of the
.Xr ppc 4
driver during ISA bus (PC architecture) initialisation. During attachment of
the ppc driver, a new ppbus structure is allocated, initialized
(linked to the adapter structure) then passed to the function
.Fn ppb_attachdevs "struct ppb_data *ppb" .
.Pp
.Fn ppb_attachdevs ""
tries to detect any PnP parallel peripheral (according to
.%T "Plug and Play Parallel Port Devices"
draft from (c)1993-4 Microsoft Corporation)
then probes and attaches known device drivers.
.Pp
During probe, device drivers are supposed to request the ppbus and try to
set their operating mode. This mode will be saved in the context structure and
returned each time the driver requests the ppbus.
.Ss Bus allocation and interrupts
ppbus allocation is mandatory not to corrupt I/O of other devices. An other
usage of ppbus allocation is to reserve the port and receive incoming
interrupts.
.Pp
Interrupts are connected to the
.Fn ppcintr ""
function which delivers them to ppbus directly with a
.Fn ppb_intr "struct ppb_link *pl"
call. ppbus redirects the
interrupt to the bus owner's handler if defined. Consequently, if a device
wants to be delivered an interrupt, it must own the ppbus.
.Ss Microsequences
.Em Microsequences
is a general purpose mechanism to allow fast low-level
manipulation of the parallel port. Microsequences may be used to do either
standard (in IEEE1284 modes) or non-standard transfers. The philosophy of
microsequences is to avoid the overhead of the ppbus layer and do most of
the job at adapter level.
.Pp
A microsequence 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 langage are coded at adapter level for efficiency.
.Pp
As an example, the
.Xr vpo 4
driver uses microsequences 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
.Sh SEE ALSO
.Xr ppbconf 9 ,
.Xr ppc 4 ,
.Xr ppi 4 ,
.Xr vpo 4 ,
.Xr nlpt 4 ,
.Xr plip 4
.Sh HISTORY
The
.Nm
manual page first appeared in
.Fx 3.0 .
.Sh AUTHOR
This
manual page was written by
.An Nicolas Souchu .