.TH USB 3 
.SH NAME
usb \- USB Host Controller Interface
.SH SYNOPSIS
.nf
.B bind -a #U /dev

.BI /dev/usb m
.BI /dev/usb m /new
.BI /dev/usb m /port
.BI /dev/usb m / n 
.BI /dev/usb m / n /ctl
.BI /dev/usb m / n /status
.BI /dev/usb m / n /setup
.BI /dev/usb m / n /ep k\fLdata
\&...

.fi
.SH DESCRIPTION
The Universal Serial Bus is a popular bus for connecting slow and medium speed
devices, such as mice, keyboards, printers, and scanners to a PC.  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
.IR hubs .
.PP
Most PCs have a two-slot hub built in, accommodating two USB devices.  To
attach more devices, one or more hubs have to be plugged in to the USB
slots of the PC.  The topology of the network is a tree with at most
127 nodes, counting both internal and leaf nodes.
.PP
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.
.PP
When a device is attached, the host queries it to determine its type
and its 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.
.PP
For each connected device there is a directory in
.BI #U/usb n\fR.
Reading
.BI #U/usb n /*/status
yields the state, class/subclass/proto, vendor-id and product-id of each device in the
first line.  The remaining lines give the state of each of the
interfaces.
.PP
To find a mouse, for example, scan the status files for the line beginning with
.IP
.EX
.BR "Enabled 0x020103"
.EE
.PP
A mouse belongs to class 3 (in the least significant byte),
.IR "human interface device" ,
subclass 1,
.IR boot ,
proto 2,
.I mouse
(proto 1 would be the keyboard).
USB class, subclass and proto codes can be found on
.BR www.usb.org .
.PP
The control interface for each device is
.I "``endpoint 0''"
and is named
.BI #U/usb n /*/setup \fR.
The control interface of the device is accessed by reading and writing
this file.
.PP
There is a separate
.I "control interface
named
.BI #U/usb n /*/ctl
which is used to configure the USB device
.IR driver .
By writing to this
file, driver endpoints can be created and configured for communication with a
device's data streams.  A mouse, for example, has one control interface
and one data interface.  By communicating with the control interface,
one can find out the device type (i.e., `mouse'), power consumption, number
on interfaces, etc.
.IR Usbd (4)
will extract all this information and, in verbose mode, print it.
.PP
By sending an `endpoint message' to the
.I ctl
file, new driver endpoints can be created.  The syntax of these messages
is
.PP
.B ep
.I n
.B bulk
.I "mode maxpkt nbuf
.PP
or
.PP
.B ep
.I "n period mode samplesize hz
.PP
The first form configures a non-real-time stream, the second an
.I isochronous
(real-time) stream.
In both forms,
.I n
is the endpoint to be configured, and
.I mode
is
.B r
for read only,
.B w
for write only, or
.B rw
for reading and writing.
In the first form,
.I maxpkt
is the maximum packet size to be used (between 8 and 1023),
and
.I nbuf
is the number of buffers to be allocated by the driver.
.PP
In the second form,
.I period
is the number of milliseconds between packets.  This number is usually
dictated by the device.  It must be between 1 and 1000.
The
.I samplesize
is the size in bytes of the data units making up packets, and
.I hz
is the number of data units transmitted or received per second.
.PP
The data rate is thus
.IR hz × samplesize
bytes per second, and the number of samples in a packet
will be 
.RI ( period × hz )/1000,
rounded up or down.
Packets do not contain fractional samples.
.PP
The mouse, which produces 3-byte samples, is configured with
.BR "ep 1 bulk r 3 32" :
endpoint 1 is configured for non-real-time read-only 3-byte messages
and allows 32 of them to be outstanding.
.PP
A usb audio output device at 44.1 KHz, 2 channels, 16-bit samples, on endpoint
4 will be configured with
.BR "ep 4 1 w 4 44100" .
.PP
If the configuration is successful, a file named
.BI ep n data
is created which can be read and/or written depending on
configuration.  Configuration is not allowed when the data endpoint
is open.
.PP
Forward
.I seek
operations on isochronous endpoints
can be used to start the I/O at a specific time.
The usb status file provides information that can be used to map file
offsets to points in time:  For each endpoint, the status file produces a line
of the form:
.PP
.B "4 0x000201 \f2nnn\fP bytes \f2nnn\fP blocks
.PP
The fields are, from left to right,
endpoint number, class/subclass/proto (as a six-digit hex number with class in the
least significant byte), number of bytes read/written, number of blocks read/written.
.PP
For isochronous devices only, an additional line is produced of the
form:
.PP
.B "bufsize \f2s\fP buffered \f2b\fP offset \f2o\fP time \f2t\fP
.PP
.I S
is the size of the DMA operations on the device (i.e., the minimum useful size
for reads and writes),
.I b
is the number of bytes currently buffered for input or output, and
.I o
and
.I t
should be interpreted to mean that byte offset
.I o
was/will be reached at time
.I t
(nanoseconds since the epoch).
.PP
To play or record samples exactly at some predetermined time, use
.I o
and
.I t
with the sampling rate to calculate the offset to seek to.
.PP
The number of bytes buffered can also be obtained using
.IR stat (2)
on the endpoint file.  See also
.IR audio (3).
.sp
.SH FILES
.TF "#U/usb n /*/status"
.TP
.BI #U/usb n /port
USB port status file; for each port, space separated: port number, hexadecimal port status, port status string
.TP
.BI #U/usb n /*/status
USB device status file; class/subclass/proto, vendor-id and product-id are found in line one
.TP
.BI #U/usb n /*/ctl
USB
.I driver
control file, used to create driver endpoints, control debugging, etc.
.TP
.BI #U/usb n /*/setup
USB
.I device
control file, used to exchange messages with a device's control channel.
.B setup
may be viewed as a preconfigured
.B ep0data
file.
.TP
.BI #U/usb n /*/ep k data
USB device data channel for the
.IR k 'th
configuration.
.SH SOURCE
.B /sys/src/9/pc/usb.h
.br
.B /sys/src/9/pc/devusb.c
.br
.B /sys/src/9/pc/usbuhci.c
.br
.SH "SEE ALSO"
.IR usb (4),
.IR usbd (4),
.IR plan9.ini (8)
.SH BUGS
OpenHCI USB cards are not yet supported.
.PP
The interface for configuring endpoints is at variance with the standard.
.PP
The notion that the endpoints themselves have a class and subclass
is a distortion of the standard.
It would be better to leave all handling of the notions of class to the
user-level support programs, and remove it from the driver.