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]
#include <sys/types.h>
#include <sys/ecppio.h>
ecpp@unit-address
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.
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.
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.
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.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.
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.
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.
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).
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.
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.
x86 only. (Backwards compatibility with former lp(4D) devices.)
1284 compliant parallel port device special files appears in both namespaces.
Device driver (SPARC)
Device driver (x86)
Driver configuration file
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.
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.
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).
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.
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.
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Architecture PCI-based systems |
| ISA-based systems (x86) |
| Interface stability Evolving |
IEEE Std 1284-1994
Driver does not support parallel port controller on the given host. Attach failed.