Devices ecpp(7D)
NAME
ecpp - IEEE 1284 compliant parallel port driver
SYNOPSIS
#include
#include
ecpp@unit-address
DESCRIPTION
The ecpp driver provides a bi-directional interface to IEEE
1284 compliant devices as well as a forward single-
directional interface to Centronics devices. In addition tothe Centronics protocol, the ecpp driver supports the IEEE
1284Compatibility, Nibble, and ECP protocols.ECPP_COMPAT_MODE and ECPP_CENTRONICS modes of operation have
logically identical handshaking protocols, however devicesthat support ECPP_COMPAT_MODE are IEEE 1284 compliant dev-
ices. IEEE 1284 compliant devices support at leastECPP_COMPAT_MODE and ECPP_NIBBLE_MODE. Centronics devices
support only ECPP_CENTRONICS mode.
By default, ECPP_COMPAT_MODE devices have a strobe handshak-
ing pulse width of 500ns. For this mode, forward data transfers are conducted by DMA. By default, the strobe pulsewidth for ECPP_CENTRONICS devices is two microseconds. For-
ward transfers for these devices are managed through PIO.The default characteristics for both ECPP_COMPAT_MODE and
ECPP_CENTRONICS devices may be changed through tunable vari-
ables defined in ecpp.conf.
The ecpp driver is an exclusive-use device, meaning that if
the device is already open, subsequent opens fail with EBUSY. Default OperationEach time the ecpp device is opened, the device is marked as
EBUSY and the configuration variables are set to theirdefault values. The write_timeout period is set to 90
seconds. The driver sets the mode variable according to the following algorithm: The driver initially attempts to negotiate thelink into ECPP_ECP_MODE during open(2). If it fails, the
driver tries to negotiate into ECPP_NIBBLE_MODE mode. If
SunOS 5.11 Last change: 3 Mar 2010 1
Devices ecpp(7D)
that fails, the driver operates in ECPP_CENTRONICS mode.
Upon successfully opening the device, IEEE 1284 compliant devices will be left idle in either reverse idle phase ofECPP_ECP_MODE or in ECPP_NIBBLE_MODE. Subsequent calls to
write(2) invokes the driver to move the link into eitherECPP_COMPAT_MODE or the forward phase of ECPP_ECP_MODE.
After the transfer completes, the link returns to idle state. The application may attempt to negotiate the device into aspecific mode or set the write_timeout values through the
ECPPIOC_SETPARMS ioctl(2) call. For mode negotiation to be
successful, both the host workstation and the peripheral must support the requested mode. TunablesCharacteristics of the ecpp driver may be tuned by the vari-
ables described in /kernel/drv/ecpp.conf. These variables
are read by the kernel during system startup. To tune thevariables, edit the ecpp.conf file and invoke update_drv(1M)
to have the kernel read the file again. Some Centronics peripherals and certain IEEE 1284 compatibleperipherals will not operate with the parallel port operat-
ing in a fast handshaking mode. If printing problems occur,set fast-centronicsand fast-1284-compatible to false. See
/kernel/drv/ecpp.conf for more information.
Read/Write Operation
The ecpp driver is a full duplex STREAMS device driver.
While an application is writing to an IEEE 1284 compliant device, another thread may read from it. Write OperationA write(2) operation returns the number of bytes success-
fully 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 theBPPIOC_GETERR ioctl(2) call. The captured status information
is overwritten each time an attempted transfer or aBPPIOC_TESTIO ioctl(2) occurs.
Read Operation If a failure or error condition occurs during a read(2), the number of bytes successfully read is returned (short read). When attempting to read a port that has no data currentlyavailable, read(2) returns 0 if O_NDELAY is set. If
O_NONBLOCK is set, read(2) returns -1 and sets errno to
EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read(2) blocks
SunOS 5.11 Last change: 3 Mar 2010 2
Devices ecpp(7D)
until data become available. IOCTLS The ioctl(2) calls described below are supported. Note thatwhen ecpp is transferring data, the driver waits until the
data has been sent to the device before processing the ioctl(2) call.The ecpp driver supports prnio(7I) interfaces.
Note -
The PRNIOC_RESET command toggles the nInit signal for 2
ms, followed by default negotiation.The following ioctl(2) calls are supported for backward com-
patibility and are not recommended for new applications:ECPPIOC_GETPARMS Get current transfer parameters. The
argument is a pointer to a structecpp_transfer_parms. 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 defaultconfiguration. See DESCRIPTION for more
information.ECPPIOC_SETPARMS Set transfer parameters. The argument is
a pointer to a structecpp_transfer_parms. If a parameter is
out of range, EINVAL is returned. If the peripheral or host device cannot support the requested mode, EPROTONOSUPPORT is returned. See below for a description ofecpp_transfer_parms and its valid param-
eters. The Transfer Parameters Structure isdefined in
. struct ecpp_transfer_parms {
int write_timeout;
int mode; };The write_timeout field is set to the
value of ecpp-transfer-timeout specified
in the ecpp.conf. The write_timeout
SunOS 5.11 Last change: 3 Mar 2010 3
Devices ecpp(7D)
field specifies how long the driver will wait for the peripheral to respond to a transfer request. The value must be greater than 0 and less thanECPP_MAX_TIMEOUT. All other values are
out of range. The mode field reflects the IEEE 1284 mode to which the parallel port is currently configured. The mode may be set to one of the following values only:ECPP_CENTRONICS, ECPP_COMPAT_MODE,
ECPP_NIBBLE_MODE, ECPP_ECP_MODE. All
other values are invalid. If the requested mode is not supported,ECPPIOC_SETPARMS will return EPROTO-
NOSUPPORT and the mode will be set toECPP_CENTRONICS mode. Afterwards, the
application may change the mode back tothe original mode with ECPPIOC_SETPARMS.
ECPPIOC_GETDEVID This ioctl gets the IEEE 1284 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 inargument. The 1284 device ID structure:
must be passed as an 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 */ }; The mode is the IEEE 1284 mode into which the port will be negotiated to retrieve device ID information. If the peripheral or host do not support the mode, EPROTONOSUPPORT is returned. Applications should set mode toECPP_NIBBLE_MODE. len is the length of
the buffer pointed to by addr. rlen is the actual length of the device ID string returned from the peripheral. If the returned rlen is greater than len, the application can callECPPIOC_GETDEVID again with a buffer
SunOS 5.11 Last change: 3 Mar 2010 4
Devices ecpp(7D)
length equal or greater than rlen. Note that the two length bytes of the IEEE 1284 device ID are not taken into account and are not returned in the user buffer.After ECPPIOC_GETDEVID successfully com-
pletes, the driver returns the link toECPP_COMPAT_MODE. The application is
responsible for determining the previous mode the link was operating in and returning the link to that mode.BPPIOC_TESTIO Tests the forward transfer readiness of
a peripheral operating in Centronics or Compatibility mode. TESTIO determines if the peripheral is ready to receive data by checking the open flags and the Centronics statussignals. If the current mode of the dev-
ice is ECPP_NIBBLE_MODE, the driver
negotiates the link intoECPP_COMPAT_MODE, check the status sig-
nals and then return the link toECPP_NIBBLE_MODE mode. If the current
mode is ECPP_CENTRONICS or
ECPP_COMPAT_MODE, TESTIO examines the
Centronics status signals in the current mode. To receive data, the device must have the nErr and Select signals asserted and must not have the PE andBusy signals asserted. If ecpp is
transferring data, TESTIO waits until the previous data sent to the driver isdelivered before executing TESTIO. How-
ever if an error condition occurs while a TESTIO is waiting, TESTIO returns immediately. If TESTIO determines that the conditions are ok, 0 is returned.Otherwise, -1 is returned, errno is set
to EIO and the state of the status pins is captured. The captured status can beretrieved using the BPPIOC_GETERR
ioctl(2) call. The timeout_occurred and
bus_error fields will never be set by
this ioctl(2).BPPIOC_GETERR Get last error status. The argument is a
pointer to a struct bpp_error_status
SunOS 5.11 Last change: 3 Mar 2010 5
Devices ecpp(7D)
defined in
The error status structure is:header file. 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 */ };The pin_status field indicates possible
error conditions. The valid bits forpin_status are: BPP_ERR_ERR,
BPP_SLCT_ERR, BPP_PE_ERR, BPP_BUSY_ERR.
A set bit indicates that the associated pin is asserted. This structure indicates the status of all the appropriate status bits at the time of the most recent error condition during a write(2) call, or the status of the bits at the most recentBPPIOC_TESTIO ioctl(2)call.
pin_status indicates possible error con-
ditions under ECPP_CENTRONICS or
ECPP_COMPAT_MODE. Under these modes, the
state of the status pins will indicate the state of the device. For instance, many Centronics printers lower the nErr signal when a paper jam occurs. The behavior of the status pins depends onthe device. Additional status informa-
tion may be retrieved through the backchannel.The timeout_occurred value is set when a
timeout occurs during write(2).bus_error is not used in this interface.
The following ioctls are used to directly read and write the parallel port status and control signals. If the currentmode of the device is ECPP_ECP_MODE or ECPP_NIBBLE_MODE, the
driver negotiates the link into ECPP_COMPAT_MODE, gets or
sets the registers and then returns the link toECPP_NIBBLE_MODE. If the current mode is ECPP_CENTRONICS or
ECPP_COMPAT_MODE, these ioctls will get/set the register
values in the current mode.SunOS 5.11 Last change: 3 Mar 2010 6
Devices ecpp(7D)
ECPPIOC_GETREGS Read register values. The argument is a
pointer to a struct ecpp_regs. See below
for a description of this structure.ECPPIOC_SETREGS Set ecpp register values. The argument is
a pointer to a struct ecpp_regs. See
below for a description of this struc-
ture. If a parameter is out of range, EINVAL is returned. The Port Register Structure is defined in
. struct ecpp_regs {
uchar dsr; /* status reg */u_char dcr; /* control reg */
};The status register is read-only. The
ECPPIOC_SETREGS ioctl has no affect on
this register. Valid bit values for dsrare: ECPP_nERR, ECPP_SLCT, ECPP_PE,
ECPP_nACK, ECPP_nBUSY. All other bits are
reserved and always return 1. The control register is read/write. Validbit values for dcr are: ECPP_STB,
ECPP_AFX, ECPP_nINIT, ECPP_SLCTIN. All
other bits are reserved. Reading reserved bits always return 1. An attempt to write 0s into these bits results in EINVAL. DEVICE SPECIAL FILES/dev/lpN Solaris x86 only. (Backwards compatibil-
ity with former lp(7D) devices.)/dev/printers/N 1284 compliant parallel port device spe-
cial files appears in both namespaces. FILESkernel/drv/ecpp
32-bit ELF kernel module
kernel/drv/sparcv9/ecpp
64-bit SPARC ELF kernel module
SunOS 5.11 Last change: 3 Mar 2010 7
Devices ecpp(7D)
kernel/drv/amd64/ecpp
64-bit x86 ELF kernel module
kernel/drv/ecpp.conf
driver configuration filekernel/drv/sparcv9/ecpp.conf
driver configuration file for 64-bit SPARC
kernel/drv/amd64/ecpp.conf
driver configuration file for 64-bit x86
ERRORS
EBADF The device is opened for write-only access and a
read is attempted, or the device is opened forread-only access and a write is attempted.
EBUSY 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.EINVAL A ECPPIOC_SETPARMS ioctl() is attempted with an
out-of-range value in the ecpp_transfer_parms
structure. A ECPPIOC_SETREGS ioctl() is attempted
with an invalid value in the ecpp_regs structure.
An ioctl() is attempted with an invalid value in the command argument.An invalid command argument is received during modload(1M) or modunload(1M). EIO The driver encountered a bus error when attemptingan access. A read or write did not complete prop-
erly, due to a peripheral error or a transfer timeout. ENXIO 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.SunOS 5.11 Last change: 3 Mar 2010 8
Devices ecpp(7D)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| Architecture | PCI-based systems ISA-|
| | based systems (x86) ||_____________________________|_____________________________|
| Availability | driver/storage/glm (Sparc) ||_____________________________|_____________________________|
| | driver/i86pc/platform (x86) ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
modload(1M), modunload(1M), update_drv(1M)ioctl(2), open(2),
read(2), write(2), attributes(5), usbprn(7D), prnio(7I), streamio(7I)IEEE Std 1284-1994
http://www.sun.com/io DIAGNOSTICS Parallel port controller not supported Driver does not support parallel port controller on the given host. Attach failed.SunOS 5.11 Last change: 3 Mar 2010 9