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