1.\" $OpenBSD: usb.4,v 1.126 2011/01/06 08:24:57 jmc 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: January 6 2011 $ 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.It Xr urndis 4 141USB Remote NDIS Ethernet device 142.El 143.Ss Wireless network interfaces 144.Bl -tag -width 12n -offset ind -compact 145.It Xr athn 4 146Atheros IEEE 802.11a/g/n wireless network device 147.It Xr atu 4 148Atmel AT76C50x IEEE 802.11b wireless network device 149.It Xr otus 4 150Atheros USB IEEE 802.11a/g/n wireless network device 151.It Xr rsu 4 152Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device 153.It Xr rum 4 154Ralink Technology USB IEEE 802.11a/b/g wireless network device 155.It Xr run 4 156Ralink Technology USB IEEE 802.11a/g/n wireless network device 157.It Xr uath 4 158Atheros USB IEEE 802.11a/b/g wireless network device 159.It Xr ubt 4 160Bluetooth adapters 161.It Xr upgt 4 162Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network device 163.It Xr ural 4 164Ralink Technology USB IEEE 802.11b/g wireless network device 165.It Xr urtw 4 166Realtek RTL8187L/RTL8187B USB IEEE 802.11b/g wireless network device 167.It Xr urtwn 4 168Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 169.It Xr wi 4 170Intersil PRISM 2-3 IEEE 802.11b wireless network device 171.It Xr zyd 4 172ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 173.El 174.Ss Serial and parallel interfaces 175.Bl -tag -width 12n -offset ind -compact 176.It Xr moscom 4 177MosChip Semiconductor MCS7703 based USB serial adapter 178.It Xr uark 4 179Arkmicro Technologies ARK3116 based USB serial adapter 180.It Xr ubsa 4 181Belkin USB serial adapter 182.It Xr uchcom 4 183WinChipHead CH341/340 based USB serial adapter 184.It Xr ucom 4 185USB tty support 186.It Xr uftdi 4 187FTDI USB serial adapter 188.It Xr uipaq 4 189iPAQ USB units 190.It Xr ulpt 4 191USB printer support 192.It Xr umct 4 193MCT USB-RS232 USB serial adapter 194.It Xr umodem 4 195USB modem support 196.It Xr umsm 4 197Qualcomm MSM modem device 198.It Xr uplcom 4 199Prolific PL-2303 USB serial adapter 200.It Xr uslcom 4 201Silicon Laboratories CP2101/CP2102 based USB serial adapter 202.It Xr uticom 4 203Texas Instruments TUSB3410 USB serial adapter 204.It Xr uvisor 4 205USB Handspring Visor 206.It Xr uvscom 4 207SUNTAC Slipper U VS-10U USB serial adapter 208.El 209.Ss Audio devices 210.Bl -tag -width 12n -offset ind -compact 211.It Xr uaudio 4 212USB audio devices 213.It Xr umidi 4 214USB MIDI devices 215.It Xr urio 4 216Diamond Multimedia Rio MP3 players 217.El 218.Ss Video devices 219.Bl -tag -width 12n -offset ind -compact 220.It Xr udl 4 221DisplayLink DL-120 / DL-160 USB display devices 222.It Xr uvideo 4 223USB video devices 224.El 225.Ss Time receiver devices 226.Bl -tag -width 12n -offset ind -compact 227.It Xr udcf 4 228Gude ADS Expert mouseCLOCK USB timedelta sensor 229.It Xr umbg 4 230Meinberg Funkuhren USB5131 timedelta sensor 231.El 232.Ss Radio receiver devices 233.Bl -tag -width 12n -offset ind -compact 234.It Xr udsbr 4 235D-Link DSB-R100 USB radio device 236.El 237.Ss Human Interface Devices 238.Bl -tag -width 12n -offset ind -compact 239.It Xr tpms 4 240Apple touchpad mouse 241.It Xr ucycom 4 242Cypress microcontroller based USB serial adapter 243.It Xr uhid 4 244Generic driver for Human Interface Devices 245.It Xr uhidev 4 246Base driver for all Human Interface Devices 247.It Xr uhts 4 248.Tn USB 249HID touchscreen support 250.It Xr ukbd 4 251.Tn USB 252keyboards that follow the boot protocol 253.It Xr ums 4 254.Tn USB 255mouse devices 256.It Xr uthum 4 257TEMPer USB temperature and humidity sensor 258.It Xr utrh 4 259USBRH temperature and humidity sensor 260.El 261.Ss Miscellaneous devices 262.Bl -tag -width 12n -offset ind -compact 263.It Xr uberry 4 264Research In Motion Blackberry 265.It Xr ugen 4 266USB generic device support 267.It Xr uow 4 268Maxim/Dallas DS2490 USB 1-Wire adapter 269.It Xr upl 4 270Prolific based host-to-host adapters 271.It Xr uscanner 4 272USB scanner support 273.It Xr uts 4 274USB touchscreen support 275.It Xr uyap 4 276USB YAP phone firmware loader 277.El 278.Sh INTRODUCTION TO USB 279There are different versions of the 280.Tn USB 281which provide different speeds. 282.Tn USB 2832 operates at 480Mb/s, while 284.Tn USB 285versions 1 and 1.1 operate at 12 Mb/s and 1.5 Mb/s for low speed devices. 286Each 287.Tn USB 288has a host controller that is the master of the bus; 289all other devices on the bus only speak when spoken to. 290.Pp 291There can be up to 127 devices (apart from the host controller) 292on a bus, each with its own address. 293The addresses are assigned 294dynamically by the host when each device is attached to the bus. 295.Pp 296Within each device there can be up to 16 endpoints. 297Each endpoint 298is individually addressed and the addresses are static. 299Each of these endpoints will communicate in one of four different modes: 300control, isochronous, bulk, or interrupt. 301A device always has at least one endpoint. 302This is a control endpoint at address 0 303and is used to give commands to the device and extract basic data, 304such as descriptors, from the device. 305Each endpoint, except the control endpoint, is unidirectional. 306.Pp 307The endpoints in a device are grouped into interfaces. 308An interface is a logical unit within a device; e.g., 309a compound device with both a keyboard and a trackball would present 310one interface for each. 311An interface can sometimes be set into different modes, 312called alternate settings, which affects how it operates. 313Different alternate settings can have different endpoints 314within it. 315.Pp 316A device may operate in different configurations. 317Depending on the 318configuration the device may present different sets of endpoints 319and interfaces. 320.Pp 321Each device located on a hub has several 322.Xr config 8 323locators: 324.Pp 325.Bl -tag -width configuration -compact 326.It Cd port 327Number of the port on closest upstream hub. 328.It Cd configuration 329Configuration the device must be in for this driver to attach. 330This locator does not set the configuration; it is iterated by the bus 331enumeration. 332.It Cd interface 333Interface number within a device that an interface driver attaches to. 334.It Cd vendor 33516-bit vendor ID of the device. 336.It Cd product 33716-bit product ID of the device. 338.It Cd release 33916-bit release (revision) number of the device. 340.El 341.Pp 342The first locator can be used to pin down a particular device 343according to its physical position in the device tree. 344The last three locators can be used to pin down a particular 345device according to what device it actually is. 346.Pp 347The bus enumeration of the 348.Tn USB 349bus proceeds in several steps: 350.Bl -enum 351.It 352Any device-specific driver can attach to the device. 353.It 354If none is found, any device class specific driver can attach. 355.It 356If none is found, all configurations are iterated over. 357For each configuration all the interfaces are iterated over and interface 358drivers can attach. 359If any interface driver attached in a certain 360configuration, the iteration over configurations is stopped. 361.It 362If still no drivers have been found, the generic 363.Tn USB 364driver can attach. 365.El 366.Sh USB CONTROLLER INTERFACE 367Use the following to get access to the 368.Tn USB 369specific structures and defines: 370.Bd -literal -offset indent 371#include <dev/usb/usb.h> 372.Ed 373.Pp 374The 375.Pa /dev/usbN 376device can be opened and a few operations can be performed on it. 377The 378.Xr poll 2 379system call will say that I/O is possible on the controller device when a 380.Tn USB 381device has been connected or disconnected to the bus. 382.Pp 383The following 384.Xr ioctl 2 385commands are supported on the controller device: 386.Bl -tag -width xxxxxx 387.\" .It Dv USB_DISCOVER 388.\" This command will cause a complete bus discovery to be initiated. 389.\" If any devices attached or detached from the bus they will be 390.\" processed during this command. 391.\" This is the only way that new devices are found on the bus. 392.It Dv USB_DEVICEINFO Fa "struct usb_device_info *" 393This command can be used to retrieve some information about a device 394on the bus. 395The 396.Va udi_addr 397field should be filled before the call and the other fields will 398be filled by information about the device on that address. 399Should no such device exist, an error is reported. 400.Bd -literal 401#define USB_MAX_DEVNAMES 4 402#define USB_MAX_DEVNAMELEN 16 403struct usb_device_info { 404 u_int8_t udi_bus; 405 u_int8_t udi_addr; /* device address */ 406 usb_event_cookie_t udi_cookie; 407 char udi_product[USB_MAX_STRING_LEN]; 408 char udi_vendor[USB_MAX_STRING_LEN]; 409 char udi_release[8]; 410 u_int16_t udi_productNo; 411 u_int16_t udi_vendorNo; 412 u_int16_t udi_releaseNo; 413 u_int8_t udi_class; 414 u_int8_t udi_subclass; 415 u_int8_t udi_protocol; 416 u_int8_t udi_config; 417 u_int8_t udi_speed; 418#define USB_SPEED_LOW 1 419#define USB_SPEED_FULL 2 420#define USB_SPEED_HIGH 3 421 int udi_power; /* power consumption */ 422 int udi_nports; 423 char udi_devnames[USB_MAX_DEVNAMES] 424 [USB_MAX_DEVNAMELEN]; 425 u_int8_t udi_ports[16]; /* hub only */ 426#define USB_PORT_ENABLED 0xff 427#define USB_PORT_SUSPENDED 0xfe 428#define USB_PORT_POWERED 0xfd 429#define USB_PORT_DISABLED 0xfc 430}; 431.Ed 432.Pp 433The 434.Va udi_bus 435field contains the device unit number of the device. 436.Pp 437The 438.Va udi_product , 439.Va udi_vendor , 440and 441.Va udi_release 442fields contain self-explanatory descriptions of the device. 443The 444.Va udi_productNo , 445.Va udi_vendorNo , 446and 447.Va udi_releaseNo 448fields contain numeric identifiers for the device. 449.Pp 450The 451.Va udi_class 452and 453.Va udi_subclass 454fields contain the device class and subclass. 455.Pp 456The 457.Va udi_config 458field shows the current configuration of the device. 459.Pp 460The 461.Va udi_protocol 462field contains the device protocol as given from the device. 463.Pp 464The 465.Va udi_speed 466field 467contains the speed of the device. 468.Pp 469The 470.Va udi_power 471field shows the power consumption in milli-amps drawn at 5 volts 472or is zero if the device is self powered. 473.Pp 474The 475.Va udi_devnames 476field contains the names and instance numbers of the device drivers 477for the devices attached to this device. 478.Pp 479If the device is a hub, the 480.Va udi_nports 481field is non-zero and the 482.Va udi_ports 483field contains the addresses of the connected devices. 484If no device is connected to a port, one of the 485.Dv USB_PORT_* 486values indicates its status. 487.It Dv USB_DEVICESTATS Fa "struct usb_device_stats *" 488This command retrieves statistics about the controller. 489.Bd -unfilled 490struct usb_device_stats { 491 u_long uds_requests[4]; 492}; 493.Ed 494.Pp 495The 496.Va uds_requests 497field is indexed by the transfer kind, i.e.\& 498.Dv UE_* , 499and indicates how many transfers of each kind have been completed 500by the controller. 501.It Dv USB_REQUEST Fa "struct usb_ctl_request *" 502This command can be used to execute arbitrary requests on the control pipe. 503This is 504.Em DANGEROUS 505and should be used with great care since it 506can destroy the bus integrity. 507.Pp 508The 509.Vt usb_ctl_request 510structure has the following definition: 511.Bd -literal 512typedef struct { 513 uByte bmRequestType; 514 uByte bRequest; 515 uWord wValue; 516 uWord wIndex; 517 uWord wLength; 518} __packed usb_device_request_t; 519 520struct usb_ctl_request { 521 int ucr_addr; 522 usb_device_request_t ucr_request; 523 void *ucr_data; 524 int ucr_flags; 525#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 526 int ucr_actlen; /* actual length transferred */ 527}; 528.Ed 529.Pp 530The 531.Va ucr_addr 532field identifies the device on which to perform the request. 533The 534.Va ucr_request 535field identifies parameters of the request, such as length and type. 536The 537.Va ucr_data 538field contains the location where data will be read from or written to. 539The 540.Va ucr_flags 541field specifies options for the request, and the 542.Va ucr_actlen 543field contains the actual length transferred as the result of the request. 544.El 545.Pp 546The include file 547.Aq Pa dev/usb/usb.h 548contains definitions for the types used by the various 549.Xr ioctl 2 550calls. 551The naming convention of the fields for the various 552.Tn USB 553descriptors exactly follows the naming in the 554.Tn USB 555specification. 556Byte sized fields can be accessed directly, but word (16-bit) 557sized fields must be accessed by the 558.Fn UGETW field 559and 560.Fn USETW field value 561macros and double word (32-bit) sized fields must be accessed by the 562.Fn UGETDW field 563and 564.Fn USETDW field value 565macros to handle byte order and alignment properly. 566.Pp 567The include file 568.Aq Pa dev/usb/usbhid.h 569similarly contains the definitions for 570Human Interface Devices 571.Pq Tn HID . 572.Sh SEE ALSO 573.Xr usbhidaction 1 , 574.Xr usbhidctl 1 , 575.Xr ioctl 2 , 576.Xr ehci 4 , 577.Xr ohci 4 , 578.Xr uhci 4 , 579.Xr config 8 , 580.Xr usbdevs 8 581.Pp 582The 583.Tn USB 584specifications can be found at: 585.Pp 586.Dl http://www.usb.org/developers/docs/ 587.Sh HISTORY 588The 589.Nm 590driver 591appeared in 592.Ox 2.6 . 593