| blob | 017e648cd7f4ccfffb98f621a5b3b3cea409cfef |
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 "April 9, 2016"
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
15 .LP
16 .nf
17 #include <sys/ecppio.h>
18 .fi
20 .LP
21 .nf
22 usbprn@unit-address
23 .fi
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. For
35 a list of recommended printers and USB parallel printer adapters, visit
36 http://\fIwww.sun.com/io\fR.
37 .sp
38 .LP
39 The \fBusbrpn\fR driver includes support for communicating with many different
40 printers. To use these printers, it may be nesessary to install and configure
41 additional format conversion packages available in the Solaris distribution.
42 Configuration of these conversion packages under the Solaris printing system
43 can be simplified through the use of the \fBprintmgr\fR(1M). This tool allows
44 selection of printer manufacturer/model information while creating a print
45 queue. For USB connected printers, it attempts to pre-select the
46 manufacturer and model information based on the 1284 device id supplied by the
47 printer.
48 .SS "UGEN (Generic USB)"
49 .LP
50 The \fBusbprn\fR driver also supports a \fBugen\fR(7D) interface allowing raw
51 access to the device, for example by \fBlibusb\fR(3LIB) applications, by
52 passing the drivers bound to each interface. Because a libusb application might
53 change the state of the device, you should not access the device through the
54 child interface drivers.
55 .SH DEFAULT OPERATION
56 .LP
57 With certain minor exceptions (outlined in the Notes sections below), the
58 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) ioctl interfaces:
59 .sp
60 .LP
61 Configuration variables are set to their default values each time the USB
62 printer device is attached. The \fBwrite_timeout\fR period (defined in the
63 ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The mode is set
64 to centronics mode (ECPP_CENTRONICS). Parameters can be changed through the
65 ECPPIOC_SETPARMS ioctl and read through the ECPPIOC_GETPARMS ioctl. Each time
66 the USB printer device is opened, the device is marked as busy and all further
67 opens will return EBUSY. Once the device is open, applications can write to the
68 device and the driver can send data and obtain device id and status.
69 .LP
70 Note -
71 .sp
72 .RS 2
73 Unlike the \fBecpp\fR(7D) driver, \fBusbprn\fR resets configuration variables
74 to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(7D) driver
75 resets configuration variables with each \fBopen\fR(2).)
76 .RE
77 .SH WRITE OPERATION
78 .LP
79 A \fBwrite\fR(2) operation returns the number of bytes successfully written to
80 the device. If a failure occurs while a driver is transferring data to printer,
81 the contents of the status bits are captured at the time of the error and can
82 be retrieved by the application program using the ECPPIOC_GETERR \fBioctl\fR(2)
83 call. The captured status information is overwritten each time an
84 ECPPIOC_TESTIO \fBioctl\fR(2) occurs.
85 .SH IOCTLS
86 .LP
87 The \fBusbprn\fR driver supports \fBprnio(7I)\fR interfaces. Note that the
88 \fBPRNIOC_RESET\fR command has no effect on USB printers.
89 .sp
90 .LP
91 The following \fBioctl\fR(2) calls are supported for backward compatibility and
92 are not recommended for new applications.
93 .sp
94 .ne 2
95 .na
96 \fB\fBECPPIOC_GETPARMS\fR\fR
97 .ad
98 .RS 20n
99 Gets current transfer parameters. The argument is a pointer to \fBstruct
100 ecpp_transfer_parms\fR. If parameters are not configured after the device is
101 opened, the structure will be set to its default configuration.
102 .LP
103 Note -
104 .sp
105 .RS 2
106 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
107 supported in \fBusbprn\fR.
108 .RE
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBECPPIOC_SETPARMS\fR\fR
115 .ad
116 .RS 20n
117 Sets transfer parameters. The argument is a pointer to a \fBstruct
118 ecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is
119 returned. If the peripheral or host device cannot support the requested mode,
120 \fBEPROTONOSUPPORT\fR is returned.
121 .sp
122 The transfer parameters structure is defined in <\fBsys/ecppio.h\fR>:
123 .sp
124 .in +2
125 .nf
126 struct ecpp_transfer_parms {
127 int write_timeout;
128 int mode;
129 };
130 .fi
131 .in -2
133 The \fBwrite_timeout\fR field, which specifies how long the driver will take to
134 transfer 8192 bytes of data to the device, is set to a default value of 90
135 seconds. The \fBwrite_timeout\fR field must be greater than one second and less
136 than 300 seconds (five minutes.)
137 .LP
138 Note -
139 .sp
140 .RS 2
141 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
142 supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in
143 \fBusbprn\fR differ from \fBecpp\fR(7D). Refer to \fBecpp\fR(7D) for
144 information.
145 .RE
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBBPPIOC_TESTIO\fR\fR
152 .ad
153 .RS 20n
154 Tests the transfer readiness of a print device and checks status bits to
155 determine if a \fBwrite\fR(2) will succeed. If status bits are set, a transfer
156 will fail. If a transfer will succeed, zero is returned. If a transfer fails,
157 the driver returns \fBEIO\fR and the state of the status bits are captured. The
158 captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call.
159 BPPIOC_TESTIO and BPPIOC_GETERR are compatible to the ioctls specified in
160 \fBbpp\fR(7D).
161 .LP
162 Note -
163 .sp
164 .RS 2
165 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
166 supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and
167 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
168 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.)
169 .RE
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fBBPPIOC_GETERR\fR\fR
176 .ad
177 .RS 20n
178 Get last error status. The argument is a pointer to a \fBstruct
179 bpp_error_status\fR. This structure indicates the status of all the appropriate
180 status bits at the time of the most recent error condition during a
181 \fBwrite\fR(2) call, or the status of the bits at the most recent BPPIOC_TESTIO
182 \fBioctl\fR(2) call.
183 .sp
184 .in +2
185 .nf
186 struct bpp_error_status {
187 char timeout_occurred; /* not used */
188 char bus_error; /* not used */
189 uchar_t pin_status; /* status of pins which
190 /* could cause error */
191 };
192 .fi
193 .in -2
195 The pin_status field indicates possible error conditions. The error status
196 structure \fBbpp_error_status\fR is defined in the include file
197 \fB<sys/bpp_io.h>\fR\&. The valid bits for \fBpin_status\fR can be
198 \fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, and \fBBPP_PE_ERR\fR. A set bit
199 indicates that the associated pin is asserted.
200 .LP
201 Note -
202 .sp
203 .RS 2
204 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
205 supported in \fBusbprn\fR. Additionally, the \fBbus_error\fR and
206 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
207 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.) Unlike \fBecpp\fR(7D), the
208 BPP_BUSY_ERR status bit is not supported by USB printers.
209 .RE
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB\fBECPPIOC_GETDEVID\fR\fR
216 .ad
217 .RS 20n
218 Gets the IEEE 1284 device ID from the peripheral. The argument is a pointer to
219 a \fBstruct ecpp_device_id\fR. Applications should set mode to ECPP_CENTRONICS.
220 If another mode is used, the driver will return \fBEPROTONOSUPPORT\fR.
221 \fBlen\fR is the length of the buffer pointed to by \fBaddr\fR. \fBrlen\fR is
222 the actual length of the device ID string returned from the peripheral. If the
223 returned \fBrlen\fR is greater than \fBlen\fR, the application should call
224 ECPPIOC_GETDEVID a second time with a buffer length equal to \fBrlen\fR.
225 .sp
226 The 1284 device ID structure:
227 .sp
228 .in +2
229 .nf
230 struct ecpp_device_id {
231 int mode; /* mode to use for reading device id */
232 int len; /* length of buffer */
233 int rlen; /* actual length of device id string */
234 char *addr; /* buffer address */
235 .fi
236 .in -2
238 .LP
239 Note -
240 .sp
241 .RS 2
242 Unlike \fBecpp\fR(7D), only the ECPP_CENTRONICS mode is currently supported in
243 \fBusbprn\fR.
244 .RE
245 .RE
247 .SH READ OPERATION
248 .LP
249 The \fBread\fR operation is not supported and returns \fBEIO\fR.
250 .SH ERRORS
251 .ne 2
252 .na
253 \fB\fBEBUSY\fR\fR
254 .ad
255 .RS 19n
256 The device has been opened and another open is attempted. An attempt has been
257 made to unload the driver while one of the units is open.
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fBEINVAL\fR\fR
264 .ad
265 .RS 19n
266 An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is
267 attempted with an out of range value in the \fBecpp_transfer_parms\fR
268 structure.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBEIO\fR\fR
275 .ad
276 .RS 19n
277 The driver has received an unrecoverable device error, or the device is not
278 responding, or the device has stalled when attempting an access. A
279 \fBwrite\fR(2) or \fBioctl\fR(2) did not complete due to a peripheral access. A
280 \fBread\fR(2) system call has been issued.
281 .RE
283 .sp
284 .ne 2
285 .na
286 \fB\fBENXIO\fR\fR
287 .ad
288 .RS 19n
289 The driver has received an \fBopen\fR(2) request for a unit for which the
290 attach failed.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fBENODEV\fR\fR
297 .ad
298 .RS 19n
299 The driver has received an \fBopen\fR(2) request for a device that has been
300 disconnected.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB\fBEPROTONOSUPPORT\fR\fR
307 .ad
308 .RS 19n
309 The driver has received a ECPPIOC_SETPARMS \fBioctl\fR(2) for a mode argument
310 other than ECPP_CENTRONICS in the \fBecpp_transfer_parms\fR structure.
311 .RE
313 .SH FILES
314 .ne 2
315 .na
316 \fB\fB/kernel/drv/usbprn\fR\fR
317 .ad
318 .RS 30n
319 32-bit x86 ELF kernel module
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fB/kernel/drv/amd64/usbprn\fR\fR
326 .ad
327 .RS 30n
328 64-bit x86 ELF kernel module
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fB/kernel/drv/sparcv9/usbprn\fR\fR
335 .ad
336 .RS 30n
337 64-bit SPARC ELF kernel module
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB/dev/usb/*/*/* \fR
344 .ad
345 .RS 30n
346 ugen(7D) nodes.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fB/dev/printers/\fIn\fR\fR\fR
353 .ad
354 .RS 30n
355 Character special files
356 .RE
358 .SH ATTRIBUTES
359 .LP
360 See \fBattributes\fR(5) for descriptions of the following attributes:
361 .sp
363 .sp
364 .TS
365 box;
366 c | c
367 l | l .
368 ATTRIBUTE TYPE ATTRIBUTE VALUE
369 _
370 Architecture SPARC, x86, PCI-based systems
371 .TE
373 .SH SEE ALSO
374 .LP
375 \fBcfgadm_usb\fR(1M), \fBprintmgr\fR(1M), \fBioctl\fR(2), \fBopen\fR(2),
376 \fBread\fR(2), \fBwrite\fR(2), \fBlibusb\fR(3LIB), \fBattributes\fR(5),
377 \fBbpp\fR(7D), \fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D)\fBprnio\fR(7I),
378 \fBattach\fR(9E)
379 .sp
380 .LP
381 \fIWriting Device Drivers\fR
382 .sp
383 .LP
384 \fIUniversal Serial Bus Specification 1.0 and 1.1\fR
385 .sp
386 .LP
387 \fIUSB Device Class Definition for Printing Devices 1.0\fR
388 .sp
389 .LP
390 \fISystem Administration Guide: Basic Administration\fR
391 .sp
392 .LP
393 http://\fIwww.sun.com/io\fR
394 .SH DIAGNOSTICS
395 .LP
396 In addition to being logged, the following messages may appear on the system
397 console. All messages are formatted in the following manner:
398 .sp
399 .in +2
400 .nf
401 Warning: <device path> (usbprn<instance num>): Error Message...
402 .fi
403 .in -2
404 .sp
406 .sp
407 .ne 2
408 .na
409 \fBDevice was disconnected while open. Data may have been lost.\fR
410 .ad
411 .sp .6
412 .RS 4n
413 The device has been hot-removed or powered off while it was open and a possible
414 data transfer was in progress. The job may be aborted.
415 .RE
417 .sp
418 .ne 2
419 .na
420 \fBCannot access <device>. Please reconnect.\fR
421 .ad
422 .sp .6
423 .RS 4n
424 There was an error in accessing the printer during reconnect. Please reconnect
425 the device.
426 .RE
428 .sp
429 .ne 2
430 .na
431 \fBDevice is not identical to the previous one on this port. Please disconnect
432 and reconnect.\fR
433 .ad
434 .sp .6
435 .RS 4n
436 A USB printer was hot-removed while open. A new device was hot-inserted which
437 is not identical to the original USB printer. Please disconnect the USB device
438 and reconnect the printer to the same port.
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fBPrinter has been reconnected but data may have been lost.\fR
445 .ad
446 .sp .6
447 .RS 4n
448 The printer that was hot-removed from its USB port has been re-inserted again
449 to the same port. It is available for access but the job that was running prior
450 to the hot-removal may be lost.
451 .RE
453 .SH NOTES
454 .LP
455 The USB printer will be power managed if the device is closed.
456 .sp
457 .LP
458 If a printer is hot-removed before a job completes, the job is terminated and
459 the driver will return EIO. All subsequent opens will return \fBENODEV\fR. If a
460 printer is hot-removed, an LP reconfiguration may not be needed if a printer is
461 re-inserted on the same port. If re-inserted on a different port, an LP
462 reconfiguration may be required.
463 .sp
464 .LP
465 The USB Parallel Printer Adapter is not hotpluggable. The printer should be
466 connected to USB Parallel Printer Adapter before plugging the USB cable into
467 host or hub port and should be removed only after disconnecting the USB cable
468 of USB Parallel Printer Adapter from the host or hub port.