1.\" $NetBSD: usb.4,v 1.102 2013/10/26 09:16:19 nonaka 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 axen 4 131ASIX Electronics AX88178a/AX88179 10/100/Gigabit USB Ethernet device 132.It Xr cdce 4 133USB Communication Device Class Ethernet device 134.It Xr cue 4 135CATC USB-EL1201A USB Ethernet device 136.It Xr kue 4 137Kawasaki LSI KL5KUSB101B USB Ethernet device 138.It Xr udav 4 139Davicom DM9601 10/100 USB Ethernet device 140.It Xr url 4 141Realtek RTL8150L 10/100 USB Ethernet device 142.El 143.Ss Wireless network interfaces 144.Bl -tag -width 12n -offset ind -compact 145.It Xr atu 4 146Atmel AT76C50x IEEE 802.11b wireless network device 147.It Xr ral 4 148Ralink Technology USB IEEE 802.11b/g wireless network device 149.It Xr rum 4 150Ralink Technology USB IEEE 802.11a/b/g wireless network device 151.It Xr run 4 152Ralink Technology USB IEEE 802.11a/b/g/n wireless network device 153.It Xr ubt 4 154USB Bluetooth dongles 155.It Xr upgt 4 156Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device 157.It Xr urtwn 4 158Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 159.It Xr zyd 4 160ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 161.El 162.Ss Serial and parallel interfaces 163.Bl -tag -width 12n -offset ind -compact 164.It Xr ubsa 4 165Belkin USB serial adapter 166.It Xr uchcom 4 167WinChipHead CH341/340 based USB serial adapter 168.It Xr ucom 4 169USB tty support 170.It Xr ucycom 4 171Cypress microcontroller based USB serial adapter 172.It Xr uftdi 4 173FT8U100AX USB serial adapter 174.It Xr ugensa 4 175USB generic serial adapter 176.It Xr uhmodem 4 177USB Huawei 3G wireless modem device 178.It Xr uipaq 4 179iPAQ USB units 180.It Xr ukyopon 4 181USB Kyocera AIR-EDGE PHONE device 182.It Xr ulpt 4 183USB printer support 184.It Xr umct 4 185MCT USB-RS232 USB serial adapter 186.It Xr umodem 4 187USB modem support 188.It Xr uplcom 4 189Prolific PL-2303 USB serial adapter 190.It Xr uslsa 4 191Silicon Laboratories CP2101/CP2102 based USB serial adapter 192.It Xr uvisor 4 193USB Handspring Visor 194.It Xr uvscom 4 195SUNTAC Slipper U VS-10U USB serial adapter 196.El 197.Ss Audio devices 198.Bl -tag -width 12n -offset ind -compact 199.It Xr uaudio 4 200USB audio devices 201.It Xr umidi 4 202USB MIDI devices 203.It Xr urio 4 204Diamond Multimedia Rio MP3 players 205.El 206.Ss Radio receiver devices 207.Bl -tag -width 12n -offset ind -compact 208.It Xr udsbr 4 209D-Link DSB-R100 USB radio device 210.El 211.Ss Human Interface Devices 212.Bl -tag -width 12n -offset ind -compact 213.It Xr uhid 4 214Generic driver for Human Interface Devices 215.It Xr uhidev 4 216Base driver for all Human Interface Devices 217.It Xr ukbd 4 218.Tn USB 219keyboards that follow the boot protocol 220.It Xr ums 4 221.Tn USB 222mouse devices 223.El 224.Ss Miscellaneous devices 225.Bl -tag -width 12n -offset ind -compact 226.It Xr stuirda 4 227Sigmaltel 4116/4220 USB-IrDA bridge 228.It Xr udsir 4 229KingSun/DonShine USB IrDA bridge 230.It Xr uep 4 231USB eGalax touch-panel 232.It Xr ugen 4 233USB generic devices 234.It Xr uirda 4 235USB IrDA bridges 236.It Xr upl 4 237Prolific based host-to-host adapters 238.It Xr uscanner 4 239USB scanner support 240.It Xr usscanner 4 241SCSI-over-USB scanners 242.It Xr ustir 4 243SigmaTel STIr4200 USB IrDA bridges 244.It Xr utoppy 4 245Topfield TF5000PVR range of digital video recorders 246.It Xr uyap 4 247USB YAP phone firmware loader 248.El 249.Sh INTRODUCTION TO USB 250The 251.Tn USB 2521.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 253.Tn USB 2542.x handles 480 Mb/s. 255Each 256.Tn USB 257has a host controller that is the master of the bus; 258all other devices on the bus only speak when spoken to. 259.Pp 260There can be up to 127 devices (apart from the host controller) 261on a bus, each with its own address. 262The addresses are assigned 263dynamically by the host when each device is attached to the bus. 264.Pp 265Within each device there can be up to 16 endpoints. 266Each endpoint 267is individually addressed and the addresses are static. 268Each of these endpoints will communicate in one of four different modes: 269control, isochronous, bulk, or interrupt. 270A device always has at least one endpoint. 271This endpoint has address 0 and is a control 272endpoint and is used to give commands to and extract basic data, 273such as descriptors, from the device. 274Each endpoint, except the control endpoint, is unidirectional. 275.Pp 276The endpoints in a device are grouped into interfaces. 277An interface is a logical unit within a device; e.g., 278a compound device with both a keyboard and a trackball would present 279one interface for each. 280An interface can sometimes be set into different modes, 281called alternate settings, which affects how it operates. 282Different alternate settings can have different endpoints 283within it. 284.Pp 285A device may operate in different configurations. 286Depending on the 287configuration the device may present different sets of endpoints 288and interfaces. 289.Pp 290Each device located on a hub has several 291.Xr config 1 292locators: 293.Bl -tag -compact -width xxxxxxxxx 294.It Cd port 295this is the number of the port on closest upstream hub. 296.It Cd configuration 297this is the configuration the device must be in for this driver to attach. 298This locator does not set the configuration; it is iterated by the bus 299enumeration. 300.It Cd interface 301this is the interface number within a device that an interface driver 302attaches to. 303.It Cd vendor 304this is the 16 bit vendor id of the device. 305.It Cd product 306this is the 16 bit product id of the device. 307.It Cd release 308this is the 16 bit release (revision) number of the device. 309.El 310The first locator can be used to pin down a particular device 311according to its physical position in the device tree. 312The last three locators can be used to pin down a particular 313device according to what device it actually is. 314.Pp 315The bus enumeration of the 316.Tn USB 317bus proceeds in several steps: 318.Bl -enum 319.It 320Any device specific driver can attach to the device. 321.It 322If none is found, any device class specific driver can attach. 323.It 324If none is found, all configurations are iterated over. 325For each configuration all the interface are iterated over and interface 326drivers can attach. 327If any interface driver attached in a certain 328configuration the iteration over configurations is stopped. 329.It 330If still no drivers have been found, the generic 331.Tn USB 332driver can attach. 333.El 334.Sh USB CONTROLLER INTERFACE 335Use the following to get access to the 336.Tn USB 337specific structures and defines. 338.Bd -literal 339#include \*[Lt]dev/usb/usb.h\*[Gt] 340.Ed 341.Pp 342The 343.Pa /dev/usbN 344can be opened and a few operations can be performed on it. 345The 346.Xr poll 2 347system call will say that I/O is possible on the controller device when a 348.Tn USB 349device has been connected or disconnected to the bus. 350.Pp 351The following 352.Xr ioctl 2 353commands are supported on the controller device: 354.Bl -tag -width xxxxxx 355.\" .It Dv USB_DISCOVER 356.\" This command will cause a complete bus discovery to be initiated. 357.\" If any devices attached or detached from the bus they will be 358.\" processed during this command. 359.\" This is the only way that new devices are found on the bus. 360.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 361This command can be used to retrieve some information about a device 362on the bus. 363The 364.Va addr 365field should be filled before the call and the other fields will 366be filled by information about the device on that address. 367Should no such device exist an error is reported. 368.Bd -literal 369struct usb_device_info { 370 uint8_t udi_bus; 371 uint8_t udi_addr; 372 usb_event_cookie_t udi_cookie; 373 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 374 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 375 char udi_release[8]; 376 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 377 uint16_t udi_productNo; 378 uint16_t udi_vendorNo; 379 uint16_t udi_releaseNo; 380 uint8_t udi_class; 381 uint8_t udi_subclass; 382 uint8_t udi_protocol; 383 uint8_t udi_config; 384 uint8_t udi_speed; 385#define USB_SPEED_LOW 1 386#define USB_SPEED_FULL 2 387#define USB_SPEED_HIGH 3 388 int udi_power; 389 int udi_nports; 390 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 391 uint8_t udi_ports[16]; 392#define USB_PORT_ENABLED 0xff 393#define USB_PORT_SUSPENDED 0xfe 394#define USB_PORT_POWERED 0xfd 395#define USB_PORT_DISABLED 0xfc 396}; 397.Ed 398.Pp 399The 400.Va product , 401.Va vendor , 402.Va release , 403and 404.Va serial 405fields contain self-explanatory descriptions of the device. 406.Pp 407The 408.Va class 409field contains the device class. 410.Pp 411The 412.Va config 413field shows the current configuration of the device. 414.Pp 415The 416.Va lowspeed 417field 418is set if the device is a 419.Tn USB 420low speed device. 421.Pp 422The 423.Va power 424field shows the power consumption in milli-amps drawn at 5 volts, 425or zero if the device is self powered. 426.Pp 427If the device is a hub the 428.Va nports 429field is non-zero and the 430.Va ports 431field contains the addresses of the connected devices. 432If no device is connected to a port one of the 433.Va USB_PORT_* 434values indicates its status. 435.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 436This command retrieves statistics about the controller. 437.Bd -literal 438struct usb_device_stats { 439 u_long uds_requests[4]; 440}; 441.Ed 442.Pp 443The 444.Va requests 445field is indexed by the transfer kind, i.e. 446.Va UE_* , 447and indicates how many transfers of each kind have been completed 448by the controller. 449.It Dv USB_REQUEST Fa "struct usb_ctl_request" 450This command can be used to execute arbitrary requests on the control pipe. 451This is 452.Em DANGEROUS 453and should be used with great care since it 454can destroy the bus integrity. 455.El 456.Pp 457The include file 458.In dev/usb/usb.h 459contains definitions for the types used by the various 460.Xr ioctl 2 461calls. 462The naming convention of the fields for the various 463.Tn USB 464descriptors exactly follows the naming in the 465.Tn USB 466specification. 467Byte sized fields can be accessed directly, but word (16 bit) 468sized fields must be access by the 469.Fn UGETW field 470and 471.Fn USETW field value 472macros to handle byte order and alignment properly. 473.Pp 474The include file 475.In dev/usb/usbhid.h 476similarly contains the definitions for 477Human Interface Devices 478.Pq Tn HID . 479.Sh USB EVENT INTERFACE 480All 481.Tn USB 482events are reported via the 483.Pa /dev/usb 484device. 485This devices can be opened for reading and each 486.Xr read 2 487will yield an event record (if something has happened). 488The 489.Xr poll 2 490system call can be used to determine if an event record is available 491for reading. 492.Pp 493The event record has the following definition: 494.Bd -literal 495struct usb_event { 496 int ue_type; 497#define USB_EVENT_CTRLR_ATTACH 1 498#define USB_EVENT_CTRLR_DETACH 2 499#define USB_EVENT_DEVICE_ATTACH 3 500#define USB_EVENT_DEVICE_DETACH 4 501#define USB_EVENT_DRIVER_ATTACH 5 502#define USB_EVENT_DRIVER_DETACH 6 503 struct timespec ue_time; 504 union { 505 struct { 506 int ue_bus; 507 } ue_ctrlr; 508 struct usb_device_info ue_device; 509 struct { 510 usb_event_cookie_t ue_cookie; 511 char ue_devname[16]; 512 } ue_driver; 513 } u; 514}; 515.Ed 516.Pp 517The 518.Va ue_type 519field identifies the type of event that is described. 520The possible events are attach/detach of a host controller, 521a device, or a device driver. 522The union contains information 523pertinent to the different types of events. 524.Pp 525The 526.Va ue_bus 527contains the number of the 528.Tn USB 529bus for host controller events. 530.Pp 531The 532.Va ue_device 533record contains information about the device in a device event event. 534.Pp 535The 536.Va ue_cookie 537is an opaque value that uniquely determines which 538device a device driver has been attached to (i.e., it equals 539the cookie value in the device that the driver attached to). 540The 541.Va ue_devname 542contains the name of the device (driver) as seen in, e.g., 543kernel messages. 544.Pp 545Note that there is a separation between device and device 546driver events. 547A device event is generated when a physical 548USB device is attached or detached. 549A single USB device may 550have zero, one, or many device drivers associated with it. 551.Sh KERNEL THREADS 552For each USB bus, i.e., for each host controller, there is 553a kernel thread that handles attach and detach of devices on 554that bus. 555The thread is named 556.Va usbN 557where 558.Va N 559is the bus number. 560.Pp 561In addition there is a kernel thread, 562.Va usbtask , 563which handles various minor tasks that are initiated from 564an interrupt context, but need to sleep, e.g., time-out 565abort of transfers. 566.Sh SEE ALSO 567.Xr usbhidaction 1 , 568.Xr usbhidctl 1 , 569.Xr cardbus 4 , 570.Xr ehci 4 , 571.Xr isa 4 , 572.Xr ohci 4 , 573.Xr pci 4 , 574.Xr pcmcia 4 , 575.Xr slhci 4 , 576.Xr uhci 4 , 577.Xr usbdevs 8 578.Rs 579.%T Universal Serial Bus Specifications Documents 580.%U http://www.usb.org/developers/docs/ 581.Re 582.Sh HISTORY 583The 584.Nm 585driver 586appeared in 587.Nx 1.4 . 588.Sh BUGS 589There should be a serial number locator, but 590.Nx 591does not have string valued locators. 592