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