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