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.0
specification. The usbprn driver supports a subset of the
ecpp(7D) parallel port driver functionality. However, unlike
the 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 may be
nesessary 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 OPERATION
With 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: 18 June 2005 1
Devices usbprn(7D)
Configuration variables are set to their default values each
time the USB printer device is attached. The writetimeout
period (defined in the ECPIOCSETPARMS ioctl description
below) is set to 90 seconds. The mode is set to centronics
mode (ECPCENTRONICS). Parameters can be changed through
the ECPIOCSETPARMS ioctl and read through the
ECPIOCGETPARMS ioctl. Each time the USB printer device is
opened, the device is marked as busy and all further opens
will return EBUSY. Once the device is open, applications can
write to the device and the driver can send data and obtain
device id and status.
Note -
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 OPERATION
A 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 the
ECPIOCGETER ioctl(2) call. The captured status informa-
tion is overwritten each time an ECPIOCTESTIO ioctl(2)
occurs.
IOCTLS
The usbprn driver supports prnio(7I) interfaces. Note that
the PRNIOCRESET 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.
ECPIOCGETPARMS Gets current transfer parameters. The
argument is a pointer to struct
ecpptransferparms. If parameters are
not configured after the device is
opened, the structure will be set to its
default configuration.
Note -
Unlike the ecpp(7D) driver, only the
ECPCENTRONICS mode is currently sup-
ported in usbprn.
SunOS 5.11 Last change: 18 June 2005 2
Devices usbprn(7D)
ECPIOCSETPARMS Sets transfer parameters. The argument
is a pointer to a struct
ecpptransferparms. If a parameter is
out of range, EINVAL is returned. If the
peripheral or host device cannot support
the requested mode, EPROTONOSUPORT is
returned.
The transfer parameters structure is
defined in :
struct ecpptransferparms {
int writetimeout;
int mode;
};
The writetimeout field, which specifies
how long the driver will take to
transfer 8192 bytes of data to the dev-
ice, is set to a default value of 90
seconds. The writetimeout field must be
greater than one second and less than
300 seconds (five minutes.)
Note -
Unlike the ecpp(7D) driver, only the
ECPCENTRONICS mode is currently sup-
ported in usbprn. Also, the semantics
of writetimeout in usbprn differ from
ecpp(7D). Refer to ecpp(7D) for infor-
mation.
BPIOCTESTIO Tests the transfer readiness of a print
device and checks status bits to deter-
mine if a write(2) will succeed. If
status bits are set, a transfer will
fail. If a transfer will succeed, zero
is returned. If a transfer fails, the
driver returns EIO and the state of the
status bits are captured. The captured
status can be retrieved using the
BPIOCGETER ioctl(2) call.
BPIOCTESTIO and BPIOCGETER are com-
patible to the ioctls specified in
bpp(7D).
Note -
Unlike the ecpp(7D) driver, only the
ECPCENTRONICS mode is currently
SunOS 5.11 Last change: 18 June 2005 3
Devices usbprn(7D)
supported in usbprn. Additionally,
buserror and timeoutoccurred fields
are not used in the usbprn interface.
(In ecpp(7D), timeoutoccurred is
used.)
BPIOCGETER Get last error status. The argument is a
pointer to a struct bpperrorstatus.
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
BPIOCTESTIO ioctl(2) call.
struct bpperrorstatus {
char timeoutoccurred; /* not used */
char buserror; /* not used */
uchart pinstatus; /* status of pins which
/* could cause error */
};
The pinstatus field indicates possible
error conditions. The error status
structure bpperrorstatus is defined in
the include file . The
valid bits for pinstatus can be
BPERER, BPSLCTER, and
BPER. A set bit indicates that the
associated pin is asserted.
Note -
Unlike the ecpp(7D) driver, only the
ECPCENTRONICS mode is currently sup-
ported in usbprn. Additionally, the
buserror and timeoutoccurred fields
are not used in the usbprn interface.
(In ecpp(7D), timeoutoccurred is
used.) Unlike ecpp(7D), the
BPBUSYER status bit is not sup-
ported by USB printers.
ECPIOCGETDEVID Gets the IE 1284 device ID from the
peripheral. The argument is a pointer to
a struct ecppdeviceid. Applications
should set mode to ECPCENTRONICS. If
another mode is used, the driver will
return EPROTONOSUPORT. len is the
length of the buffer pointed to by addr.
SunOS 5.11 Last change: 18 June 2005 4
Devices usbprn(7D)
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 call
ECPIOCGETDEVID a second time with a
buffer length equal to rlen.
The 1284 device ID structure:
struct ecppdeviceid {
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 */
Note -
Unlike ecpp(7D), only the
ECPCENTRONICS mode is currently sup-
ported in usbprn.
READ OPERATION
The read operation is not supported and returns EIO.
ERORS
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. A
ECPIOCSETPARMS ioctl(2) is attempted
with an out of range value in the
ecpptransferparms 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) or
ioctl(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.
SunOS 5.11 Last change: 18 June 2005 5
Devices usbprn(7D)
ENODEV The driver has received an open(2)
request for a device that has been
disconnected.
EPROTONOSUPORT The driver has received a
ECPIOCSETPARMS ioctl(2) for a mode
argument other than ECPCENTRONICS in
the ecpptransferparms structure.
FILES
/kernel/drv/usbprn 32-bit x86 ELF kernel module
/kernel/drv/amd64/usbprn 64-bit x86 ELF kernel module
/kernel/drv/sparcv9/usbprn 64-bit SPARC ELF kernel module
/dev/usb/*/*/* ugen(7D) nodes.
/dev/printers/n Character special files
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture SPARC, x86, PCI-based systems
Availability SUNWusb
SEE ALSO
cfgadmusb(1M), printmgr(1M), ioctl(2), open(2), read(2),
write(2), libusb(3LIB), attributes(5), bpp(7D), ecpp(7D),
ugen(7D), usba(7D)prnio(7I), attach(9E)
Writing Device Drivers
SunOS 5.11 Last change: 18 June 2005 6
Devices usbprn(7D)
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 may
appear on the system console. All messages are formatted in
the following manner:
Warning: (usbprn): Error Message...
Device was disconnected while open. Data may 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 may 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 may 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 the
hot-removal may be lost.
NOTES
SunOS 5.11 Last change: 18 June 2005 7
Devices usbprn(7D)
The USB printer will be power managed if the device is
closed.
If a printer is hot-removed before a job completes, the job
is terminated and the driver will return EIO. All subsequent
opens will return ENODEV. If a printer is hot-removed, an LP
reconfiguration may not be needed if a printer is re-
inserted on the same port. If re-inserted on a different
port, an LP reconfiguration may 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: 18 June 2005 8
|
