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