Devices usbprn(7D)
NAME
usbprn - USB printer class driver
SYNOPSIS
#include
#include
usbprn@unit-address
DESCRIPTION
The usbprn driver is a USBA (Solaris USB Architecture) com-
pliant client driver that supports the USB Printer Class 1.0specification. The usbprn driver supports a subset of the
ecpp(7D) parallel port driver functionality. However, unlikethe STREAMS-based ecpp driver, usbprn is a character driver.
The usbprn driver supports all USB printer-class compliant
printers. For a list of recommended printers and USB paral-
lel printer adapters, visit http://www.sun.com/io. The usbrpn driver includes support for communicating with many different printers. To use these printers, it might benesessary to install and configure additional format conver-
sion packages available in the Solaris distribution. Confi-
guration of these conversion packages under the Solaris printing system can be simplified through the use of the printmgr(1M). This tool allows selection of printer manufacturer/model information while creating a print queue.For USB connected printers, it attempts to pre-select the
the manufacturer and model information based on the 1284 device id supplied by the printer. UGEN (Generic USB)The usbprn driver also supports a ugen(7D) interface allow-
ing raw access to the device, for example by libusb(3LIB)applications, by passing the drivers bound to each inter-
face. Because a libusb application might change the state of the device, you should not access the device through the child interface drivers. DEFAULT OPERATIONWith certain minor exceptions (outlined in the Notes sec-
tions below), the usbprn driver supports a subset of the
ecpp(7D) ioctl interfaces:SunOS 5.11 Last change: 25 Feb 2010 1
Devices usbprn(7D)
Configuration variables are set to their default values eachtime the USB printer device is attached. The write_timeout
period (defined in the ECPPIOC_SETPARMS ioctl description
below) is set to 90 seconds. The mode is set to centronicsmode (ECPP_CENTRONICS). Parameters can be changed through
the ECPPIOC_SETPARMS ioctl and read through the
ECPPIOC_GETPARMS ioctl. Each time the USB printer device is
opened, the device is marked as busy and all further opens returns EBUSY. Once the device is open, applications can write to the device and the driver can send data and obtain device id and status.Unlike the ecpp(7D) driver, usbprn resets configuration
variables to their default values with each attach(9E). (The ecpp(7D) driver resets configuration variables with each open(2).) WRITE OPERATIONA write(2) operation returns the number of bytes success-
fully written to the device. If a failure occurs while a driver is transferring data to printer, the contents of the status bits are captured at the time of the error and can be retrieved by the application program using theECPPIOC_GETERR ioctl(2) call. The captured status informa-
tion is overwritten each time an ECPPIOC_TESTIO ioctl(2)
occurs. IOCTLSThe usbprn driver supports prnio(7I) interfaces. Note that
the PRNIOC_RESET command has no effect on USB printers.
The following ioctl(2) calls are supported for backward com-
patibility and are not recommended for new applications.ECPPIOC_GETPARMS Gets current transfer parameters. The
argument is a pointer to structecpp_transfer_parms. If parameters are
not configured after the device is opened, the structure is set to its default configuration. Unlike the ecpp(7D) driver, only theECPP_CENTRONICS mode is currently sup-
ported in usbprn.
ECPPIOC_SETPARMS Sets transfer parameters. The argument
is a pointer to a structecpp_transfer_parms. If a parameter is
out of range, EINVAL is returned. If theSunOS 5.11 Last change: 25 Feb 2010 2
Devices usbprn(7D)
peripheral or host device cannot support the requested mode, EPROTONOSUPPORT is returned. The transfer parameters structure is defined in: struct ecpp_transfer_parms {
int write_timeout;
int mode; };The write_timeout field, which specifies
how long the driver takes to transfer 8192 bytes of data to the device, is set to a default value of 90 seconds. Thewrite_timeout field must be greater than
one second and less than 300 seconds (five minutes.) Unlike the ecpp(7D) driver, only theECPP_CENTRONICS mode is currently sup-
ported in usbprn. Also, the semantics of
write_timeout in usbprn differ from
ecpp(7D). Refer to ecpp(7D) for informa-
tion.BPPIOC_TESTIO Tests the transfer readiness of a print
device and checks status bits to deter-
mine if a write(2) succeeds. If status bits are set, a transfer fails. If a transfer succeeds, zero is returned. If a transfer fails, the driver returns EIO and the state of the status bits are captured. The captured status can beretrieved using the BPPIOC_GETERR
ioctl(2) call. Unlike the ecpp(7D) driver, only theECPP_CENTRONICS mode is currently sup-
ported in usbprn. Additionally,
bus_error and timeout_occurred fields
are not used in the usbprn interface.
(In ecpp(7D), timeout_occurred is used.)
BPPIOC_GETERR Get last error status. The argument is a
pointer to a struct bpp_error_status.
This structure indicates the status of all the appropriate status bits at the time of the most recent error conditionSunOS 5.11 Last change: 25 Feb 2010 3
Devices usbprn(7D)
during a write(2) call, or the status of the bits at the most recentBPPIOC_TESTIO ioctl(2) call.
struct bpp_error_status {
char timeout_occurred; /* not used */
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 error statusstructure bpp_error_status is defined in
the include file
. The valid bits for pin_status can be
BPP_ERR_ERR, BPP_SLCT_ERR, and
BPP_PE_ERR. A set bit indicates that the
associated pin is asserted. Unlike the ecpp(7D) driver, only theECPP_CENTRONICS mode is currently sup-
ported in usbprn. Additionally, the
bus_error and timeout_occurred fields
are not used in the usbprn interface.
(In ecpp(7D), timeout_occurred is used.)
Unlike ecpp(7D), the BPP_BUSY_ERR status
bit is not supported by USB printers.ECPPIOC_GETDEVID Gets the IEEE 1284 device ID from the
peripheral. The argument is a pointer toa struct ecpp_device_id. Applications
should set mode to ECPP_CENTRONICS. If
another mode is used, the driver returns EPROTONOSUPPORT. 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 should callECPPIOC_GETDEVID a second time with a
buffer length equal to rlen. 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 */SunOS 5.11 Last change: 25 Feb 2010 4
Devices usbprn(7D)
Unlike ecpp(7D), only theECPP_CENTRONICS mode is currently sup-
ported in usbprn.
READ OPERATION The read operation is not supported and returns EIO.ERRORS
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 An unsupported IOCTL has been received. AECPPIOC_SETPARMS ioctl(2) is attempted
with an out of range value in theecpp_transfer_parms structure.
EIO The driver has received an unrecoverable device error, or the device is not responding, or the device has stalled when attempting an access. A write(2) orioctl(2) did not complete due to a peri-
pheral access. A read(2) system call has been issued. ENXIO The driver has received an open(2) request for a unit for which the attach failed. ENODEV The driver has received an open(2) request for a device that has been disconnected. EPROTONOSUPPORT The driver has received aECPPIOC_SETPARMS ioctl(2) for a mode
argument other than ECPP_CENTRONICS in
the ecpp_transfer_parms structure.
FILES/kernel/drv/usbprn 32-bit x86 ELF kernel module
/kernel/drv/amd64/usbprn 64-bit x86 ELF kernel module
SunOS 5.11 Last change: 25 Feb 2010 5
Devices usbprn(7D)
/kernel/drv/sparcv9/usbprn 64-bit SPARC ELF kernel module
/dev/usb/*/*/* ugen(7D) nodes. /dev/printers/n Character special filesATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:_____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|______________________________|
| Architecture | SPARC, x86, PCI-based systems|
|_____________________________|______________________________|
| Availability | driver/usb ||_____________________________|______________________________|
SEE ALSO
cfgadm_usb(1M), printmgr(1M), ioctl(2), open(2), read(2),
write(2), libusb(3LIB), attributes(5), ecpp(7D), ugen(7D), usba(7D)prnio(7I), attach(9E) Writing Device Drivers Universal Serial Bus Specification 1.0 and 1.1 USB Device Class Definition for Printing Devices 1.0 System Administration Guide: Basic Administration http://www.sun.com/io DIAGNOSTICS In addition to being logged, the following messages can appear on the system console. All messages are formatted in the following manner:Warning:
(usbprn ): Error Message... SunOS 5.11 Last change: 25 Feb 2010 6
Devices usbprn(7D)
Device was disconnected while open. Data might have been lost.The device has been hot-removed or powered off while it
was open and a possible data transfer was in progress. The job might be aborted. Cannot access. Please reconnect. There was an error in accessing the printer during reconnect. Please reconnect the device. Device is not identical to the previous one on this port. Please disconnect and reconnect. A USB printer was hot-removed while open. A new device
was hot-inserted which is not identical to the original
USB printer. Please disconnect the USB device and recon-
nect the printer to the same port. Printer has been reconnected but data might have been lost.The printer that was hot-removed from its USB port has
been re-inserted again to the same port. It is available
for access but the job that was running prior to thehot-removal might be lost.
NOTES The USB printer is power managed if the device is closed.If a printer is hot-removed before a job completes, the job
is terminated and the driver returns EIO. All subsequentopens returns ENODEV. If a printer is hot-removed, an LP
reconfiguration might not be needed if a printer is re-
inserted on the same port. If re-inserted on a different
port, an LP reconfiguration might be required. The USB Parallel Printer Adapter is not hotpluggable. The printer should be connected to USB Parallel Printer Adapter before plugging the USB cable into host or hub port and should be removed only after disconnecting the USB cable of USB Parallel Printer Adapter from the host or hub port.SunOS 5.11 Last change: 25 Feb 2010 7