term% cat index.txt USB(3) Library Functions Manual USB(3)
delim $$
NAME
usb - USB Host Controller Interface
SYNOPSIS
bind -a #u /dev
/dev/usb
/dev/usb/ctl
/dev/usb/epN.M
/dev/usb/epN.M/data
/dev/usb/epN.M/ctl
...
DESCRIPTION
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 at‐
tached 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(4). Device drivers are implemented by sepa‐
rate 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 con‐
figured by usbd.
Devices and Endpoints
A device includes one or more functions (e.g., audio output, volume
control buttons, mouse input, etc.) Communication with device func‐
tions is performed by some combination of issuing control requests to,
sending data to, and receiving data from device endpoints. Endpoints
can be understood as addresses in the bus. There are several types:
Control
Their main use is to configure devices. Writing a message with
a specific format (specified in the USB specification) issues a
request to the device. If the request implies a reply, a read
can be made next to retrieve the requested data (if the write
succeeded).
Interrupt
Used to send and receive messages to or from a specific device
function (e.g., to read events from a mouse).
Bulk Used to send and receive larger amounts of data through streams
(e.g., to write blocks to a disk).
Isochronous
Used to send and receive data in a timely manner (e.g., to write
audio samples to a speaker).
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.
Operation
Bus enumeration and device configuration is performed by usbd(4) and
not by this driver. The driver provides an interface to access exist‐
ing endpoints (initially those for the built-in root hubs), to create
and configure other ones, and to perform I/O through them.
Each directory /dev/usb/epN.M represents an endpoint, where N is a num‐
ber identifying a device and M is a number identifying one of its end‐
points.
For each device attached to the bus, and configured by usbd(4), an end‐
point zero (a setup endpoint) is provided at /dev/usb/epN.0 for config‐
uring 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 dri‐
ver 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.
data
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 indi‐
cating 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 usb(2))
to resume I/O. The most common error is indicating problems in commu‐
nication 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 control request).
ctl and status
The ctl file can be read to learn about the endpoint. It contains in‐
formation 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:
(the first line is wrapped to make it fit here)
enabled control rw speed full maxpkt 64 pollival 0
samplesz 0 hz 0 hub 1 port 3 busy
storage csp 0x500608 vid 0x951 did 0x1613 Kingston 'DT 101 II'
The first line contains status information. The rest is information
supplied by usbd(4) as an aid to locate devices. The status informa‐
tion includes:
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 its ctl file, but most
will not be accepted from now on). Upon severe errors, perhaps
a physical detachment from the bus, the endpoint enters the de‐
tached state and no further I/O is accepted on it. Files for an
endpoint (including its directory) vanish when the device is de‐
tached and its files are no longer open. Root hubs may not be
detached.
Endpoint type
control, iso, interrupt, or bulk, indicating the type of trans‐
fer supported by the endpoint.
Endpoint mode
One 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
Used when performing I/O on the data file.
Polling interval
The polling period expressed as a number of µframes (for high-
speed endpoints) or frames (for low- and full-speed endpoints).
Note that a µframe takes 125 µs while a frame takes 1 ms.
This is only of relevance for interrupt and isochronous end‐
points. This value determines how often I/O happens. Note that
the control request adjusting the polling interval does not use
these units, to make things easier for USB device drivers.
Sample size
Number of bytes per I/O sample (isochronous endpoints only).
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 while the data file is open and otherwise. This is useful to
avoid disturbing endpoints already run by a device driver.
The second line contains information describing the device:
Class name
As provided by the device itself.
CSP Class, Subclass, and Protocol for the device. If the device
contains different functions and has more CSPs, all of them will
be listed. The first one is that of the device itself. For ex‐
ample, a mouse and keyboard combo may identify itself as a key‐
board but then include two CSPs, one for the keyboard and an‐
other one for the mouse.
Vid and Did
Vendor and device identifiers.
Device strings
Provided 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.
Control requests
Endpoint control files accept the following requests. In most cases
the driver does not issue them, leaving the task to either usbd(4) or
the usb driver library documented in usb(2).
detach Prevent further I/O on the device (delete the endpoint) and re‐
move its file interface as soon as no process is using their
files.
maxpkt n
Set the maximum packet size to n bytes.
pollival n
Only for interrupt and isochronous endpoints. Set the polling
interval as a function of the value n given by the endpoint de‐
scriptor. The interval value used is the period n in bus time
units for low- and full-speed interrupt endpoints. Otherwise,
the actual interval is $2 sup n$ and not n. Bus time units are
1 ms for low- and full-speed endpoints and 125 µs for high-
speed endpoints. In most cases, the device driver may ignore
all this and issue the control request supplying the polling in‐
terval value as found in the endpoint descriptor. The kernel
adjusts the value according to the endpoint configuration and
converts it into the number of frames or µframes between two
consecutive polls.
samplesz n
Use n as the number of bytes per sample.
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(4)
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 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 val‐
ues make diagnostics more verbose. stops debugging diagnostics.
causes just problem reports. Bigger values report almost every‐
thing.
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:
new n type mode
Creates a new endpoint with number n of the given type (ctl,
bulk, intr, or iso). Mode may be r, w, or rw, which creates,
respectively, an input, output, or input/output endpoint.
speed {low|full|high}
Set the endpoint speed to full, low, or high, respectively.
hub Tell this driver that the endpoint corresponds to a hub device.
Setup endpoints for hub devices also accept his request:
newdev {low|full|high} port
Create a new setup endpoint to represent a new device. The
first argument is the device speed. Port is the port number
where the device is attached (the hub is implied by the endpoint
where the control request is issued).
The file /dev/usb/ctl provides all the information provided by the var‐
ious ctl files when read. It accepts several requests that refer to
the entire driver and not to particular endpoints:
debug n
Sets the global debug flag to n.
dump Dumps data structures for inspection.
FILES
#u/usb root of the USB interface
SOURCE
/sys/src/9/port/usb.h
/sys/src/9/*/*usb?hci.h
/sys/src/9/*/devusb.c
/sys/src/9/*/usb?hci*.c
SEE ALSO
usb(2), usb(4), usbd(4), plan9.ini(8)
BUGS
USB controllers limit the speed of all their ports to that of the slow‐
est 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.
USB(3)