Finally they arrive! ppbus (Parallel Port Bus framework) manpages.

1 files changed, 267 insertions, 0 deletions

diff --git a/share/man/man4/ppbus.4 b/share/man/man4/ppbus.4
new file mode 100644
index 0000000..1a860ed
--- /dev/null
+++ b/share/man/man4/ppbus.4
@@ -0,0 +1,267 @@
+.\" 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 ppbus"
+.Pp
+.Cd "controller vpo at ppbus?"
+.Pp
+.Cd "device nlpt at ppbus?"
+.Cd "device plip at ppbus?"
+.Cd "device ppi 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 .