1 USBPRN(7D) Devices USBPRN(7D)
2
3
4
5 NAME
6 usbprn - USB printer class driver
7
8 SYNOPSIS
9 #include <sys/usb/clients/printer/usb_printer.h>
10
11
12 #include <sys/ecppio.h>
13
14
15 usbprn@unit-address
16
17
18 DESCRIPTION
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
25
26 The usbprn driver supports all USB printer-class compliant printers.
27
28
29 The usbrpn driver includes support for communicating with many
30 different printers. To use these printers, it may be necessary to
31 install and configure additional format conversion packages available
32 in the Solaris distribution. Configuration of these conversion
33 packages under the Solaris printing system can be simplified through
34 the use of the printmgr(1M). This tool allows selection of printer
35 manufacturer/model information while creating a print queue. For USB
36 connected printers, it attempts to pre-select the manufacturer and
37 model information based on the 1284 device id supplied by the printer.
38
39 UGEN (Generic USB)
40 The usbprn driver also supports a ugen(7D) interface allowing raw
41 access to the device, for example by libusb applications, by passing
42 the drivers bound to each interface. Because a libusb application might
43 change the state of the device, you should not access the device
44 through the child interface drivers.
45
46 DEFAULT OPERATION
47 With certain minor exceptions (outlined in the Notes sections below),
48 the usbprn driver supports a subset of the ecpp(7D) ioctl interfaces:
49
50
51 Configuration variables are set to their default values each time the
52 USB printer device is attached. The write_timeout period (defined in
53 the ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The
54 mode is set to centronics mode (ECPP_CENTRONICS). Parameters can be
55 changed through the ECPPIOC_SETPARMS ioctl and read through the
56 ECPPIOC_GETPARMS ioctl. Each time the USB printer device is opened, the
57 device is marked as busy and all further opens will return EBUSY. Once
58 the device is open, applications can write to the device and the driver
59 can send data and obtain device id and status.
60
61 Note -
62
63 Unlike the ecpp(7D) driver, usbprn resets configuration variables to
64 their default values with each attach(9E). (The ecpp(7D) driver
65 resets configuration variables with each open(2).)
66
67 WRITE OPERATION
68 A write(2) operation returns the number of bytes successfully written
69 to the device. If a failure occurs while a driver is transferring data
70 to printer, the contents of the status bits are captured at the time of
71 the error and can be retrieved by the application program using the
72 ECPPIOC_GETERR ioctl(2) call. The captured status information is
73 overwritten each time an ECPPIOC_TESTIO ioctl(2) occurs.
74
75 IOCTLS
76 The usbprn driver supports prnio(7I) interfaces. Note that the
77 PRNIOC_RESET command has no effect on USB printers.
78
79
80 The following ioctl(2) calls are supported for backward compatibility
81 and are not recommended for new applications.
82
83 ECPPIOC_GETPARMS
84 Gets current transfer parameters. The argument is a
85 pointer to struct ecpp_transfer_parms. If
86 parameters are not configured after the device is
87 opened, the structure will be set to its default
88 configuration.
89
90 Note -
91
92 Unlike the ecpp(7D) driver, only the
93 ECPP_CENTRONICS mode is currently supported in
94 usbprn.
95
96
97 ECPPIOC_SETPARMS
98 Sets transfer parameters. The argument is a pointer
99 to a struct ecpp_transfer_parms. If a parameter is
100 out of range, EINVAL is returned. If the peripheral
101 or host device cannot support the requested mode,
102 EPROTONOSUPPORT is returned.
103
104 The transfer parameters structure is defined in
105 <sys/ecppio.h>:
106
107 struct ecpp_transfer_parms {
108 int write_timeout;
109 int mode;
110 };
111
112 The write_timeout field, which specifies how long
113 the driver will take to transfer 8192 bytes of data
114 to the device, is set to a default value of 90
115 seconds. The write_timeout field must be greater
116 than one second and less than 300 seconds (five
117 minutes.)
118
119 Note -
120
121 Unlike the ecpp(7D) driver, only the
122 ECPP_CENTRONICS mode is currently supported in
123 usbprn. Also, the semantics of write_timeout in
124 usbprn differ from ecpp(7D). Refer to ecpp(7D)
125 for information.
126
127
128 BPPIOC_TESTIO
129 Tests the transfer readiness of a print device and
130 checks status bits to determine if a write(2) will
131 succeed. If status bits are set, a transfer will
132 fail. If a transfer will succeed, zero is returned.
133 If a transfer fails, the driver returns EIO and the
134 state of the status bits are captured. The captured
135 status can be retrieved using the BPPIOC_GETERR
136 ioctl(2) call.
137
138 Note -
139
140 Unlike the ecpp(7D) driver, only the
141 ECPP_CENTRONICS mode is currently supported in
142 usbprn. Additionally, bus_error and
143 timeout_occurred fields are not used in the
144 usbprn interface. (In ecpp(7D), timeout_occurred
145 is used.)
146
147
148 BPPIOC_GETERR
149 Get last error status. The argument is a pointer to
150 a struct bpp_error_status. This structure indicates
151 the status of all the appropriate status bits at
152 the time of the most recent error condition during
153 a write(2) call, or the status of the bits at the
154 most recent BPPIOC_TESTIO ioctl(2) call.
155
156 struct bpp_error_status {
157 char timeout_occurred; /* not used */
158 char bus_error; /* not used */
159 uchar_t pin_status; /* status of pins which
160 /* could cause error */
161 };
162
163 The pin_status field indicates possible error
164 conditions. The error status structure
165 bpp_error_status is defined in the include file
166 <sys/bpp_io.h>. The valid bits for pin_status can
167 be BPP_ERR_ERR, BPP_SLCT_ERR, and BPP_PE_ERR. A set
168 bit indicates that the associated pin is asserted.
169
170 Note -
171
172 Unlike the ecpp(7D) driver, only the
173 ECPP_CENTRONICS mode is currently supported in
174 usbprn. Additionally, the bus_error and
175 timeout_occurred fields are not used in the
176 usbprn interface. (In ecpp(7D), timeout_occurred
177 is used.) Unlike ecpp(7D), the BPP_BUSY_ERR
178 status bit is not supported by USB printers.
179
180
181 ECPPIOC_GETDEVID
182 Gets the IEEE 1284 device ID from the peripheral.
183 The argument is a pointer to a struct
184 ecpp_device_id. Applications should set mode to
185 ECPP_CENTRONICS. If another mode is used, the
186 driver will return EPROTONOSUPPORT. len is the
187 length of the buffer pointed to by addr. rlen is
188 the actual length of the device ID string returned
189 from the peripheral. If the returned rlen is
190 greater than len, the application should call
191 ECPPIOC_GETDEVID a second time with a buffer length
192 equal to rlen.
193
194 The 1284 device ID structure:
195
196 struct ecpp_device_id {
197 int mode; /* mode to use for reading device id */
198 int len; /* length of buffer */
199 int rlen; /* actual length of device id string */
200 char *addr; /* buffer address */
201
202
203 Note -
204
205 Unlike ecpp(7D), only the ECPP_CENTRONICS mode is
206 currently supported in usbprn.
207
208
209 READ OPERATION
210 The read operation is not supported and returns EIO.
211
212 ERRORS
213 EBUSY
214 The device has been opened and another open is
215 attempted. An attempt has been made to unload the
216 driver while one of the units is open.
217
218
219 EINVAL
220 An unsupported IOCTL has been received. A
221 ECPPIOC_SETPARMS ioctl(2) is attempted with an out
222 of range value in the ecpp_transfer_parms structure.
223
224
225 EIO
226 The driver has received an unrecoverable device
227 error, or the device is not responding, or the
228 device has stalled when attempting an access. A
229 write(2) or ioctl(2) did not complete due to a
230 peripheral access. A read(2) system call has been
231 issued.
232
233
234 ENXIO
235 The driver has received an open(2) request for a
236 unit for which the attach failed.
237
238
239 ENODEV
240 The driver has received an open(2) request for a
241 device that has been disconnected.
242
243
244 EPROTONOSUPPORT
245 The driver has received a ECPPIOC_SETPARMS ioctl(2)
246 for a mode argument other than ECPP_CENTRONICS in
247 the ecpp_transfer_parms structure.
248
249
250 FILES
251 /kernel/drv/usbprn
252 32-bit x86 ELF kernel module
253
254
255 /kernel/drv/amd64/usbprn
256 64-bit x86 ELF kernel module
257
258
259 /kernel/drv/sparcv9/usbprn
260 64-bit SPARC ELF kernel module
261
262
263 /dev/usb/*/*/*
264 ugen(7D) nodes.
265
266
267 /dev/printers/n
268 Character special files
269
270
271 ATTRIBUTES
272 See attributes(5) for descriptions of the following attributes:
273
274
275
276
277 +---------------+-------------------------------+
278 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
279 +---------------+-------------------------------+
280 |Architecture | SPARC, x86, PCI-based systems |
281 +---------------+-------------------------------+
282
283 SEE ALSO
284 cfgadm_usb(1M), printmgr(1M), ioctl(2), open(2), read(2), write(2),
285 attributes(5), ecpp(7D), ugen(7D), usba(7D), prnio(7I), attach(9E)
286
287
288 Writing Device Drivers
289
290
291 Universal Serial Bus Specification 1.0 and 1.1
292
293
294 USB Device Class Definition for Printing Devices 1.0
295
296
297 System Administration Guide: Basic Administration
298
299 DIAGNOSTICS
300 In addition to being logged, the following messages may appear on the
301 system console. All messages are formatted in the following manner:
302
303 Warning: <device path> (usbprn<instance num>): Error Message...
304
305
306
307 Device was disconnected while open. Data may have been lost.
308
309 The device has been hot-removed or powered off while it was open
310 and a possible data transfer was in progress. The job may be
311 aborted.
312
313
314 Cannot access <device>. Please reconnect.
315
316 There was an error in accessing the printer during reconnect.
317 Please reconnect the device.
318
319
320 Device is not identical to the previous one on this port. Please
321 disconnect and reconnect.
322
323 A USB printer was hot-removed while open. A new device was hot-
324 inserted which is not identical to the original USB printer. Please
325 disconnect the USB device and reconnect the printer to the same
326 port.
327
328
329 Printer has been reconnected but data may have been lost.
330
331 The printer that was hot-removed from its USB port has been re-
332 inserted again to the same port. It is available for access but the
333 job that was running prior to the hot-removal may be lost.
334
335
336 NOTES
337 The USB printer will be power managed if the device is closed.
338
339
340 If a printer is hot-removed before a job completes, the job is
341 terminated and the driver will return EIO. All subsequent opens will
342 return ENODEV. If a printer is hot-removed, an LP reconfiguration may
343 not be needed if a printer is re-inserted on the same port. If re-
344 inserted on a different port, an LP reconfiguration may be required.
345
346
347 The USB Parallel Printer Adapter is not hotpluggable. The printer
348 should be connected to USB Parallel Printer Adapter before plugging the
349 USB cable into host or hub port and should be removed only after
350 disconnecting the USB cable of USB Parallel Printer Adapter from the
351 host or hub port.
352
353
354
355 May 17, 2020 USBPRN(7D)