'\" te .\" Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved. .TH usbprn 7D "5 Jan 2023" "SunOS 5.11" "Devices" .SH NAME usbprn \- USB printer class driver .SH SYNOPSIS .LP .nf #include .fi .LP .nf #include .fi .LP .nf usbprn@unit-address .fi .SH DESCRIPTION .sp .LP The \fBusbprn\fR driver is a USBA (Solaris USB Architecture) compliant client driver that supports the \fIUSB Printer Class 1.0\fR specification. The \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) parallel port driver functionality. However, unlike the STREAMS-based \fBecpp\fR driver, \fBusbprn\fR is a character driver. .sp .LP The \fBusbprn\fR driver supports all USB printer-class compliant printers. For a list of recommended printers and USB parallel printer adapters, visit http://\fIwww.sun.com/io\fR. .sp .LP The \fBusbrpn\fR driver includes support for communicating with many different printers. To use these printers, it might be nesessary to install and configure additional format conversion packages available in the Oracle Solaris distribution. .SS "UGEN (Generic USB)" .sp .LP The \fBusbprn\fR driver also supports a \fBugen\fR(7D) interface allowing raw access to the device, for example by \fBlibusb\fR(3LIB) applications, by passing the drivers bound to each interface. Because a libusb application might change the state of the device, you should not access the device through the child interface drivers. .SH DEFAULT OPERATION .sp .LP With certain minor exceptions (outlined in the Notes sections below), the \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) ioctl interfaces: .sp .LP Configuration variables are set to their default values each time the USB printer device is attached. The \fBwrite_timeout\fR 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 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. .sp .LP Unlike the \fBecpp\fR(7D) driver, \fBusbprn\fR resets configuration variables to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(7D) driver resets configuration variables with each \fBopen\fR(2).) .SH WRITE OPERATION .sp .LP A \fBwrite\fR(2) operation returns the number of bytes successfully 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 \fBioctl\fR(2) call. The captured status information is overwritten each time an ECPPIOC_TESTIO \fBioctl\fR(2) occurs. .SH IOCTLS .sp .LP The \fBusbprn\fR driver supports \fBprnio(7I)\fR interfaces. Note that the \fBPRNIOC_RESET\fR command has no effect on USB printers. .sp .LP The following \fBioctl\fR(2) calls are supported for backward compatibility and are not recommended for new applications. .sp .ne 2 .mk .na \fB\fBECPPIOC_GETPARMS\fR\fR .ad .RS 20n .rt Gets current transfer parameters. The argument is a pointer to \fBstruct ecpp_transfer_parms\fR. If parameters are not configured after the device is opened, the structure is set to its default configuration. .sp Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently supported in \fBusbprn\fR. .RE .sp .ne 2 .mk .na \fB\fBECPPIOC_SETPARMS\fR\fR .ad .RS 20n .rt Sets transfer parameters. The argument is a pointer to a \fBstruct ecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is returned. If the peripheral or host device cannot support the requested mode, \fBEPROTONOSUPPORT\fR is returned. .sp The transfer parameters structure is defined in <\fBsys/ecppio.h\fR>: .sp .in +2 .nf struct ecpp_transfer_parms { int write_timeout; int mode; }; .fi .in -2 The \fBwrite_timeout\fR 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. The \fBwrite_timeout\fR field must be greater than one second and less than 300 seconds (five minutes.) .sp Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in \fBusbprn\fR differ from \fBecpp\fR(7D). Refer to \fBecpp\fR(7D) for information. .RE .sp .ne 2 .mk .na \fB\fBBPPIOC_TESTIO\fR\fR .ad .RS 20n .rt Tests the transfer readiness of a print device and checks status bits to determine if a \fBwrite\fR(2) succeeds. If status bits are set, a transfer fails. If a transfer succeeds, zero is returned. If a transfer fails, the driver returns \fBEIO\fR and the state of the status bits are captured. The captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call. .sp Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.) .RE .sp .ne 2 .mk .na \fB\fBBPPIOC_GETERR\fR\fR .ad .RS 20n .rt Get last error status. The argument is a pointer to a \fBstruct bpp_error_status\fR. This structure indicates the status of all the appropriate status bits at the time of the most recent error condition during a \fBwrite\fR(2) call, or the status of the bits at the most recent BPPIOC_TESTIO \fBioctl\fR(2) call. .sp .in +2 .nf 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 */ }; .fi .in -2 The pin_status field indicates possible error conditions. The error status structure \fBbpp_error_status\fR is defined in the include file \fB\fR\&. The valid bits for \fBpin_status\fR can be \fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, and \fBBPP_PE_ERR\fR. A set bit indicates that the associated pin is asserted. .sp Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently supported in \fBusbprn\fR. Additionally, the \fBbus_error\fR and \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.) Unlike \fBecpp\fR(7D), the BPP_BUSY_ERR status bit is not supported by USB printers. .RE .sp .ne 2 .mk .na \fB\fBECPPIOC_GETDEVID\fR\fR .ad .RS 20n .rt Gets the IEEE 1284 device ID from the peripheral. The argument is a pointer to a \fBstruct ecpp_device_id\fR. Applications should set mode to ECPP_CENTRONICS. If another mode is used, the driver returns \fBEPROTONOSUPPORT\fR. \fBlen\fR is the length of the buffer pointed to by \fBaddr\fR. \fBrlen\fR is the actual length of the device ID string returned from the peripheral. If the returned \fBrlen\fR is greater than \fBlen\fR, the application should call ECPPIOC_GETDEVID a second time with a buffer length equal to \fBrlen\fR. .sp The 1284 device ID structure: .sp .in +2 .nf 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 */ .fi .in -2 Unlike \fBecpp\fR(7D), only the ECPP_CENTRONICS mode is currently supported in \fBusbprn\fR. .RE .SH READ OPERATION .sp .LP The \fBread\fR operation is not supported and returns \fBEIO\fR. .SH ERRORS .sp .ne 2 .mk .na \fB\fBEBUSY\fR\fR .ad .RS 19n .rt 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. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 19n .rt An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is attempted with an out of range value in the \fBecpp_transfer_parms\fR structure. .RE .sp .ne 2 .mk .na \fB\fBEIO\fR\fR .ad .RS 19n .rt The driver has received an unrecoverable device error, or the device is not responding, or the device has stalled when attempting an access. A \fBwrite\fR(2) or \fBioctl\fR(2) did not complete due to a peripheral access. A \fBread\fR(2) system call has been issued. .RE .sp .ne 2 .mk .na \fB\fBENXIO\fR\fR .ad .RS 19n .rt The driver has received an \fBopen\fR(2) request for a unit for which the attach failed. .RE .sp .ne 2 .mk .na \fB\fBENODEV\fR\fR .ad .RS 19n .rt The driver has received an \fBopen\fR(2) request for a device that has been disconnected. .RE .sp .ne 2 .mk .na \fB\fBEPROTONOSUPPORT\fR\fR .ad .RS 19n .rt The driver has received a ECPPIOC_SETPARMS \fBioctl\fR(2) for a mode argument other than ECPP_CENTRONICS in the \fBecpp_transfer_parms\fR structure. .RE .SH FILES .sp .ne 2 .mk .na \fB\fB/kernel/drv/amd64/usbprn\fR\fR .ad .RS 30n .rt 64-bit x86 ELF kernel module .RE .sp .ne 2 .mk .na \fB\fB/kernel/drv/sparcv9/usbprn\fR\fR .ad .RS 30n .rt 64-bit SPARC ELF kernel module .RE .sp .ne 2 .mk .na \fB/dev/usb/*/*/*\fR .ad .RS 30n .rt ugen(7D) nodes. .RE .sp .ne 2 .mk .na \fB\fB/dev/printers/\fIn\fR\fR\fR .ad .RS 30n .rt Character special files .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ ArchitectureSPARC, x86, PCI-based systems _ Availabilitysystem/io/usb .TE .SH SEE ALSO .sp .LP \fBcfgadm_usb\fR(1M), \fBioctl\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBlibusb\fR(3LIB), \fBattributes\fR(5), \fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D)\fBprnio\fR(7I), \fBattach\fR(9E) .sp .LP \fIWriting Device Drivers for Oracle Solaris 11.2\fR .sp .LP \fIUniversal Serial Bus Specification 1.0 and 1.1\fR .sp .LP \fIUSB Device Class Definition for Printing Devices 1.0\fR .sp .LP \fIIntroduction to Oracle Solaris 11.3 Administration\fR .sp .LP http://www.oracle.com .SH DIAGNOSTICS .sp .LP In addition to being logged, the following messages can appear on the system console. All messages are formatted in the following manner: .sp .in +2 .nf Warning: (usbprn): Error Message... .fi .in -2 .sp .sp .ne 2 .mk .na \fBDevice was disconnected while open. Data might have been lost.\fR .ad .sp .6 .RS 4n 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. .RE .sp .ne 2 .mk .na \fBCannot access . Please reconnect.\fR .ad .sp .6 .RS 4n There was an error in accessing the printer during reconnect. Please reconnect the device. .RE .sp .ne 2 .mk .na \fBDevice is not identical to the previous one on this port. Please disconnect and reconnect.\fR .ad .sp .6 .RS 4n 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 reconnect the printer to the same port. .RE .sp .ne 2 .mk .na \fBPrinter has been reconnected but data might have been lost.\fR .ad .sp .6 .RS 4n 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 might be lost. .RE .SH NOTES .sp .LP The USB printer is power managed if the device is closed. .sp .LP If a printer is hot-removed before a job completes, the job is terminated and the driver returns EIO. All subsequent opens returns \fBENODEV\fR. 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. .sp .LP 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.