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