NAME

	usb – USB Host Controller Interface

SYNOPSIS

	bind –a #U /dev /dev/usbm /dev/usbm/new /dev/usbm/port /dev/usbm/n /dev/usbm/n/ctl /dev/usbm/n/status /dev/usbm/n/setup /dev/usbm/n/epkdata ...

DESCRIPTION

The Universal Serial Bus is a complex yet popular bus for connecting devices, such as mice, keyboards, printers, scanners, and (eventually with USB 2) disks 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 hubs. 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. 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 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. Discovery For each connected device there is a directory in #U/usbn. Reading #U/usbn/*/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. To find a mouse, for example, scan the status files for the line beginning with Enabled 0x020103 A mouse belongs to class 3 (in the least significant byte), human interface device, subclass 1, boot, proto 2, mouse (proto 1 would be the keyboard). USB class, subclass and proto codes can be found on www.usb.org. Device Control The control interface for each device is ``endpoint 0'' and is named #U/usbn/*/setup. The control interface of the device is accessed by reading and writing this file. There is a separate control interface named #U/usbn/*/ctl which is used to configure the USB device 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. Usbd(4) will extract all this information and, in verbose mode, print it. By sending an `endpoint message' to the ctl file, new driver endpoints can be created. The syntax of these messages is ep n ctl mode maxpkt nbuf or ep n bulk mode maxpkt nbuf or ep n period mode maxpkt or ep n period mode samplesize hz There are four forms for, respectively, Control, Bulk, Interrupt and Isochronous traffic (see USB specs for what that means). In all forms, n is the endpoint to be configured, and mode is r for read only, w for write only, or rw for reading and writing. Maxpkt is the maximum packet size to be used (between 8 and 1023), and nbuf is the number of buffers to be allocated by the driver. Period is the number of milliseconds between packets (iso) or polls (interrupt). This number is usually dictated by the device. It must be between 1 and 1000. The samplesize is the size in bytes of the data units making up packets, and hz is the number of data units transmitted or received per second. The data rate for an isochronous channel is hzxsamplesize bytes per second, and the number of samples in a packet will be (periodxhz)/1000, rounded up or down. Packets do not contain fractional samples. A 16–bit stereo 44.1 KHz audio stream will thus have 44100 4–byte samples per second, typically in a 1ms period. Ove a 10 ms period, this yields 9 packets of 176 bytes followed by a 180–byte packet (the driver figures it out for you). The mouse, which produces 3–byte samples, is configured with ep 1 ctl r 3 32: endpoint 1 is configured for non–real–time read–only 3–byte messages and allows 32 of them to be outstanding. A usb audio output device at 44.1 KHz, 2 channels, 16–bit samples, on endpoint 4 will be configured with ep 4 1 w 4 44100. If the configuration is successful, a file named epndata is created which can be read and/or written depending on configuration. Configuration is not allowed when the data endpoint is open. Isochronous Streams Forward 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: 4 0x000201 nnn bytes nnn blocks 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. For isochronous devices only, an additional line is produced of the form: bufsize s buffered b offset o time t S is the size of the DMA operations on the device (i.e., the minimum useful size for reads and writes), b is the number of bytes currently buffered for input or output, and o and t should be interpreted to mean that byte offset o was/will be reached at time t (nanoseconds since the epoch). To play or record samples exactly at some predetermined time, use o and t with the sampling rate to calculate the offset to seek to. The number of bytes buffered can also be obtained using stat(2) on the endpoint file. See also audio(3).

FILES

#U/usbn/port         USB port status file; for each port, space separated: port number, hexadecimal port status, port status string #U/usbn/*/status     USB device status file; class/subclass/proto, vendor–id and product–id are found in line one #U/usbn/*/ctl        USB driver control file, used to create driver endpoints, control debugging, etc. #U/usbn/*/setup      USB device control file, used to exchange messages with a device's control channel. setup may be viewed as a preconfigured ep0data file. #U/usbn/*/epkdata    USB device data channel for the k'th configuration.

SOURCE

	/sys/src/9/pc/usb.h /sys/src/9/pc/devusb.c /sys/src/9/pc/usb[ou]hci.c

SEE ALSO

	usb(4), usbd(4), plan9.ini(8)

BUGS

EHCI USB 2 controllers are not yet supported. The interface for configuring endpoints is at variance with the standard. 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. There may be a timing bug that makes disk accesses via UHCI much slower than necessary.

Copyright © 2008 Lucent Technologies. All rights reserved.