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