1ugen(7D) Devices ugen(7D)
2
6 ugen - USB generic driver
7
9 Node Name@unit-address
10 #include <sys/usb/clients/ugen/usb_ugen.h>
13
16 ugen is a generic USBA (Solaris USB Architecture) compliant client
17 character driver that presents USB devices to applications through a
18 standard open(2), close(2), read(2), write(2), aioread(3C),
19 aiowrite(3C) Unix interface. Uninterpreted raw data are transfered to
20 and from the device via file descriptors created for each USB endpoint.
21 Status is obtained by reading file descriptors created for endpoint and
22 full device status.
23 ugen supports control, bulk, isochronous and interrupt (in and out)
26 transfers. libusb(3LIB) uses ugen to access devices that do not contain
27 drivers (such as digital cameras and PDAs). Refer to
28 /usr/sfw/share/doc/libusb/libusb.txt for details.
29
31 In general, no explicit binding of the ugen driver is necessary because
32 usb_mid(7D) is the default driver for devices without a class or vendor
33 unique driver. usb_mid(7D) creates the same logical device names as
34 ugen, but only if no child interfaces are explicitly bound to ugen. If
35 it is necessary to bind ugen explicitly to a device or interface, the
36 following section explains the necessary steps.
37 ugen can bind to a device with one or more interfaces in its entirety,
40 or to a single interface of that device. The binding type depends on
41 information that is passed to add_drv(1M) or update_drv(1M).
42 An add_drv(1M) command binds ugen to a list of device types it is to
45 control. update_drv(1M) adds an additional device type to the list of
46 device types being managed by the driver.
47 Names used to bind drivers can be found in /var/adm/messages. When a
50 device is on-lined after hot insertion, and no driver is found, there
51 will be an entry containing:
52 USB 2.0 device (usb<vid>,<pid>)...
54 where vid is the USB vendor identifier in hex and pid is the product
58 identifier in hex supplied by the device descriptor usb_dev_descr(9S).
59 When using ugen for the first time, you must add the driver utilizing
62 add_drv(1M), using a command of the following form:
63 Assuming that the vid is 472 and pid is b0b0:
65 add_drv -n -m '* <device perms> <owner> <group>'
67 -i '"usb472,b0b0"' ugen
68 If the command fails with:
72 (ugen) already in use as a driver or alias.
74 ...add the device using update_drv(1M):
78 update_drv -a -m '* <device perms> <owner> <group>'
80 -i '"usb472,b0b0"' ugen
81 This binds ugen to the entire device.
85 If ugen only binds to one interface of the device, use the following
88 driver_alias instead of usb<vid>,<pid>:
89 usbif<vid>,<pid>.config<cfg value>.<interface number>
91 where cfg value is the value of bConfigurationValue in the configura‐
95 tion descriptor (usb_cfg_descr(9S)). For example "usbif1234,4567.con‐
96 fig1.0."
97 Note that you can use update_drv to also remove bindings. Please see
100 update_drv(1M) for more information.
101 After a successful add_drv or update_drv, remove the device and rein‐
104 sert. Check with the prtconf(1M) -D option to determine if ugen is suc‐
105 cessfully bound to the device and the nodes created in
106 /dev/usb/<vid>.<pid> (see below).
107 An example showing how to bind a child device representing interface 0
110 of configuration 1 of a composite device follows:
111 update_drv -a -m '* 0666 root sys'
113 -i '"usbif472,b0b0.config1.0"' ugen
114 Note that you can completely uninstall the ugen driver and delete it
118 from the system by doing:
119 pkgrm SUNWugen
121 Any pkgadd of SUNWugen after the pkgrm reactivates any pre-existing
125 ugen driver device-bindings.
126 Any pre-existing ugen driver device-bindings are preserved across oper‐
129 ating system upgrades.
130
132 For each device or child device it manages, ugen creates one logical
133 device name for device-wide status and one logical device name for end‐
134 point 0. ugen also creates logical device names for all other endpoints
135 within the device node's binding scope (interface or device), plus log‐
136 ical device names for their status.
137 If separate ugen instances control different interfaces of the same
140 device, the device-wide status and endpoint logical device names cre‐
141 ated for each instance will share access to the same source or endpoint
142 pipes. For example, a device with two interfaces, each operated by
143 their own ugen instance, will show endpoint0 as if0cntrl0 to the first
144 interface, and will show it as if1cntrl0 to the second interface. Both
145 of these logical device names share endpoint0. Likewise for the same
146 device, ugen makes the device-wide status available as if0devstat to
147 the first interface and as if1devstat to the second interface. if0devs‐
148 tat and if1devstat both return the same data.
149 Any ugen logical device name can be held open by only one user at a
152 time, regardless of whether the O_EXCL flag passed to open(2). When a
153 single pipe or data source is shared by multiple logical device names,
154 such as if[0,1]cntrl0 or if[0,1]devstat above, more than one logical
155 device name sharing the pipe or data source can be open at a time.
156 However, only one user may access the shared pipe or data source at a
157 time, regardless of the logical device name used for access.
158 When ugen is bound to an entire device, the following logical device
161 names are created (each on a single line). N represents the instance
162 number of the device type.
163 Endpoint 0 (default endpoint):
165 /dev/usb/<vid>.<pid>/<N>/cntrl0
167 /dev/usb/<vid>.<pid>/<N>/cntrl0stat
168 For example:
170 /dev/usb/472.b0b0/0/cntrl0
172 /dev/usb/472.b0b0/0/cntrl0stat
173 Configuration index 1, Endpoints > 0, alternate 0:
175 /dev/usb/<vid>.<pid>/<N>/if<interface#>
177 <in|out|cntrl><endpoint#>
178 /dev/usb/<vid>.<pid>/<N>/if<interface#>
179 <in|out|cntrl><endpoint#>stat
180 For example:
182 /dev/usb/472.b0b0/0/if0in1
184 /dev/usb/472.b0b0/0/if0in1stat
185 Configuration index 1, Endpoints > 0, alternate > 0:
187 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
189 <alternate><in|out|cntrl><endpoint#>
190 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
191 <alternate<in|out|cntrl><endpoint#>stat
192 For example:
194 /dev/usb/472.b0b0/0/if0.1in3
196 /dev/usb/472.b0b0/0/if0.1in3stat
197 Configuration index> 1, Endpoints > 0, alternate 0:
199 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
200 <in|out|cntrl><endpoint#>
201 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
202 <in|out|cntrl><endpoint#>stat
203 For example:
205 /dev/usb/472.b0b0/0/cfg2if0in1
207 /dev/usb/472.b0b0/0/cfg2if0in1stat
208 Note that the configuration value from the configuration
210 descriptor indexed by the configuration index is used in
211 the node name and not the configuration index itself.
212 Configuration index> 1, Endpoints > 0, alternate > 0:
214 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
215 <alternate<in|out|cntrl><endpoint#>
216 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
217 <alternate<in|out|cntrl><endpoint#>stat
218 For example:
220 /dev/usb/472.b0b0/0/cfg2if0.1in1
222 /dev/usb/472.b0b0/0/cfg2if0.1in1stat
223 Device status:
225 /dev/usb/<vid>.<pid>/<N>/devstat
227 For example:
229 /dev/usb/472.b0b0/0/devstat
231 When ugen is bound to a single device interface, the following logical
235 device nodes are created:
236 Endpoint 0 (default endpoint):
238 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0
240 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0stat
241 For example:
243 /dev/usb/472.b0b0/0/if0cntrl0
245 /dev/usb/472.b0b0/0/if0cntrl0stat
246 Device status:
248 /dev/usb/<vid>.<pid>/<N>/if<interface#>devstat
249 For example:
251 /dev/usb/472.b0b0/0/if0devstat
252 The format for all other logical device names is identical to the for‐
256 mat used when ugen is bound to the entire device.
257 Opening the endpoint of a different configuration or different alter‐
260 nate interface will cause an implicit change of configuration or a
261 switch to an alternate interface. A configuration change is prohibited
262 when any non-zero endpoint device nodes are open. An alternate inter‐
263 face switch is prohibited if any endpoint in the same interface is
264 open.
265
267 A device may be hot-removed at any time. Following hot-removal, the
268 device status changes to USB_DEV_STAT_DISCONNECTED, the status of open
269 endpoints change to USB_LC_STAT_DISCONNECTED upon their access, and all
270 subsequent transfer requests fail. Endpoints are reactivated by first
271 reinserting the device and then closing and reopening all endpoints
272 that were open when the device was disconnected.
273
275 CPR (Checkpoint/Resume) may be initiated at any time and is treated
276 similarly to a hot-removal. Upon successful suspend and resume, all
277 subsequent transfer requests fail as an indication to the application
278 to reinitialize. Applications should close and reopen all endpoints to
279 reinstate them. All endpoint and device status on Resume (before close
280 and reopen) is USB_LC_STAT_SUSPENDED. A system suspend will fail while
281 ugen is performing a transfer.
282
284 Devices which support remote wakeup can be power managed when they have
285 no open logical device nodes. When an application opens the first logi‐
286 cal device node of a device, that application should assume that a
287 reinitialization of device state is required.
288
290 Applications can monitor device status changes by reading the device
291 status from the device status logical name. When opened without O_NON‐
292 BLOCK and O_NDELAY, all reads from that file descriptor (with the
293 exception of the the intial read that follows the open) block until a
294 device status change occurs. Calls to read will always return immedi‐
295 ately if opened with O_NONBLOCK or O_NDELAY. Nonblocking calls to read
296 which have no data to return, return no error and zero bytes read.
297 Device statuses are:
300 USB_DEV_STAT_ONLINE Device is available.
302 USB_DEV_STAT_DISCONNECTED Device has been disconnected.
305 USB_DEV_STAT_RESUMED Device has been resumed, however, end‐
308 points which were open on suspend have not
309 yet been closed and reopened.
310 USB_DEV_STAT_UNAVAILABLE Device has been reconnected, however, end‐
313 points which were open on disconnect have
314 not yet been closed and reopened.
315 The following code reads the device status device logical name:
319 int fd;
321 int status;
322 if ((fd = open("/dev/usb/472.b0b0/0/devstat",
324 O_RDONLY)) < 0) {
325 /* handle error */
326 }
327 if (read(fd, &status, sizeof(status)) != sizeof(status)) {
329 /* handle error */
330 }
331 switch (status) {
333 case USB_DEV_STAT_DISCONNECTED:
334 printf ("Terminating as device has been disconnected.\n");
335 exit (0);
336 case USB_DEV_STAT_RESUMED:
338 case USB_DEV_STAT_UNAVAILABLE:
339 /*
340 * Close and reopen endpoints to reestablish device access,
341 * then reset device.
342 */
343 break;
344 case USB_DEV_STAT_ONLINE:
346 default:
347 break;
348 }
349 Use poll(2) to block on several logical names simultaneously, including
353 device status logical names. Poll indicates when reading a logical
354 name would return data. See poll(2) for details. Calls to read may be
355 done whether or not they follow calls to poll.
356
358 Each data endpoint has a corresponding status logical name. Use the
359 status logical name to retrieve the state of the data endpoint, includ‐
360 ing detail on how its most recent transfer failed. Reads of the status
361 file descriptors always return immediately. See the ERRORS section for
362 more information on endpoint status values. All logical device name
363 files created for returning status must be opened with O_RDONLY.
364 The following code illustrates reading the status file descriptor of an
367 endpoint which just failed a data transfer in order to get more infor‐
368 mation on the failure.
369 int data_xfered, status;
371 int ep1_data_fd, ep1_stat_fd;
372 uchar_t request[8];
373 ep1_data_fd = open ("/dev/usb/472.b0b0/0/if0out1", O_WRONLY);
375 if (ep1_data_fd < 0) {
377 /* Handle open error. */
378 }
379 ep1_stat_fd = open ("/dev/usb/472.b0b0/0/if0out1stat",
381 O_RDONLY);
382 if (ep1_stat_fd < 0) {
383 /* Handle open error. */
384 }
385 data_xfered = write(ep1_data_fd, request, sizeof (request));
387 /* An error occured during the data transfer. */
389 if (data_xfered != sizeof (request)) {
390 /* Read status file descriptor for details on failure. */
392 if (read(ep1_stat_fd, (int *)&status, sizeof (status)) !=
393 sizeof (status)) {
394 status = USB_LC_STAT_UNSPECIFIED_ERR;
395 }
396 /* Take appropriate action. */
398 switch (status) {
399 case USB_LC_STAT_STALL:
400 printf ("Endpoint stalled.\n");
401 break;
402 case ...
403 ...
404 }
405 }
407
410 The control endpoint is typically used to set up the device and to
411 query device status or configuration.
412 Applications requiring I/O on a control endpoint should open the corre‐
415 sponding logical device name and use regular UNIX I/O system calls. For
416 example: read(2), write(2), aioread(3C) and aiowrite(3C). poll(2) is
417 not supported on control endpoints.
418 A control endpoint must be opened with O_RDWR since it is bidirec‐
421 tional. It cannot be opened with O_NONBLOCK or O_NDELAY.
422 For example:
425 fd = open("/dev/usb/472.b0b0/0/cntrl0", O_RDWR);
427 fdstat = open("/dev/usb/472.b0b0/0/cntrl0stat", O_RDONLY);
431 Control endpoints can be read and written. A read operation receives
435 data from the device and a write operation sends data to the device.
436 To perform a control-IN transfer, perform a write(2) of USB setup data
439 (see section 9.3 of the USB 1.1 or 2.0 specifications) followed by a
440 read(2) on the same control endpoint to fetch the desired data. For
441 example:
442 void init_cntrl_req(
444 uchar_t *req, uchar_t bmRequestType, uchar_t bRequest,
445 ushort_t wValue, ushort_t wIndex, ushort_t wLength) {
446 req[0] = bmRequestType;
447 req[1] = bRequest;
448 req[2] = 0xFF & wValue;
449 req[3] = 0xFF & (wValue >> 8);
450 req[4] = 0xFF & wIndex;
451 req[5] = 0xFF & (wIndex >> 8);
452 req[6] = 0xFF & wLength;
453 req[7] = 0xFF & (wLength >> 8);
454 }
455 ....
457 uchar_t dev_descr_req[8];
460 usb_dev_descr_t descr;
461 init_cntrl_req(dev_descr_req,
463 USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
464 USB_DESCR_TYPE_SETUP_DEV, 0, sizeof (descr));
465 count = write(fd, dev_descr_req, sizeof (dev_descr_req));
467 if (count != sizeof (dev_descr_req)) {
468 /* do some error recovery */
469 ...
470 }
471 count = read(fd, &descr, sizeof (descr));
473 if (count != sizeof (descr)) {
474 /* do some error recovery */
475 }
476 The application can issue any number of reads to read data received on
480 a control endpoint. ugen successfully completes all reads, returning
481 the number of bytes transferred. Zero is returned when there is no data
482 to transfer.
483 If the read/write fails and returns -1, you can access the endpoint's
486 status device logical name for precise error information:
487 int status;
489 count = read(fdstat, &status, sizeof (status));
491 if (count == sizeof (status)) {
492 switch (status) {
493 case USB_LC_STAT_SUSPENDED:
494 case USB_LC_STAT_DISCONNECTED:
495 /* close all endpoints */
496 ...
497 break;
498 default:
499 ...
500 break;
501 }
502 }
503 Refer to the ERRORS section for all possible error values.
507 To perform a control-OUT transfer, send in a single transfer, the USB
510 setup data followed by any accompanying data bytes.
511 /* 1st 8 bytes of wbuf are setup. */
513 init_cntrl_req(wbuf, .......);
514 /* Data bytes begin at byte 8 of wbuf. */
516 bcopy(data, &wuf[8], sizeof (data));
517 /* Send it all in a single transfer. */
519 count = write(fd, wbuf, sizeof (wbuf));
520 A write(2) returns the number of bytes (both setup and data) actually
524 transferred, (whether or not the write is completely successful), pro‐
525 vided that some data is actually transferred. When no data is trans‐
526 ferred, write(2) returns -1. Applications can read the corresponding
527 endpoint status to retrieve detailed error information. Note that it is
528 an error to specify a size different than:
529 (number of data bytes + number of setup bytes).
532 Here is a more extensive example which gets all descriptors of a device
535 configuration. For sake of brevity, uninteresting parts are omitted.
536 #include <sys/usb/usba.h>
538 #include <sys/usb/clients/ugen/usb_ugen.h>
539 uchar_t *config_cloud;
541 uchar_t *curr_descr;
542 uchar_t *bytes;
544 int curr_descr_len;
546 int curr_descr_type;
547 usb_cfg_descr_t cfg_descr;
549 usb_if_descr_t if_descr;
550 usb_ep_descr_t ep_descr;
551 /* See 9.13 of USB 2.0 spec for ordering. */
553 static char *pipetypes[] = {
554 "Control", "Isochronous", "Bulk", "Interrupt"
555 };
556 /*
558 * Setup to send a request to read just the config descriptor. The
559 * size of the whole cloud, containing all cfg, interface, endpoint,
560 * class and vendor-specific descriptors, will be returned as part of
561 * the config descriptor.
562 */
563 init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
564 USB_DESCR_TYPE_SETUP_CFG, 0, USB_CFG_DESCR_SIZE);
565 /*
567 * Write setup data. USB device will prepare to return the whole
568 * config cloud as a response to this. We will read this separately.
569 */
570 count = write(ctrl_fd, &setup_data, sizeof (setup_data));
571 if (count != sizeof (setup_data)) {
572 /* Error recovery. */
573 } else {
574 count = read(ctrl_fd, &cfg_descr, USB_CFG_DESCR_SIZE);
575 if (count != USB_CFG_DESCR_SIZE) {
576 /* Error recovery. */
577 }
578 }
579 /* USB data is little endian. */
581 bytes = (uchar_t *)(&cfg_descr.wTotalLength);
582 totalLength = bytes[0] + (bytes[1] << 8);
583 /*
585 * The size of the whole cloud is in the bLength field. Set up
586 * to read this amount of data, to get the whole cloud.
587 */
588 config_cloud = malloc(totalLength);
589 init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
591 USB_DESCR_TYPE_SETUP_CFG, 0, totalLength);
592 count = write(ctrl_fd, &setup_data, sizeof (setup_data));
594 if (count != sizeof (setup_data)) {
595 /* Error recovery. */
596 } else {
597 count = read(ctrl_fd, config_cloud, totalLength);
598 if (count != totalLength) {
599 /* Error recovery. */
600 }
601 }
602 /* Got the data. Now loop, dumping out the descriptors found. */
604 curr_descr = config_cloud;
606 offset = 0;
607 while (offset < totalLength) {
608 /* All descr have length and type at offset 0 and 1 */
610 curr_descr_len = curr_descr[0];
611 curr_descr_type = curr_descr[1];
612 switch (curr_descr_type) {
614 case USB_DESCR_TYPE_CFG:
615 /*
617 * Copy data into separate structure, needed for
618 * proper alignment of all non char fields. Note:
619 * non-char fields of all descriptors begin on aligned
620 * boundaries. The issue is that some structures may
621 * be adjacent to others which have an odd-numbered
622 * byte size, and may thus start on an odd-numbered
623 * boundary. */
624 bcopy(curr_descr, &cfg_descr, curr_descr_len);
625 /* Remember to read any words in endian-neutral way. */
627 (void) printf("\nConfig %d found.\n",
629 cfg_descr.bConfigurationValue);
630 break;
631 case USB_DESCR_TYPE_IF:
633 bcopy(curr_descr, &if_descr, curr_descr_len);
634 (void) printf("\n\tInterface %d, Alt %d found.\n",
635 if_descr.bInterfaceNumber,
636 if_descr.bAlternateSetting);
637 break;
638 case USB_DESCR_TYPE_EP:
640 bcopy(curr_descr, &ep_descr, curr_descr_len);
641 (void) printf("\n\t\tEndpoint %d (%s-%s) found.\n",
642 (ep_descr.bEndpointAddress & USB_EP_NUM_MASK),
643 (pipetypes[
644 ep_descr.bmAttributes & USB_EP_ATTR_MASK]),
645 ((ep_descr.bEndpointAddress &
646 USB_EP_DIR_IN) ? "IN" : "OUT"));
647 break;
648 default:
650 (void) printf(
651 "\n\t\t\tOther descriptor found. Type:%d\n",
652 curr_descr_type);
653 break;
654 }
655 offset += curr_descr_len;
657 curr_descr = &config_cloud[offset];
658 }
659
662 Applications requiring data from an interrupt-IN endpoint should open
663 the corresponding logical device name and use read(2), aioread(3C) and
664 poll(2) system calls.
665 An interrupt-IN endpoint must be opened with O_RDONLY. It can also be
668 opened using O_NONBLOCK or O_NDELAY if desired.
669 fd = open("/dev/usb/472.b0b0/0/if0in1", O_RDONLY);
671 fdstat = open("/dev/usb/472.b0b0/0/if0in1stat", O_RDONLY);
674 ugen starts polling interrupt—IN endpoints immediately upon opening
679 them and stops polling them upon closure. (Polling refers to interroga‐
680 tion of the device by the driver and should not be confused with
681 poll(2), which is an interrogation of the driver by the application.)
682 A read(2) of an endpoint opened with the O_NONBLOCK or O_NDELAY flags
685 set will not block when there is insufficient data available to satisfy
686 the request. The read simply returns what it can without signifying any
687 error.
688 Applications should continuously check for and consume interrupt data.
691 ugen enables buffering of up to one second of incoming data. In case of
692 buffer overflow, ugen stops polling the interrupt-IN endpoint until the
693 application consumes all the data. In this case, a read(2) of an empty
694 buffer returns -1, sets the endpoint status to
695 USB_LC_STAT_INTR_BUF_FULL (to indicate that the buffer had been full
696 and polling had been stopped) and causes ugen to start polling the end‐
697 point again. To retrieve the status, the application can open and read
698 the corresponding endpoint's status device logical name.
699 for (;;) {
701 count = read(fd, buf, sizeof(buf));
702 if (count == -1) {
703 int cnt, status;
704 cnt = read(fdstat, &status, sizeof (status));
706 if (cnt == -1) {
707 /* more error recovery here */
708 } else {
709 switch (status) {
710 case USB_LC_STAT_INTR_BUF_FULL:
711 ...
712 break;
713 default:
714 ...
715 break;
716 }
717 }
718 }
719 /* process the data */
720 ....
721 }
722 ugen will never drop data. However, the device may drop data if the
726 application cannot read it at the rate that it is produced.
727 Applications requiring unbuffered data from an interrupt-IN endpoint
730 should open the associated status endpoint with O_RDWR before opening
731 the associated interrupt-IN endpoint and write a control byte with
732 USB_EP_INTR_ONE_XFER set. All other bits are reserved and should be 0.
733 "One transfer" mode will persist until disabled explicitly after the
736 associated interrupt-IN endpoint has been closed by writing a control
737 byte with USB_EP_INTR_ONE_XFER cleared.
738 "One transfer" mode is implicitly disabled when the status/control end‐
741 point is closed.
742 Attempts to change the "one transfer" mode while the endpoint is open
745 will result in EINVAL.
746 An application can open multiple interrupt-IN endpoints and can call
749 poll(2) to monitor the availability of new data. (Note: poll works with
750 interrupt-IN data endpoints, not their status endpoints.)
751 struct pollfd pfd[2];
753 bzero(pfd, sizeof (pfd));
755 pfd[0].fd = fd1; /* fd1 is one interrupt-IN endpoint. */
756 pfd[0].events = POLLIN;
757 pfd[1].fd = fd2; /* fd2 is another interrupt-IN endpoint. */
758 pfd[1].events = POLLIN;
759 for (;;) {
761 poll(pfd, 2, -1);
762 if (pfd[0].revents & POLLIN) {
764 count = read(fd1, buf, sizeof (buf));
765 ....
766 }
767 if (pfd[1].revents & POLLIN) {
768 count = read(fd2, buf, sizeof (buf));
769 ....
770 }
771 }
772 You can monitor the device status endpoint via poll(2) concurrently
776 with the multiple interrupt-IN endpoints. Simply add another pollfd
777 element to the pfd array in the previous code example, and initialize
778 the new element's fd field with the file descriptor of the device
779 status endpoint (opened without O_NONBLOCK or O_NDELAY). Set the new
780 element's event field to POLLIN like the other elements. Note that only
781 interrupt-IN endpoints and the device status endpoint can be monitored
782 using poll(2).
783
785 Applications requiring output on an interrupt-OUT endpoint can open the
786 corresponding logical device name and perform regular UNIX I/O sys‐
787 tem calls such as write(2) and aiowrite(3C).
788 An interrupt-OUT endpoint must be opened with O_WRONLY.
791 fd = open("/dev/usb/472.b0b0/0/if0out3", O_WRONLY);
793 fdstat = open("/dev/usb/472.b0b0/0/if0out3stat", O_RDONLY);
795 Data can be written to an interrupt-OUT endpoint as follows:
801 count = write(fd, buf, sizeof (buf)):
803 if (count == -1) {
804 /* error recovery */
805 }
806
809 Applications requiring I/O on a bulk endpoint can open the correspond‐
810 ing logical device name and perform regular UNIX I/O system calls. For
811 example: read(2), write(2), aioread(3C) and aiowrite(3C). poll(2) is
812 not supported on bulk endpoints.
813 A bulk endpoint must be opened with O_RDONLY or O_WRONLY and cannot be
816 opened with O_NONBLOCK or O_NDELAY:
817 fd = open("/dev/usb/472.b0b0/0/if0in2", O_RDONLY);
819 fdstat = open("/dev/usb/472.b0b0/0/if0in2stat", O_RDONLY);
822 Data can be read from a bulk-IN endpoint as follows:
826 count = read(fd, buf, sizeof (buf)):
828 if (count == -1) {
829 /* error recovery */
830 }
831 Data can be written to a bulk-OUT endpoint as follows:
833 count = write(fd, buf, sizeof (buf)):
835 if (count == -1) {
836 /* error recovery */
837 }
838
841 Applications requiring I/O on an isochronous endpoint can open the cor‐
842 responding logical device name and perform regular UNIX I/O system
843 calls such as read(2), write(2), poll(2), aioread(3C) and aiowrite(3C).
844 An isochronous endpoint must be opened with O_RDWR.
845 fd = open("/dev/usb/472.b0b0/0/if0.3in2", O_RDWR);
847 fdstat = open("/dev/usb/472.b0b0/0/if0.3in2stat", O_RDONLY);
849 Applications can use the status logical name to retrieve the state of
853 the isochronous data endpoint, including details on why the most recent
854 transfer failed.
855 Applications have the flexibility to specify the number of isochronous
858 packets and the size of individual packets they want to transfer.
859 Applications should use the following data structures to exchange
860 isochronous packet information with the ugen driver:
861 typedef struct ugen_isoc_pkt_descr {
863 /*
864 * Set by the application, for all isochro.
865 * requests, to the num. of bytes to xfer
866 * in a packet.
867 */
868 ushort_t dsc_isoc_pkt_len;
869 /*
871 * Set by ugen to actual num. of bytes sent/received
872 * in a packet.
873 */
874 ushort_t dsc_isoc_pkt_actual_len;
875 /*
877 * Per pkt. status set by ugen driver both for the
878 * isochronous IN and OUT requests. Application can
879 * use USB_LC_STAT_* to parse the status.
880 */
881 int dsc_isoc_pkt_status;
882 } ugen_isoc_pkt_descr_t;
883 typedef struct ugen_isoc_req_head {
885 /* pkt count of the isoc request */
886 int req_isoc_pkts_count;
887 /* pkt descriptors */
889 ugen_isoc_pkt_descr_t req_isoc_pkt_descrs[1];
890 } ugen_isoc_req_head_t;
891 req_isoc_pkts_count is limited by the capability of the USB host con‐
895 troller driver. The current upper bound for the uhci and ohci drivers
896 is 512. The upper bound for the ehci driver is 1024.
897 For an isochronous-IN endpoint, applications must first use the
900 ugen_isoc_req_head_t structure followed by ugen_isoc_pkt_descr_t to
901 write packet request information to the ugen node. The ugen driver then
902 checks the validity of the request. If it is valid, the driver immedi‐
903 ately begins isochronous polling on the IN endpoint and applications
904 can proceed with read(2) of the data on the isochronous-IN endpoint.
905 Upon successful return of read(2), isochronous packet descriptors
906 (whose dsc_isoc_pkt_actual_len and dsc_isoc_pkt_status fields were
907 filled by the driver) are returned, followed by the request's device
908 payload data.
909 Applications should continuously check for and consume isochronous
912 data. The ugen driver enables buffering of up to eight seconds of
913 incoming data for full-speed isochronous endpoint, one second of data
914 for high-speed isochronous endpoints who request one transaction per
915 microframe and 1/3 of a second of incoming data for high-speed high-
916 bandwidth isochronous endpoints who request three transactions per
917 microframe. In case of buffer overflow, ugen discards the oldest data.
918 The isochronous-IN polling can only be stopped by a close(2) associated
921 file descriptor. If applications want to change packet information,
922 they must first close(2) the endpoint to stop the isochronous-IN
923 polling, then open(2) the endpoint and write(2) new packets request.
924 The following example shows how to read an isochronous-IN endpoint:
927 #include <sys/usb/clients/ugen/usb_ugen.h>
929 char *buf, *p;
931 ushort_t pktlen;
932 int pktcnt, i;
933 int len;
934 ugen_isoc_req_head_t *req;
935 ugen_isoc_pkt_descr_t *pktdesc;
936 char rdbuf[5000];
937 pktcnt = 4; /* 4 packets in this request */
939 len = sizeof(int) +
941 sizeof(ugen_isoc_pkt_descr_t) * pktcount;
942 buf = malloc(len);
944 if (!buf) {
945 /* Error recovery. */
946 }
947 req = (ugen_isoc_req_head_t *)buf;
949 req->req_isoc_pkts_count = pktcnt;
950 pktdesc = (ugen_isoc_pkt_descr_t *)
952 (req->req_isoc_pkt_descrs);
953 for (i = 0; i < pktcnt; i++) {
955 /*
956 * pktlen should not exceed xfer
957 * capability of an endpoint
958 */
959 pktdesc[i].dsc_isoc_pkt_len = pktlen;
960 pktdesc[i].dsc_isoc_pkt_actual_len = 0;
962 pktdesc[i].dsc_isoc_pkt_status = 0;
963 }
964 /*
966 * write request info to driver and len must
967 * be exactly the sum of
968 * sizeof(int) + sizeof(ugen_isoc_pkt_descr_t) * pktcnt.
969 * Otherwise, an error is returned.
970 */
971 if (write(fd, buf, len) < 0) {
972 /* Error recovery. */
973 }
974 /*
976 * Read length should be sum of all pkt descriptors
977 * length + payload data length of all pkts
978 * (sizeof(ugen_isoc_pkt_descr_t) + pktlen) * pktcnt
979 */
980 if (read(fd, rdbuf, (sizeof(ugen_isoc_pkt_descr_t) +
981 pktlen) * pktcnt) < 0) {
982 /* Error recovery. */
983 }
984 pktdesc = (ugen_isoc_pkt_descr_t *) rdbuf;
986 /* points to payload beginning */
988 p = rdbuf + pktcnt * sizeof(ugen_isoc_pkt_descr_t);
989 for (i = 0; i < pktcnt; i++) {
991 printf("packet %d len = %d,"
992 " actual_len = %d, status = 0x%x0,
993 i, pktdesc->dsc_isoc_pkt_len,
994 pktdesc->dsc_isoc_pkt_actual_len,
995 pktdesc->dsc_isoc_pkt_status);
996 /* Processing data */
998 /*
1000 * next packet data payload, do NOT use
1001 * dsc_isoc_pkt_actual_len
1002 */
1003 p += pktdesc->dsc_isoc_pkt_len;
1004 pktdesc++;
1006 }
1007 For an isochronous-OUT endpoint, applications use the same packet
1011 descriptor and request structures to write request information to the
1012 ugen node. Following the packet request head information is the packet
1013 payload data. Upon successful return of write(2), applications can
1014 read(2) the same ugen file immediately to retrieve the individual
1015 packet transfer status of the last request. If the application isn't
1016 concerned about the status, it can omit it.
1017 In the following example, an application transfers data on an
1020 isochronous-OUT endpoint:
1021 #include <sys/usb/clients/ugen/usb_ugen.h>
1023 char *buf, *p;
1024 ushort_t i, pktlen;
1025 int len, pktcnt;
1026 ugen_isoc_req_head_t *req;
1027 ugen_isoc_pkt_descr_t *pktdesc;
1028 char rdbuf[4096];
1029 pktcnt = 4;
1031 /*
1033 * set packet length to a proper value, don't
1034 * exceed endpoint's capability
1035 */
1036 pktlen = 1024;
1037 len = sizeof(int) +
1039 sizeof(ugen_isoc_pkt_descr_t) * pktcount;
1040 len += pktlen * pktcnt;
1042 buf = malloc(len);
1044 if (!buf) {
1045 /* Error recovery. */
1046 }
1047 req = (ugen_isoc_req_head_t *)buf;
1049 req->req_isoc_pkts_count = pktcnt;
1050 pktdesc =
1052 (ugen_isoc_pkt_descr_t *)(req->req_isoc_pkt_descrs);
1053 for (i = 0; i < pktcnt; i++) {
1055 pktdesc[i].dsc_isoc_pkt_len = pktlen;
1056 pktdesc[i].dsc_isoc_pkt_actual_len = 0;
1057 pktdesc[i].dsc_isoc_pkt_status = 0;
1058 }
1059 /* moving to beginning of payload data */
1061 p = buf + sizeof(int) + sizeof(*pktdesc) * pktcnt;
1062 for (i = 0; i < pktcnt; i++) {
1063 /* fill in the data buffer */
1065 p += pktlen;
1067 }
1068 /*
1070 * write packet request information and data to ugen driver
1071 *
1072 * len should be the exact value of sizeof(int) +
1073 * sizeof(ugen_isoc_pkt_descr_t) * pktcnt + payload length
1074 */
1075 if (write(fd, buf, len) < 0) {
1076 /* Error recovery. */
1077 }
1078 /* read packet status */
1080 if (read(fd, rdbuf, sizeof(*pktdesc) * pktcnt) < 0) {
1081 /* Error recovery. */
1083 } else {
1085 /* Parse every packet's transfer status */
1087 }
1089
1092 The following statuses are returned by endpoint status device logical
1093 names:
1094 USB_LC_STAT_NOERROR
1096 No error.
1098 USB_LC_STAT_CRC
1101 CRC error detected.
1103 USB_LC_STAT_BITSTUFFING
1106 Bit stuffing error.
1108 USB_LC_STAT_DATA_TOGGLE_MM
1111 Data toggle did not match.
1113 USB_LC_STAT_STALL
1116 Endpoint returned stall.
1118 USB_LC_STAT_DEV_NOT_RESP
1121 Device not responding.
1123 USB_LC_STAT_UNEXP_PID
1126 Unexpected Packet Identifier (PID).
1128 USB_LC_STAT_PID_CHECKFAILURE
1131 Check bits on PID failed.
1133 USB_LC_STAT_DATA_OVERRUN
1136 Data overrun.
1138 USB_LC_STAT_DATA_UNDERRUN
1141 Data underrun.
1143 USB_LC_STAT_BUFFER_OVERRUN
1146 Buffer overrun.
1148 USB_LC_STAT_BUFFER_UNDERRUN
1151 Buffer underrun.
1153 USB_LC_STAT_TIMEOUT
1156 Command timed out.
1158 USB_LC_STAT_NOT_ACCESSED
1161 Not accessed by the hardware.
1163 USB_LC_STAT_UNSPECIFIED_ERR
1166 Unspecified USBA or HCD error.
1168 USB_LC_STAT_NO_BANDWIDTH
1171 No bandwidth available.
1173 USB_LC_STAT_HW_ERR
1176 Host Controller h/w error.
1178 USB_LC_STAT_SUSPENDED
1181 Device was suspended.
1183 USB_LC_STAT_DISCONNECTED
1186 Device was disconnected.
1188 USB_LC_STAT_INTR_BUF_FULL
1191 Polling was stopped as the interrupt-IN data buffer was full. Buf‐
1193 fer is now empty and polling has been resumed.
1194 USB_LC_STAT_INTERRUPTED
1197 Request was interrupted.
1199 USB_LC_STAT_NO_RESOURCES
1202 No resources available for request.
1204 USB_LC_STAT_INTR_POLLING_FAILED
1207 Failed to restart polling.
1209 USB_LC_STAT_ISOC_POLLING_FAILED
1212 Failed to start isochronous polling.
1214 USB_LC_STAT_ISOC_UNINITIALIZED
1217 Isochronous packet information not initialized.
1219 USB_LC_STAT_ISOC_PKT_ERROR
1222 All packets in this isochronous request have errors. The polling on
1224 this isochronous-IN endpoint is suspended and can be resumed on
1225 next read(2).
1226 The following system call errno values are returned:
1230 EINVAL An attempt was made to enable or disable "one transfer" mode
1232 while the associated endpoint was open.
1233 EBUSY The endpoint has been opened and another open is attempted.
1236 EACCES An endpoint open was attempted with incorrect flags.
1239 ENOTSUP Operation not supported.
1242 ENXIO Device associated with the file descriptor does not exist.
1245 ENODEV Device has been hot-removed or a suspend/resume happened
1248 before this command.
1249 EIO An I/O error occurred. Send a read on the endpoint status
1252 minor node to get the exact error information.
1253 EINTR Interrupted system call.
1256 ENOMEM No memory for the allocation of internal structures.
1259
1262 /kernel/drv/ugen 32 bit ELF kernel module (x86 platform only)
1263 /kernel/drv/sparcv9/ugen 64 bit ELF kernel module
1264 /dev/usb/<vid>.<pid>/<N>/cntrl0
1266 /dev/usb/<vid>.<pid>/<N>/cntrl0stat
1267 /dev/usb/<vid>.<pid>/<N>/if<interface#>
1269 <in|out|cntrl><endpoint#>
1270 /dev/usb/<vid>.<pid>/<N>/if<interface#>
1271 <in|out|cntrl><endpoint#>stat
1272 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
1274 <alternate><in|out|cntrl<endpoint#>
1275 /dev/usb/<vid>.<pid>/<N>/if<interface#>.
1276 <alternate><in|out|cntrl><endpoint#>stat
1277 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
1279 <in|out|cntrl><endpoint#>
1280 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>
1281 <in|out|cntrl<endpoint#stat>
1282 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
1284 <alternate><in|out|cntrl><endpoint#>
1285 /dev/usb/<vid>.<pid>/<N>/cfg<value>if<interface#>.
1286 <alternate><in|out|cntrl><endpoint#>stat
1287 /dev/usb/<vid>.<pid>/<N>/devstat
1290 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0
1292 /dev/usb/<vid>.<pid>/<N>/if<interface#>cntrl0stat
1293 where N is an integer representing the instance number of this type of
1297 device. (All logical device names for a single device share the same
1298 N.)
1299
1301 See attributes(5) for descriptions of the following attributes:
1302 ┌─────────────────────────────┬─────────────────────────────┐
1307 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
1308 ├─────────────────────────────┼─────────────────────────────┤
1309 │Architecture │PCI-based SPARC │
1310 ├─────────────────────────────┼─────────────────────────────┤
1311 │Availability │SUNWugen, SUNWugenu │
1312 └─────────────────────────────┴─────────────────────────────┘
1313
1315 libusb(3LIB), close(2), poll(2), read(2), write(2), aioread(3C),
1316 aiowrite(3C), usba(7D), usb_dev_descr(9S).
1317
1319 In addition to being logged, the following messages may appear on the
1320 system console. All messages are formatted in the following manner:
1321 Warning: <device path> (ugen<instance num>): Error Message...
1323 Too many minor nodes.
1327 Device has too many minor nodes. Not all are available.
1329 Instance number too high (<number>).
1332 Too many devices are using this driver.
1334 Cannot access <device>. Please reconnect.
1337 This device has been disconnected because a device other than the
1339 original one has been inserted. The driver informs you of this fact
1340 by displaying the name of the original device.
1341 Device is not identical to the previous one on this port. Please dis‐
1344 connect and reconnect.
1345 Same condition as described above; however in this case, the driver
1347 is unable to identify the original device with a name string.
1348
1351 ugen returns -1 for all commands and sets errno to ENODEV when device
1352 has been hot-removed or resumed from a suspend. The application must
1353 close and reopen all open minor nodes to reinstate successful communi‐
1354 cation.
1355SunOS 5.11 3 Dec 2008 ugen(7D)