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