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