1.\" $NetBSD: usb.4,v 1.101 2013/05/28 12:24:24 kiyohara Exp $ 2.\" 3.\" Copyright (c) 1999-2012 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 30, 2012 31.Dt USB 4 32.Os 33.Sh NAME 34.Nm usb 35.Nd Universal Serial Bus driver 36.Sh SYNOPSIS 37.Cd "ehci* at cardbus? function ?" 38.Cd "ehci* at pci? dev ? function ?" 39.Cd "ohci* at cardbus? function ?" 40.Cd "ohci* at pci? dev ? function ?" 41.Cd "slhci* at isa? port ? irq ?" 42.Cd "slhci* at pcmcia? function ?" 43.Cd "uhci* at cardbus? function ?" 44.Cd "uhci* at pci? dev ? function ?" 45.Cd "usb* at ehci? flags X" 46.Cd "usb* at ohci? flags X" 47.Cd "usb* at uhci? flags X" 48.Cd "usb* at slhci? flags X" 49.Cd "uhub* at usb?" 50.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 51.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 52.Pp 53.Cd options USBVERBOSE 54.Pp 55.In dev/usb/usb.h 56.In dev/usb/usbhid.h 57.Sh DESCRIPTION 58.Nx 59provides machine-independent bus support and drivers for 60.Tn USB 61devices. 62.Pp 63The 64.Nx 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 ) . 73The 74.Tn USB 75bus attaches to the controller and the root hub attaches 76to the bus. 77Further devices, which may include further hubs, 78attach to other hubs. 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 88device controls 89.Tn USB 90hubs and must always be present since there is at least a root hub in any 91.Tn USB 92system. 93.Pp 94The 95.Va flags 96argument to the 97.Va usb 98device affects the order in which the device detection happens 99during cold boot. 100Normally, only the USB host controller and the 101.Va usb 102device are detected during the autoconfiguration when the 103machine is booted. 104The rest of the devices are detected once 105the system becomes functional and the kernel thread for the 106.Va usb 107device is started. 108Sometimes it is desirable to have a device detected early in the 109boot process, e.g., the console keyboard. 110To achieve this use a 111.Va flags 112value of 1. 113.Pp 114.Nx 115supports the following machine-independent 116.Tn USB 117drivers: 118.Ss Storage devices 119.Bl -tag -width 12n -offset ind -compact 120.It Xr umass 4 121.Tn USB 122Mass Storage Devices, e.g., external disk drives 123.El 124.Ss Wired network interfaces 125.Bl -tag -width 12n -offset ind -compact 126.It Xr aue 4 127ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 128.It Xr axe 4 129ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 130.It Xr cdce 4 131USB Communication Device Class Ethernet device 132.It Xr cue 4 133CATC USB-EL1201A USB Ethernet device 134.It Xr kue 4 135Kawasaki LSI KL5KUSB101B USB Ethernet device 136.It Xr udav 4 137Davicom DM9601 10/100 USB Ethernet device 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 ral 4 146Ralink Technology USB IEEE 802.11b/g 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/b/g/n wireless network device 151.It Xr ubt 4 152USB Bluetooth dongles 153.It Xr upgt 4 154Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device 155.It Xr urtwn 4 156Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 157.It Xr zyd 4 158ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 159.El 160.Ss Serial and parallel interfaces 161.Bl -tag -width 12n -offset ind -compact 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 ugensa 4 173USB generic serial adapter 174.It Xr uhmodem 4 175USB Huawei 3G wireless modem device 176.It Xr uipaq 4 177iPAQ USB units 178.It Xr ukyopon 4 179USB Kyocera AIR-EDGE PHONE device 180.It Xr ulpt 4 181USB printer support 182.It Xr umct 4 183MCT USB-RS232 USB serial adapter 184.It Xr umodem 4 185USB modem support 186.It Xr uplcom 4 187Prolific PL-2303 USB serial adapter 188.It Xr uslsa 4 189Silicon Laboratories CP2101/CP2102 based USB serial adapter 190.It Xr uvisor 4 191USB Handspring Visor 192.It Xr uvscom 4 193SUNTAC Slipper U VS-10U USB serial adapter 194.El 195.Ss Audio devices 196.Bl -tag -width 12n -offset ind -compact 197.It Xr uaudio 4 198USB audio devices 199.It Xr umidi 4 200USB MIDI devices 201.It Xr urio 4 202Diamond Multimedia Rio MP3 players 203.El 204.Ss Radio receiver devices 205.Bl -tag -width 12n -offset ind -compact 206.It Xr udsbr 4 207D-Link DSB-R100 USB radio device 208.El 209.Ss Human Interface Devices 210.Bl -tag -width 12n -offset ind -compact 211.It Xr uhid 4 212Generic driver for Human Interface Devices 213.It Xr uhidev 4 214Base driver for all Human Interface Devices 215.It Xr ukbd 4 216.Tn USB 217keyboards that follow the boot protocol 218.It Xr ums 4 219.Tn USB 220mouse devices 221.El 222.Ss Miscellaneous devices 223.Bl -tag -width 12n -offset ind -compact 224.It Xr stuirda 4 225Sigmaltel 4116/4220 USB-IrDA bridge 226.It Xr udsir 4 227KingSun/DonShine USB IrDA bridge 228.It Xr uep 4 229USB eGalax touch-panel 230.It Xr ugen 4 231USB generic devices 232.It Xr uirda 4 233USB IrDA bridges 234.It Xr upl 4 235Prolific based host-to-host adapters 236.It Xr uscanner 4 237USB scanner support 238.It Xr usscanner 4 239SCSI-over-USB scanners 240.It Xr ustir 4 241SigmaTel STIr4200 USB IrDA bridges 242.It Xr utoppy 4 243Topfield TF5000PVR range of digital video recorders 244.It Xr uyap 4 245USB YAP phone firmware loader 246.El 247.Sh INTRODUCTION TO USB 248The 249.Tn USB 2501.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 251.Tn USB 2522.x handles 480 Mb/s. 253Each 254.Tn USB 255has a host controller that is the master of the bus; 256all other devices on the bus only speak when spoken to. 257.Pp 258There can be up to 127 devices (apart from the host controller) 259on a bus, each with its own address. 260The addresses are assigned 261dynamically by the host when each device is attached to the bus. 262.Pp 263Within each device there can be up to 16 endpoints. 264Each endpoint 265is individually addressed and the addresses are static. 266Each of these endpoints will communicate in one of four different modes: 267control, isochronous, bulk, or interrupt. 268A device always has at least one endpoint. 269This endpoint has address 0 and is a control 270endpoint and is used to give commands to and extract basic data, 271such as descriptors, from the device. 272Each endpoint, except the control endpoint, is unidirectional. 273.Pp 274The endpoints in a device are grouped into interfaces. 275An interface is a logical unit within a device; e.g., 276a compound device with both a keyboard and a trackball would present 277one interface for each. 278An interface can sometimes be set into different modes, 279called alternate settings, which affects how it operates. 280Different alternate settings can have different endpoints 281within it. 282.Pp 283A device may operate in different configurations. 284Depending on the 285configuration the device may present different sets of endpoints 286and interfaces. 287.Pp 288Each device located on a hub has several 289.Xr config 1 290locators: 291.Bl -tag -compact -width xxxxxxxxx 292.It Cd port 293this is the number of the port on closest upstream hub. 294.It Cd configuration 295this is the configuration the device must be in for this driver to attach. 296This locator does not set the configuration; it is iterated by the bus 297enumeration. 298.It Cd interface 299this is the interface number within a device that an interface driver 300attaches to. 301.It Cd vendor 302this is the 16 bit vendor id of the device. 303.It Cd product 304this is the 16 bit product id of the device. 305.It Cd release 306this is the 16 bit release (revision) number of the device. 307.El 308The first locator can be used to pin down a particular device 309according to its physical position in the device tree. 310The last three locators can be used to pin down a particular 311device according to what device it actually is. 312.Pp 313The bus enumeration of the 314.Tn USB 315bus proceeds in several steps: 316.Bl -enum 317.It 318Any device specific driver can attach to the device. 319.It 320If none is found, any device class specific driver can attach. 321.It 322If none is found, all configurations are iterated over. 323For each configuration all the interface are iterated over and interface 324drivers can attach. 325If any interface driver attached in a certain 326configuration the iteration over configurations is stopped. 327.It 328If still no drivers have been found, the generic 329.Tn USB 330driver can attach. 331.El 332.Sh USB CONTROLLER INTERFACE 333Use the following to get access to the 334.Tn USB 335specific structures and defines. 336.Bd -literal 337#include \*[Lt]dev/usb/usb.h\*[Gt] 338.Ed 339.Pp 340The 341.Pa /dev/usbN 342can be opened and a few operations can be performed on it. 343The 344.Xr poll 2 345system call will say that I/O is possible on the controller device when a 346.Tn USB 347device has been connected or disconnected to the bus. 348.Pp 349The following 350.Xr ioctl 2 351commands are supported on the controller device: 352.Bl -tag -width xxxxxx 353.\" .It Dv USB_DISCOVER 354.\" This command will cause a complete bus discovery to be initiated. 355.\" If any devices attached or detached from the bus they will be 356.\" processed during this command. 357.\" This is the only way that new devices are found on the bus. 358.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 359This command can be used to retrieve some information about a device 360on the bus. 361The 362.Va addr 363field should be filled before the call and the other fields will 364be filled by information about the device on that address. 365Should no such device exist an error is reported. 366.Bd -literal 367struct usb_device_info { 368 uint8_t udi_bus; 369 uint8_t udi_addr; 370 usb_event_cookie_t udi_cookie; 371 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 372 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 373 char udi_release[8]; 374 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 375 uint16_t udi_productNo; 376 uint16_t udi_vendorNo; 377 uint16_t udi_releaseNo; 378 uint8_t udi_class; 379 uint8_t udi_subclass; 380 uint8_t udi_protocol; 381 uint8_t udi_config; 382 uint8_t udi_speed; 383#define USB_SPEED_LOW 1 384#define USB_SPEED_FULL 2 385#define USB_SPEED_HIGH 3 386 int udi_power; 387 int udi_nports; 388 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 389 uint8_t udi_ports[16]; 390#define USB_PORT_ENABLED 0xff 391#define USB_PORT_SUSPENDED 0xfe 392#define USB_PORT_POWERED 0xfd 393#define USB_PORT_DISABLED 0xfc 394}; 395.Ed 396.Pp 397The 398.Va product , 399.Va vendor , 400.Va release , 401and 402.Va serial 403fields contain self-explanatory descriptions of the device. 404.Pp 405The 406.Va class 407field contains the device class. 408.Pp 409The 410.Va config 411field shows the current configuration of the device. 412.Pp 413The 414.Va lowspeed 415field 416is set if the device is a 417.Tn USB 418low speed device. 419.Pp 420The 421.Va power 422field shows the power consumption in milli-amps drawn at 5 volts, 423or zero if the device is self powered. 424.Pp 425If the device is a hub the 426.Va nports 427field is non-zero and the 428.Va ports 429field contains the addresses of the connected devices. 430If no device is connected to a port one of the 431.Va USB_PORT_* 432values indicates its status. 433.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 434This command retrieves statistics about the controller. 435.Bd -literal 436struct usb_device_stats { 437 u_long uds_requests[4]; 438}; 439.Ed 440.Pp 441The 442.Va requests 443field is indexed by the transfer kind, i.e. 444.Va UE_* , 445and indicates how many transfers of each kind have been completed 446by the controller. 447.It Dv USB_REQUEST Fa "struct usb_ctl_request" 448This command can be used to execute arbitrary requests on the control pipe. 449This is 450.Em DANGEROUS 451and should be used with great care since it 452can destroy the bus integrity. 453.El 454.Pp 455The include file 456.In dev/usb/usb.h 457contains definitions for the types used by the various 458.Xr ioctl 2 459calls. 460The naming convention of the fields for the various 461.Tn USB 462descriptors exactly follows the naming in the 463.Tn USB 464specification. 465Byte sized fields can be accessed directly, but word (16 bit) 466sized fields must be access by the 467.Fn UGETW field 468and 469.Fn USETW field value 470macros to handle byte order and alignment properly. 471.Pp 472The include file 473.In dev/usb/usbhid.h 474similarly contains the definitions for 475Human Interface Devices 476.Pq Tn HID . 477.Sh USB EVENT INTERFACE 478All 479.Tn USB 480events are reported via the 481.Pa /dev/usb 482device. 483This devices can be opened for reading and each 484.Xr read 2 485will yield an event record (if something has happened). 486The 487.Xr poll 2 488system call can be used to determine if an event record is available 489for reading. 490.Pp 491The event record has the following definition: 492.Bd -literal 493struct usb_event { 494 int ue_type; 495#define USB_EVENT_CTRLR_ATTACH 1 496#define USB_EVENT_CTRLR_DETACH 2 497#define USB_EVENT_DEVICE_ATTACH 3 498#define USB_EVENT_DEVICE_DETACH 4 499#define USB_EVENT_DRIVER_ATTACH 5 500#define USB_EVENT_DRIVER_DETACH 6 501 struct timespec ue_time; 502 union { 503 struct { 504 int ue_bus; 505 } ue_ctrlr; 506 struct usb_device_info ue_device; 507 struct { 508 usb_event_cookie_t ue_cookie; 509 char ue_devname[16]; 510 } ue_driver; 511 } u; 512}; 513.Ed 514.Pp 515The 516.Va ue_type 517field identifies the type of event that is described. 518The possible events are attach/detach of a host controller, 519a device, or a device driver. 520The union contains information 521pertinent to the different types of events. 522.Pp 523The 524.Va ue_bus 525contains the number of the 526.Tn USB 527bus for host controller events. 528.Pp 529The 530.Va ue_device 531record contains information about the device in a device event event. 532.Pp 533The 534.Va ue_cookie 535is an opaque value that uniquely determines which 536device a device driver has been attached to (i.e., it equals 537the cookie value in the device that the driver attached to). 538The 539.Va ue_devname 540contains the name of the device (driver) as seen in, e.g., 541kernel messages. 542.Pp 543Note that there is a separation between device and device 544driver events. 545A device event is generated when a physical 546USB device is attached or detached. 547A single USB device may 548have zero, one, or many device drivers associated with it. 549.Sh KERNEL THREADS 550For each USB bus, i.e., for each host controller, there is 551a kernel thread that handles attach and detach of devices on 552that bus. 553The thread is named 554.Va usbN 555where 556.Va N 557is the bus number. 558.Pp 559In addition there is a kernel thread, 560.Va usbtask , 561which handles various minor tasks that are initiated from 562an interrupt context, but need to sleep, e.g., time-out 563abort of transfers. 564.Sh SEE ALSO 565.Xr usbhidaction 1 , 566.Xr usbhidctl 1 , 567.Xr cardbus 4 , 568.Xr ehci 4 , 569.Xr isa 4 , 570.Xr ohci 4 , 571.Xr pci 4 , 572.Xr pcmcia 4 , 573.Xr slhci 4 , 574.Xr uhci 4 , 575.Xr usbdevs 8 576.Rs 577.%T Universal Serial Bus Specifications Documents 578.%U http://www.usb.org/developers/docs/ 579.Re 580.Sh HISTORY 581The 582.Nm 583driver 584appeared in 585.Nx 1.4 . 586.Sh BUGS 587There should be a serial number locator, but 588.Nx 589does not have string valued locators. 590