Print this page
4023 - Typo in file(1) manpage and various others
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/ugen.7d
+++ new/usr/src/man/man7d/ugen.7d
1 1 '\" te
2 2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 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 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 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 UGEN 7D "Dec 3, 2008"
6 +.TH UGEN 7D "Sep 10, 2013"
7 7 .SH NAME
8 8 ugen \- USB generic driver
9 9 .SH SYNOPSIS
10 10 .LP
11 11 .nf
12 12 \fBNode Name@unit-address\fR
13 13 .fi
14 14
15 15 .LP
16 16 .nf
17 17 \fB#include <sys/usb/clients/ugen/usb_ugen.h>\fR
18 18 .fi
19 19
20 20 .SH DESCRIPTION
21 21 .sp
22 22 .LP
23 23 \fBugen\fR is a generic USBA (Solaris USB Architecture) compliant client
24 24 character driver that presents USB devices to applications through a standard
25 25 \fBopen\fR(2), \fBclose\fR(2), \fBread\fR(2), \fBwrite\fR(2),
26 26 \fBaioread\fR(3C), \fBaiowrite\fR(3C) Unix interface. Uninterpreted raw data
27 27 are transfered to and from the device via file descriptors created for each USB
28 28 endpoint. Status is obtained by reading file descriptors created for endpoint
29 29 and full device status.
30 30 .sp
31 31 .LP
32 32 \fBugen\fR supports control, bulk, isochronous and interrupt (in and out)
33 33 transfers. \fBlibusb\fR(3LIB) uses \fBugen\fR to access devices that do not
34 34 contain drivers (such as digital cameras and PDAs). Refer to
35 35 \fB/usr/sfw/share/doc/libusb/libusb.txt\fR for details.
36 36 .SH BINDING
37 37 .sp
38 38 .LP
39 39 In general, no explicit binding of the \fBugen\fR driver is necessary because
40 40 \fBusb_mid\fR(7D) is the default driver for devices without a class or vendor
41 41 unique driver. \fBusb_mid\fR(7D) creates the same logical device names as
42 42 \fBugen\fR, but only if no child interfaces are explicitly bound to \fBugen\fR.
43 43 If it is necessary to bind \fBugen\fR explicitly to a device or interface, the
44 44 following section explains the necessary steps.
45 45 .sp
46 46 .LP
47 47 \fBugen\fR can bind to a device with one or more interfaces in its entirety, or
48 48 to a single interface of that device. The binding type depends on information
49 49 that is passed to \fBadd_drv\fR(1M) or \fBupdate_drv\fR(1M).
50 50 .sp
51 51 .LP
52 52 An \fBadd_drv\fR(1M) command binds \fBugen\fR to a list of device types it is
53 53 to control. \fBupdate_drv\fR(1M) adds an additional device type to the list of
54 54 device types being managed by the driver.
55 55 .sp
56 56 .LP
57 57 Names used to bind drivers can be found in \fB/var/adm/messages\fR. When a
58 58 device is on-lined after hot insertion, and no driver is found, there will be
59 59 an entry containing:
60 60 .sp
61 61 .in +2
62 62 .nf
63 63 USB 2.0 device (usb<vid>,<pid>)...
64 64 .fi
65 65 .in -2
66 66
67 67 .sp
68 68 .LP
69 69 where vid is the USB vendor identifier in hex and pid is the product
70 70 identifier in hex supplied by the device descriptor \fBusb_dev_descr\fR(9S).
71 71 .sp
72 72 .LP
73 73 When using ugen for the first time, you must add the driver utilizing
74 74 \fBadd_drv\fR(1M), using a command of the following form:
75 75 .sp
76 76 .in +2
77 77 .nf
78 78 Assuming that the vid is 472 and pid is b0b0:
79 79
80 80 add_drv -n -m '* <device perms> <owner> <group>'
81 81 -i '"usb472,b0b0"' ugen
82 82 .fi
83 83 .in -2
84 84
85 85 .sp
86 86 .LP
87 87 If the command fails with:
88 88 .sp
89 89 .in +2
90 90 .nf
91 91 (ugen) already in use as a driver or alias.
92 92 .fi
93 93 .in -2
94 94
95 95 .sp
96 96 .LP
97 97 \&...add the device using \fBupdate_drv\fR(1M):
98 98 .sp
99 99 .in +2
100 100 .nf
101 101 update_drv -a -m '* <device perms> <owner> <group>'
102 102 -i '"usb472,b0b0"' ugen
103 103 .fi
104 104 .in -2
105 105
106 106 .sp
107 107 .LP
108 108 This binds \fBugen\fR to the entire device.
109 109 .sp
110 110 .LP
111 111 If ugen only binds to one interface of the device, use the following
112 112 driver_alias instead of usb<vid>,<pid>:
113 113 .sp
114 114 .in +2
115 115 .nf
116 116 usbif<vid>,<pid>.config<cfg value>.<interface number>
117 117 .fi
118 118 .in -2
119 119
120 120 .sp
121 121 .LP
122 122 where cfg value is the value of bConfigurationValue in the configuration
123 123 descriptor (\fBusb_cfg_descr\fR(9S)). For example "usbif1234,4567.config1.0."
124 124 .sp
125 125 .LP
126 126 Note that you can use update_drv to also remove bindings. Please see
127 127 \fBupdate_drv\fR(1M) for more information.
128 128 .sp
129 129 .LP
130 130 After a successful add_drv or update_drv, remove the device and reinsert. Check
131 131 with the \fBprtconf\fR(1M) -D option to determine if \fBugen\fR is successfully
132 132 bound to the device and the nodes created in /dev/usb/<vid>.<pid> (see below).
133 133 .sp
134 134 .LP
135 135 An example showing how to bind a child device representing interface 0 of
136 136 configuration 1 of a composite device follows:
137 137 .sp
138 138 .in +2
139 139 .nf
140 140 update_drv -a -m '* 0666 root sys'
141 141 -i '"usbif472,b0b0.config1.0"' ugen
142 142 .fi
143 143 .in -2
144 144
145 145 .sp
146 146 .LP
147 147 Note that you can completely uninstall the \fBugen\fR driver and delete it from
148 148 the system by doing:
149 149 .sp
150 150 .in +2
151 151 .nf
152 152 pkgrm SUNWugen
153 153 .fi
154 154 .in -2
155 155
156 156 .sp
157 157 .LP
158 158 Any \fBpkgadd\fR of SUNWugen after the \fBpkgrm\fR reactivates any pre-existing
159 159 ugen driver device-bindings.
160 160 .sp
161 161 .LP
162 162 Any pre-existing ugen driver device-bindings are preserved across operating
163 163 system upgrades.
164 164 .SH LOGICAL DEVICE NAME FORMAT
165 165 .sp
166 166 .LP
167 167 For each device or child device it manages, \fBugen\fR creates one logical
168 168 device name for device-wide status and one logical device name for endpoint 0.
169 169 \fBugen\fR also creates logical device names for all other endpoints within the
170 170 device node's binding scope (interface or device), plus logical device names
171 171 for their status.
172 172 .sp
173 173 .LP
174 174 If separate \fBugen\fR instances control different interfaces of the same
175 175 device, the device-wide status and endpoint logical device names created for
176 176 each instance will share access to the same source or endpoint pipes. For
177 177 example, a device with two interfaces, each operated by their own \fBugen\fR
178 178 instance, will show \fBendpoint0\fR as \fBif0cntrl0\fR to the first interface,
179 179 and will show it as \fBif1cntrl0\fR to the second interface. Both of these
180 180 logical device names share \fBendpoint0\fR. Likewise for the same device,
181 181 \fBugen\fR makes the device-wide status available as \fBif0devstat\fR to the
182 182 first interface and as \fBif1devstat\fR to the second interface.
183 183 \fBif0devstat\fR and \fBif1devstat\fR both return the same data.
184 184 .sp
185 185 .LP
186 186 Any \fBugen\fR logical device name can be held open by only one user at a time,
187 187 regardless of whether the\fB O_EXCL\fR flag passed to \fBopen\fR(2). When a
188 188 single pipe or data source is shared by multiple logical device names, such as
189 189 if[0,1]cntrl0 or if[0,1]devstat above, more than one logical device name
190 190 sharing the pipe or data source can be open at a time. However, only one user
191 191 may access the shared pipe or data source at a time, regardless of the logical
192 192 device name used for access.
193 193 .sp
194 194 .LP
195 195 When \fBugen\fR is bound to an entire device, the following logical device
196 196 names are created (each on a single line). \fIN\fR represents the instance
197 197 number of the device type.
198 198 .sp
199 199 .in +2
200 200 .nf
201 201 Endpoint 0 (default endpoint):
202 202
203 203 /dev/usb/<vid>.<pid>/<N>/cntrl0
204 204 /dev/usb/<vid>.<pid>/<N>/cntrl0stat
205 205
206 206 For example:
207 207
208 208 /dev/usb/472.b0b0/0/cntrl0
209 209 /dev/usb/472.b0b0/0/cntrl0stat
210 210
211 211 Configuration index 1, Endpoints > 0, alternate 0:
212 212
213 213 /dev/usb/<vid>.<pid>/<N>/if<interface#>
214 214 <in|out|cntrl><endpoint#>
215 215 /dev/usb/<vid>.<pid>/<N>/if<interface#>
216 216 <in|out|cntrl><endpoint#>stat
217 217
218 218 For example:
219 219
220 220 /dev/usb/472.b0b0/0/if0in1
221 221 /dev/usb/472.b0b0/0/if0in1stat
222 222
223 223 Configuration index 1, Endpoints > 0, alternate > 0:
224 224
225 225 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
226 226 <alternate><in|out|cntrl><endpoint#>
227 227 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
228 228 <alternate<in|out|cntrl><endpoint#>stat
229 229
230 230 For example:
231 231
232 232 /dev/usb/472.b0b0/0/if0.1in3
233 233 /dev/usb/472.b0b0/0/if0.1in3stat
234 234
235 235 Configuration index> 1, Endpoints > 0, alternate 0:
236 236 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
237 237 <in|out|cntrl><endpoint#>
238 238 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
239 239 <in|out|cntrl><endpoint#>stat
240 240
241 241 For example:
242 242
243 243 /dev/usb/472.b0b0/0/cfg2if0in1
244 244 /dev/usb/472.b0b0/0/cfg2if0in1stat
245 245
246 246 Note that the configuration value from the configuration
247 247 descriptor indexed by the configuration index is used in
248 248 the node name and not the configuration index itself.
249 249
250 250 Configuration index> 1, Endpoints > 0, alternate > 0:
251 251 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
252 252 <alternate<in|out|cntrl><endpoint#>
253 253 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
254 254 <alternate<in|out|cntrl><endpoint#>stat
255 255
256 256 For example:
257 257
258 258 /dev/usb/472.b0b0/0/cfg2if0.1in1
259 259 /dev/usb/472.b0b0/0/cfg2if0.1in1stat
260 260
261 261 Device status:
262 262
263 263 /dev/usb/<vid>.<pid>/<N>/devstat
264 264
265 265 For example:
266 266
267 267 /dev/usb/472.b0b0/0/devstat
268 268 .fi
269 269 .in -2
270 270
271 271 .sp
272 272 .LP
273 273 When \fBugen\fR is bound to a single device interface, the following logical
274 274 device nodes are created:
275 275 .sp
276 276 .in +2
277 277 .nf
278 278 Endpoint 0 (default endpoint):
279 279
280 280 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0
281 281 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0stat
282 282
283 283 For example:
284 284
285 285 /dev/usb/472.b0b0/0/if0cntrl0
286 286 /dev/usb/472.b0b0/0/if0cntrl0stat
287 287
288 288 Device status:
289 289 /dev/usb/<vid>.<pid>/<N>/if<interface#>devstat
290 290
291 291 For example:
292 292 /dev/usb/472.b0b0/0/if0devstat
293 293 .fi
294 294 .in -2
295 295
296 296 .sp
297 297 .LP
298 298 The format for all other logical device names is identical to the format used
299 299 when \fBugen\fR is bound to the entire device.
300 300 .sp
301 301 .LP
302 302 Opening the endpoint of a different configuration or different alternate
303 303 interface will cause an implicit change of configuration or a switch to an
304 304 alternate interface. A configuration change is prohibited when any non-zero
305 305 endpoint device nodes are open. An alternate interface switch is prohibited if
306 306 any endpoint in the same interface is open.
307 307 .SH HOT-PLUGGING
308 308 .sp
309 309 .LP
310 310 A device may be hot-removed at any time. Following hot-removal, the device
311 311 status changes to USB_DEV_STAT_DISCONNECTED, the status of open endpoints
312 312 change to USB_LC_STAT_DISCONNECTED upon their access, and all subsequent
313 313 transfer requests fail. Endpoints are reactivated by first reinserting the
314 314 device and then closing and reopening all endpoints that were open when the
315 315 device was disconnected.
316 316 .SH CPR (CHECKPOINT/RESUME)
317 317 .sp
318 318 .LP
319 319 CPR (Checkpoint/Resume) may be initiated at any time and is treated similarly
320 320 to a hot-removal. Upon successful suspend and resume, all subsequent transfer
321 321 requests fail as an indication to the application to reinitialize. Applications
322 322 should close and reopen all endpoints to reinstate them. All endpoint and
323 323 device status on Resume (before close and reopen) is USB_LC_STAT_SUSPENDED. A
324 324 system suspend will fail while \fBugen\fR is performing a transfer.
325 325 .SH DEVICE POWER MANAGEMENT
326 326 .sp
327 327 .LP
328 328 Devices which support remote wakeup can be power managed when they have no open
329 329 logical device nodes. When an application opens the first logical device node
330 330 of a device, that application should assume that a reinitialization of device
331 331 state is required.
332 332 .SH DEVICE STATUS MANAGEMENT
333 333 .sp
334 334 .LP
335 335 Applications can monitor device status changes by reading the device status
336 336 from the device status logical name. When opened without O_NONBLOCK and
337 337 O_NDELAY, all reads from that file descriptor (with the exception of the the
338 338 intial read that follows the open) block until a device status change occurs.
339 339 Calls to read will always return immediately if opened with \fBO_NONBLOCK\fR or
340 340 \fBO_NDELAY\fR. Nonblocking calls to read which have no data to return, return
341 341 no error and zero bytes read.
342 342 .sp
343 343 .LP
344 344 Device statuses are:
345 345 .sp
346 346 .ne 2
347 347 .na
348 348 \fBUSB_DEV_STAT_ONLINE\fR
349 349 .ad
350 350 .RS 29n
351 351 Device is available.
352 352 .RE
353 353
354 354 .sp
355 355 .ne 2
356 356 .na
357 357 \fBUSB_DEV_STAT_DISCONNECTED\fR
358 358 .ad
359 359 .RS 29n
360 360 Device has been disconnected.
361 361 .RE
362 362
363 363 .sp
364 364 .ne 2
365 365 .na
366 366 \fBUSB_DEV_STAT_RESUMED\fR
367 367 .ad
368 368 .RS 29n
369 369 Device has been resumed, however, endpoints which were open on suspend have not
370 370 yet been closed and reopened.
371 371 .RE
372 372
373 373 .sp
374 374 .ne 2
375 375 .na
376 376 \fBUSB_DEV_STAT_UNAVAILABLE\fR
377 377 .ad
378 378 .RS 29n
379 379 Device has been reconnected, however, endpoints which were open on disconnect
380 380 have not yet been closed and reopened.
381 381 .RE
382 382
383 383 .sp
384 384 .LP
385 385 The following code reads the device status device logical name:
386 386 .sp
387 387 .in +2
388 388 .nf
389 389 int fd;
390 390 int status;
391 391
392 392 if ((fd = open("/dev/usb/472.b0b0/0/devstat",
393 393 O_RDONLY)) < 0) {
394 394 /* handle error */
395 395 }
396 396
397 397 if (read(fd, &status, sizeof(status)) != sizeof(status)) {
398 398 /* handle error */
399 399 }
400 400
401 401 switch (status) {
402 402 case USB_DEV_STAT_DISCONNECTED:
403 403 printf ("Terminating as device has been disconnected.\en");
404 404 exit (0);
405 405
406 406 case USB_DEV_STAT_RESUMED:
407 407 case USB_DEV_STAT_UNAVAILABLE:
408 408 /*
409 409 * Close and reopen endpoints to reestablish device access,
410 410 * then reset device.
411 411 */
412 412 break;
413 413
414 414 case USB_DEV_STAT_ONLINE:
415 415 default:
416 416 break;
417 417 }
418 418 .fi
419 419 .in -2
420 420
421 421 .sp
422 422 .LP
423 423 Use \fBpoll\fR(2) to block on several logical names simultaneously, including
424 424 device status logical names. Poll indicates when reading a logical name would
425 425 return data. See \fBpoll\fR(2) for details. Calls to read may be done whether
426 426 or not they follow calls to poll.
427 427 .SH ENDPOINT STATUS MANAGEMENT
428 428 .sp
429 429 .LP
430 430 Each data endpoint has a corresponding status logical name. Use the status
431 431 logical name to retrieve the state of the data endpoint, including detail on
432 432 how its most recent transfer failed. Reads of the status file descriptors
433 433 always return immediately. See the ERRORS section for more information on
434 434 endpoint status values. All logical device name files created for returning
435 435 status must be opened with \fBO_RDONLY\fR.
436 436 .sp
437 437 .LP
438 438 The following code illustrates reading the status file descriptor of an
439 439 endpoint which just failed a data transfer in order to get more information on
440 440 the failure.
441 441 .sp
442 442 .in +2
443 443 .nf
444 444 int data_xfered, status;
445 445 int ep1_data_fd, ep1_stat_fd;
446 446 uchar_t request[8];
447 447
448 448 ep1_data_fd = open ("/dev/usb/472.b0b0/0/if0out1", O_WRONLY);
449 449
450 450 if (ep1_data_fd < 0) {
451 451 /* Handle open error. */
452 452 }
453 453
454 454 ep1_stat_fd = open ("/dev/usb/472.b0b0/0/if0out1stat",
455 455 O_RDONLY);
456 456 if (ep1_stat_fd < 0) {
457 457 /* Handle open error. */
458 458 }
459 459
460 460 data_xfered = write(ep1_data_fd, request, sizeof (request));
461 461
462 462 /* An error occured during the data transfer. */
463 463 if (data_xfered != sizeof (request)) {
464 464
465 465 /* Read status file descriptor for details on failure. */
466 466 if (read(ep1_stat_fd, (int *)&status, sizeof (status)) !=
467 467 sizeof (status)) {
468 468 status = USB_LC_STAT_UNSPECIFIED_ERR;
469 469 }
470 470
471 471 /* Take appropriate action. */
472 472 switch (status) {
473 473 case USB_LC_STAT_STALL:
474 474 printf ("Endpoint stalled.\en");
475 475 break;
476 476 case ...
477 477 ...
478 478 }
479 479
480 480 }
481 481 .fi
482 482 .in -2
483 483
484 484 .SH CONTROL TRANSFERS
485 485 .sp
486 486 .LP
487 487 The control endpoint is typically used to set up the device and to query device
488 488 status or configuration.
489 489 .sp
490 490 .LP
491 491 Applications requiring I/O on a control endpoint should open the corresponding
492 492 logical device name and use regular UNIX I/O system calls. For example:
493 493 \fBread\fR(2), \fBwrite\fR(2), \fBaioread\fR(3C) and \fBaiowrite\fR(3C).
494 494 \fBpoll\fR(2) is not supported on control endpoints.
495 495 .sp
496 496 .LP
497 497 A control endpoint must be opened with \fBO_RDWR\fR since it is bidirectional.
498 498 It cannot be opened with \fBO_NONBLOCK\fR or \fBO_NDELAY\fR.
499 499 .sp
500 500 .LP
501 501 For example:
502 502 .sp
503 503 .in +2
504 504 .nf
505 505 fd = open("/dev/usb/472.b0b0/0/cntrl0", O_RDWR);
506 506
507 507 .fi
508 508 .in -2
509 509
510 510 .sp
511 511 .in +2
512 512 .nf
513 513 fdstat = open("/dev/usb/472.b0b0/0/cntrl0stat", O_RDONLY);
514 514 .fi
515 515 .in -2
516 516
517 517 .sp
518 518 .LP
519 519 Control endpoints can be read and written. A \fBread\fR operation receives data
520 520 \fBfrom\fR the device and a \fBwrite\fR operation sends data \fBto\fR the
521 521 device.
522 522 .sp
523 523 .LP
524 524 To perform a control-IN transfer, perform a \fBwrite\fR(2) of USB setup data
525 525 (see section 9.3 of the \fIUSB 1.1\fR or \fI2.0\fR specifications) followed by
526 526 a \fBread\fR(2) on the same control endpoint to fetch the desired data. For
527 527 example:
528 528 .sp
529 529 .in +2
530 530 .nf
531 531 void init_cntrl_req(
532 532 uchar_t *req, uchar_t bmRequestType, uchar_t bRequest,
533 533 ushort_t wValue, ushort_t wIndex, ushort_t wLength) {
534 534 req[0] = bmRequestType;
535 535 req[1] = bRequest;
536 536 req[2] = 0xFF & wValue;
537 537 req[3] = 0xFF & (wValue >> 8);
538 538 req[4] = 0xFF & wIndex;
539 539 req[5] = 0xFF & (wIndex >> 8);
540 540 req[6] = 0xFF & wLength;
541 541 req[7] = 0xFF & (wLength >> 8);
542 542 }
543 543
544 544 ....
545 545
546 546
547 547 uchar_t dev_descr_req[8];
548 548 usb_dev_descr_t descr;
549 549
550 550 init_cntrl_req(dev_descr_req,
551 551 USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
552 552 USB_DESCR_TYPE_SETUP_DEV, 0, sizeof (descr));
553 553
554 554 count = write(fd, dev_descr_req, sizeof (dev_descr_req));
555 555 if (count != sizeof (dev_descr_req)) {
556 556 /* do some error recovery */
557 557 ...
558 558 }
559 559
560 560 count = read(fd, &descr, sizeof (descr));
561 561 if (count != sizeof (descr)) {
562 562 /* do some error recovery */
563 563 }
564 564 .fi
565 565 .in -2
566 566
567 567 .sp
568 568 .LP
569 569 The application can issue any number of reads to read data received on a
570 570 control endpoint. \fBugen\fR successfully completes all reads, returning the
571 571 number of bytes transferred. Zero is returned when there is no data to
572 572 transfer.
573 573 .sp
574 574 .LP
575 575 If the \fBread\fR/\fBwrite\fR fails and returns \fB-1\fR, you can access the
576 576 endpoint's status device logical name for precise error information:
577 577 .sp
578 578 .in +2
579 579 .nf
580 580 int status;
581 581
582 582 count = read(fdstat, &status, sizeof (status));
583 583 if (count == sizeof (status)) {
584 584 switch (status) {
585 585 case USB_LC_STAT_SUSPENDED:
586 586 case USB_LC_STAT_DISCONNECTED:
587 587 /* close all endpoints */
588 588 ...
589 589 break;
590 590 default:
591 591 ...
592 592 break;
593 593 }
594 594 }
595 595 .fi
596 596 .in -2
597 597
598 598 .sp
599 599 .LP
600 600 Refer to the ERRORS section for all possible error values.
601 601 .sp
602 602 .LP
603 603 To perform a control-OUT transfer, send in a single transfer, the USB setup
604 604 data followed by any accompanying data bytes.
605 605 .sp
606 606 .in +2
607 607 .nf
608 608 /* 1st 8 bytes of wbuf are setup. */
609 609 init_cntrl_req(wbuf, .......);
610 610
611 611 /* Data bytes begin at byte 8 of wbuf. */
612 612 bcopy(data, &wuf[8], sizeof (data));
613 613
614 614 /* Send it all in a single transfer. */
615 615 count = write(fd, wbuf, sizeof (wbuf));
616 616 .fi
617 617 .in -2
618 618
619 619 .sp
620 620 .LP
621 621 A \fBwrite\fR(2) returns the number of bytes (both setup and data) actually
622 622 transferred, (whether or not the \fBwrite\fR is completely successful),
623 623 provided that some data is actually transferred. When no data is transferred,
624 624 \fBwrite\fR(2) returns \fB-1\fR. Applications can read the corresponding
625 625 endpoint status to retrieve detailed error information. Note that it is an
626 626 error to specify a size different than:
627 627 .sp
628 628 .LP
629 629 (number of data bytes + number of setup bytes).
630 630 .sp
631 631 .LP
632 632 Here is a more extensive example which gets all descriptors of a device
633 633 configuration. For sake of brevity, uninteresting parts are omitted.
634 634 .sp
635 635 .in +2
636 636 .nf
637 637 #include <sys/usb/usba.h>
638 638 #include <sys/usb/clients/ugen/usb_ugen.h>
639 639
640 640 uchar_t *config_cloud;
641 641 uchar_t *curr_descr;
642 642
643 643 uchar_t *bytes;
644 644
645 645 int curr_descr_len;
646 646 int curr_descr_type;
647 647
648 648 usb_cfg_descr_t cfg_descr;
649 649 usb_if_descr_t if_descr;
650 650 usb_ep_descr_t ep_descr;
651 651
652 652 /* See 9.13 of USB 2.0 spec for ordering. */
653 653 static char *pipetypes[] = {
654 654 "Control", "Isochronous", "Bulk", "Interrupt"
655 655 };
656 656
657 657 /*
658 658 * Setup to send a request to read just the config descriptor. The
659 659 * size of the whole cloud, containing all cfg, interface, endpoint,
660 660 * class and vendor-specific descriptors, will be returned as part of
661 661 * the config descriptor.
662 662 */
663 663 init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
664 664 USB_DESCR_TYPE_SETUP_CFG, 0, USB_CFG_DESCR_SIZE);
665 665
666 666 /*
667 667 * Write setup data. USB device will prepare to return the whole
668 668 * config cloud as a response to this. We will read this separately.
669 669 */
670 670 count = write(ctrl_fd, &setup_data, sizeof (setup_data));
671 671 if (count != sizeof (setup_data)) {
672 672 /* Error recovery. */
673 673 } else {
674 674 count = read(ctrl_fd, &cfg_descr, USB_CFG_DESCR_SIZE);
675 675 if (count != USB_CFG_DESCR_SIZE) {
676 676 /* Error recovery. */
677 677 }
678 678 }
679 679
680 680 /* USB data is little endian. */
681 681 bytes = (uchar_t *)(&cfg_descr.wTotalLength);
682 682 totalLength = bytes[0] + (bytes[1] << 8);
683 683
684 684 /*
685 685 * The size of the whole cloud is in the bLength field. Set up
686 686 * to read this amount of data, to get the whole cloud.
687 687 */
688 688 config_cloud = malloc(totalLength);
689 689
690 690 init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
691 691 USB_DESCR_TYPE_SETUP_CFG, 0, totalLength);
692 692
693 693 count = write(ctrl_fd, &setup_data, sizeof (setup_data));
694 694 if (count != sizeof (setup_data)) {
695 695 /* Error recovery. */
696 696 } else {
697 697 count = read(ctrl_fd, config_cloud, totalLength);
698 698 if (count != totalLength) {
699 699 /* Error recovery. */
700 700 }
701 701 }
702 702
703 703 /* Got the data. Now loop, dumping out the descriptors found. */
704 704
705 705 curr_descr = config_cloud;
706 706 offset = 0;
707 707 while (offset < totalLength) {
708 708
709 709 /* All descr have length and type at offset 0 and 1 */
710 710 curr_descr_len = curr_descr[0];
711 711 curr_descr_type = curr_descr[1];
712 712
713 713 switch (curr_descr_type) {
714 714 case USB_DESCR_TYPE_CFG:
715 715
716 716 /*
717 717 * Copy data into separate structure, needed for
718 718 * proper alignment of all non char fields. Note:
719 719 * non-char fields of all descriptors begin on aligned
720 720 * boundaries. The issue is that some structures may
721 721 * be adjacent to others which have an odd-numbered
722 722 * byte size, and may thus start on an odd-numbered
723 723 * boundary. */
724 724 bcopy(curr_descr, &cfg_descr, curr_descr_len);
725 725
726 726 /* Remember to read any words in endian-neutral way. */
727 727
728 728 (void) printf("\enConfig %d found.\en",
729 729 cfg_descr.bConfigurationValue);
730 730 break;
731 731
732 732 case USB_DESCR_TYPE_IF:
733 733 bcopy(curr_descr, &if_descr, curr_descr_len);
734 734 (void) printf("\en\etInterface %d, Alt %d found.\en",
735 735 if_descr.bInterfaceNumber,
736 736 if_descr.bAlternateSetting);
737 737 break;
738 738
739 739 case USB_DESCR_TYPE_EP:
740 740 bcopy(curr_descr, &ep_descr, curr_descr_len);
741 741 (void) printf("\en\et\etEndpoint %d (%s-%s) found.\en",
742 742 (ep_descr.bEndpointAddress & USB_EP_NUM_MASK),
743 743 (pipetypes[
744 744 ep_descr.bmAttributes & USB_EP_ATTR_MASK]),
745 745 ((ep_descr.bEndpointAddress &
746 746 USB_EP_DIR_IN) ? "IN" : "OUT"));
747 747 break;
748 748
749 749 default:
750 750 (void) printf(
751 751 "\en\et\et\etOther descriptor found. Type:%d\en",
752 752 curr_descr_type);
753 753 break;
754 754 }
755 755
756 756 offset += curr_descr_len;
757 757 curr_descr = &config_cloud[offset];
758 758 }
759 759 .fi
760 760 .in -2
761 761
762 762 .SH INTERRUPT-IN TRANSFERS
763 763 .sp
764 764 .LP
765 765 Applications requiring data from an interrupt-IN endpoint should open the
766 766 corresponding logical device name and use \fBread\fR(2), \fBaioread\fR(3C) and
767 767 \fBpoll\fR(2) system calls.
768 768 .sp
769 769 .LP
770 770 An interrupt-IN endpoint must be opened with \fBO_RDONLY\fR. It can also be
771 771 opened using \fBO_NONBLOCK\fR or \fBO_NDELAY\fR if desired.
772 772 .sp
773 773 .in +2
774 774 .nf
775 775 fd = open("/dev/usb/472.b0b0/0/if0in1", O_RDONLY);
776 776 .fi
777 777 .in -2
778 778
779 779 .sp
780 780 .in +2
781 781 .nf
782 782 fdstat = open("/dev/usb/472.b0b0/0/if0in1stat", O_RDONLY);
783 783
784 784 .fi
785 785 .in -2
786 786
787 787 .sp
788 788 .LP
789 789 \fBugen\fR starts polling interrupt\(emIN endpoints immediately upon opening
790 790 them and stops polling them upon closure. (Polling refers to interrogation of
791 791 the device by the driver and should not be confused with \fBpoll\fR(2), which
792 792 is an interrogation of the driver by the application.)
793 793 .sp
794 794 .LP
795 795 A \fBread\fR(2) of an endpoint opened with the \fBO_NONBLOCK\fR or
796 796 \fBO_NDELAY\fR flags set will not block when there is insufficient data
797 797 available to satisfy the request. The \fBread\fR simply returns what it can
798 798 without signifying any error.
799 799 .sp
800 800 .LP
801 801 Applications should continuously check for and consume interrupt data.
802 802 \fBugen\fR enables buffering of up to one second of incoming data. In case of
803 803 buffer overflow, \fBugen\fR stops polling the interrupt-IN endpoint until the
804 804 application consumes all the data. In this case, a \fBread\fR(2) of an empty
805 805 buffer returns \fB-1\fR, sets the endpoint status to
806 806 \fBUSB_LC_STAT_INTR_BUF_FULL\fR (to indicate that the buffer had been full and
807 807 polling had been stopped) and causes \fBugen\fR to start polling the endpoint
808 808 again. To retrieve the status, the application can open and read the
809 809 corresponding endpoint's status device logical name.
810 810 .sp
811 811 .in +2
812 812 .nf
813 813 for (;;) {
814 814 count = read(fd, buf, sizeof(buf));
815 815 if (count == -1) {
816 816 int cnt, status;
817 817
818 818 cnt = read(fdstat, &status, sizeof (status));
819 819 if (cnt == -1) {
820 820 /* more error recovery here */
821 821 } else {
822 822 switch (status) {
823 823 case USB_LC_STAT_INTR_BUF_FULL:
824 824 ...
825 825 break;
826 826 default:
827 827 ...
828 828 break;
829 829 }
830 830 }
831 831 }
832 832 /* process the data */
833 833 ....
834 834 }
835 835 .fi
836 836 .in -2
837 837
838 838 .sp
839 839 .LP
840 840 \fBugen\fR will never drop data. However, the device may drop data if the
841 841 application cannot read it at the rate that it is produced.
842 842 .sp
843 843 .LP
844 844 Applications requiring unbuffered data from an interrupt-IN endpoint should
845 845 open the associated status endpoint with O_RDWR before opening the associated
846 846 interrupt-IN endpoint and write a control byte with USB_EP_INTR_ONE_XFER set.
847 847 All other bits are reserved and should be 0.
848 848 .sp
849 849 .LP
850 850 "One transfer" mode will persist until disabled explicitly after the associated
851 851 interrupt-IN endpoint has been closed by writing a control byte with
852 852 USB_EP_INTR_ONE_XFER cleared.
853 853 .sp
854 854 .LP
855 855 "One transfer" mode is implicitly disabled when the status/control endpoint is
856 856 closed.
857 857 .sp
858 858 .LP
859 859 Attempts to change the "one transfer" mode while the endpoint is open will
860 860 result in \fBEINVAL\fR.
861 861 .sp
862 862 .LP
863 863 An application can open multiple interrupt-IN endpoints and can call
864 864 \fBpoll\fR(2) to monitor the availability of new data. (Note: poll works with
865 865 interrupt-IN data endpoints, not their status endpoints.)
866 866 .sp
867 867 .in +2
868 868 .nf
869 869 struct pollfd pfd[2];
870 870
871 871 bzero(pfd, sizeof (pfd));
872 872 pfd[0].fd = fd1; /* fd1 is one interrupt-IN endpoint. */
873 873 pfd[0].events = POLLIN;
874 874 pfd[1].fd = fd2; /* fd2 is another interrupt-IN endpoint. */
875 875 pfd[1].events = POLLIN;
876 876
877 877 for (;;) {
878 878 poll(pfd, 2, -1);
879 879
880 880 if (pfd[0].revents & POLLIN) {
881 881 count = read(fd1, buf, sizeof (buf));
882 882 ....
883 883 }
884 884 if (pfd[1].revents & POLLIN) {
885 885 count = read(fd2, buf, sizeof (buf));
886 886 ....
887 887 }
888 888 }
889 889 .fi
890 890 .in -2
891 891
892 892 .sp
893 893 .LP
894 894 You can monitor the device status endpoint via \fBpoll\fR(2) concurrently with
895 895 the multiple interrupt-IN endpoints. Simply add another pollfd element to the
896 896 pfd array in the previous code example, and initialize the new element's
897 897 \fBfd\fR field with the file descriptor of the device status endpoint (opened
898 898 without O_NONBLOCK or O_NDELAY). Set the new element's event field to POLLIN
899 899 like the other elements. Note that only interrupt-IN endpoints and the device
900 900 status endpoint can be monitored using \fBpoll\fR(2).
901 901 .SH INTERRUPT-OUT TRANSFERS
902 902 .sp
903 903 .LP
904 904 Applications requiring output on an interrupt-OUT endpoint can open the
905 905 corresponding logical device name and perform regular UNIX I/O system calls
906 906 such as \fBwrite\fR(2) and \fBaiowrite\fR(3C).
907 907 .sp
908 908 .LP
909 909 An interrupt-OUT endpoint must be opened with O_WRONLY.
910 910 .sp
911 911 .in +2
912 912 .nf
913 913 fd = open("/dev/usb/472.b0b0/0/if0out3", O_WRONLY);
914 914
915 915 fdstat = open("/dev/usb/472.b0b0/0/if0out3stat", O_RDONLY);
916 916
917 917
918 918 .fi
919 919 .in -2
920 920
921 921 .sp
922 922 .LP
923 923 Data can be written to an interrupt-OUT endpoint as follows:
924 924 .sp
925 925 .in +2
926 926 .nf
927 927 count = write(fd, buf, sizeof (buf)):
928 928 if (count == -1) {
929 929 /* error recovery */
930 930 }
931 931 .fi
932 932 .in -2
933 933
934 934 .SH BULK TRANSFERS
935 935 .sp
936 936 .LP
937 937 Applications requiring I/O on a bulk endpoint can open the corresponding
938 938 logical device name and perform regular UNIX I/O system calls. For example:
939 939 \fBread\fR(2), \fBwrite\fR(2), \fBaioread\fR(3C) and \fBaiowrite\fR(3C).
940 940 \fBpoll\fR(2) is not supported on bulk endpoints.
941 941 .sp
942 942 .LP
943 943 A bulk endpoint must be opened with \fBO_RDONLY\fR or \fBO_WRONLY\fR and cannot
944 944 be opened with \fBO_NONBLOCK\fR or \fBO_NDELAY:\fR
945 945 .sp
946 946 .in +2
947 947 .nf
948 948 fd = open("/dev/usb/472.b0b0/0/if0in2", O_RDONLY);
949 949 .fi
950 950 .in -2
951 951
952 952 .sp
953 953 .in +2
954 954 .nf
955 955 fdstat = open("/dev/usb/472.b0b0/0/if0in2stat", O_RDONLY);
956 956 .fi
957 957 .in -2
958 958
959 959 .sp
960 960 .LP
961 961 Data can be read from a bulk-IN endpoint as follows:
962 962 .sp
963 963 .in +2
964 964 .nf
965 965 count = read(fd, buf, sizeof (buf)):
966 966 if (count == -1) {
967 967 /* error recovery */
968 968 }
969 969
970 970 Data can be written to a bulk-OUT endpoint as follows:
971 971
972 972 count = write(fd, buf, sizeof (buf)):
973 973 if (count == -1) {
974 974 /* error recovery */
975 975 }
976 976 .fi
977 977 .in -2
978 978
979 979 .SH ISOCHRONOUS TRANSFERS
980 980 .sp
981 981 .LP
982 982 Applications requiring I/O on an isochronous endpoint can open the
983 983 corresponding logical device name and perform regular UNIX I/O system calls
984 984 such as \fBread\fR(2), \fBwrite\fR(2), \fBpoll\fR(2), \fBaioread\fR(3C) and
985 985 \fBaiowrite\fR(3C). An isochronous endpoint must be opened with \fBO_RDWR\fR.
986 986 .sp
987 987 .in +2
988 988 .nf
989 989 fd = open("/dev/usb/472.b0b0/0/if0.3in2", O_RDWR);
990 990
991 991 fdstat = open("/dev/usb/472.b0b0/0/if0.3in2stat", O_RDONLY);
992 992 .fi
993 993 .in -2
994 994
995 995 .sp
996 996 .LP
997 997 Applications can use the status logical name to retrieve the state of the
998 998 isochronous data endpoint, including details on why the most recent transfer
999 999 failed.
1000 1000 .sp
1001 1001 .LP
1002 1002 Applications have the flexibility to specify the number of isochronous packets
1003 1003 and the size of individual packets they want to transfer. Applications should
1004 1004 use the following data structures to exchange isochronous packet information
1005 1005 with the \fBugen\fR driver:
1006 1006 .sp
1007 1007 .in +2
1008 1008 .nf
1009 1009 typedef struct ugen_isoc_pkt_descr {
1010 1010 /*
1011 1011 * Set by the application, for all isochro.
1012 1012 * requests, to the num. of bytes to xfer
1013 1013 * in a packet.
1014 1014 */
1015 1015 ushort_t dsc_isoc_pkt_len;
1016 1016
1017 1017 /*
1018 1018 * Set by ugen to actual num. of bytes sent/received
1019 1019 * in a packet.
1020 1020 */
1021 1021 ushort_t dsc_isoc_pkt_actual_len;
1022 1022
1023 1023 /*
1024 1024 * Per pkt. status set by ugen driver both for the
1025 1025 * isochronous IN and OUT requests. Application can
1026 1026 * use USB_LC_STAT_* to parse the status.
1027 1027 */
1028 1028 int dsc_isoc_pkt_status;
1029 1029 } ugen_isoc_pkt_descr_t;
1030 1030
1031 1031 typedef struct ugen_isoc_req_head {
1032 1032 /* pkt count of the isoc request */
1033 1033 int req_isoc_pkts_count;
1034 1034
1035 1035 /* pkt descriptors */
1036 1036 ugen_isoc_pkt_descr_t req_isoc_pkt_descrs[1];
1037 1037 } ugen_isoc_req_head_t;
1038 1038 .fi
1039 1039 .in -2
1040 1040
1041 1041 .sp
1042 1042 .LP
1043 1043 \fBreq_isoc_pkts_count\fR is limited by the capability of the USB host
1044 1044 controller driver. The current upper bound for the \fBuhci\fR and \fBohci\fR
1045 1045 drivers is 512. The upper bound for the \fBehci\fR driver is 1024.
1046 1046 .sp
1047 1047 .LP
1048 1048 For an isochronous-IN endpoint, applications must first use the
1049 1049 \fBugen_isoc_req_head_t\fR structure followed by \fBugen_isoc_pkt_descr_t\fR to
1050 1050 write packet request information to the \fBugen\fR node. The \fBugen\fR driver
1051 1051 then checks the validity of the request. If it is valid, the driver immediately
1052 1052 begins isochronous polling on the IN endpoint and applications can proceed with
1053 1053 \fBread\fR(2) of the data on the isochronous-IN endpoint. Upon successful
1054 1054 return of \fBread\fR(2), isochronous packet descriptors (whose
1055 1055 \fBdsc_isoc_pkt_actual_len\fR and \fBdsc_isoc_pkt_status\fR fields were filled
1056 1056 by the driver) are returned, followed by the request's device payload data.
1057 1057 .sp
1058 1058 .LP
1059 1059 Applications should continuously check for and consume isochronous data. The
1060 1060 \fBugen\fR driver enables buffering of up to eight seconds of incoming data for
1061 1061 full-speed isochronous endpoint, one second of data for high-speed isochronous
1062 1062 endpoints who request one transaction per microframe and 1/3 of a second of
1063 1063 incoming data for high-speed high-bandwidth isochronous endpoints who request
1064 1064 three transactions per microframe. In case of buffer overflow, \fBugen\fR
1065 1065 discards the oldest data.
1066 1066 .sp
1067 1067 .LP
1068 1068 The isochronous-IN polling can only be stopped by a \fBclose\fR(2) associated
1069 1069 file descriptor. If applications want to change packet information, they must
1070 1070 first \fBclose\fR(2) the endpoint to stop the isochronous-IN polling, then
1071 1071 \fBopen\fR(2) the endpoint and \fBwrite\fR(2) new packets request.
1072 1072 .sp
1073 1073 .LP
1074 1074 The following example shows how to read an isochronous-IN endpoint:
1075 1075 .sp
1076 1076 .in +2
1077 1077 .nf
1078 1078 #include <sys/usb/clients/ugen/usb_ugen.h>
1079 1079
1080 1080 char *buf, *p;
1081 1081 ushort_t pktlen;
1082 1082 int pktcnt, i;
1083 1083 int len;
1084 1084 ugen_isoc_req_head_t *req;
1085 1085 ugen_isoc_pkt_descr_t *pktdesc;
1086 1086 char rdbuf[5000];
1087 1087
1088 1088 pktcnt = 4; /* 4 packets in this request */
1089 1089
1090 1090 len = sizeof(int) +
1091 1091 sizeof(ugen_isoc_pkt_descr_t) * pktcount;
1092 1092
1093 1093 buf = malloc(len);
1094 1094 if (!buf) {
1095 1095 /* Error recovery. */
1096 1096 }
1097 1097
1098 1098 req = (ugen_isoc_req_head_t *)buf;
1099 1099 req->req_isoc_pkts_count = pktcnt;
1100 1100
1101 1101 pktdesc = (ugen_isoc_pkt_descr_t *)
1102 1102 (req->req_isoc_pkt_descrs);
1103 1103
1104 1104 for (i = 0; i < pktcnt; i++) {
1105 1105 /*
1106 1106 * pktlen should not exceed xfer
1107 1107 * capability of an endpoint
1108 1108 */
1109 1109 pktdesc[i].dsc_isoc_pkt_len = pktlen;
1110 1110
1111 1111 pktdesc[i].dsc_isoc_pkt_actual_len = 0;
1112 1112 pktdesc[i].dsc_isoc_pkt_status = 0;
1113 1113 }
1114 1114
1115 1115 /*
1116 1116 * write request info to driver and len must
1117 1117 * be exactly the sum of
1118 1118 * sizeof(int) + sizeof(ugen_isoc_pkt_descr_t) * pktcnt.
1119 1119 * Otherwise, an error is returned.
1120 1120 */
1121 1121 if (write(fd, buf, len) < 0) {
1122 1122 /* Error recovery. */
1123 1123 }
1124 1124
1125 1125 /*
1126 1126 * Read length should be sum of all pkt descriptors
1127 1127 * length + payload data length of all pkts
1128 1128 * (sizeof(ugen_isoc_pkt_descr_t) + pktlen) * pktcnt
1129 1129 */
1130 1130 if (read(fd, rdbuf, (sizeof(ugen_isoc_pkt_descr_t) +
1131 1131 pktlen) * pktcnt) < 0) {
|
↓ open down ↓ |
1115 lines elided |
↑ open up ↑ |
1132 1132 /* Error recovery. */
1133 1133 }
1134 1134
1135 1135 pktdesc = (ugen_isoc_pkt_descr_t *) rdbuf;
1136 1136
1137 1137 /* points to payload beginning */
1138 1138 p = rdbuf + pktcnt * sizeof(ugen_isoc_pkt_descr_t);
1139 1139
1140 1140 for (i = 0; i < pktcnt; i++) {
1141 1141 printf("packet %d len = %d,"
1142 - " actual_len = %d, status = 0x%x\n",
1142 + " actual_len = %d, status = 0x%x\en",
1143 1143 i, pktdesc->dsc_isoc_pkt_len,
1144 1144 pktdesc->dsc_isoc_pkt_actual_len,
1145 1145 pktdesc->dsc_isoc_pkt_status);
1146 1146
1147 1147 /* Processing data */
1148 1148
1149 1149 /*
1150 1150 * next packet data payload, do NOT use
1151 1151 * dsc_isoc_pkt_actual_len
1152 1152 */
1153 1153 p += pktdesc->dsc_isoc_pkt_len;
1154 1154
1155 1155 pktdesc++;
1156 1156 }
1157 1157 .fi
1158 1158 .in -2
1159 1159
1160 1160 .sp
1161 1161 .LP
1162 1162 For an isochronous-OUT endpoint, applications use the same packet descriptor
1163 1163 and request structures to write request information to the \fBugen\fR node.
1164 1164 Following the packet request head information is the packet payload data. Upon
1165 1165 successful return of \fBwrite\fR(2), applications can \fBread\fR(2) the same
1166 1166 \fBugen\fR file immediately to retrieve the individual packet transfer status
1167 1167 of the last request. If the application isn't concerned about the status, it
1168 1168 can omit it.
1169 1169 .sp
1170 1170 .LP
1171 1171 In the following example, an application transfers data on an isochronous-OUT
1172 1172 endpoint:
1173 1173 .sp
1174 1174 .in +2
1175 1175 .nf
1176 1176 #include <sys/usb/clients/ugen/usb_ugen.h>
1177 1177 char *buf, *p;
1178 1178 ushort_t i, pktlen;
1179 1179 int len, pktcnt;
1180 1180 ugen_isoc_req_head_t *req;
1181 1181 ugen_isoc_pkt_descr_t *pktdesc;
1182 1182 char rdbuf[4096];
1183 1183
1184 1184 pktcnt = 4;
1185 1185
1186 1186 /*
1187 1187 * set packet length to a proper value, don't
1188 1188 * exceed endpoint's capability
1189 1189 */
1190 1190 pktlen = 1024;
1191 1191
1192 1192 len = sizeof(int) +
1193 1193 sizeof(ugen_isoc_pkt_descr_t) * pktcount;
1194 1194
1195 1195 len += pktlen * pktcnt;
1196 1196
1197 1197 buf = malloc(len);
1198 1198 if (!buf) {
1199 1199 /* Error recovery. */
1200 1200 }
1201 1201
1202 1202 req = (ugen_isoc_req_head_t *)buf;
1203 1203 req->req_isoc_pkts_count = pktcnt;
1204 1204
1205 1205 pktdesc =
1206 1206 (ugen_isoc_pkt_descr_t *)(req->req_isoc_pkt_descrs);
1207 1207
1208 1208 for (i = 0; i < pktcnt; i++) {
1209 1209 pktdesc[i].dsc_isoc_pkt_len = pktlen;
1210 1210 pktdesc[i].dsc_isoc_pkt_actual_len = 0;
1211 1211 pktdesc[i].dsc_isoc_pkt_status = 0;
1212 1212 }
1213 1213
1214 1214 /* moving to beginning of payload data */
1215 1215 p = buf + sizeof(int) + sizeof(*pktdesc) * pktcnt;
1216 1216 for (i = 0; i < pktcnt; i++) {
1217 1217
1218 1218 /* fill in the data buffer */
1219 1219
1220 1220 p += pktlen;
1221 1221 }
1222 1222
1223 1223 /*
1224 1224 * write packet request information and data to ugen driver
1225 1225 *
1226 1226 * len should be the exact value of sizeof(int) +
1227 1227 * sizeof(ugen_isoc_pkt_descr_t) * pktcnt + payload length
1228 1228 */
1229 1229 if (write(fd, buf, len) < 0) {
1230 1230 /* Error recovery. */
1231 1231 }
1232 1232
1233 1233 /* read packet status */
1234 1234 if (read(fd, rdbuf, sizeof(*pktdesc) * pktcnt) < 0) {
1235 1235
1236 1236 /* Error recovery. */
1237 1237
1238 1238 } else {
1239 1239
1240 1240 /* Parse every packet's transfer status */
1241 1241
1242 1242 }
1243 1243 .fi
1244 1244 .in -2
1245 1245
1246 1246 .SH ERRORS
1247 1247 .sp
1248 1248 .LP
1249 1249 The following statuses are returned by endpoint status device logical names:
1250 1250 .sp
1251 1251 .ne 2
1252 1252 .na
1253 1253 \fBUSB_LC_STAT_NOERROR\fR
1254 1254 .ad
1255 1255 .sp .6
1256 1256 .RS 4n
1257 1257 No error.
1258 1258 .RE
1259 1259
1260 1260 .sp
1261 1261 .ne 2
1262 1262 .na
1263 1263 \fBUSB_LC_STAT_CRC\fR
1264 1264 .ad
1265 1265 .sp .6
1266 1266 .RS 4n
1267 1267 CRC error detected.
1268 1268 .RE
1269 1269
1270 1270 .sp
1271 1271 .ne 2
1272 1272 .na
1273 1273 \fBUSB_LC_STAT_BITSTUFFING\fR
1274 1274 .ad
1275 1275 .sp .6
1276 1276 .RS 4n
1277 1277 Bit stuffing error.
1278 1278 .RE
1279 1279
1280 1280 .sp
1281 1281 .ne 2
1282 1282 .na
1283 1283 \fBUSB_LC_STAT_DATA_TOGGLE_MM\fR
1284 1284 .ad
1285 1285 .sp .6
1286 1286 .RS 4n
1287 1287 Data toggle did not match.
1288 1288 .RE
1289 1289
1290 1290 .sp
1291 1291 .ne 2
1292 1292 .na
1293 1293 \fBUSB_LC_STAT_STALL\fR
1294 1294 .ad
1295 1295 .sp .6
1296 1296 .RS 4n
1297 1297 Endpoint returned stall.
1298 1298 .RE
1299 1299
1300 1300 .sp
1301 1301 .ne 2
1302 1302 .na
1303 1303 \fBUSB_LC_STAT_DEV_NOT_RESP\fR
1304 1304 .ad
1305 1305 .sp .6
1306 1306 .RS 4n
1307 1307 Device not responding.
1308 1308 .RE
1309 1309
1310 1310 .sp
1311 1311 .ne 2
1312 1312 .na
1313 1313 \fBUSB_LC_STAT_UNEXP_PID\fR
1314 1314 .ad
1315 1315 .sp .6
1316 1316 .RS 4n
1317 1317 Unexpected Packet Identifier (PID).
1318 1318 .RE
1319 1319
1320 1320 .sp
1321 1321 .ne 2
1322 1322 .na
1323 1323 \fBUSB_LC_STAT_PID_CHECKFAILURE\fR
1324 1324 .ad
1325 1325 .sp .6
1326 1326 .RS 4n
1327 1327 Check bits on PID failed.
1328 1328 .RE
1329 1329
1330 1330 .sp
1331 1331 .ne 2
1332 1332 .na
1333 1333 \fBUSB_LC_STAT_DATA_OVERRUN\fR
1334 1334 .ad
1335 1335 .sp .6
1336 1336 .RS 4n
1337 1337 Data overrun.
1338 1338 .RE
1339 1339
1340 1340 .sp
1341 1341 .ne 2
1342 1342 .na
1343 1343 \fBUSB_LC_STAT_DATA_UNDERRUN\fR
1344 1344 .ad
1345 1345 .sp .6
1346 1346 .RS 4n
1347 1347 Data underrun.
1348 1348 .RE
1349 1349
1350 1350 .sp
1351 1351 .ne 2
1352 1352 .na
1353 1353 \fBUSB_LC_STAT_BUFFER_OVERRUN\fR
1354 1354 .ad
1355 1355 .sp .6
1356 1356 .RS 4n
1357 1357 Buffer overrun.
1358 1358 .RE
1359 1359
1360 1360 .sp
1361 1361 .ne 2
1362 1362 .na
1363 1363 \fBUSB_LC_STAT_BUFFER_UNDERRUN\fR
1364 1364 .ad
1365 1365 .sp .6
1366 1366 .RS 4n
1367 1367 Buffer underrun.
1368 1368 .RE
1369 1369
1370 1370 .sp
1371 1371 .ne 2
1372 1372 .na
1373 1373 \fBUSB_LC_STAT_TIMEOUT\fR
1374 1374 .ad
1375 1375 .sp .6
1376 1376 .RS 4n
1377 1377 Command timed out.
1378 1378 .RE
1379 1379
1380 1380 .sp
1381 1381 .ne 2
1382 1382 .na
1383 1383 \fBUSB_LC_STAT_NOT_ACCESSED\fR
1384 1384 .ad
1385 1385 .sp .6
1386 1386 .RS 4n
1387 1387 Not accessed by the hardware.
1388 1388 .RE
1389 1389
1390 1390 .sp
1391 1391 .ne 2
1392 1392 .na
1393 1393 \fBUSB_LC_STAT_UNSPECIFIED_ERR\fR
1394 1394 .ad
1395 1395 .sp .6
1396 1396 .RS 4n
1397 1397 Unspecified USBA or HCD error.
1398 1398 .RE
1399 1399
1400 1400 .sp
1401 1401 .ne 2
1402 1402 .na
1403 1403 \fBUSB_LC_STAT_NO_BANDWIDTH\fR
1404 1404 .ad
1405 1405 .sp .6
1406 1406 .RS 4n
1407 1407 No bandwidth available.
1408 1408 .RE
1409 1409
1410 1410 .sp
1411 1411 .ne 2
1412 1412 .na
1413 1413 \fBUSB_LC_STAT_HW_ERR\fR
1414 1414 .ad
1415 1415 .sp .6
1416 1416 .RS 4n
1417 1417 Host Controller h/w error.
1418 1418 .RE
1419 1419
1420 1420 .sp
1421 1421 .ne 2
1422 1422 .na
1423 1423 \fBUSB_LC_STAT_SUSPENDED\fR
1424 1424 .ad
1425 1425 .sp .6
1426 1426 .RS 4n
1427 1427 Device was suspended.
1428 1428 .RE
1429 1429
1430 1430 .sp
1431 1431 .ne 2
1432 1432 .na
1433 1433 \fBUSB_LC_STAT_DISCONNECTED\fR
1434 1434 .ad
1435 1435 .sp .6
1436 1436 .RS 4n
1437 1437 Device was disconnected.
1438 1438 .RE
1439 1439
1440 1440 .sp
1441 1441 .ne 2
1442 1442 .na
1443 1443 \fBUSB_LC_STAT_INTR_BUF_FULL\fR
1444 1444 .ad
1445 1445 .sp .6
1446 1446 .RS 4n
1447 1447 Polling was stopped as the interrupt-IN data buffer was full. Buffer is now
1448 1448 empty and polling has been resumed.
1449 1449 .RE
1450 1450
1451 1451 .sp
1452 1452 .ne 2
1453 1453 .na
1454 1454 \fBUSB_LC_STAT_INTERRUPTED\fR
1455 1455 .ad
1456 1456 .sp .6
1457 1457 .RS 4n
1458 1458 Request was interrupted.
1459 1459 .RE
1460 1460
1461 1461 .sp
1462 1462 .ne 2
1463 1463 .na
1464 1464 \fBUSB_LC_STAT_NO_RESOURCES\fR
1465 1465 .ad
1466 1466 .sp .6
1467 1467 .RS 4n
1468 1468 No resources available for request.
1469 1469 .RE
1470 1470
1471 1471 .sp
1472 1472 .ne 2
1473 1473 .na
1474 1474 \fBUSB_LC_STAT_INTR_POLLING_FAILED\fR
1475 1475 .ad
1476 1476 .sp .6
1477 1477 .RS 4n
1478 1478 Failed to restart polling.
1479 1479 .RE
1480 1480
1481 1481 .sp
1482 1482 .ne 2
1483 1483 .na
1484 1484 \fBUSB_LC_STAT_ISOC_POLLING_FAILED\fR
1485 1485 .ad
1486 1486 .sp .6
1487 1487 .RS 4n
1488 1488 Failed to start isochronous polling.
1489 1489 .RE
1490 1490
1491 1491 .sp
1492 1492 .ne 2
1493 1493 .na
1494 1494 \fBUSB_LC_STAT_ISOC_UNINITIALIZED\fR
1495 1495 .ad
1496 1496 .sp .6
1497 1497 .RS 4n
1498 1498 Isochronous packet information not initialized.
1499 1499 .RE
1500 1500
1501 1501 .sp
1502 1502 .ne 2
1503 1503 .na
1504 1504 \fBUSB_LC_STAT_ISOC_PKT_ERROR\fR
1505 1505 .ad
1506 1506 .sp .6
1507 1507 .RS 4n
1508 1508 All packets in this isochronous request have errors. The polling on this
1509 1509 isochronous-IN endpoint is suspended and can be resumed on next \fBread\fR(2).
1510 1510 .RE
1511 1511
1512 1512 .sp
1513 1513 .LP
1514 1514 The following system call \fBerrno\fR values are returned:
1515 1515 .sp
1516 1516 .ne 2
1517 1517 .na
1518 1518 \fB\fBEINVAL\fR\fR
1519 1519 .ad
1520 1520 .RS 11n
1521 1521 An attempt was made to enable or disable "one transfer" mode while the
1522 1522 associated endpoint was open.
1523 1523 .RE
1524 1524
1525 1525 .sp
1526 1526 .ne 2
1527 1527 .na
1528 1528 \fB\fBEBUSY\fR\fR
1529 1529 .ad
1530 1530 .RS 11n
1531 1531 The endpoint has been opened and another open is attempted.
1532 1532 .RE
1533 1533
1534 1534 .sp
1535 1535 .ne 2
1536 1536 .na
1537 1537 \fB\fBEACCES\fR\fR
1538 1538 .ad
1539 1539 .RS 11n
1540 1540 An endpoint open was attempted with incorrect flags.
1541 1541 .RE
1542 1542
1543 1543 .sp
1544 1544 .ne 2
1545 1545 .na
1546 1546 \fB\fBENOTSUP\fR\fR
1547 1547 .ad
1548 1548 .RS 11n
1549 1549 Operation not supported.
1550 1550 .RE
1551 1551
1552 1552 .sp
1553 1553 .ne 2
1554 1554 .na
1555 1555 \fB\fBENXIO\fR\fR
1556 1556 .ad
1557 1557 .RS 11n
1558 1558 Device associated with the file descriptor does not exist.
1559 1559 .RE
1560 1560
1561 1561 .sp
1562 1562 .ne 2
1563 1563 .na
1564 1564 \fBENODEV\fR
1565 1565 .ad
1566 1566 .RS 11n
1567 1567 Device has been hot-removed or a suspend/resume happened before this command.
1568 1568 .RE
1569 1569
1570 1570 .sp
1571 1571 .ne 2
1572 1572 .na
1573 1573 \fBEIO\fR
1574 1574 .ad
1575 1575 .RS 11n
1576 1576 An I/O error occurred. Send a read on the endpoint status minor node to get the
1577 1577 exact error information.
1578 1578 .RE
1579 1579
1580 1580 .sp
1581 1581 .ne 2
1582 1582 .na
1583 1583 \fBEINTR\fR
1584 1584 .ad
1585 1585 .RS 11n
1586 1586 Interrupted system call.
1587 1587 .RE
1588 1588
1589 1589 .sp
1590 1590 .ne 2
1591 1591 .na
1592 1592 \fBENOMEM\fR
1593 1593 .ad
1594 1594 .RS 11n
1595 1595 No memory for the allocation of internal structures.
1596 1596 .RE
1597 1597
1598 1598 .SH FILES
1599 1599 .sp
1600 1600 .in +2
1601 1601 .nf
1602 1602 /kernel/drv/ugen 32 bit ELF kernel module (x86 platform only)
1603 1603 /kernel/drv/sparcv9/ugen 64 bit ELF kernel module
1604 1604
1605 1605 /dev/usb/<vid>.<pid>/<N>/cntrl0
1606 1606 /dev/usb/<vid>.<pid>/<N>/cntrl0stat
1607 1607
1608 1608 /dev/usb/<vid>.<pid>/<N>/if<interface#>
1609 1609 <in|out|cntrl><endpoint#>
1610 1610 /dev/usb/<vid>.<pid>/<N>/if<interface#>
1611 1611 <in|out|cntrl><endpoint#>stat
1612 1612
1613 1613 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
1614 1614 <alternate><in|out|cntrl<endpoint#>
1615 1615 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
1616 1616 <alternate><in|out|cntrl><endpoint#>stat
1617 1617
1618 1618 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
1619 1619 <in|out|cntrl><endpoint#>
1620 1620 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
1621 1621 <in|out|cntrl<endpoint#stat>
1622 1622
1623 1623 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
1624 1624 <alternate><in|out|cntrl><endpoint#>
1625 1625 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
1626 1626 <alternate><in|out|cntrl><endpoint#>stat
1627 1627
1628 1628
1629 1629 /dev/usb/<vid>.<pid>/<N>/devstat
1630 1630
1631 1631 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0
1632 1632 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0stat
1633 1633 .fi
1634 1634 .in -2
1635 1635
1636 1636 .sp
1637 1637 .LP
1638 1638 where \fIN\fR is an integer representing the instance number of this type of
1639 1639 device. (All logical device names for a single device share the same \fIN\fR.)
1640 1640 .SH ATTRIBUTES
1641 1641 .sp
1642 1642 .LP
1643 1643 See \fBattributes\fR(5) for descriptions of the following attributes:
1644 1644 .sp
1645 1645
1646 1646 .sp
1647 1647 .TS
1648 1648 box;
1649 1649 c | c
1650 1650 l | l .
1651 1651 ATTRIBUTE TYPE ATTRIBUTE VALUE
1652 1652 _
1653 1653 Architecture PCI-based SPARC
1654 1654 .TE
1655 1655
1656 1656 .SH SEE ALSO
1657 1657 .sp
1658 1658 .LP
1659 1659 \fBlibusb\fR(3LIB), \fBclose\fR(2), \fBpoll\fR(2), \fBread\fR(2),
1660 1660 \fBwrite\fR(2), \fBaioread\fR(3C), \fBaiowrite\fR(3C), \fBusba\fR(7D),
1661 1661 \fBusb_dev_descr\fR(9S).
1662 1662 .SH DIAGNOSTICS
1663 1663 .sp
1664 1664 .LP
1665 1665 In addition to being logged, the following messages may appear on the system
1666 1666 console. All messages are formatted in the following manner:
1667 1667 .sp
1668 1668 .in +2
1669 1669 .nf
1670 1670 Warning: <device path> (ugen<instance num>): Error Message...
1671 1671 .fi
1672 1672 .in -2
1673 1673 .sp
1674 1674
1675 1675 .sp
1676 1676 .ne 2
1677 1677 .na
1678 1678 \fBToo many minor nodes. \fR
1679 1679 .ad
1680 1680 .sp .6
1681 1681 .RS 4n
1682 1682 Device has too many minor nodes. Not all are available.
1683 1683 .RE
1684 1684
1685 1685 .sp
1686 1686 .ne 2
1687 1687 .na
1688 1688 \fBInstance number too high (<\fInumber\fR>).\fR
1689 1689 .ad
1690 1690 .sp .6
1691 1691 .RS 4n
1692 1692 Too many devices are using this driver.
1693 1693 .RE
1694 1694
1695 1695 .sp
1696 1696 .ne 2
1697 1697 .na
1698 1698 \fBCannot access <device>. Please reconnect.\fR
1699 1699 .ad
1700 1700 .sp .6
1701 1701 .RS 4n
1702 1702 This device has been disconnected because a device other than the original one
1703 1703 has been inserted. The driver informs you of this fact by displaying the name
1704 1704 of the original device.
1705 1705 .RE
1706 1706
1707 1707 .sp
1708 1708 .ne 2
1709 1709 .na
1710 1710 \fBDevice is not identical to the previous one on this port. Please disconnect
1711 1711 and reconnect.\fR
1712 1712 .ad
1713 1713 .sp .6
1714 1714 .RS 4n
1715 1715 Same condition as described above; however in this case, the driver is unable
1716 1716 to identify the original device with a name string.
1717 1717 .RE
1718 1718
1719 1719 .SH NOTES
1720 1720 .sp
1721 1721 .LP
1722 1722 \fBugen\fR returns \fB-1\fR for all commands and sets \fBerrno\fR to
1723 1723 \fBENODEV\fR when device has been hot-removed or resumed from a suspend. The
1724 1724 application must close and reopen all open minor nodes to reinstate successful
1725 1725 communication.
|
↓ open down ↓ |
573 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX