Name

ugen– USB generic driver

Synopsis

Node Name@unit-address

#include <sys/usb/clients/ugen/usb_ugen.h>

Description

ugen
is a generic USBA (Solaris USB Architecture) compliant client character driver that presents USB devices to applications through a standard open(2), close(2), read(2), write(2), aioread(3AIO), aiowrite(3AIO) Unix interface. Uninterpreted raw data are transfered to and from the device via file descriptors created for each USB endpoint. Status is obtained by reading file descriptors created for endpoint and full device
status.

ugen supports control, bulk, and interrupt (in and out) transfers. Isochronous transfers are not supported. libusb(3LIB) uses ugen to
access devices that do not contain drivers such as digital cameras and PDAs. Refer to /usr/sfw/share/doc/libusb/libusb.txt for details

BINDING

In general, no explicit binding of the ugen driver is necessary because usb_mid(7D) is the default driver for devices without a class or vendor unique driver. usb_mid(7D) creates the same logical device names as ugen, but only if no child interfaces are explicitly bound to ugen. If it is necessary to bind ugen explicitly to a device
or interface, the following section explains the necessary steps.

ugen can bind to a device with one or more interfaces in its entirety, or to a single interface of that device. The binding type depends on information that is passed to add_drv(1M) or update_drv(1M).

An add_drv(1M) command binds ugen to a list of device types it is to control. update_drv(1M) adds an additional device type to the list of device types being managed by the driver.

Names used to bind drivers can be found in /var/adm/messages. When a device is onlined after hot insertion, and no driver is found, there will be an entry containing:

USB 2.0 device (usb<vid>,<pid>)...

where vid is the USB vendor identifier
in hex and pid is the product identifier in hex supplied by the device descriptor usb_dev_descr(9S).

When using ugen for the first time, you must add the driver utilizing add_drv(1M), using a command of the following form:

If ugen only binds to one interface of the device, use the following driver_alias instead of usb<vid>,<pid>:

usbif<vid>,<pid>.config<cfg value>.<interface number>

where cfg value is the value of bConfigurationValue in the configuration descriptor (usb_cfg_descr(9S)). For example "usbif1234,4567.config1.0."

Note that you can use update_drv to also remove bindings. Please see update_drv(1M) for more information.

After a successful add_drv or update_drv, remove the device and reinsert. Check with the prtconf(1M) -D option to determine if ugen is
successfully bound to the device and the nodes created in /dev/usb/<vid>.<pid> (see below).

An example showing how to bind a child device representing interface 0 of configuration 1 of a composite device follows:

Note that you can completely uninstall the ugen driver and delete it from the system by doing:

pkgrm SUNWugen

Any pkgadd of SUNWugen after the pkgrm reactivates any pre-existing ugen driver device-bindings.

Any pre-existing ugen driver device-bindings are preserved across operating system upgrades.

LOGICAL DEVICE NAME FORMAT

For each device or child device it manages, ugen creates one logical device name for device-wide status and one logical device name for endpoint 0. ugen also creates logical device names for all other endpoints within the device node's binding scope (interface
or device), plus logical device names for their status.

If separate ugen instances control different interfaces of the same device, the device-wide status and endpoint logical device names created for each instance will share access to the same source or endpoint pipes. For example, a device with two interfaces, each operated by their
own ugen instance, will show endpoint0 as if0cntrl0 to the first interface, and will show it as if1cntrl0 to the second interface. Both of these logical device names share endpoint0. Likewise for the same device, ugen makes the device-wide status available as if0devstat to the first interface and as if1devstat to the second interface. if0devstat and if1devstat both return the same data.

Any ugen logical device name can be held open by only one user at a time, regardless of whether the O_EXCL flag passed to open(2).
When a single pipe or data source is shared by multiple logical device names, such as if[0,1]cntrl0 or if[0,1]devstat above, more than one logical device name sharing the pipe or data source can be open at a time. However, only one user may access the shared pipe or data source at a time, regardless
of the logical device name used for access.

When ugen is bound to an entire device, the following logical device names are created (each on a single line). N represents the instance number of the device type.

The format for all other logical device names is identical to the format used when ugen is bound to the entire device.

Opening the endpoint of a different configuration or different alternate interface will cause an implicit change of configuration or a switch to an alternate interface. A configuration change is prohibited when any non-zero endpoint device nodes are open. An alternate interface switch is prohibited
if any endpoint in the same interface is open.

HOT-PLUGGING

A device may be hot-removed at any time. Following hot-removal, the device status changes to USB_DEV_STAT_DISCONNECTED, the status of open endpoints change to USB_LC_STAT_DISCONNECTED upon their access, and all subsequent transfer requests fail. Endpoints are reactivated by first reinserting the
device and then closing and reopening all endpoints that were open when the device was disconnected.

CPR (CHECKPOINT/RESUME)

CPR (Checkpoint/Resume) may be initiated at any time and is treated similarly to a hot-removal. Upon successful suspend and resume, all subsequent transfer requests fail as an indication to the application to reinitialize. Applications should close and reopen all endpoints to reinstate them. All
endpoint and device status on Resume (before close and reopen) is USB_LC_STAT_SUSPENDED. A system suspend will fail while ugen is performing a transfer.

DEVICE POWER MANAGEMENT

Devices which support remote wakeup can be power managed when they have no open logical device nodes. When an application opens the first logical device node of a device, that application should assume that a reinitialization of device state is required.

DEVICE STATUS MANAGEMENT

Applications can monitor device status changes by reading the device status from the device status logical name. When opened without O_NONBLOCK and O_NDELAY, all reads from that file descriptor (with the exception of the the intial read that follows the open) block until a device status change occurs.
Calls to read will always return immediately if opened with O_NONBLOCK or O_NDELAY. Nonblocking calls to read which have no data to return, return no error and zero bytes read.

Device statuses are:

USB_DEV_STAT_ONLINE

Device is available.

USB_DEV_STAT_DISCONNECTED

Device has been disconnected.

USB_DEV_STAT_RESUMED

Device has been resumed, however, endpoints which were open on suspend have not yet been closed and reopened.

USB_DEV_STAT_UNAVAILABLE

Device has been reconnected, however, endpoints which were open on disconnect have not yet been closed and reopened.

Use poll(2) to block on several logical names simultaneously, including device status logical names. Poll indicates when reading a logical name would return
data. See poll(2) for details. Calls to read may be done whether or not they follow calls to poll.

ENDPOINT STATUS MANAGEMENT

Each data endpoint has a corresponding status logical name. Use the status logical name to retrieve the state of the data endpoint, including detail on how its most recent transfer failed. Reads of the status file descriptors always return immediately. See the ERRORS section for more information
on endpoint status values. All logical device name files created for returning status must be opened with O_RDONLY.

The following code illustrates reading the status file descriptor of an endpoint which just failed a data transfer in order to get more information on the failure.

CONTROL TRANSFERS

The control endpoint is typically used to set up the device and to query device status or configuration.

Applications requiring I/O on a control endpoint should open the corresponding logical device name and use regular UNIX I/O system calls. For example: read(2), write(2), aioread(3AIO) and aiowrite(3AIO). poll(2) is
not supported on control endpoints.

A control endpoint must be opened with O_RDWR since it is bidirectional. It cannot be opened with O_NONBLOCK or O_NDELAY.

For example:

fd = open("/dev/usb/472.b0b0/0/cntrl0", O_RDWR);

fdstat = open("/dev/usb/472.b0b0/0/cntrl0stat", O_RDONLY);

Control endpoints can be read and written. A read operation receives data from the device and a write operation sends data to the device.

To perform a control-IN transfer, perform a write(2) of USB setup data (see section 9.3 of the USB 1.1 or 2.0 specifications)
followed by a read(2) on the same control endpoint to fetch the desired data. For example:

The application can issue any number of reads to read data received on a control endpoint. ugen successfully completes all reads, returning the number of bytes transferred. Zero is returned when there is no data to transfer.

If the read/write fails and returns –1, you can access the endpoint's status device logical name for precise error information:

A write(2) returns the number of bytes (both setup and data) actually transferred, (whether or not the write is completely successful), provided
that some data is actually transferred. When no data is transferred, write(2) returns -1. Applications can read the corresponding endpoint
status to retrieve detailed error information. Note that it is an error to specify a size different than:

(number of data bytes + number of setup bytes).

Here is a more extensive example which gets all descriptors of a device configuration. For sake of brevity, uninteresting parts are omitted.

INTERRUPT-IN TRANSFERS

Applications requiring data from an interrupt-IN endpoint should open the corresponding logical device name and use read(2), aioread(3AIO) and poll(2) system calls.

An interrupt-IN endpoint must be opened with O_RDONLY. It can also be opened using O_NONBLOCK or O_NDELAY if desired.

fd = open("/dev/usb/472.b0b0/0/if0in1", O_RDONLY);

fdstat = open("/dev/usb/472.b0b0/0/if0in1stat", O_RDONLY);

ugen starts polling interrupt—IN endpoints immediately upon opening them and stops polling them upon closure. (Polling refers to interrogation of the device by the driver and should not be confused with poll(2), which is an interrogation of the driver by the application.)

A read(2) of an endpoint opened with the O_NONBLOCK or O_NDELAY flags set will not block when there is insufficient data
available to satisfy the request. The read simply returns what it can without signifying any error.

Applications should continuously check for and consume interrupt data. ugen enables buffering of up to one second of incoming data. In case of buffer overflow, ugen stops polling the interrupt-IN endpoint until the application consumes all the data. In this
case, a read(2) of an empty buffer returns -1, sets the endpoint status to USB_LC_STAT_INTR_BUF_FULL (to indicate that
the buffer had been full and polling had been stopped) and causes ugen to start polling the endpoint again. To retrieve the status, the application can open and read the corresponding endpoint's status device logical name.

ugen will never drop data. However, the device may drop data if the application cannot read it at the rate that it is produced.

Applications requiring unbuffered data from an interrupt-IN endpoint should open the associated status endpoint with O_RDWR before opening the associated interrupt-IN endpoint and write a control byte with USB_EP_INTR_ONE_XFER set. All other bits are reserved and should be 0.

"One transfer" mode will persist until disabled explicitly after the associated interrupt-IN endpoint has been closed by writing a control byte with USB_EP_INTR_ONE_XFER cleared.

"One transfer" mode is implicitly disabled when the status/control endpoint is closed.

Attempts to change the "one transfer" mode while the endpoint is open will result in EINVAL.

An application can open multiple interrupt-IN endpoints and can call poll(2) to monitor the availability of new data. (Note: poll works with interrupt-IN data
endpoints, not their status endpoints.)

You can monitor the device status endpoint via poll(2) concurrently with the multiple interrupt-IN endpoints. Simply add another pollfd element to the pfd array
in the previous code example, and initialize the new element's fd field with the file descriptor of the device status endpoint (opened without O_NONBLOCK or O_NDELAY). Set the new element's event field to POLLIN like the other elements. Note that only interrupt–IN endpoints
and the device status endpoint can be monitored using poll(2).

INTERRUPT-OUT TRANSFERS

Applications requiring output on an interrupt-OUT endpoint can open the corresponding logical device name and perform regular UNIX I/O system calls such as write(2)
and aiowrite(3AIO).

BULK TRANSFERS

Applications requiring I/O on a bulk endpoint can open the corresponding logical device name and perform regular UNIX I/O system calls. For example: read(2), write(2), aioread(3AIO) and aiowrite(3AIO). poll(2) is
not supported on bulk endpoints.

A bulk endpoint must be opened with O_RDONLY or O_WRONLY and cannot be opened with O_NONBLOCK or O_NDELAY:

See Also

Diagnostics

In addition to being logged, the following messages may appear on the system console. All messages are formatted in the following manner:

Warning: <device path> (ugen<instance num>): Error Message...

Too many minor nodes.

Device has too many minor nodes. Not all are available.

Instance number too high (<number>).

Too many devices are using this driver.

Cannot access <device>. Please reconnect.

This device has been disconnected because a device other than the original one has been inserted. The driver informs you of this fact by displaying the name of the original device.

Device is not identical to the previous one on this port. Please disconnect and reconnect.

Same condition as described above; however in this case, the driver is unable to identify the original device with a name string.

Notes

Isochronous transfers are not supported.

ugen returns -1 for all commands and sets errno to ENODEV when device has been hot-removed or resumed from a suspend. The application must close and reopen all open minor nodes to reinstate successful communication.