usb – USB Host Controller Interface|
bind –a #u /dev |
The Universal Serial Bus is a complex yet popular bus for connecting
all kind of devices to a computer. It is a four–wire tree–shaped
bus that provides both communication and (limited) power to devices.
Branching points in the tree are provided by devices called hubs.
Hubs provide ports where USB devices (also hubs)
can be attached. |
Most PCs have one or more USB controllers called host controllers. Each one has a built–in hub called a root hub providing several ports. In some cases, more hubs are built–in and attached to a root hub port. The topology of the network is a tree with at most 127 nodes, counting both internal and leaf nodes.
Host controllers come in four flavours: UHCI and OHCI for USB 1 (up to 12 Mb/s), EHCI for USB 2 (up to 480 Mb/s) and XHCI for USB 3 (up to 5 Gb/s). We currently support all but XHCI, which is still quite new.
The USB bus is fully controlled by the host; all devices are polled. Hubs are passive in the sense that they do not poll the devices attached to them. The host polls those devices and the hubs merely route the messages.
Devices may be added to or removed from the bus at any time. When a device is attached, the host queries it to determine its type and speed. The querying process is standardized. The first level of querying is the same for all devices, the next is somewhat specialized for particular classes of devices (such as mice, keyboards, or audio devices). Specialization continues as subclasses and subsubclasses are explored.
Enumeration of the bus and initial configuration of devices is done by a user level program, usbd. Device drivers are implemented by separate user programs, although some of them may be statically linked into usbd.
The kernel device described in this page is responsible for providing
I/O for using the devices through so called endpoints. Access
to the host controller is hidden from user programs, which see
just a set of endpoints. After system initialization, some endpoints
are created by the device to permit I/O to root hubs. All
other devices must be configured by usbd.
Devices and Endpoints
All USB devices include at least a control endpoint to perform
device configuration. This is called the setup endpoint or endpoint
zero. After configuring a device, other endpoints may be created
as dictated by the device to perform actual I/O.
Each directory /dev/usb/epN.M represents an endpoint, where N is a number identifying a device and M is a number identifying one of its endpoints.
For each device attached to the bus, and configured by usbd, an endpoint zero (a setup endpoint) is provided at /dev/usb/epN.0 for configuring the device. This is always a control endpoint and represents the device itself.
The device driver may use the setup endpoint to issue control requests and perhaps to create more endpoints for the device. Each new endpoint created has its own directory as said above. For example, if the driver for the device /dev/usb/epN.0 creates the endpoint number 3 for that device, a directory /dev/usb/epN.3 will be available to access that endpoint.
All endpoint directories contain two files: data and ctl. The
former has mode bit DMEXCL set and can be open by only one process
at a time.
The data file is used to perform actual I/O. In general, reading from it retrieves data from the endpoint and writing into it sends data to the endpoint. For control endpoints, writing to this file issues a control request (which may include data); if the request retrieves data from the device, a following read on the file will provide such data.
USB errors reported by the endpoint upon I/O failures are passed to the user process through the error string. I/O stalls not resulting from an error, usually an indication from the device, are reported by indicating that the number of bytes transferred has been zero. In most cases, the correct course of action after noticing the stall is for the device driver to issue a `clear halt' request (see unstall in nusb(2)) to resume I/O. The most common error is crc/timeout indicating problems in communication with the device (eg., a physical detach of the device or a wiring problem).
For control and isochronous transfers, there is an implicit timeout
performed by the kernel and it is not necessary for applications
to place their own timers. For other transfer types, the kernel
will not time out any operation by default (but see the timeout
ctl and status
The ctl file can be read to learn about the endpoint. It contains information that can be used to locate a particular device (or endpoint). It also accepts writes with textual control requests described later.
This may result from the read of an endpoint control file:
Device state One of config, enabled, and detached. An endpoint starts in the config state, and accepts control commands written to its ctl file to configure the endpoint. When configured, the state is enabled and the data file is used as described above (several control requests can still be issued to
Endpoint modeOne of r, w, or rw, depending on the direction of the endpoint (in, out, or inout).
Speed low (1.5 Mb/s), full (12 Mb/s), or high (480 Mb/s).
Maximum packet size
Frequency Number of samples per second (Hertz).
Hub address Device address of the hub where the device is attached.
Port number Port number (in the hub) where the device is attached.
Usage busy while the data file is open and idle otherwise. This is useful to avoid disturbing endpoints already run by a device driver.
The second line contains information describing the device:
Device stringsProvided by the device and identifying the manufacturer and type of device.
For example, to find a mouse not yet in use by a driver, scan
the ctl files for enabled, idle, and csp 0x020103. A mouse belongs
to class 3 (in the least significant byte), human interface device,
subclass 1, boot, protocol 2, mouse (protocol 1 would be the keyboard).
USB class, subclass and proto codes can be
found at http://www.usb.org.
hz n Use n as the number of samples per second.
ntds n Use n as the number of transactions per frame (or µframe), as reported by the descriptor.
clrhalt Clear the halt condition for an endpoint. Used to recover from a stall caused by a device to signal its driver (usually due to an unknown request or a failure to complete one).
info string Replaces description information in ctl with string. Usbd uses this to add device descriptions.
address Tell this driver that the device has been given an address, which causes the device to enter the enabled state.
name str Generates an additional file name, str , for the data file of the endpoint. This file name appears in the root directory of the #u tree. For example, this is used by the audio device driver to make the data file also available as /dev/audio.
debug n Enable debugging of the endpoint. N is an integer; larger values make diagnostics more verbose. 0 stops debugging diagnostics. 1 causes just problem reports. Bigger values report almost everything.
timeout n Enable time–outs for the endpoint. Transfers are timed out by the kernel after n ms. This should not be used for control and isochronous endpoints, which are always timed out.
Setup endpoints (those represented by epN.0 directories) also
accept the following requests:
Setup endpoints for hub devices also accept his request:
debug nSets the global debug flag to n.
dump Dumps data structures for inspection.
#u/usb root of the USB interface|
nusb(2), nusb(4), plan9.ini(8)|
USB controllers limit the speed of all their ports to that of
the slowest device connected to any one of them. |
Isochronous input streams are not implemented for OHCI.
Some EHCI controllers drop completion interrupts and so must be
polled, which hurts throughput.