1.\" $OpenBSD: usb.4,v 1.113 2009/11/07 05:18:09 deraadt Exp $ 2.\" $NetBSD: usb.4,v 1.15 1999/07/29 14:20:32 augustss Exp $ 3.\" 4.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Lennart Augustsson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: November 7 2009 $ 32.Dt USB 4 33.Os 34.Sh NAME 35.Nm usb 36.Nd introduction to Universal Serial Bus support 37.Sh SYNOPSIS 38.Cd "# zaurus specific" 39.Cd "ohci0 at pxaip?" 40.Cd "# all architectures" 41.Cd "ehci* at cardbus?" 42.Cd "uhci* at cardbus?" 43.Cd "ohci* at cardbus?" 44.Cd "ehci* at pci?" 45.Cd "uhci* at pci?" 46.Cd "ohci* at pci?" 47.Cd "usb* at ehci? flags 0x00" 48.Cd "usb* at uhci? flags 0x00" 49.Cd "usb* at ohci? flags 0x00" 50.Cd "uhub* at usb?" 51.Cd "uhub* at uhub?" 52.Pp 53.Cd option USBVERBOSE 54.Pp 55.Fd "#include <dev/usb/usb.h>" 56.Fd "#include <dev/usb/usbhid.h>" 57.Sh DESCRIPTION 58.Ox 59provides machine-independent bus support and drivers for Universal Serial Bus 60.Pq Tn USB 61devices. 62.Pp 63The 64.Ox 65.Nm 66driver has three layers (like 67.Xr scsi 4 68and 69.Xr pcmcia 4 ) : 70the controller, the bus, and the device layer. 71The controller attaches to a physical bus (like 72.Xr pci 4 73or 74.Xr cardbus 4 ) . 75The 76.Tn USB 77bus attaches to the controller and the root hub attaches to the 78.Tn USB 79bus. 80Devices, which may include further hubs, attach to the root hub. 81The attachment forms the same tree structure as the physical 82.Tn USB 83device tree. 84For each 85.Tn USB 86device there may be additional drivers attached to it. 87.Pp 88The 89.Cm uhub 90driver controls 91.Tn USB 92hubs and must always be present since there is at least one root hub in any 93.Tn USB 94system. 95.Pp 96The 97.Cm flags 98are used to specify if the devices on the 99.Tn USB 100bus should be probed 101early in the boot process. 102If the 103.Cm flags 104are specified with a value of 1, the 105.Tn USB 106bus will be probed when the 107.Tn USB 108host device is attached instead of waiting 109until kernel processes start running. 110.Pp 111.Ox 112provides support for the following devices. 113Note that not all architectures support all devices. 114.Ss Storage devices 115.Bl -tag -width 12n -offset ind -compact 116.It Xr umass 4 117.Tn USB 118Mass Storage Devices, e.g., external disk drives 119.El 120.Ss Wired network interfaces 121.Bl -tag -width 12n -offset ind -compact 122.It Xr aue 4 123ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 124.It Xr axe 4 125ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 126.It Xr cdce 4 127USB Communication Device Class Ethernet device 128.It Xr cue 4 129CATC USB-EL1201A USB Ethernet device 130.It Xr kue 4 131Kawasaki LSI KL5KUSB101B USB Ethernet device 132.It Xr mos 4 133MOSCHIP MCS7730/7830 10/100 USB 2.0 Ethernet device 134.It Xr udav 4 135Davicom DM9601 10/100 USB Ethernet device 136.It Xr ueagle 4 137Analog Devices Eagle ADSL modems 138.It Xr url 4 139Realtek RTL8150L 10/100 USB Ethernet device 140.El 141.Ss Wireless network interfaces 142.Bl -tag -width 12n -offset ind -compact 143.It Xr atu 4 144Atmel AT76C50x IEEE 802.11b wireless network device 145.It Xr otus 4 146Atheros USB IEEE 802.11a/g/n wireless network device 147.It Xr rum 4 148Ralink Technology USB IEEE 802.11a/b/g wireless network device 149.It Xr run 4 150Ralink Technology USB IEEE 802.11a/g/n wireless network device 151.It Xr uath 4 152Atheros USB IEEE 802.11a/b/g wireless network device 153.It Xr ubt 4 154Bluetooth adapters 155.It Xr upgt 4 156Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network device 157.It Xr ural 4 158Ralink Technology USB IEEE 802.11b/g wireless network device 159.It Xr urtw 4 160Realtek RTL8187L/RTL8187B USB IEEE 802.11b/g wireless network device 161.It Xr wi 4 162Intersil PRISM 2-3 IEEE 802.11b wireless network device 163.It Xr zyd 4 164ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 165.El 166.Ss Serial and parallel interfaces 167.Bl -tag -width 12n -offset ind -compact 168.It Xr moscom 4 169MosChip Semiconductor MCS7703 based USB serial adapter 170.It Xr uark 4 171Arkmicro Technologies ARK3116 based USB serial adapter 172.It Xr ubsa 4 173Belkin USB serial adapter 174.It Xr uchcom 4 175WinChipHead CH341/340 based USB serial adapter 176.It Xr ucom 4 177USB tty support 178.It Xr ucycom 4 179Cypress microcontroller based USB serial adapter 180.It Xr uftdi 4 181FTDI USB serial adapter 182.It Xr uipaq 4 183iPAQ USB units 184.It Xr ulpt 4 185USB printer support 186.It Xr umct 4 187MCT USB-RS232 USB serial adapter 188.It Xr umodem 4 189USB modem support 190.It Xr umsm 4 191Qualcomm MSM modem device 192.It Xr uplcom 4 193Prolific PL-2303 USB serial adapter 194.It Xr uslcom 4 195Silicon Laboratories CP2101/CP2102 based USB serial adapter 196.It Xr uticom 4 197Texas Instruments TUSB3410 USB serial adapter 198.It Xr uvisor 4 199USB Handspring Visor 200.It Xr uvscom 4 201SUNTAC Slipper U VS-10U USB serial adapter 202.El 203.Ss Audio devices 204.Bl -tag -width 12n -offset ind -compact 205.It Xr uaudio 4 206USB audio devices 207.It Xr umidi 4 208USB MIDI devices 209.It Xr urio 4 210Diamond Multimedia Rio MP3 players 211.El 212.Ss Video devices 213.Bl -tag -width 12n -offset ind -compact 214.It Xr udl 4 215DisplayLink DL-120 / DL-160 USB display devices 216.It Xr uvideo 4 217USB video devices 218.El 219.Ss Time receiver devices 220.Bl -tag -width 12n -offset ind -compact 221.It Xr udcf 4 222Gude ADS Expert mouseCLOCK USB timedelta sensor 223.It Xr umbg 4 224Meinberg Funkuhren USB5131 timedelta sensor 225.El 226.Ss Radio receiver devices 227.Bl -tag -width 12n -offset ind -compact 228.It Xr udsbr 4 229D-Link DSB-R100 USB radio device 230.El 231.Ss Human Interface Devices 232.Bl -tag -width 12n -offset ind -compact 233.It Xr tpms 4 234Apple touchpad mouse 235.It Xr uhid 4 236Generic driver for Human Interface Devices 237.It Xr uhidev 4 238Base driver for all Human Interface Devices 239.It Xr ukbd 4 240.Tn USB 241keyboards that follow the boot protocol 242.It Xr ums 4 243.Tn USB 244mouse devices 245.El 246.Ss Miscellaneous devices 247.Bl -tag -width 12n -offset ind -compact 248.It Xr uberry 4 249Research In Motion Blackberry 250.It Xr ugen 4 251USB generic device support 252.It Xr uow 4 253Maxim/Dallas DS2490 USB 1-Wire adapter 254.It Xr upl 4 255Prolific based host-to-host adapters 256.It Xr uscanner 4 257USB scanner support 258.It Xr usscanner 4 259SCSI-over-USB scanners 260.It Xr uts 4 261USB touchscreen support 262.It Xr uyap 4 263USB YAP phone firmware loader 264.El 265.Sh INTRODUCTION TO USB 266There are different versions of the 267.Tn USB 268which provide different speeds. 269.Tn USB 2702 operates at 480Mb/s, while 271.Tn USB 272versions 1 and 1.1 operate at 12 Mb/s and 1.5 Mb/s for low speed devices. 273Each 274.Tn USB 275has a host controller that is the master of the bus; 276all other devices on the bus only speak when spoken to. 277.Pp 278There can be up to 127 devices (apart from the host controller) 279on a bus, each with its own address. 280The addresses are assigned 281dynamically by the host when each device is attached to the bus. 282.Pp 283Within each device there can be up to 16 endpoints. 284Each endpoint 285is individually addressed and the addresses are static. 286Each of these endpoints will communicate in one of four different modes: 287control, isochronous, bulk, or interrupt. 288A device always has at least one endpoint. 289This is a control endpoint at address 0 290and is used to give commands to the device and extract basic data, 291such as descriptors, from the device. 292Each endpoint, except the control endpoint, is unidirectional. 293.Pp 294The endpoints in a device are grouped into interfaces. 295An interface is a logical unit within a device; e.g., 296a compound device with both a keyboard and a trackball would present 297one interface for each. 298An interface can sometimes be set into different modes, 299called alternate settings, which affects how it operates. 300Different alternate settings can have different endpoints 301within it. 302.Pp 303A device may operate in different configurations. 304Depending on the 305configuration the device may present different sets of endpoints 306and interfaces. 307.Pp 308Each device located on a hub has several 309.Xr config 8 310locators: 311.Pp 312.Bl -tag -width configuration -compact 313.It Cd port 314Number of the port on closest upstream hub. 315.It Cd configuration 316Configuration the device must be in for this driver to attach. 317This locator does not set the configuration; it is iterated by the bus 318enumeration. 319.It Cd interface 320Interface number within a device that an interface driver attaches to. 321.It Cd vendor 32216-bit vendor ID of the device. 323.It Cd product 32416-bit product ID of the device. 325.It Cd release 32616-bit release (revision) number of the device. 327.El 328.Pp 329The first locator can be used to pin down a particular device 330according to its physical position in the device tree. 331The last three locators can be used to pin down a particular 332device according to what device it actually is. 333.Pp 334The bus enumeration of the 335.Tn USB 336bus proceeds in several steps: 337.Bl -enum 338.It 339Any device-specific driver can attach to the device. 340.It 341If none is found, any device class specific driver can attach. 342.It 343If none is found, all configurations are iterated over. 344For each configuration all the interfaces are iterated over and interface 345drivers can attach. 346If any interface driver attached in a certain 347configuration, the iteration over configurations is stopped. 348.It 349If still no drivers have been found, the generic 350.Tn USB 351driver can attach. 352.El 353.Sh USB CONTROLLER INTERFACE 354Use the following to get access to the 355.Tn USB 356specific structures and defines: 357.Bd -literal 358.Fd #include <dev/usb/usb.h> 359.Ed 360.Pp 361The 362.Pa /dev/usbN 363device can be opened and a few operations can be performed on it. 364The 365.Xr poll 2 366system call will say that I/O is possible on the controller device when a 367.Tn USB 368device has been connected or disconnected to the bus. 369.Pp 370The following 371.Xr ioctl 2 372commands are supported on the controller device: 373.Bl -tag -width xxxxxx 374.\" .It Dv USB_DISCOVER 375.\" This command will cause a complete bus discovery to be initiated. 376.\" If any devices attached or detached from the bus they will be 377.\" processed during this command. 378.\" This is the only way that new devices are found on the bus. 379.It Dv USB_DEVICEINFO Fa "struct usb_device_info *" 380This command can be used to retrieve some information about a device 381on the bus. 382The 383.Va udi_addr 384field should be filled before the call and the other fields will 385be filled by information about the device on that address. 386Should no such device exist, an error is reported. 387.Bd -literal 388#define USB_MAX_DEVNAMES 4 389#define USB_MAX_DEVNAMELEN 16 390struct usb_device_info { 391 u_int8_t udi_bus; 392 u_int8_t udi_addr; /* device address */ 393 usb_event_cookie_t udi_cookie; 394 char udi_product[USB_MAX_STRING_LEN]; 395 char udi_vendor[USB_MAX_STRING_LEN]; 396 char udi_release[8]; 397 u_int16_t udi_productNo; 398 u_int16_t udi_vendorNo; 399 u_int16_t udi_releaseNo; 400 u_int8_t udi_class; 401 u_int8_t udi_subclass; 402 u_int8_t udi_protocol; 403 u_int8_t udi_config; 404 u_int8_t udi_speed; 405#define USB_SPEED_LOW 1 406#define USB_SPEED_FULL 2 407#define USB_SPEED_HIGH 3 408 int udi_power; /* power consumption */ 409 int udi_nports; 410 char udi_devnames[USB_MAX_DEVNAMES] 411 [USB_MAX_DEVNAMELEN]; 412 u_int8_t udi_ports[16]; /* hub only */ 413#define USB_PORT_ENABLED 0xff 414#define USB_PORT_SUSPENDED 0xfe 415#define USB_PORT_POWERED 0xfd 416#define USB_PORT_DISABLED 0xfc 417}; 418.Ed 419.Pp 420The 421.Va udi_bus 422field contains the device unit number of the device. 423.Pp 424The 425.Va udi_product , 426.Va udi_vendor , 427and 428.Va udi_release 429fields contain self-explanatory descriptions of the device. 430The 431.Va udi_productNo , 432.Va udi_vendorNo , 433and 434.Va udi_releaseNo 435fields contain numeric identifiers for the device. 436.Pp 437The 438.Va udi_class 439and 440.Va udi_subclass 441fields contain the device class and subclass. 442.Pp 443The 444.Va udi_config 445field shows the current configuration of the device. 446.Pp 447The 448.Va udi_protocol 449field contains the device protocol as given from the device. 450.Pp 451The 452.Va udi_speed 453field 454contains the speed of the device. 455.Pp 456The 457.Va udi_power 458field shows the power consumption in milli-amps drawn at 5 volts 459or is zero if the device is self powered. 460.Pp 461The 462.Va udi_devnames 463field contains the names and instance numbers of the device drivers 464for the devices attached to this device. 465.Pp 466If the device is a hub, the 467.Va udi_nports 468field is non-zero and the 469.Va udi_ports 470field contains the addresses of the connected devices. 471If no device is connected to a port, one of the 472.Dv USB_PORT_* 473values indicates its status. 474.It Dv USB_DEVICESTATS Fa "struct usb_device_stats *" 475This command retrieves statistics about the controller. 476.Bd -unfilled 477struct usb_device_stats { 478 u_long uds_requests[4]; 479}; 480.Ed 481.Pp 482The 483.Va uds_requests 484field is indexed by the transfer kind, i.e.\& 485.Dv UE_* , 486and indicates how many transfers of each kind have been completed 487by the controller. 488.It Dv USB_REQUEST Fa "struct usb_ctl_request *" 489This command can be used to execute arbitrary requests on the control pipe. 490This is 491.Em DANGEROUS 492and should be used with great care since it 493can destroy the bus integrity. 494.Pp 495The 496.Vt usb_ctl_request 497structure has the following definition: 498.Bd -literal 499typedef struct { 500 uByte bmRequestType; 501 uByte bRequest; 502 uWord wValue; 503 uWord wIndex; 504 uWord wLength; 505} __packed usb_device_request_t; 506 507struct usb_ctl_request { 508 int ucr_addr; 509 usb_device_request_t ucr_request; 510 void *ucr_data; 511 int ucr_flags; 512#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 513 int ucr_actlen; /* actual length transferred */ 514}; 515.Ed 516.Pp 517The 518.Va ucr_addr 519field identifies the device on which to perform the request. 520The 521.Va ucr_request 522field identifies parameters of the request, such as length and type. 523The 524.Va ucr_data 525field contains the location where data will be read from or written to. 526The 527.Va ucr_flags 528field specifies options for the request, and the 529.Va ucr_actlen 530field contains the actual length transferred as the result of the request. 531.El 532.Pp 533The include file 534.Aq Pa dev/usb/usb.h 535contains definitions for the types used by the various 536.Xr ioctl 2 537calls. 538The naming convention of the fields for the various 539.Tn USB 540descriptors exactly follows the naming in the 541.Tn USB 542specification. 543Byte sized fields can be accessed directly, but word (16-bit) 544sized fields must be accessed by the 545.Fn UGETW field 546and 547.Fn USETW field value 548macros and double word (32-bit) sized fields must be accessed by the 549.Fn UGETDW field 550and 551.Fn USETDW field value 552macros to handle byte order and alignment properly. 553.Pp 554The include file 555.Aq Pa dev/usb/usbhid.h 556similarly contains the definitions for 557Human Interface Devices 558.Pq Tn HID . 559.Sh SEE ALSO 560.Xr usbhidaction 1 , 561.Xr usbhidctl 1 , 562.Xr ioctl 2 , 563.Xr ehci 4 , 564.Xr ohci 4 , 565.Xr uhci 4 , 566.Xr config 8 , 567.Xr usbdevs 8 568.Pp 569The 570.Tn USB 571specifications can be found at: 572.Pp 573.Dl http://www.usb.org/developers/docs/ 574.Sh HISTORY 575The 576.Nm 577driver 578appeared in 579.Ox 2.6 . 580