1.\" Copyright (c) 1997, 1998 2.\" Nick Hibma <hibma@skylink.it>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by Bill Paul. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 29.\" THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd February 21, 1999 34.Dt USB 4 35.Os FreeBSD 36.Sh NAME 37.Nm usb 38.Nd Universal Serial Bus 39.Sh SYNOPSIS 40.Cd "device usb" 41.Sh DESCRIPTION 42.Fx 43provides machine-independent bus support and drivers for 44.Tn USB 45devices. 46.Pp 47The 48.Nm 49driver has three layers: the controller, the bus, and the 50device layer. 51The controller attaches to a physical bus 52(like 53.Xr pci 4 ). 54The 55.Tn USB 56bus attaches to the controller and the root hub attaches 57to the controller. 58Any devices attached to the bus will attach to the root hub 59or another hub attached to the USB bus. 60.Pp 61The 62.Nm uhub 63device will always be present as it is needed for the 64root hub. 65.Pp 66.Sh INTRODUCTION TO USB 67The 68.Tn USB 69is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 70Each 71.Tn USB 72has a host controller that is the master of the bus; 73all other devices on the bus only speak when spoken to. 74.Pp 75There can be up to 127 devices (apart from the host controller) 76on a bus, each with its own address. 77The addresses are assigned 78dynamically by the host when each device is attached to the bus. 79.Pp 80Within each device there can be up to 16 endpoints. 81Each endpoint 82is individually addressed and the addresses are static. 83Each of these endpoints will communicate in one of four different modes: 84control, isochronous, bulk, or interrupt. 85A device always has at least one endpoint. 86This endpoint has address 0 and is a control 87endpoint and is used to give commands to and extract basic data, 88such as descriptors, from the device. 89Each endpoint, except the control endpoint, is unidirectional. 90.Pp 91The endpoints in a device are grouped into interfaces. 92An interface is a logical unit within a device; e.g. 93a compound device with both a keyboard and a trackball would present 94one interface for each. 95An interface can sometimes be set into different modes, 96called alternate settings, which affects how it operates. 97Different alternate settings can have different endpoints 98within it. 99.Pp 100A device may operate in different configurations. 101Depending on the 102configuration the device may present different sets of endpoints 103and interfaces. 104.Pp 105Each device located on a hub has several 106.Xr config 8 107locators: 108.Bl -tag -compact -width xxxxxx 109.It Cd port 110this is the number of the port on the closest upstream hub. 111.It Cd configuration 112this is the configuration the device must be in for this driver to attach. 113This locator does not set the configuration; it is iterated by the bus 114enumeration. 115.It Cd interface 116this is the interface number within a device that an interface driver 117attaches to. 118.El 119.Pp 120The bus enumeration of the 121.Tn USB 122bus proceeds in several steps: 123.Bl -enum 124.It 125Any device specific driver can to attach to the device. 126.It 127If none is found, any device class specific driver can attach. 128.It 129If none is found, all configurations are iterated over. 130For each configuration all the interface are iterated over and interface 131drivers can attach. 132If any interface driver attached in a certain 133configuration the iteration over configurations is stopped. 134.It 135If still no drivers have been found, the generic 136.Tn USB 137driver can attach. 138.El 139.Sh USB CONTROLLER INTERFACE 140Use the following to get access to the 141.Tn USB 142specific structurs and defines. 143.Bd -literal 144#include <sys/dev/usb.h> 145.Ed 146.Pp 147The 148.Pa /dev/usbN 149can be opened and a few operations can be performed on it. 150The 151.Xr poll 2 152system call will say that I/O is possible on the controller device when a 153.Tn USB 154device has been connected or disconnected to the bus. 155.Pp 156The following 157.Xr ioctl 2 158commands are supported on the controller device: 159.Bl -tag -width xxxxxx 160.It Dv USB_DISCOVER 161This command will cause a complete bus discovery to be initiated. 162If any devices attached or detached from the bus they will be 163processed during this command. 164This is the only way that new devices are found on the bus. 165.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 166This command can be used to retrieve some information about a device 167on the bus. 168The 169.Va addr 170field should be filled before the call and the other fields will 171be filled by information about the device on that address. 172Should no such device exist an error is reported. 173.Bd -literal 174struct usb_device_info { 175 u_int8_t bus; 176 u_int8_t addr; 177# define USBDEVNAME_NR 4 178# define USBDEVNAME_LEN 10 179 char devnames[USBDEVNAME_NR][USBDEVNAME_LEN]; 180 char product[USB_MAX_STRING_LEN]; 181 char vendor[USB_MAX_STRING_LEN]; 182 char release[8]; 183 u_int16_t productNo; 184 u_int16_t vendorNo; 185 u_int16_t releaseNo; 186 u_int8_t class; 187 u_int8_t subclass; 188 u_int8_t protocol; 189 u_int8_t config; 190 u_int8_t lowspeed; 191 int power; 192 int nports; 193 u_int8_t ports[16]; 194#define USB_PORT_ENABLED 0xff 195#define USB_PORT_SUSPENDED 0xfe 196#define USB_PORT_POWERED 0xfd 197#define USB_PORT_DISABLED 0xfc 198}; 199.Ed 200.Pp 201.Va bus 202and 203.Va addr 204contain the topological information for the device. 205.Va devnames 206contains the device names of the connected drivers. 207For example the 208third USB Zip drive connected will be 209.Li umass2 . 210The 211.Va product , vendor 212and 213.Va release 214fields contain self-explanatory descriptions of the device. 215.Va productNo , vendorNo , releaseNo , class , subclass 216and 217.Va protocol 218contain the corresponding values from the device descriptors. 219The 220.Va config 221field shows the current configuration of the device. 222.Pp 223.Va lowspeed 224indicates whether the device is a full speed (0) or low speed (1) 225device. 226The 227.Va power 228field shows the power consumption in milli-amps drawn at 5 volts, 229or zero if the device is self powered. 230.Pp 231If the device is a hub the 232.Va nports 233field is non-zero and the 234.Va ports 235field contains the addresses of the connected devices. 236If no device is connected to a port one of the 237.Va USB_PORT_* 238values indicates its status. 239.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 240This command retrieves statistics about the controller. 241.Bd -literal 242struct usb_device_stats { 243 u_long requests[4]; 244}; 245.Ed 246.Pp 247The 248.Va requests 249field is indexed by the transfer kind, i.e. 250.Va UE_* , 251and indicates how many transfers of each kind that has been completed 252by the controller. 253.It Dv USB_REQUEST Fa "struct usb_ctl_request" 254This command can be used to execute arbitrary requests on the control pipe. 255This is 256.Em DANGEROUS 257and should be used with great care since it 258can destroy the bus integrity. 259.El 260.Pp 261The include file 262.Aq Pa dev/usb/usb.h 263contains definitions for the types used by the various 264.Xr ioctl 2 265calls. 266The naming convention of the fields for the various 267.Tn USB 268descriptors exactly follows the naming in the 269.Tn USB 270specification. 271Byte sized fields can be accessed directly, but word (16 bit) 272sized fields must be access by the 273.Fn UGETW field 274and 275.Fn USETW field value 276macros to handle byte order and alignment properly. 277.Pp 278The include file 279.Aq Pa dev/usb/usbhid.h 280similarly contains the definitions for 281Human Interface Devices 282.Pq Tn HID . 283.Sh SEE ALSO 284The 285.Tn USB 286specifications can be found at 287.Dv http://www.usb.org/developers/docs.htm . 288.Pp 289.Xr pci 4 , 290.Xr ohci 4 , 291.Xr ugen 4 , 292.Xr uhci 4 , 293.Xr uhid 4 , 294.Xr ukbd 4 , 295.Xr ulpt 4 , 296.Xr ums 4 , 297.Xr usbd 8 , 298.Xr usbdevs 8 299.Sh HISTORY 300The 301.Nm 302driver first appeared in 303.Fx 3.0 . 304.Sh AUTHORS 305The 306.Nm 307driver was written by 308.An Lennart Augustsson Aq augustss@carlstedt.se 309for the 310.Nx 311project. 312