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