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