USB(3) 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 con-
trollers. 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). Spe-
cialization 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
Page 1 Plan 9 (printed 11/23/24)
USB(3) USB(3)
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 config-
ured 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 functions 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. Writ-
ing 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 man-
ner (e.g., to write audio samples to a
speaker).
All USB devices include at least a control endpoint to per-
form device configuration. This is called the setup end-
point or endpoint zero. After configuring a device, other
endpoints may be created as dictated by the device to per-
form actual I/O.
Operation
Bus enumeration and device configuration is performed by
usbd and not by this driver. The driver provides an inter-
face to access existing 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 number identifying a device and M is a number identi-
fying one of its endpoints.
For each device attached to the bus, and configured by usbd,
Page 2 Plan 9 (printed 11/23/24)
USB(3) USB(3)
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 con-
trol 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.
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 indicating that the number
of bytes transferred has been zero. In most cases, the cor-
rect 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' control request).
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:
(the first line is wrapped to make it fit here)
enabled control rw speed full maxpkt 64 pollival 0
Page 3 Plan 9 (printed 11/23/24)
USB(3) USB(3)
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 as an aid to locate devices.
The status information 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 config-
ured, 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 detached state and no further I/O is
accepted on it. Files for an endpoint
(including its directory) vanish when the
device is detached and its files are no
longer open. Root hubs may not be detached.
Endpoint type control, iso, interrupt, or bulk, indicating
the type of transfer supported by the end-
point.
Endpoint mode One of r, w, or rw, depending on the direc-
tion 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 endpoints. This
value determines how often I/O happens. Note
that the control request adjusting the pol-
ling 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).
Page 4 Plan 9 (printed 11/23/24)
USB(3) USB(3)
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 disturb-
ing 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 example, a mouse and
keyboard combo may identify itself as a key-
board but then include two CSPs, one for the
keyboard and another 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 or the usb driver library documented in
nusb(2).
detach Prevent further I/O on the device (delete the
endpoint) and remove 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 descriptor. The
interval value used is the period n in bus time
Page 5 Plan 9 (printed 11/23/24)
USB(3) USB(3)
units for low- and full-speed interrupt end-
points. 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 interval value as
found in the endpoint descriptor. The kernel
adjusts the value according to the endpoint con-
figuration 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.
uframes n If n is set to 1 for an isochronous endpoint,
read(2) from the data file will not cross μframe
boundaries.
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 descrip-
tions.
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 inte-
ger; larger values make diagnostics more ver-
bose. `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:
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.
Page 6 Plan 9 (printed 11/23/24)
USB(3) USB(3)
speed {low|full|high}
Set the endpoint speed to full, low, or high, respec-
tively.
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 various ctl files when read. It accepts several
requests that refer to the entire driver and not to particu-
lar 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/port/devusb.c
/sys/src/9/*/usb*.c
SEE ALSO
nusb(2), nusb(4), plan9.ini(8)
BUGS
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.
Page 7 Plan 9 (printed 11/23/24)