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 February 21, 1999 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 157.In dev/usb/usb.h 158.Pp 159The 160.Pa /dev/usb Ns Ar N 161can be opened and a few operations can be performed on it. 162The 163.Xr poll 2 164system call will say that I/O is possible on the controller device when a 165.Tn USB 166device has been connected or disconnected to the bus. 167.Pp 168The following 169.Xr ioctl 2 170commands are supported on the controller device: 171.Bl -tag -width xxxxxx 172.It Dv USB_DISCOVER 173This command will cause a complete bus discovery to be initiated. 174If any devices attached or detached from the bus they will be 175processed during this command. 176This is the only way that new devices are found on the bus. 177.It Dv USB_DEVICEINFO Vt "struct usb_device_info" 178This command can be used to retrieve some information about a device 179on the bus. 180The 181.Va udi_addr 182field should be filled before the call and the other fields will 183be filled by information about the device on that address. 184Should no such device exist, an error is reported. 185.Bd -literal 186#define USB_MAX_DEVNAMES 4 187#define USB_MAX_DEVNAMELEN 16 188struct usb_device_info { 189 u_int8_t udi_bus; 190 u_int8_t udi_addr; /* device address */ 191 usb_event_cookie_t udi_cookie; 192 char udi_product[USB_MAX_STRING_LEN]; 193 char udi_vendor[USB_MAX_STRING_LEN]; 194 char udi_release[8]; 195 u_int16_t udi_productNo; 196 u_int16_t udi_vendorNo; 197 u_int16_t udi_releaseNo; 198 u_int8_t udi_class; 199 u_int8_t udi_subclass; 200 u_int8_t udi_protocol; 201 u_int8_t udi_config; 202 u_int8_t udi_speed; 203#define USB_SPEED_LOW 1 204#define USB_SPEED_FULL 2 205#define USB_SPEED_HIGH 3 206 int udi_power;/* power consumption in mA, 0 if selfpowered */ 207 int udi_nports; 208 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 209 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */ 210#define USB_PORT_ENABLED 0xff 211#define USB_PORT_SUSPENDED 0xfe 212#define USB_PORT_POWERED 0xfd 213#define USB_PORT_DISABLED 0xfc 214}; 215.Ed 216.Pp 217.Va udi_bus 218and 219.Va udi_addr 220contain the topological information for the device. 221.Va udi_devnames 222contains the device names of the connected drivers. 223For example, the 224third 225.Tn USB 226Zip drive connected will be 227.Li umass2 . 228The 229.Va udi_product , udi_vendor 230and 231.Va udi_release 232fields contain self-explanatory descriptions of the device. 233.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass 234and 235.Va udi_protocol 236contain the corresponding values from the device descriptors. 237The 238.Va udi_config 239field shows the current configuration of the device. 240.Pp 241.Va udi_peed 242indicates whether the device is at low speed 243.Pq Dv USB_SPEED_LOW , 244full speed 245.Pq Dv USB_SPEED_FULL 246or high speed 247.Pq Dv USB_SPEED_HIGH . 248The 249.Va udi_power 250field shows the power consumption in milli-amps drawn at 5 volts, 251or zero if the device is self powered. 252.Pp 253If the device is a hub, the 254.Va udi_nports 255field is non-zero, and the 256.Va udi_ports 257field contains the addresses of the connected devices. 258If no device is connected to a port, one of the 259.Dv USB_PORT_* 260values indicates its status. 261.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 262This command retrieves statistics about the controller. 263.Bd -literal 264struct usb_device_stats { 265 u_long uds_requests[4]; 266}; 267.Ed 268.Pp 269The 270.Va udi_requests 271field is indexed by the transfer kind, i.e.\& 272.Dv UE_* , 273and indicates how many transfers of each kind that has been completed 274by the controller. 275.It Dv USB_REQUEST Vt "struct usb_ctl_request" 276This command can be used to execute arbitrary requests on the control pipe. 277This is 278.Em DANGEROUS 279and should be used with great care since it 280can destroy the bus integrity. 281.El 282.Pp 283The include file 284.Aq Pa dev/usb/usb.h 285contains definitions for the types used by the various 286.Xr ioctl 2 287calls. 288The naming convention of the fields for the various 289.Tn USB 290descriptors exactly follows the naming in the 291.Tn USB 292specification. 293Byte sized fields can be accessed directly, but word (16 bit) 294sized fields must be access by the 295.Fn UGETW field 296and 297.Fn USETW field value 298macros to handle byte order and alignment properly. 299.Pp 300The include file 301.Aq Pa dev/usb/usbhid.h 302similarly contains the definitions for 303Human Interface Devices 304.Pq Tn HID . 305.Sh USB EVENT INTERFACE 306All 307.Tn USB 308events are reported via the 309.Pa /dev/usb 310device. 311This devices can be opened for reading and each 312.Xr read 2 313will yield an event record (if something has happened). 314The 315.Xr poll 2 316system call can be used to determine if an event record is available 317for reading. 318.Pp 319The event record has the following definition: 320.Bd -literal 321struct usb_event { 322 int ue_type; 323#define USB_EVENT_CTRLR_ATTACH 1 324#define USB_EVENT_CTRLR_DETACH 2 325#define USB_EVENT_DEVICE_ATTACH 3 326#define USB_EVENT_DEVICE_DETACH 4 327#define USB_EVENT_DRIVER_ATTACH 5 328#define USB_EVENT_DRIVER_DETACH 6 329 struct timespec ue_time; 330 union { 331 struct { 332 int ue_bus; 333 } ue_ctrlr; 334 struct usb_device_info ue_device; 335 struct { 336 usb_event_cookie_t ue_cookie; 337 char ue_devname[16]; 338 } ue_driver; 339 } u; 340}; 341.Ed 342The 343.Va ue_type 344field identifies the type of event that is described. 345The possible events are attach/detach of a host controller, 346a device, or a device driver. 347The union contains information 348pertinent to the different types of events. 349Macros, 350.Fn USB_EVENT_IS_ATTACH "ue_type" 351and 352.Fn USB_EVENT_IS_DETACH "ue_type" 353can be used to determine if an event was an 354.Dq attach 355or a 356.Dq detach 357request. 358.Pp 359The 360.Va ue_bus 361contains the number of the 362.Tn USB 363bus for host controller events. 364.Pp 365The 366.Va ue_device 367record contains information about the device in a device event event. 368.Pp 369The 370.Va ue_cookie 371is an opaque value that uniquely determines which which 372device a device driver has been attached to (i.e., it equals 373the cookie value in the device that the driver attached to). 374.Pp 375The 376.Va ue_devname 377contains the name of the device (driver) as seen in, e.g., 378kernel messages. 379.Pp 380Note that there is a separation between device and device 381driver events. 382A device event is generated when a physical 383.Tn USB 384device is attached or detached. 385A single 386.Tn USB 387device may 388have zero, one, or many device drivers associated with it. 389.Sh SEE ALSO 390The 391.Tn USB 392specifications can be found at: 393.Pp 394.D1 Pa http://www.usb.org/developers/docs/ 395.Pp 396.Xr aue 4 , 397.Xr cue 4 , 398.Xr kue 4 , 399.Xr ohci 4 , 400.Xr pci 4 , 401.Xr ucom 4 , 402.Xr ugen 4 , 403.Xr uhci 4 , 404.Xr uhid 4 , 405.Xr ukbd 4 , 406.Xr ulpt 4 , 407.Xr umass 4 , 408.Xr ums 4 , 409.Xr uplcom 4 , 410.Xr urio 4 , 411.Xr uscanner 4 , 412.Xr uvscom 4 , 413.Xr usbd 8 , 414.Xr usbdevs 8 415.Sh HISTORY 416The 417.Nm 418driver first appeared in 419.Fx 3.0 . 420.Sh AUTHORS 421The 422.Nm 423driver was written by 424.An Lennart Augustsson Aq augustss@carlstedt.se 425for the 426.Nx 427project. 428