usbprn(7D)
NAME
usbprn - USB printer class driver
SYNOPSIS
#include <sys/usb/clients/printer/usb_printer.h>
#include <sys/ecppio.h>
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.
Support of the usbprn driver includes many inkjet and other
printers which require support for protocols other than text
and postscript. A PostScript conversion package such as
GhostScript or CUPS, plus the proper protocol support
modules, is needed to operate these printers. Conversion
packages can be obtained from the Solaris Software companion
CD, available at
http://www.sun.com/software/solaris/binaries/package.html.
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:
Configuration variables are set to their default values each
time 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 centronics
mode (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
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
ECPPIOC_GETERR ioctl(2) call. The captured status informa-
tion is overwritten each time an ECPPIOC_TESTIO ioctl(2)
occurs.
IOCTLS
The 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 struct ecpp_transfer_parms. 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 ECPP_CENTRONICS
mode is currently supported in usbprn.
ECPPIOC_SETPARMS
Sets 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, EPRO-
TONOSUPPORT is returned.
The transfer parameters structure is defined in
<sys/ecppio.h>:
struct ecpp_transfer_parms {
int write_timeout;
int mode;
};
The write_timeout field, which specifies how long the
driver will take to transfer 8192 bytes of data to the
device, is set to a default value of 90 seconds. The
write_timeout field must be greater than one second
and less than 300 seconds (five minutes.)
Note:
Unlike the ecpp(7D) driver, only the ECPP_CENTRONICS
mode is currently supported in usbprn. Also, the seman-
tics of write_timeout in usbprn differ from ecpp(7D).
Refer to ecpp(7D) for information.
BPPIOC_TESTIO
Tests the transfer readiness of a print device and
checks status bits to determine 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 BPPIOC_GETERR ioctl(2)
call. BPPIOC_TESTIO and BPPIOC_GETERR are compatible
to the ioctls specified in bpp(7D).
Note:
Unlike the ecpp(7D) driver, only the ECPP_CENTRONICS
mode is currently supported 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 condition during a
write(2) call, or the status of the bits at the
most recent BPPIOC_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 condi-
tions. The error status structure bpp_error_status is
defined in the include file <sys/bpp_io.h>. The valid
bits for pin_status can be BPP_ERR_ERR, BPP_SLCT_ERR,
and BPP_PE_ERR. A set bit indicates that the associ-
ated pin is asserted.
Note:
Unlike the ecpp(7D) driver, only the ECPP_CENTRONICS
mode is currently supported 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 to a struct ecpp_device_id.
Applications should set mode to ECPP_CENTRONICS. If
another mode is used, the driver will return EPROTO-
NOSUPPORT. 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 call
ECPPIOC_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 */
Note:
Unlike ecpp(7D), only the ECPP_CENTRONICS mode is
currently supported 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. A
ECPPIOC_SETPARMS ioctl(2) is attempted with an out of
range value in the ecpp_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) or
ioctl(2) did not complete due to a peripheral 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 dev-
ice that has been disconnected.
EPROTONOSUPPORT
The driver has received a ECPPIOC_SETPARMS ioctl(2)
for a mode argument other than ECPP_CENTRONICS in the
ecpp_transfer_parms structure.
FILES
/kernel/drv/usbprn
32 bit ELF kernel module for original USBA framework.*
/kernel/drv/sparcv9/usbprn
64 bit ELF kernel module for original USBA framework.*
(SPARC only).
/kernel/drv/usba10_usbprn
32 bit ELF kernel module for USBA 1.0 framework.*
/kernel/drv/sparcv9/usba10_usbprn
64 bit ELF kernel module for USBA 1.0 framework.*
(SPARC only).
/kernel/drv/usba10_usbprn.conf
usba10_usbprn configuration file
/dev/printers/n
Character special files
* Please see www.sun.com/desktop/whitepapers.html for
more information regarding USB dual framework implementa-
tion, USBA 1.0, and USB 2.0.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| Architecture | PCI-based systems |
| ____________________________|_____________________________|_
| Availability | SUNWusb (All architectures)|
| | SUNWusbx (SPARC only) |
|_____________________________|_____________________________|
SEE ALSO
cfgadm_usb(1M), printmgr(1M), ioctl(2), open(2), read(2),
write(2), attributes(5), bpp(7D), ecpp(7D), usba(7D),
prnio(7I), attach(9E)
Writing Device Drivers
Universal Serial Bus Specification 2.0
USB Device Class Definition for Printing Devices 1.0
System Administration Guide: Basic Administration
http://www.sun.com/desktop/whitepapers.html
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: <device path> (usbprn<instance num>): Error Message...
or
Warning: <device path> (usba10_usbprn<instance num>): 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 pro-
gress. The job may be aborted.
Cannot access <device>. Please reconnect <device name>.
There was an error in accessing the printer during
reconnect. Please reconnect the device.
disconnect and reconnect.
Device is not identical to the previous one on this port. Please
A USB printer was hot-removed while open. A new device
was hot-inserted which is not identical to the origi-
nal USB printer. Please disconnect the USB device and
reconnect 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 avail-
able for access but the job that was running prior to
the hot-removal may be lost.
NOTES
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.
Man(1) output converted with
man2html