1usbprn(7D) Devices usbprn(7D)
2
6 usbprn - USB printer class driver
7
9 #include <sys/usb/clients/printer/usb_printer.h>
10 #include <sys/ecppio.h>
13 usbprn@unit-address
16
19 The usbprn driver is a USBA (Solaris USB Architecture) compliant client
20 driver that supports the USB Printer Class 1.0 specification. The
21 usbprn driver supports a subset of the ecpp(7D) parallel port driver
22 functionality. However, unlike the STREAMS-based ecpp driver, usbprn is
23 a character driver.
24 The usbprn driver supports all USB printer-class compliant printers.
27 For a list of recommended printers and USB parallel printer adapters,
28 visit http://www.sun.com/io.
29 The usbrpn driver includes support for communicating with many differ‐
32 ent printers. To use these printers, it may be nesessary to install and
33 configure additional format conversion packages available in the
34 Solaris distribution. Configuration of these conversion packages under
35 the Solaris printing system can be simplified through the use of the
36 printmgr(1M). This tool allows selection of printer manufacturer/model
37 information while creating a print queue. For USB connected printers,
38 it attempts to pre-select the the manufacturer and model information
39 based on the 1284 device id supplied by the printer.
40 UGEN (Generic USB)
42 The usbprn driver also supports a ugen(7D) interface allowing raw
43 access to the device, for example by libusb(3LIB) applications, by
44 passing the drivers bound to each interface. Because a libusb applica‐
45 tion might change the state of the device, you should not access the
46 device through the child interface drivers.
47
49 With certain minor exceptions (outlined in the Notes sections below),
50 the usbprn driver supports a subset of the ecpp(7D) ioctl interfaces:
51 Configuration variables are set to their default values each time the
54 USB printer device is attached. The write_timeout period (defined in
55 the ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The
56 mode is set to centronics mode (ECPP_CENTRONICS). Parameters can be
57 changed through the ECPPIOC_SETPARMS ioctl and read through the ECP‐
58 PIOC_GETPARMS ioctl. Each time the USB printer device is opened, the
59 device is marked as busy and all further opens will return EBUSY. Once
60 the device is open, applications can write to the device and the driver
61 can send data and obtain device id and status.
62 Note -
64 Unlike the ecpp(7D) driver, usbprn resets configuration variables to
66 their default values with each attach(9E). (The ecpp(7D) driver
67 resets configuration variables with each open(2).)
68
70 A write(2) operation returns the number of bytes successfully written
71 to the device. If a failure occurs while a driver is transferring data
72 to printer, the contents of the status bits are captured at the time of
73 the error and can be retrieved by the application program using the
74 ECPPIOC_GETERR ioctl(2) call. The captured status information is over‐
75 written each time an ECPPIOC_TESTIO ioctl(2) occurs.
76
78 The usbprn driver supports prnio(7I) interfaces. Note that the
79 PRNIOC_RESET command has no effect on USB printers.
80 The following ioctl(2) calls are supported for backward compatibility
83 and are not recommended for new applications.
84 ECPPIOC_GETPARMS Gets current transfer parameters. The argument is a
86 pointer to struct ecpp_transfer_parms. If parame‐
87 ters are not configured after the device is opened,
88 the structure will be set to its default configura‐
89 tion.
90 Note -
92 Unlike the ecpp(7D) driver, only the ECPP_CEN‐
94 TRONICS mode is currently supported in usbprn.
95 ECPPIOC_SETPARMS Sets transfer parameters. The argument is a pointer
98 to a struct ecpp_transfer_parms. If a parameter is
99 out of range, EINVAL is returned. If the peripheral
100 or host device cannot support the requested mode,
101 EPROTONOSUPPORT is returned.
102 The transfer parameters structure is defined in
104 <sys/ecppio.h>:
105 struct ecpp_transfer_parms {
107 int write_timeout;
108 int mode;
109 };
110 The write_timeout field, which specifies how long
112 the driver will take to transfer 8192 bytes of data
113 to the device, is set to a default value of 90 sec‐
114 onds. The write_timeout field must be greater than
115 one second and less than 300 seconds (five min‐
116 utes.)
117 Note -
119 Unlike the ecpp(7D) driver, only the ECPP_CEN‐
121 TRONICS mode is currently supported in usbprn.
122 Also, the semantics of write_timeout in usbprn
123 differ from ecpp(7D). Refer to ecpp(7D) for
124 information.
125 BPPIOC_TESTIO Tests the transfer readiness of a print device and
128 checks status bits to determine if a write(2) will
129 succeed. If status bits are set, a transfer will
130 fail. If a transfer will succeed, zero is returned.
131 If a transfer fails, the driver returns EIO and the
132 state of the status bits are captured. The captured
133 status can be retrieved using the BPPIOC_GETERR
134 ioctl(2) call. BPPIOC_TESTIO and BPPIOC_GETERR are
135 compatible to the ioctls specified in bpp(7D).
136 Note -
138 Unlike the ecpp(7D) driver, only the ECPP_CEN‐
140 TRONICS mode is currently supported in usbprn.
141 Additionally, bus_error and timeout_occurred
142 fields are not used in the usbprn interface. (In
143 ecpp(7D), timeout_occurred is used.)
144 BPPIOC_GETERR Get last error status. The argument is a pointer to
147 a struct bpp_error_status. This structure indicates
148 the status of all the appropriate status bits at
149 the time of the most recent error condition during
150 a write(2) call, or the status of the bits at the
151 most recent BPPIOC_TESTIO ioctl(2) call.
152 struct bpp_error_status {
154 char timeout_occurred; /* not used */
155 char bus_error; /* not used */
156 uchar_t pin_status; /* status of pins which
157 /* could cause error */
158 };
159 The pin_status field indicates possible error con‐
161 ditions. The error status structure bpp_error_sta‐
162 tus is defined in the include file <sys/bpp_io.h>.
163 The valid bits for pin_status can be BPP_ERR_ERR,
164 BPP_SLCT_ERR, and BPP_PE_ERR. A set bit indicates
165 that the associated pin is asserted.
166 Note -
168 Unlike the ecpp(7D) driver, only the ECPP_CEN‐
170 TRONICS mode is currently supported in usbprn.
171 Additionally, the bus_error and timeout_occurred
172 fields are not used in the usbprn interface. (In
173 ecpp(7D), timeout_occurred is used.) Unlike
174 ecpp(7D), the BPP_BUSY_ERR status bit is not sup‐
175 ported by USB printers.
176 ECPPIOC_GETDEVID Gets the IEEE 1284 device ID from the peripheral.
179 The argument is a pointer to a struct
180 ecpp_device_id. Applications should set mode to
181 ECPP_CENTRONICS. If another mode is used, the
182 driver will return EPROTONOSUPPORT. len is the
183 length of the buffer pointed to by addr. rlen is
184 the actual length of the device ID string returned
185 from the peripheral. If the returned rlen is
186 greater than len, the application should call ECP‐
187 PIOC_GETDEVID a second time with a buffer length
188 equal to rlen.
189 The 1284 device ID structure:
191 struct ecpp_device_id {
193 int mode; /* mode to use for reading device id */
194 int len; /* length of buffer */
195 int rlen; /* actual length of device id string */
196 char *addr; /* buffer address */
197 Note -
200 Unlike ecpp(7D), only the ECPP_CENTRONICS mode is
202 currently supported in usbprn.
203
206 The read operation is not supported and returns EIO.
207
209 EBUSY The device has been opened and another open is
210 attempted. An attempt has been made to unload the
211 driver while one of the units is open.
212 EINVAL An unsupported IOCTL has been received. A ECP‐
215 PIOC_SETPARMS ioctl(2) is attempted with an out of
216 range value in the ecpp_transfer_parms structure.
217 EIO The driver has received an unrecoverable device
220 error, or the device is not responding, or the
221 device has stalled when attempting an access. A
222 write(2) or ioctl(2) did not complete due to a
223 peripheral access. A read(2) system call has been
224 issued.
225 ENXIO The driver has received an open(2) request for a
228 unit for which the attach failed.
229 ENODEV The driver has received an open(2) request for a
232 device that has been disconnected.
233 EPROTONOSUPPORT The driver has received a ECPPIOC_SETPARMS ioctl(2)
236 for a mode argument other than ECPP_CENTRONICS in
237 the ecpp_transfer_parms structure.
238
241 /kernel/drv/usbprn 32-bit x86 ELF kernel module
242 /kernel/drv/amd64/usbprn 64-bit x86 ELF kernel module
245 /kernel/drv/sparcv9/usbprn 64-bit SPARC ELF kernel module
248 /dev/usb/*/*/* [22mugen(7D) nodes.
251 /dev/printers/n Character special files
254
257 See attributes(5) for descriptions of the following attributes:
258 ┌─────────────────────────────┬──────────────────────────────┐
263 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
264 ├─────────────────────────────┼──────────────────────────────┤
265 │Architecture │SPARC, x86, PCI-based systems │
266 ├─────────────────────────────┼──────────────────────────────┤
267 │Availability │SUNWusb │
268 └─────────────────────────────┴──────────────────────────────┘
269
271 cfgadm_usb(1M), printmgr(1M), ioctl(2), open(2), read(2), write(2),
272 libusb(3LIB), attributes(5), bpp(7D), ecpp(7D), ugen(7D),
273 usba(7D)prnio(7I), attach(9E)
274 Writing Device Drivers
277 Universal Serial Bus Specification 1.0 and 1.1
280 USB Device Class Definition for Printing Devices 1.0
283 System Administration Guide: Basic Administration
286 http://www.sun.com/io
289
291 In addition to being logged, the following messages may appear on the
292 system console. All messages are formatted in the following manner:
293 Warning: <device path> (usbprn<instance num>): Error Message...
295 Device was disconnected while open. Data may have been lost.
299 The device has been hot-removed or powered off while it was open
301 and a possible data transfer was in progress. The job may be
302 aborted.
303 Cannot access <device>. Please reconnect.
306 There was an error in accessing the printer during reconnect.
308 Please reconnect the device.
309 Device is not identical to the previous one on this port. Please dis‐
312 connect and reconnect.
313 A USB printer was hot-removed while open. A new device was hot-
315 inserted which is not identical to the original USB printer. Please
316 disconnect the USB device and reconnect the printer to the same
317 port.
318 Printer has been reconnected but data may have been lost.
321 The printer that was hot-removed from its USB port has been re-
323 inserted again to the same port. It is available for access but the
324 job that was running prior to the hot-removal may be lost.
325
328 The USB printer will be power managed if the device is closed.
329 If a printer is hot-removed before a job completes, the job is termi‐
332 nated and the driver will return EIO. All subsequent opens will return
333 ENODEV. If a printer is hot-removed, an LP reconfiguration may not be
334 needed if a printer is re-inserted on the same port. If re-inserted on
335 a different port, an LP reconfiguration may be required.
336 The USB Parallel Printer Adapter is not hotpluggable. The printer
339 should be connected to USB Parallel Printer Adapter before plugging the
340 USB cable into host or hub port and should be removed only after dis‐
341 connecting the USB cable of USB Parallel Printer Adapter from the host
342 or hub port.
343SunOS 5.11 18 June 2005 usbprn(7D)