1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH USBPRN 7D "May 13, 2017"
7 .SH NAME
8 usbprn \- USB printer class driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/usb/clients/printer/usb_printer.h>
13 .fi
14
15 .LP
16 .nf
17 #include <sys/ecppio.h>
18 .fi
19
20 .LP
21 .nf
22 usbprn@unit-address
23 .fi
24
25 .SH DESCRIPTION
26 .LP
27 The \fBusbprn\fR driver is a USBA (Solaris USB Architecture) compliant client
28 driver that supports the \fIUSB Printer Class 1.0\fR specification. The
29 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) parallel port
30 driver functionality. However, unlike the STREAMS-based \fBecpp\fR driver,
31 \fBusbprn\fR is a character driver.
32 .sp
33 .LP
34 The \fBusbprn\fR driver supports all USB printer-class compliant printers.
35 .sp
36 .LP
37 The \fBusbrpn\fR driver includes support for communicating with many different
38 printers. To use these printers, it may be necessary to install and configure
39 additional format conversion packages available in the Solaris distribution.
40 Configuration of these conversion packages under the Solaris printing system
41 can be simplified through the use of the \fBprintmgr\fR(1M). This tool allows
42 selection of printer manufacturer/model information while creating a print
43 queue. For USB connected printers, it attempts to pre-select the
44 manufacturer and model information based on the 1284 device id supplied by the
45 printer.
46 .SS "UGEN (Generic USB)"
47 .LP
48 The \fBusbprn\fR driver also supports a \fBugen\fR(7D) interface allowing raw
49 access to the device, for example by libusb applications, by
50 passing the drivers bound to each interface. Because a libusb application might
51 change the state of the device, you should not access the device through the
52 child interface drivers.
53 .SH DEFAULT OPERATION
54 .LP
55 With certain minor exceptions (outlined in the Notes sections below), the
56 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) ioctl interfaces:
57 .sp
58 .LP
59 Configuration variables are set to their default values each time the USB
60 printer device is attached. The \fBwrite_timeout\fR period (defined in the
61 ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The mode is set
62 to centronics mode (ECPP_CENTRONICS). Parameters can be changed through the
63 ECPPIOC_SETPARMS ioctl and read through the ECPPIOC_GETPARMS ioctl. Each time
64 the USB printer device is opened, the device is marked as busy and all further
65 opens will return EBUSY. Once the device is open, applications can write to the
66 device and the driver can send data and obtain device id and status.
67 .LP
68 Note -
69 .sp
70 .RS 2
71 Unlike the \fBecpp\fR(7D) driver, \fBusbprn\fR resets configuration variables
72 to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(7D) driver
73 resets configuration variables with each \fBopen\fR(2).)
74 .RE
75 .SH WRITE OPERATION
76 .LP
77 A \fBwrite\fR(2) operation returns the number of bytes successfully written to
78 the device. If a failure occurs while a driver is transferring data to printer,
79 the contents of the status bits are captured at the time of the error and can
80 be retrieved by the application program using the ECPPIOC_GETERR \fBioctl\fR(2)
81 call. The captured status information is overwritten each time an
82 ECPPIOC_TESTIO \fBioctl\fR(2) occurs.
83 .SH IOCTLS
84 .LP
85 The \fBusbprn\fR driver supports \fBprnio\fR(7I) interfaces. Note that the
86 \fBPRNIOC_RESET\fR command has no effect on USB printers.
87 .sp
88 .LP
89 The following \fBioctl\fR(2) calls are supported for backward compatibility and
90 are not recommended for new applications.
91 .sp
92 .ne 2
93 .na
94 \fB\fBECPPIOC_GETPARMS\fR\fR
95 .ad
96 .RS 20n
97 Gets current transfer parameters. The argument is a pointer to \fBstruct
98 ecpp_transfer_parms\fR. If parameters are not configured after the device is
99 opened, the structure will be set to its default configuration.
100 .LP
101 Note -
102 .sp
103 .RS 2
104 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
137 .sp
138 .RS 2
139 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
140 supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in
141 \fBusbprn\fR differ from \fBecpp\fR(7D). Refer to \fBecpp\fR(7D) for
142 information.
143 .RE
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fBBPPIOC_TESTIO\fR\fR
150 .ad
151 .RS 20n
152 Tests the transfer readiness of a print device and checks status bits to
153 determine if a \fBwrite\fR(2) will succeed. If status bits are set, a transfer
154 will fail. If a transfer will succeed, zero is returned. If a transfer fails,
155 the driver returns \fBEIO\fR and the state of the status bits are captured. The
156 captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call.
157 BPPIOC_TESTIO and BPPIOC_GETERR are compatible to the ioctls specified in
158 \fBbpp\fR(7D).
159 .LP
160 Note -
161 .sp
162 .RS 2
163 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
164 supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and
165 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
166 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.)
167 .RE
168 .RE
169
170 .sp
171 .ne 2
172 .na
173 \fB\fBBPPIOC_GETERR\fR\fR
174 .ad
175 .RS 20n
176 Get last error status. The argument is a pointer to a \fBstruct
177 bpp_error_status\fR. This structure indicates the status of all the appropriate
178 status bits at the time of the most recent error condition during a
226 .in +2
227 .nf
228 struct ecpp_device_id {
229 int mode; /* mode to use for reading device id */
230 int len; /* length of buffer */
231 int rlen; /* actual length of device id string */
232 char *addr; /* buffer address */
233 .fi
234 .in -2
235
236 .LP
237 Note -
238 .sp
239 .RS 2
240 Unlike \fBecpp\fR(7D), only the ECPP_CENTRONICS mode is currently supported in
241 \fBusbprn\fR.
242 .RE
243 .RE
244
245 .SH READ OPERATION
246 .LP
247 The \fBread\fR operation is not supported and returns \fBEIO\fR.
248 .SH ERRORS
249 .ne 2
250 .na
251 \fB\fBEBUSY\fR\fR
252 .ad
253 .RS 19n
254 The device has been opened and another open is attempted. An attempt has been
255 made to unload the driver while one of the units is open.
256 .RE
257
258 .sp
259 .ne 2
260 .na
261 \fB\fBEINVAL\fR\fR
262 .ad
263 .RS 19n
264 An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is
265 attempted with an out of range value in the \fBecpp_transfer_parms\fR
266 structure.
337
338 .sp
339 .ne 2
340 .na
341 \fB/dev/usb/*/*/* \fR
342 .ad
343 .RS 30n
344 ugen(7D) nodes.
345 .RE
346
347 .sp
348 .ne 2
349 .na
350 \fB\fB/dev/printers/\fIn\fR\fR\fR
351 .ad
352 .RS 30n
353 Character special files
354 .RE
355
356 .SH ATTRIBUTES
357 .LP
358 See \fBattributes\fR(5) for descriptions of the following attributes:
359 .sp
360
361 .sp
362 .TS
363 box;
364 c | c
365 l | l .
366 ATTRIBUTE TYPE ATTRIBUTE VALUE
367 _
368 Architecture SPARC, x86, PCI-based systems
369 .TE
370
371 .SH SEE ALSO
372 .LP
373 \fBcfgadm_usb\fR(1M), \fBprintmgr\fR(1M), \fBioctl\fR(2), \fBopen\fR(2),
374 \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
375 \fBbpp\fR(7D), \fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D), \fBprnio\fR(7I),
376 \fBattach\fR(9E)
377 .sp
378 .LP
379 \fIWriting Device Drivers\fR
380 .sp
381 .LP
382 \fIUniversal Serial Bus Specification 1.0 and 1.1\fR
383 .sp
384 .LP
385 \fIUSB Device Class Definition for Printing Devices 1.0\fR
386 .sp
387 .LP
388 \fISystem Administration Guide: Basic Administration\fR
389 .SH DIAGNOSTICS
390 .LP
391 In addition to being logged, the following messages may appear on the system
392 console. All messages are formatted in the following manner:
393 .sp
394 .in +2
395 .nf
396 Warning: <device path> (usbprn<instance num>): Error Message...
397 .fi
398 .in -2
399 .sp
400
401 .sp
402 .ne 2
403 .na
404 \fBDevice was disconnected while open. Data may have been lost.\fR
405 .ad
406 .sp .6
407 .RS 4n
408 The device has been hot-removed or powered off while it was open and a possible
409 data transfer was in progress. The job may be aborted.
410 .RE
429 .sp .6
430 .RS 4n
431 A USB printer was hot-removed while open. A new device was hot-inserted which
432 is not identical to the original USB printer. Please disconnect the USB device
433 and reconnect the printer to the same port.
434 .RE
435
436 .sp
437 .ne 2
438 .na
439 \fBPrinter has been reconnected but data may have been lost.\fR
440 .ad
441 .sp .6
442 .RS 4n
443 The printer that was hot-removed from its USB port has been re-inserted again
444 to the same port. It is available for access but the job that was running prior
445 to the hot-removal may be lost.
446 .RE
447
448 .SH NOTES
449 .LP
450 The USB printer will be power managed if the device is closed.
451 .sp
452 .LP
453 If a printer is hot-removed before a job completes, the job is terminated and
454 the driver will return EIO. All subsequent opens will return \fBENODEV\fR. If a
455 printer is hot-removed, an LP reconfiguration may not be needed if a printer is
456 re-inserted on the same port. If re-inserted on a different port, an LP
457 reconfiguration may be required.
458 .sp
459 .LP
460 The USB Parallel Printer Adapter is not hotpluggable. The printer should be
461 connected to USB Parallel Printer Adapter before plugging the USB cable into
462 host or hub port and should be removed only after disconnecting the USB cable
463 of USB Parallel Printer Adapter from the host or hub port.
|
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH USBPRN 7D "May 17, 2020"
7 .SH NAME
8 usbprn \- USB printer class driver
9 .SH SYNOPSIS
10 .nf
11 #include <sys/usb/clients/printer/usb_printer.h>
12 .fi
13
14 .LP
15 .nf
16 #include <sys/ecppio.h>
17 .fi
18
19 .LP
20 .nf
21 usbprn@unit-address
22 .fi
23
24 .SH DESCRIPTION
25 The \fBusbprn\fR driver is a USBA (Solaris USB Architecture) compliant client
26 driver that supports the \fIUSB Printer Class 1.0\fR specification. The
27 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) parallel port
28 driver functionality. However, unlike the STREAMS-based \fBecpp\fR driver,
29 \fBusbprn\fR is a character driver.
30 .sp
31 .LP
32 The \fBusbprn\fR driver supports all USB printer-class compliant printers.
33 .sp
34 .LP
35 The \fBusbrpn\fR driver includes support for communicating with many different
36 printers. To use these printers, it may be necessary to install and configure
37 additional format conversion packages available in the Solaris distribution.
38 Configuration of these conversion packages under the Solaris printing system
39 can be simplified through the use of the \fBprintmgr\fR(1M). This tool allows
40 selection of printer manufacturer/model information while creating a print
41 queue. For USB connected printers, it attempts to pre-select the
42 manufacturer and model information based on the 1284 device id supplied by the
43 printer.
44 .SS "UGEN (Generic USB)"
45 The \fBusbprn\fR driver also supports a \fBugen\fR(7D) interface allowing raw
46 access to the device, for example by libusb applications, by
47 passing the drivers bound to each interface. Because a libusb application might
48 change the state of the device, you should not access the device through the
49 child interface drivers.
50 .SH DEFAULT OPERATION
51 With certain minor exceptions (outlined in the Notes sections below), the
52 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) ioctl interfaces:
53 .sp
54 .LP
55 Configuration variables are set to their default values each time the USB
56 printer device is attached. The \fBwrite_timeout\fR period (defined in the
57 ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The mode is set
58 to centronics mode (ECPP_CENTRONICS). Parameters can be changed through the
59 ECPPIOC_SETPARMS ioctl and read through the ECPPIOC_GETPARMS ioctl. Each time
60 the USB printer device is opened, the device is marked as busy and all further
61 opens will return EBUSY. Once the device is open, applications can write to the
62 device and the driver can send data and obtain device id and status.
63 .LP
64 Note -
65 .sp
66 .RS 2
67 Unlike the \fBecpp\fR(7D) driver, \fBusbprn\fR resets configuration variables
68 to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(7D) driver
69 resets configuration variables with each \fBopen\fR(2).)
70 .RE
71 .SH WRITE OPERATION
72 A \fBwrite\fR(2) operation returns the number of bytes successfully written to
73 the device. If a failure occurs while a driver is transferring data to printer,
74 the contents of the status bits are captured at the time of the error and can
75 be retrieved by the application program using the ECPPIOC_GETERR \fBioctl\fR(2)
76 call. The captured status information is overwritten each time an
77 ECPPIOC_TESTIO \fBioctl\fR(2) occurs.
78 .SH IOCTLS
79 The \fBusbprn\fR driver supports \fBprnio\fR(7I) interfaces. Note that the
80 \fBPRNIOC_RESET\fR command has no effect on USB printers.
81 .sp
82 .LP
83 The following \fBioctl\fR(2) calls are supported for backward compatibility and
84 are not recommended for new applications.
85 .sp
86 .ne 2
87 .na
88 \fB\fBECPPIOC_GETPARMS\fR\fR
89 .ad
90 .RS 20n
91 Gets current transfer parameters. The argument is a pointer to \fBstruct
92 ecpp_transfer_parms\fR. If parameters are not configured after the device is
93 opened, the structure will be set to its default configuration.
94 .LP
95 Note -
96 .sp
97 .RS 2
98 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
131 .sp
132 .RS 2
133 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
134 supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in
135 \fBusbprn\fR differ from \fBecpp\fR(7D). Refer to \fBecpp\fR(7D) for
136 information.
137 .RE
138 .RE
139
140 .sp
141 .ne 2
142 .na
143 \fB\fBBPPIOC_TESTIO\fR\fR
144 .ad
145 .RS 20n
146 Tests the transfer readiness of a print device and checks status bits to
147 determine if a \fBwrite\fR(2) will succeed. If status bits are set, a transfer
148 will fail. If a transfer will succeed, zero is returned. If a transfer fails,
149 the driver returns \fBEIO\fR and the state of the status bits are captured. The
150 captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call.
151 .LP
152 Note -
153 .sp
154 .RS 2
155 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
156 supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and
157 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
158 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.)
159 .RE
160 .RE
161
162 .sp
163 .ne 2
164 .na
165 \fB\fBBPPIOC_GETERR\fR\fR
166 .ad
167 .RS 20n
168 Get last error status. The argument is a pointer to a \fBstruct
169 bpp_error_status\fR. This structure indicates the status of all the appropriate
170 status bits at the time of the most recent error condition during a
218 .in +2
219 .nf
220 struct ecpp_device_id {
221 int mode; /* mode to use for reading device id */
222 int len; /* length of buffer */
223 int rlen; /* actual length of device id string */
224 char *addr; /* buffer address */
225 .fi
226 .in -2
227
228 .LP
229 Note -
230 .sp
231 .RS 2
232 Unlike \fBecpp\fR(7D), only the ECPP_CENTRONICS mode is currently supported in
233 \fBusbprn\fR.
234 .RE
235 .RE
236
237 .SH READ OPERATION
238 The \fBread\fR operation is not supported and returns \fBEIO\fR.
239 .SH ERRORS
240 .ne 2
241 .na
242 \fB\fBEBUSY\fR\fR
243 .ad
244 .RS 19n
245 The device has been opened and another open is attempted. An attempt has been
246 made to unload the driver while one of the units is open.
247 .RE
248
249 .sp
250 .ne 2
251 .na
252 \fB\fBEINVAL\fR\fR
253 .ad
254 .RS 19n
255 An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is
256 attempted with an out of range value in the \fBecpp_transfer_parms\fR
257 structure.
328
329 .sp
330 .ne 2
331 .na
332 \fB/dev/usb/*/*/* \fR
333 .ad
334 .RS 30n
335 ugen(7D) nodes.
336 .RE
337
338 .sp
339 .ne 2
340 .na
341 \fB\fB/dev/printers/\fIn\fR\fR\fR
342 .ad
343 .RS 30n
344 Character special files
345 .RE
346
347 .SH ATTRIBUTES
348 See \fBattributes\fR(5) for descriptions of the following attributes:
349 .sp
350
351 .sp
352 .TS
353 box;
354 c | c
355 l | l .
356 ATTRIBUTE TYPE ATTRIBUTE VALUE
357 _
358 Architecture SPARC, x86, PCI-based systems
359 .TE
360
361 .SH SEE ALSO
362 \fBcfgadm_usb\fR(1M), \fBprintmgr\fR(1M), \fBioctl\fR(2), \fBopen\fR(2),
363 \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
364 \fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D), \fBprnio\fR(7I),
365 \fBattach\fR(9E)
366 .sp
367 .LP
368 \fIWriting Device Drivers\fR
369 .sp
370 .LP
371 \fIUniversal Serial Bus Specification 1.0 and 1.1\fR
372 .sp
373 .LP
374 \fIUSB Device Class Definition for Printing Devices 1.0\fR
375 .sp
376 .LP
377 \fISystem Administration Guide: Basic Administration\fR
378 .SH DIAGNOSTICS
379 In addition to being logged, the following messages may appear on the system
380 console. All messages are formatted in the following manner:
381 .sp
382 .in +2
383 .nf
384 Warning: <device path> (usbprn<instance num>): Error Message...
385 .fi
386 .in -2
387 .sp
388
389 .sp
390 .ne 2
391 .na
392 \fBDevice was disconnected while open. Data may have been lost.\fR
393 .ad
394 .sp .6
395 .RS 4n
396 The device has been hot-removed or powered off while it was open and a possible
397 data transfer was in progress. The job may be aborted.
398 .RE
417 .sp .6
418 .RS 4n
419 A USB printer was hot-removed while open. A new device was hot-inserted which
420 is not identical to the original USB printer. Please disconnect the USB device
421 and reconnect the printer to the same port.
422 .RE
423
424 .sp
425 .ne 2
426 .na
427 \fBPrinter has been reconnected but data may have been lost.\fR
428 .ad
429 .sp .6
430 .RS 4n
431 The printer that was hot-removed from its USB port has been re-inserted again
432 to the same port. It is available for access but the job that was running prior
433 to the hot-removal may be lost.
434 .RE
435
436 .SH NOTES
437 The USB printer will be power managed if the device is closed.
438 .sp
439 .LP
440 If a printer is hot-removed before a job completes, the job is terminated and
441 the driver will return EIO. All subsequent opens will return \fBENODEV\fR. If a
442 printer is hot-removed, an LP reconfiguration may not be needed if a printer is
443 re-inserted on the same port. If re-inserted on a different port, an LP
444 reconfiguration may be required.
445 .sp
446 .LP
447 The USB Parallel Printer Adapter is not hotpluggable. The printer should be
448 connected to USB Parallel Printer Adapter before plugging the USB cable into
449 host or hub port and should be removed only after disconnecting the USB cable
450 of USB Parallel Printer Adapter from the host or hub port.
|