Unleashed v1.4

[unleashed.git] / share / man / man7d / ecpp.7d

'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ECPP 7D "May 13, 2017"
.SH NAME
ecpp \- IEEE 1284 compliant parallel port driver
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
.fi

.LP
.nf
#include <sys/ecppio.h>
.fi

.LP
.nf
ecpp@unit-address
.fi

.SH DESCRIPTION
.LP
The \fBecpp\fR driver provides a bi-directional interface to \fIIEEE 1284\fR
compliant devices as well as a forward single-directional interface to
Centronics devices. In addition to the Centronics protocol, the \fBecpp\fR
driver supports the \fIIEEE 1284\fRCompatibility, Nibble, and ECP protocols.
\fBECPP_COMPAT_MODE\fR and \fBECPP_CENTRONICS\fR modes of operation have
logically identical handshaking protocols, however devices that support
\fBECPP_COMPAT_MODE\fR are \fIIEEE 1284\fR compliant devices. \fIIEEE 1284\fR
compliant devices support at least \fBECPP_COMPAT_MODE\fR and
\fBECPP_NIBBLE_MODE\fR. Centronics devices support only \fBECPP_CENTRONICS\fR
mode.
.sp
.LP
By default, \fBECPP_COMPAT_MODE\fR devices have a strobe handshaking pulse
width of 500ns. For this mode, forward data transfers are conducted by DMA. By
default, the strobe pulse width for \fBECPP_CENTRONICS\fR devices is two
microseconds. Forward transfers for these devices are managed through PIO. The
default characteristics for both \fBECPP_COMPAT_MODE\fR and
\fBECPP_CENTRONICS\fR devices may be changed through tunable variables defined
in \fBecpp.conf\fR.
.sp
.LP
The \fBecpp\fR driver is an \fIexclusive-use\fR device, meaning that if the
device is already open, subsequent opens fail with \fBEBUSY\fR.
.SS "Default Operation"
.LP
Each time the \fBecpp\fR device is opened, the device is marked as \fBEBUSY\fR
and the configuration variables are set to their default values. The
\fBwrite_timeout\fR period is set to 90 seconds.
.sp
.LP
The driver sets the mode variable according to the following algorithm: The
driver initially attempts to negotiate the link into \fBECPP_ECP_MODE\fR during
\fBopen\fR(2). If it fails, the driver tries to negotiate into
\fBECPP_NIBBLE_MODE\fR mode. If that fails, the driver operates in
\fBECPP_CENTRONICS\fR mode. Upon successfully opening the device, \fIIEEE
1284\fR compliant devices will be left idle in either reverse idle phase of
\fBECPP_ECP_MODE\fR or in \fBECPP_NIBBLE_MODE\fR. Subsequent calls to
\fBwrite\fR(2) invokes the driver to move the link into either
\fBECPP_COMPAT_MODE\fR or the forward phase of \fBECPP_ECP_MODE\fR. After the
transfer completes, the link returns to idle state.
.sp
.LP
The application may attempt to negotiate the device into a specific mode or set
the \fBwrite_timeout\fR values through the \fBECPPIOC_SETPARMS\fR
\fBioctl\fR(2) call. For mode negotiation to be successful, both the host
workstation and the peripheral must support the requested mode.
.SS "Tunables"
.LP
 Characteristics of the \fBecpp\fR driver may be tuned by the variables
described in \fB/kernel/drv/ecpp.conf\fR. These variables are read by the
kernel during system startup. To tune the variables, edit the \fBecpp.conf\fR
file and invoke \fBupdate_drv\fR(8) to have the kernel read the file again.
.sp
.LP
Some Centronics peripherals and certain \fIIEEE 1284\fR compatible peripherals
will not operate with the parallel port operating in a fast handshaking mode.
If printing problems occur, set "fast-centronics" and "fast-1284-compatible" to
"false." See \fB/kernel/drv/ecpp.conf\fR for more information.
.SS "Read/Write Operation"
.LP
The \fBecpp\fR driver is a full duplex STREAMS device driver. While an
application is writing to an \fIIEEE 1284\fR compliant device, another thread
may read from it.
.SS "Write Operation"
.LP
A \fBwrite\fR(2) operation returns the number of bytes successfully written to
the stream head. If a failure occurs while a Centronics device is transferring
data, the content of the status bits will be captured at the time of the error
and can be retrieved by the application program using the \fBBPPIOC_GETERR\fR
\fBioctl\fR(2) call. The captured status information is overwritten each time
an attempted transfer or a \fBBPPIOC_TESTIO\fR \fBioctl\fR(2) occurs.
.SS "Read Operation"
.LP
If a failure or error condition occurs during a \fBread\fR(2), the number of
bytes successfully read is returned (short read). When attempting to read a
port that has no data currently available, \fBread\fR(2) returns \fB0\fR if
\fBO_NDELAY\fR is set. If \fBO_NONBLOCK\fR is set, \fBread\fR(2) returns
\fB-1\fR and sets errno to \fBEAGAIN.\fR If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR
are clear, \fBread\fR(2) blocks until data become available.
.SH IOCTLS
.LP
The \fBioctl\fR(2) calls described below are supported. Note that when
\fBecpp\fR is transferring data, the driver waits until the data has been sent
to the device before processing the \fBioctl\fR(2) call.
.sp
.LP
The ecpp driver supports \fBprnio\fR(7I) interfaces.
.LP
Note -
.sp
.RS 2
The \fBPRNIOC_RESET\fR command toggles the \fBnInit\fR signal for 2 ms,
followed by default negotiation.
.RE
.sp
.LP
The following \fBioctl\fR(2) calls are supported for backward compatibility and
are not recommended for new applications:
.sp
.ne 2
.na
\fB\fBECPPIOC_GETPARMS\fR\fR
.ad
.RS 20n
Get current transfer parameters. The argument is a pointer to a struct
\fBecpp_transfer_parms\fR. See below for a description of the elements of this
structure. If no parameters have been configured since the device was opened,
the structure will be set to its default configuration. See Default Operation
above for more information.
.RE

.sp
.ne 2
.na
\fB\fBECPPIOC_SETPARMS\fR\fR
.ad
.RS 20n
Set transfer parameters. The argument is a pointer to a struct
\fBecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is
returned. If the peripheral or host device cannot support the requested mode,
\fBEPROTONOSUPPORT\fR is returned. See below for a description of
\fBecpp_transfer_parms\fR and its valid parameters.
.sp
The Transfer Parameters Structure is defined in <\fBsys/ecppio.h\fR>.
.sp
.in +2
.nf
struct ecpp_transfer_parms {
    int  write_timeout;
    int  mode;
};
.fi
.in -2

The \fBwrite_timeout\fR field is set to the value of
\fBecpp-transfer-timeout\fR specified in the \fBecpp.conf\fR. The
\fBwrite_timeout\fR field specifies how long the driver will wait for the
peripheral to respond to a transfer request. The value must be greater than
\fB0\fR and less than \fBECPP_MAX_TIMEOUT.\fR All other values are out of
range.
.sp
The mode field reflects the \fIIEEE 1284\fR mode to which the parallel port is
currently configured. The mode may be set to one of the following values only:
\fBECPP_CENTRONICS\fR, \fBECPP_COMPAT_MODE\fR, \fBECPP_NIBBLE_MODE\fR,
\fBECPP_ECP_MODE\fR. All other values are invalid. If the requested mode is not
supported, \fBECPPIOC_SETPARMS\fR will return \fBEPROTONOSUPPORT\fR and the
mode will be set to \fBECPP_CENTRONICS\fR mode. Afterwards, the application may
change the mode back to the original mode with \fBECPPIOC_SETPARMS\fR.
.RE

.sp
.ne 2
.na
\fB\fBECPPIOC_GETDEVID\fR\fR
.ad
.RS 20n
This ioctl gets the \fIIEEE 1284\fR device ID from the peripheral in specified
mode. Currently, the device ID can be retrieved only in Nibble mode. A pointer
to the structure defined in \fB<sys/ecppsys.h>\fR must be passed as an
argument.
.sp
The 1284 device ID structure:
.sp
.in +2
.nf
struct ecpp_device_id {
  int  mode; /* mode to use for reading device id */
  int  len;  /* length of buffer */
  int  rlen;  /* actual length of device id string */
  char *addr; /* buffer address */
};
.fi
.in -2

The mode is the \fIIEEE 1284\fR mode into which the port will be negotiated to
retrieve device ID information. If the peripheral or host do not support the
mode, \fBEPROTONOSUPPORT\fR is returned. Applications should set mode to
\fBECPP_NIBBLE_MODE\fR. \fBlen\fR is the length of the buffer pointed to by
\fBaddr\fR. \fBrlen\fR is the actual length of the device ID string returned
from the peripheral. If the returned \fBrlen\fR is greater than \fBlen\fR, the
application can call \fBECPPIOC_GETDEVID\fR again with a buffer length equal or
greater than \fBrlen\fR. Note that the two length bytes of the \fIIEEE 1284\fR
device ID are not taken into account and are not returned in the user buffer.
.sp
After \fBECPPIOC_GETDEVID\fR successfully completes, the driver returns the
link to \fBECPP_COMPAT_MODE\fR. The application is responsible for determining
the previous mode the link was operating in and returning the link to that
mode.
.RE

.sp
.ne 2
.na
\fB\fBBPPIOC_TESTIO\fR\fR
.ad
.RS 20n
Tests the forward transfer readiness of a peripheral operating in Centronics or
Compatibility mode.
.sp
\fBTESTIO\fR determines if the peripheral is ready to receive data by checking
the open flags and the Centronics status signals. If the current mode of the
device is \fBECPP_NIBBLE_MODE\fR, the driver negotiates the link into
\fBECPP_COMPAT_MODE\fR, check the status signals and then return the link to
\fBECPP_NIBBLE_MODE\fR mode. If the current mode is \fBECPP_CENTRONICS\fR or
\fBECPP_COMPAT_MODE\fR, \fBTESTIO\fR examines the Centronics status signals in
the current mode. To receive data, the device must have the \fBnErr\fR and
\fBSelect\fR signals asserted and must not have the \fBPE\fR and \fBBusy\fR
signals asserted. If \fBecpp\fR is transferring data, \fBTESTIO\fR waits until
the previous data sent to the driver is delivered before executing
\fBTESTIO\fR. However if an error condition occurs while a \fBTESTIO\fR is
waiting, \fBTESTIO\fR returns immediately. If \fBTESTIO\fR determines that the
conditions are ok, \fB0\fR is returned. Otherwise, \fB-1\fR is returned, errno
is set to \fBEIO\fR and the state of the status pins is captured. The captured
status can be retrieved using the \fBBPPIOC_GETERR\fR \fBioctl\fR(2) call. The
\fBtimeout_occurred\fR and \fBbus_error\fR fields will never be set by this
\fBioctl\fR(2). \fBBPPIOC_TESTIO\fR and \fBBPPIOC_GETERR\fR are compatible to
the ioctls specified in \fBbpp\fR(7D).
.RE

.sp
.ne 2
.na
\fB\fBBPPIOC_GETERR\fR\fR
.ad
.RS 20n
Get last error status. The argument is a pointer to a \fBstruct
bpp_error_status\fR defined in \fB<sys/bpp_io.h>\fR header file. The error
status structure is:
.sp
.in +2
.nf
struct bpp_error_status {
   char    timeout_occurred; /* 1=timeout */
   char    bus_error;        /* not used */
   uchar_t pin_status;       /* status of pins which
                             /* could cause error */
};
.fi
.in -2

The pin_status field indicates possible error conditions. The valid bits for
pin_status are: \fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, \fBBPP_PE_ERR\fR,
\fBBPP_BUSY_ERR\fR. A set bit indicates that the associated pin is asserted.
.sp
This structure indicates the status of all the appropriate status bits at the
time of the most recent error condition during a \fBwrite\fR(2) call, or the
status of the bits at the most recent \fBBPPIOC_TESTIO\fR \fBioctl\fR(2)call.
.sp
\fBpin_status\fR indicates possible error conditions under
\fBECPP_CENTRONICS\fR or \fBECPP_COMPAT_MODE\fR. Under these modes, the state
of the status pins will indicate the state of the device. For instance, many
Centronics printers lower the \fBnErr\fR signal when a paper jam occurs. The
behavior of the status pins depends on the device. Additional status
information may be retrieved through the backchannel.
.sp
The \fBtimeout_occurred\fR value is set when a timeout occurs during
\fBwrite\fR(2). \fBbus_error\fR is not used in this interface.
.RE

.sp
.LP
The following ioctls are used to directly read and write the parallel port
status and control signals. If the current mode of the device is
\fBECPP_ECP_MODE\fR or \fBECPP_NIBBLE_MODE\fR, the driver negotiates the link
into \fBECPP_COMPAT_MODE\fR, gets or sets the registers and then returns the
link to \fBECPP_NIBBLE_MODE\fR. If the current mode is \fBECPP_CENTRONICS\fR or
\fBECPP_COMPAT_MODE\fR, these ioctls will get/set the register values in the
current mode.
.sp
.ne 2
.na
\fB\fBECPPIOC_GETREGS\fR\fR
.ad
.RS 19n
Read register values. The argument is a pointer to a \fBstruct ecpp_regs\fR.
See below for a description of this structure.
.RE

.sp
.ne 2
.na
\fB\fBECPPIOC_SETREGS\fR\fR
.ad
.RS 19n
Set \fBecpp\fR register values. The argument is a pointer to a \fBstruct
ecpp_regs\fR. See below for a description of this structure. If a parameter is
out of range, \fBEINVAL\fR is returned.
.sp
The Port Register Structure is defined in <\fBsys/ecppio.h\fR>.
.sp
.in +2
.nf
struct ecpp_regs {
    uchar     dsr;  /* status reg */
    u_char    dcr;  /* control reg */
};
.fi
.in -2

The status register is read-only. The \fBECPPIOC_SETREGS\fR ioctl has no affect
on this register. Valid bit values for dsr are: \fBECPP_nERR\fR,
\fBECPP_SLCT\fR, \fBECPP_PE\fR, \fBECPP_nACK\fR, \fBECPP_nBUSY\fR. All other
bits are reserved and always return \fB1\fR.
.sp
The control register is read/write. Valid bit values for dcr are:
\fBECPP_STB\fR, \fBECPP_AFX\fR, \fBECPP_nINIT\fR, \fBECPP_SLCTIN\fR. All other
bits are reserved. Reading reserved bits always return 1. An attempt to write
0s into these bits results in \fBEINVAL\fR.
.RE

.SH DEVICE SPECIAL FILES
.ne 2
.na
\fB\fB/dev/lp\fIN\fR\fR\fR
.ad
.RS 19n
Solaris x86 only. (Backwards compatibility with former \fBlp\fR(7D) devices.)
.RE

.sp
.ne 2
.na
\fB\fB/dev/printers/\fIN\fR\fR\fR
.ad
.RS 19n
1284 compliant parallel port device special files appears in both namespaces.
.RE

.SH FILES
.ne 2
.na
\fB\fBkernel/drv/ecpp\fR\fR
.ad
.sp .6
.RS 4n
32-bit ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fBkernel/drv/sparcv9/ecpp\fR\fR
.ad
.sp .6
.RS 4n
64-bit SPARC ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fBkernel/drv/amd64/ecpp\fR\fR
.ad
.sp .6
.RS 4n
64-bit x86 ELF kernel module
.RE

.sp
.ne 2
.na
\fB\fBkernel/drv/ecpp.conf\fR\fR
.ad
.sp .6
.RS 4n
driver configuration file
.RE

.sp
.ne 2
.na
\fB\fBkernel/drv/sparcv9/ecpp.conf\fR\fR
.ad
.sp .6
.RS 4n
driver configuration file for 64-bit SPARC
.RE

.sp
.ne 2
.na
\fB\fBkernel/drv/amd64/ecpp.conf\fR\fR
.ad
.sp .6
.RS 4n
driver configuration file for 64-bit x86
.RE

.SH ERRORS
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
The device is opened for write-only access and a read is attempted, or the
device is opened for read-only access and a write is attempted.
.RE

.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
The device has been opened and another open is attempted. An attempt has been
made to unload the driver while one of the units is open.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
A \fBECPPIOC_SETPARMS\fR \fBioctl()\fR is attempted with an out-of-range value
in the \fBecpp_transfer_parms\fR structure. A \fBECPPIOC_SETREGS\fR
\fBioctl()\fR is attempted with an invalid value in the \fBecpp_regs\fR
structure. An \fBioctl()\fR is attempted with an invalid value in the command
argument.An invalid command argument is received during \fBmodload\fR(8) or
\fBmodunload\fR(8).
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
The driver encountered a bus error when attempting an access. A read or write
did not complete properly, due to a peripheral error or a transfer timeout.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
The driver has received an open request for a unit for which the attach failed.
The driver has received a write request for a unit which has an active
peripheral error.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Architecture    PCI-based systems
_
        ISA-based systems (x86)
_
Interface stability     Evolving
.TE

.SH SEE ALSO
.LP
\fBmodload\fR(8), \fBmodunload\fR(8), \fBupdate_drv\fR(8), \fBioctl\fR(2),
\fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
\fBbpp\fR(7D), \fBusbprn\fR(7D), \fBprnio\fR(7I), \fBstreamio\fR(7I)
.sp
.LP
\fIIEEE Std 1284-1994\fR
.SH DIAGNOSTICS
.ne 2
.na
\fBParallel port controller not supported\fR
.ad
.sp .6
.RS 4n
Driver does not support parallel port controller on the given host. Attach
failed.
.RE