Tribblix: manual page: ecpp.4d

ECPP(4D) Devices ECPP(4D)

NAME

ecpp - IEEE 1284 compliant parallel port driver

SYNOPSIS

#include <sys/types.h>

#include <sys/ecppio.h>

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 to the Centronics protocol, the
ecpp driver supports the IEEE 1284 Compatibility, Nibble, and ECP
protocols. ECPP_COMPAT_MODE and ECPP_CENTRONICS modes of operation
have logically identical handshaking protocols, however devices that
support ECPP_COMPAT_MODE are IEEE 1284 compliant devices. IEEE 1284
compliant devices support at least ECPP_COMPAT_MODE and
ECPP_NIBBLE_MODE. Centronics devices support only ECPP_CENTRONICS
mode.

By default, ECPP_COMPAT_MODE 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 ECPP_CENTRONICS
devices is two microseconds. Forward 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 variables 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 Operation

Each time the ecpp device is opened, the device is marked as EBUSY
and the configuration variables are set to their default 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 the link into
ECPP_ECP_MODE during open(2). If it fails, the driver tries to
negotiate into ECPP_NIBBLE_MODE mode. If 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 of ECPP_ECP_MODE or in ECPP_NIBBLE_MODE.
Subsequent calls to write(2) invokes the driver to move the link into
either ECPP_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 a specific
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.

Tunables

Characteristics of the ecpp driver may be tuned by the variables
described in /kernel/drv/ecpp.conf. These variables are read by the
kernel during system startup. To tune the variables, edit the
ecpp.conf file and invoke update_drv(8) to have the kernel read the
file again.

Some Centronics peripherals and certain IEEE 1284 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
/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 Operation

A write(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 BPPIOC_GETERR ioctl(2) call. The captured status
information is overwritten each time an attempted transfer or a
BPPIOC_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 currently available, 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 until data become available.

IOCTLS

The ioctl(2) calls described below are supported. Note that when 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(4I) 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 compatibility
and are not recommended for new applications:

ECPPIOC_GETPARMS
Get current transfer parameters. The argument is
a pointer to a struct ecpp_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 default configuration. See Default
Operation above for more information.

ECPPIOC_SETPARMS
Set transfer parameters. The argument is a
pointer to a struct ecpp_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 of ecpp_transfer_parms
and its valid parameters.

The Transfer Parameters Structure is defined in
<sys/ecppio.h>.

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 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 than ECPP_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
EPROTONOSUPPORT and the mode will be set to
ECPP_CENTRONICS mode. Afterwards, the application
may change the mode back to the 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 in
<sys/ecppsys.h> must be passed as an argument.

The 1284 device ID structure:

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 to ECPP_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 call ECPPIOC_GETDEVID again with
a buffer 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 completes,
the driver returns the link to ECPP_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 status signals. If the current mode of
the device is ECPP_NIBBLE_MODE, the driver
negotiates the link into ECPP_COMPAT_MODE, check
the status signals and then return the link to
ECPP_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 and Busy signals asserted.
If ecpp is transferring data, TESTIO waits until
the previous data sent to the driver is delivered
before executing TESTIO. However 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 be retrieved 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 defined in
<sys/bpp_io.h> header file. The error status
structure is:

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 for pin_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 recent
BPPIOC_TESTIO ioctl(2)call.

pin_status indicates possible error conditions
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 on the device. Additional
status information 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 current mode 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 to ECPP_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.

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 structure. If a parameter is
out of range, EINVAL is returned.

The Port Register Structure is defined in
<sys/ecppio.h>.

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 dsr are: 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. Valid bit
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
x86 only. (Backwards compatibility with former
lp(4D) devices.)

/dev/printers/N
1284 compliant parallel port device special files
appears in both namespaces.

FILES

/kernel/drv/sparcv9/ecpp

Device driver (SPARC)

/kernel/drv/amd64/ecpp

Device driver (x86)

/kernel/drv/ecpp.conf

Driver configuration file

ERRORS

EBADF
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.

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(8) or modunload(8).

EIO
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.

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.

ATTRIBUTES

DIAGNOSTICS

Parallel port controller not supported

Driver does not support parallel port controller on the given
host. Attach failed.

May 17, 2020 ECPP(4D)