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