1.\" Copyright (c) 1997, 1998 2.\" Nick Hibma <n_hibma@FreeBSD.org>. 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. Neither the name of the author nor the names of any co-contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 26.\" THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd April 20, 2005 31.Dt USB 4 32.Os 33.Sh NAME 34.Nm usb 35.Nd Universal Serial Bus 36.Sh SYNOPSIS 37.Cd "device usb" 38.Pp 39.In dev/usb/usb.h 40.In dev/usb/usbhid.h 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 60.Tn USB 61bus. 62.Pp 63The 64.Nm uhub 65device will always be present as it is needed for the 66root hub. 67.Sh INTRODUCTION TO USB 68The 69.Tn USB 70is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 71Each 72.Tn USB 73has a host controller that is the master of the bus; 74all other devices on the bus only speak when spoken to. 75.Pp 76There can be up to 127 devices (apart from the host controller) 77on a bus, each with its own address. 78The addresses are assigned 79dynamically by the host when each device is attached to the bus. 80.Pp 81Within each device there can be up to 16 endpoints. 82Each endpoint 83is individually addressed and the addresses are static. 84Each of these endpoints will communicate in one of four different modes: 85.Em control , isochronous , bulk , 86or 87.Em interrupt . 88A device always has at least one endpoint. 89This endpoint has address 0 and is a control 90endpoint and is used to give commands to and extract basic data, 91such as descriptors, from the device. 92Each endpoint, except the control endpoint, is unidirectional. 93.Pp 94The endpoints in a device are grouped into interfaces. 95An interface is a logical unit within a device; e.g.\& 96a compound device with both a keyboard and a trackball would present 97one interface for each. 98An interface can sometimes be set into different modes, 99called alternate settings, which affects how it operates. 100Different alternate settings can have different endpoints 101within it. 102.Pp 103A device may operate in different configurations. 104Depending on the 105configuration, the device may present different sets of endpoints 106and interfaces. 107.\" .Pp 108.\" Each device located on a hub has several 109.\" .Xr config 8 110.\" locators: 111.\" .Bl -tag -compact -width xxxxxx 112.\" .It Cd port 113.\" this is the number of the port on the closest upstream hub. 114.\" .It Cd configuration 115.\" this is the configuration the device must be in for this driver to attach. 116.\" This locator does not set the configuration; it is iterated by the bus 117.\" enumeration. 118.\" .It Cd interface 119.\" this is the interface number within a device that an interface driver 120.\" attaches to. 121.\" .It Cd vendor 122.\" this is the 16 bit vendor id of the device. 123.\" .It Cd product 124.\" this is the 16 bit product id of the device. 125.\" .It Cd release 126.\" this is the 16 bit release (revision) number of the device. 127.\" .El 128.\" The first locator can be used to pin down a particular device 129.\" according to its physical position in the device tree. 130.\" The last three locators can be used to pin down a particular 131.\" device according to what device it actually is. 132.Pp 133The bus enumeration of the 134.Tn USB 135bus proceeds in several steps: 136.Bl -enum 137.It 138Any device specific driver can attach to the device. 139.It 140If none is found, any device class specific driver can attach. 141.It 142If none is found, all configurations are iterated over. 143For each configuration, all the interfaces are iterated over, and interface 144drivers can attach. 145If any interface driver attached in a certain 146configuration, the iteration over configurations is stopped. 147.It 148If still no drivers have been found, the generic 149.Tn USB 150driver can attach. 151.El 152.Sh USB CONTROLLER INTERFACE 153Use the following to get access to the 154.Tn USB 155specific structures and defines. 156.Pp 157The 158.Pa /dev/usb Ns Ar N 159can be opened and a few operations can be performed on it. 160The 161.Xr poll 2 162system call will say that I/O is possible on the controller device when a 163.Tn USB 164device has been connected or disconnected to the bus. 165.Pp 166The following 167.Xr ioctl 2 168commands are supported on the controller device: 169.Bl -tag -width xxxxxx 170.It Dv USB_DISCOVER 171This command will cause a complete bus discovery to be initiated. 172If any devices attached or detached from the bus they will be 173processed during this command. 174This is the only way that new devices are found on the bus. 175.It Dv USB_DEVICEINFO Vt "struct usb_device_info" 176This command can be used to retrieve some information about a device 177on the bus. 178The 179.Va udi_addr 180field should be filled before the call and the other fields will 181be filled by information about the device on that address. 182Should no such device exist, an error is reported. 183.Bd -literal 184#define USB_MAX_DEVNAMES 4 185#define USB_MAX_DEVNAMELEN 16 186struct usb_device_info { 187 u_int8_t udi_bus; 188 u_int8_t udi_addr; /* device address */ 189 usb_event_cookie_t udi_cookie; 190 char udi_product[USB_MAX_STRING_LEN]; 191 char udi_vendor[USB_MAX_STRING_LEN]; 192 char udi_release[8]; 193 u_int16_t udi_productNo; 194 u_int16_t udi_vendorNo; 195 u_int16_t udi_releaseNo; 196 u_int8_t udi_class; 197 u_int8_t udi_subclass; 198 u_int8_t udi_protocol; 199 u_int8_t udi_config; 200 u_int8_t udi_speed; 201#define USB_SPEED_LOW 1 202#define USB_SPEED_FULL 2 203#define USB_SPEED_HIGH 3 204 int udi_power;/* power consumption in mA, 0 if selfpowered */ 205 int udi_nports; 206 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 207 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */ 208#define USB_PORT_ENABLED 0xff 209#define USB_PORT_SUSPENDED 0xfe 210#define USB_PORT_POWERED 0xfd 211#define USB_PORT_DISABLED 0xfc 212}; 213.Ed 214.Pp 215.Va udi_bus 216and 217.Va udi_addr 218contain the topological information for the device. 219.Va udi_devnames 220contains the device names of the connected drivers. 221For example, the 222third 223.Tn USB 224Zip drive connected will be 225.Li umass2 . 226The 227.Va udi_product , udi_vendor 228and 229.Va udi_release 230fields contain self-explanatory descriptions of the device. 231.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass 232and 233.Va udi_protocol 234contain the corresponding values from the device descriptors. 235The 236.Va udi_config 237field shows the current configuration of the device. 238.Pp 239.Va udi_speed 240indicates whether the device is at low speed 241.Pq Dv USB_SPEED_LOW , 242full speed 243.Pq Dv USB_SPEED_FULL 244or high speed 245.Pq Dv USB_SPEED_HIGH . 246The 247.Va udi_power 248field shows the power consumption in milli-amps drawn at 5 volts, 249or zero if the device is self powered. 250.Pp 251If the device is a hub, the 252.Va udi_nports 253field is non-zero, and the 254.Va udi_ports 255field contains the addresses of the connected devices. 256If no device is connected to a port, one of the 257.Dv USB_PORT_* 258values indicates its status. 259.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 260This command retrieves statistics about the controller. 261.Bd -literal 262struct usb_device_stats { 263 u_long uds_requests[4]; 264}; 265.Ed 266.Pp 267The 268.Va udi_requests 269field is indexed by the transfer kind, i.e.\& 270.Dv UE_* , 271and indicates how many transfers of each kind that has been completed 272by the controller. 273.It Dv USB_REQUEST Vt "struct usb_ctl_request" 274This command can be used to execute arbitrary requests on the control pipe. 275This is 276.Em DANGEROUS 277and should be used with great care since it 278can destroy the bus integrity. 279.El 280.Pp 281The include file 282.In dev/usb/usb.h 283contains definitions for the types used by the various 284.Xr ioctl 2 285calls. 286The naming convention of the fields for the various 287.Tn USB 288descriptors exactly follows the naming in the 289.Tn USB 290specification. 291Byte sized fields can be accessed directly, but word (16 bit) 292sized fields must be access by the 293.Fn UGETW field 294and 295.Fn USETW field value 296macros to handle byte order and alignment properly. 297.Pp 298The include file 299.In dev/usb/usbhid.h 300similarly contains the definitions for 301Human Interface Devices 302.Pq Tn HID . 303.Sh USB EVENT INTERFACE 304All 305.Tn USB 306events are reported via the 307.Pa /dev/usb 308device. 309This device can be opened for reading and each 310.Xr read 2 311will yield an event record (if something has happened). 312The 313.Xr poll 2 314system call can be used to determine if an event record is available 315for reading. 316.Pp 317The event record has the following definition: 318.Bd -literal 319struct usb_event { 320 int ue_type; 321#define USB_EVENT_CTRLR_ATTACH 1 322#define USB_EVENT_CTRLR_DETACH 2 323#define USB_EVENT_DEVICE_ATTACH 3 324#define USB_EVENT_DEVICE_DETACH 4 325#define USB_EVENT_DRIVER_ATTACH 5 326#define USB_EVENT_DRIVER_DETACH 6 327 struct timespec ue_time; 328 union { 329 struct { 330 int ue_bus; 331 } ue_ctrlr; 332 struct usb_device_info ue_device; 333 struct { 334 usb_event_cookie_t ue_cookie; 335 char ue_devname[16]; 336 } ue_driver; 337 } u; 338}; 339.Ed 340The 341.Va ue_type 342field identifies the type of event that is described. 343The possible events are attach/detach of a host controller, 344a device, or a device driver. 345The union contains information 346pertinent to the different types of events. 347Macros, 348.Fn USB_EVENT_IS_ATTACH "ue_type" 349and 350.Fn USB_EVENT_IS_DETACH "ue_type" 351can be used to determine if an event was an 352.Dq attach 353or a 354.Dq detach 355request. 356.Pp 357The 358.Va ue_bus 359contains the number of the 360.Tn USB 361bus for host controller events. 362.Pp 363The 364.Va ue_device 365record contains information about the device in a device event event. 366.Pp 367The 368.Va ue_cookie 369is an opaque value that uniquely determines which 370device a device driver has been attached to (i.e., it equals 371the cookie value in the device that the driver attached to). 372.Pp 373The 374.Va ue_devname 375contains the name of the device (driver) as seen in, e.g., 376kernel messages. 377.Pp 378Note that there is a separation between device and device 379driver events. 380A device event is generated when a physical 381.Tn USB 382device is attached or detached. 383A single 384.Tn USB 385device may 386have zero, one, or many device drivers associated with it. 387.Sh SEE ALSO 388The 389.Tn USB 390specifications can be found at: 391.Pp 392.D1 Pa http://www.usb.org/developers/docs/ 393.Pp 394.Xr aue 4 , 395.Xr cue 4 , 396.Xr ehci 4 , 397.Xr kue 4 , 398.Xr ohci 4 , 399.Xr pci 4 , 400.Xr ucom 4 , 401.Xr ugen 4 , 402.Xr uhci 4 , 403.Xr uhid 4 , 404.Xr ukbd 4 , 405.Xr ulpt 4 , 406.Xr umass 4 , 407.Xr ums 4 , 408.Xr uplcom 4 , 409.Xr urio 4 , 410.Xr uscanner 4 , 411.Xr uvscom 4 , 412.Xr usbdevs 8 413.Sh HISTORY 414The 415.Nm 416driver first appeared in 417.Fx 3.0 . 418.Sh AUTHORS 419The 420.Nm 421driver was written by 422.An Lennart Augustsson Aq augustss@carlstedt.se 423for the 424.Nx 425project. 426