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: src/share/man/man4/usb.4,v 1.32 2005/04/20 07:33:09 simon Exp $ 29.\" 30.Dd August 19, 2013 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 bus/usb/usb.h 40.In bus/usb/usbhid.h 41.Sh DESCRIPTION 42.Dx 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.Ss Storage devices 68.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 69.\".It Xr natausb 4 70.\"... 71.It Xr umass 4 72Mass Storage Devices, e.g., external disk drives 73.El 74.Ss Wired network interfaces 75.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 76.It Xr aue 4 77ADMtek AN986 Pegasus Ethernet driver 78.It Xr axe 4 79ASIX Electronics AX88172 Ethernet driver 80.It Xr cue 4 81CATC USB-EL1210A Ethernet driver 82.It Xr kue 4 83Kawasaki LSI KL5KUSB101B Ethernet driver 84.It Xr lgue 4 85USB CDC (communication device class) driver for the LG P-500 smartphone 86.It Xr rue 4 87RealTek RTL8150 Ethernet driver 88.El 89.Ss Wireless network interfaces 90.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 91.It Xr ndis 4 92NDIS miniport driver wrapper 93.It Xr rum 4 94Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver 95.It Xr run 4 96Ralink Technology RT2700U/RT2800U/RT3000U IEEE 802.11 driver 97.It Xr ubt 4 98Bluetooth adapters 99.\".It Xr ural 4 100.\"Ralink Technology RT2500USB IEEE 802.11 driver 101.It Xr urtwn 4 102Realtek RTL8188CU/RTL8192CU IEEE 802.11 driver 103.El 104.Ss Serial and parallel interfaces 105.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 106.It Xr moscom 4 107MosChip Semiconductor MCS7703 based serial adapters 108.It Xr uark 4 109Arkmicro Technologies ARK3116 based serial adapters 110.It Xr ubsa 4 111Belkin serial adapters 112.It Xr uchcom 4 113WinChipHead CH341/CH340 serial adapters 114.It Xr ucom 4 115tty support 116.It Xr uftdi 4 117serial devices based on the FTDI chips 118.It Xr ugensa 4 119generic serial device 120.It Xr ulpt 4 121printer support 122.It Xr umct 4 123Magic Control Technology USB-232 based serial adapters 124.It Xr uplcom 4 125Prolific PL-2303/2303X/2303HX serial adapters 126.It Xr uslcom 4 127Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge 128.It Xr uticom 4 129Texas Instruments TUSB3410 RS232 to USB converter 130.It Xr uvisor 4 131support for the Handspring Visor, a Palmpilot compatible PDA 132.It Xr uvscom 4 133SUNTAC Slipper U VS-10U serial adapters 134.El 135.Ss Audio devices 136.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 137.It Xr snd_uaudio 4 138audio device driver 139.It Xr urio 4 140driver for the Rio500 MP3 player 141.El 142.Ss Radio receiver devices 143.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 144.It Xr ufm 4 145Cypress Semiconductor FM Radio 146.El 147.Ss Human Interface Devices 148.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 149.It Xr uhid 4 150generic driver for Human Interface Devices 151.It Xr ukbd 4 152keyboards that follow the boot protocol 153.It Xr ums 4 154mouse devices 155.El 156.Ss Miscellaneous devices 157.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact 158.It Xr ugen 4 159generic device support 160.It Xr uscanner 4 161scanner support 162.El 163.Sh INTRODUCTION TO USB 164The 165.Tn USB 166is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 167Each 168.Tn USB 169has a host controller that is the master of the bus; 170all other devices on the bus only speak when spoken to. 171.Pp 172There can be up to 127 devices (apart from the host controller) 173on a bus, each with its own address. 174The addresses are assigned 175dynamically by the host when each device is attached to the bus. 176.Pp 177Within each device there can be up to 16 endpoints. 178Each endpoint 179is individually addressed and the addresses are static. 180Each of these endpoints will communicate in one of four different modes: 181.Em control , isochronous , bulk , 182or 183.Em interrupt . 184A device always has at least one endpoint. 185This endpoint has address 0 and is a control 186endpoint and is used to give commands to and extract basic data, 187such as descriptors, from the device. 188Each endpoint, except the control endpoint, is unidirectional. 189.Pp 190The endpoints in a device are grouped into interfaces. 191An interface is a logical unit within a device; e.g.\& 192a compound device with both a keyboard and a trackball would present 193one interface for each. 194An interface can sometimes be set into different modes, 195called alternate settings, which affects how it operates. 196Different alternate settings can have different endpoints 197within it. 198.Pp 199A device may operate in different configurations. 200Depending on the 201configuration, the device may present different sets of endpoints 202and interfaces. 203.\".Pp 204.\"Each device located on a hub has several 205.\".Xr config 8 206.\"locators: 207.\".Bl -tag -compact -width xxxxxx 208.\".It Cd port 209.\"this is the number of the port on the closest upstream hub. 210.\".It Cd configuration 211.\"this is the configuration the device must be in for this driver to attach. 212.\"This locator does not set the configuration; it is iterated by the bus 213.\"enumeration. 214.\".It Cd interface 215.\"this is the interface number within a device that an interface driver 216.\"attaches to. 217.\".It Cd vendor 218.\"this is the 16 bit vendor id of the device. 219.\".It Cd product 220.\"this is the 16 bit product id of the device. 221.\".It Cd release 222.\"this is the 16 bit release (revision) number of the device. 223.\".El 224.\"The first locator can be used to pin down a particular device 225.\"according to its physical position in the device tree. 226.\"The last three locators can be used to pin down a particular 227.\"device according to what device it actually is. 228.Pp 229The bus enumeration of the 230.Tn USB 231bus proceeds in several steps: 232.Bl -enum 233.It 234Any device specific driver can attach to the device. 235.It 236If none is found, any device class specific driver can attach. 237.It 238If none is found, all configurations are iterated over. 239For each configuration, all the interfaces are iterated over, and interface 240drivers can attach. 241If any interface driver attached in a certain 242configuration, the iteration over configurations is stopped. 243.It 244If still no drivers have been found, the generic 245.Tn USB 246driver can attach. 247.El 248.Sh USB CONTROLLER INTERFACE 249Use the following to get access to the 250.Tn USB 251specific structures and defines. 252.Pp 253.In bus/usb/usb.h 254.Pp 255The 256.Pa /dev/usb Ns Ar N 257can be opened and a few operations can be performed on it. 258The 259.Xr poll 2 260system call will say that I/O is possible on the controller device when a 261.Tn USB 262device has been connected or disconnected to the bus. 263.Pp 264The following 265.Xr ioctl 2 266commands are supported on the controller device: 267.Bl -tag -width xxxxxx 268.It Dv USB_DISCOVER 269This command will cause a complete bus discovery to be initiated. 270If any devices attached or detached from the bus they will be 271processed during this command. 272This is the only way that new devices are found on the bus. 273.It Dv USB_DEVICEINFO Vt "struct usb_device_info" 274This command can be used to retrieve some information about a device 275on the bus. 276The 277.Va udi_addr 278field should be filled before the call and the other fields will 279be filled by information about the device on that address. 280Should no such device exist, an error is reported. 281.Bd -literal 282#define USB_MAX_DEVNAMES 4 283#define USB_MAX_DEVNAMELEN 16 284struct usb_device_info { 285 u_int8_t udi_bus; 286 u_int8_t udi_addr; /* device address */ 287 usb_event_cookie_t udi_cookie; 288 char udi_product[USB_MAX_STRING_LEN]; 289 char udi_vendor[USB_MAX_STRING_LEN]; 290 char udi_release[8]; 291 u_int16_t udi_productNo; 292 u_int16_t udi_vendorNo; 293 u_int16_t udi_releaseNo; 294 u_int8_t udi_class; 295 u_int8_t udi_subclass; 296 u_int8_t udi_protocol; 297 u_int8_t udi_config; 298 u_int8_t udi_speed; 299#define USB_SPEED_LOW 1 300#define USB_SPEED_FULL 2 301#define USB_SPEED_HIGH 3 302 int udi_power; /* power consumption in mA, 0 if selfpowered */ 303 int udi_nports; 304 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 305 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */ 306#define USB_PORT_ENABLED 0xff 307#define USB_PORT_SUSPENDED 0xfe 308#define USB_PORT_POWERED 0xfd 309#define USB_PORT_DISABLED 0xfc 310}; 311.Ed 312.Pp 313.Va udi_bus 314and 315.Va udi_addr 316contain the topological information for the device. 317.Va udi_devnames 318contains the device names of the connected drivers. 319For example, the 320third 321.Tn USB 322Zip drive connected will be 323.Li umass2 . 324The 325.Va udi_product , udi_vendor 326and 327.Va udi_release 328fields contain self-explanatory descriptions of the device. 329.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass 330and 331.Va udi_protocol 332contain the corresponding values from the device descriptors. 333The 334.Va udi_config 335field shows the current configuration of the device. 336.Pp 337.Va udi_speed 338indicates whether the device is at low speed 339.Pq Dv USB_SPEED_LOW , 340full speed 341.Pq Dv USB_SPEED_FULL 342or high speed 343.Pq Dv USB_SPEED_HIGH . 344The 345.Va udi_power 346field shows the power consumption in milli-amps drawn at 5 volts, 347or zero if the device is self powered. 348.Pp 349If the device is a hub, the 350.Va udi_nports 351field is non-zero, and the 352.Va udi_ports 353field contains the addresses of the connected devices. 354If no device is connected to a port, one of the 355.Dv USB_PORT_* 356values indicates its status. 357.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 358This command retrieves statistics about the controller. 359.Bd -literal 360struct usb_device_stats { 361 u_long uds_requests[4]; 362}; 363.Ed 364.Pp 365The 366.Va uds_requests 367field is indexed by the transfer kind, i.e.\& 368.Dv UE_* , 369and indicates how many transfers of each kind that has been completed 370by the controller. 371.It Dv USB_REQUEST Vt "struct usb_ctl_request" 372This command can be used to execute arbitrary requests on the control pipe. 373This is 374.Em DANGEROUS 375and should be used with great care since it 376can destroy the bus integrity. 377.El 378.Pp 379The include file 380.In bus/usb/usb.h 381contains definitions for the types used by the various 382.Xr ioctl 2 383calls. 384The naming convention of the fields for the various 385.Tn USB 386descriptors exactly follows the naming in the 387.Tn USB 388specification. 389Byte sized fields can be accessed directly, but word (16 bit) 390sized fields must be access by the 391.Fn UGETW field 392and 393.Fn USETW field value 394macros to handle byte order and alignment properly. 395.Pp 396The include file 397.In bus/usb/usbhid.h 398similarly contains the definitions for 399Human Interface Devices 400.Pq Tn HID . 401.Sh USB EVENT INTERFACE 402All 403.Tn USB 404events are reported via the 405.Pa /dev/usb 406device. 407This devices can be opened for reading and each 408.Xr read 2 409will yield an event record (if something has happened). 410The 411.Xr poll 2 412system call can be used to determine if an event record is available 413for reading. 414.Pp 415The event record has the following definition: 416.Bd -literal 417struct usb_event { 418 int ue_type; 419#define USB_EVENT_CTRLR_ATTACH 1 420#define USB_EVENT_CTRLR_DETACH 2 421#define USB_EVENT_DEVICE_ATTACH 3 422#define USB_EVENT_DEVICE_DETACH 4 423#define USB_EVENT_DRIVER_ATTACH 5 424#define USB_EVENT_DRIVER_DETACH 6 425 struct timespec ue_time; 426 union { 427 struct { 428 int ue_bus; 429 } ue_ctrlr; 430 struct usb_device_info ue_device; 431 struct { 432 usb_event_cookie_t ue_cookie; 433 char ue_devname[16]; 434 } ue_driver; 435 } u; 436}; 437.Ed 438The 439.Va ue_type 440field identifies the type of event that is described. 441The possible events are attach/detach of a host controller, 442a device, or a device driver. 443The union contains information 444pertinent to the different types of events. 445Macros, 446.Fn USB_EVENT_IS_ATTACH "ue_type" 447and 448.Fn USB_EVENT_IS_DETACH "ue_type" 449can be used to determine if an event was an 450.Dq attach 451or a 452.Dq detach 453request. 454.Pp 455The 456.Va ue_bus 457contains the number of the 458.Tn USB 459bus for host controller events. 460.Pp 461The 462.Va ue_device 463record contains information about the device in a device event. 464.Pp 465The 466.Va ue_cookie 467is an opaque value that uniquely determines which 468device a device driver has been attached to (i.e., it equals 469the cookie value in the device that the driver attached to). 470.Pp 471The 472.Va ue_devname 473contains the name of the device (driver) as seen in, e.g., 474kernel messages. 475.Pp 476Note that there is a separation between device and device 477driver events. 478A device event is generated when a physical 479.Tn USB 480device is attached or detached. 481A single 482.Tn USB 483device may 484have zero, one, or many device drivers associated with it. 485.Sh SEE ALSO 486The 487.Tn USB 488specifications can be found at: 489.Pp 490.D1 Pa http://www.usb.org/developers/docs/ 491.Pp 492.Xr ehci 4 , 493.Xr ohci 4 , 494.Xr pci 4 , 495.Xr uhci 4 , 496.Xr usbd 8 , 497.Xr usbdevs 8 498.Sh HISTORY 499The 500.Nm 501driver first appeared in 502.Fx 3.0 . 503.Sh AUTHORS 504The 505.Nm 506driver was written by 507.An Lennart Augustsson Aq Mt augustss@carlstedt.se 508for the 509.Nx 510project. 511