1.\" $NetBSD: usb.4,v 1.123 2024/12/23 10:15:59 nia Exp $ 2.\" 3.\" Copyright (c) 1999-2024 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 December 23, 2024 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 ure 4 113Realtek RTL8152/RTL8153 10/100/Gigabit USB Ethernet device 114.It Xr url 4 115Realtek RTL8150L 10/100 USB Ethernet device 116.It Xr urndis 4 117USB Remote NDIS Ethernet device 118.It Xr usmsc 4 119SMSC LAN95xx 10/100 USB Ethernet device 120.El 121.Ss Wireless network interfaces 122.Bl -tag -width 12n -offset ind -compact 123.It Xr atu 4 124Atmel AT76C50x IEEE 802.11b wireless network device 125.It Xr ral 4 126Ralink Technology USB IEEE 802.11b/g wireless network device 127.It Xr rum 4 128Ralink Technology USB IEEE 802.11a/b/g wireless network device 129.It Xr run 4 130Ralink Technology USB IEEE 802.11a/b/g/n wireless network device 131.It Xr ubt 4 132USB Bluetooth dongles 133.It Xr upgt 4 134Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device 135.It Xr urtwn 4 136Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 137.It Xr zyd 4 138ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 139.El 140.Ss Serial and parallel interfaces 141.Bl -tag -width 12n -offset ind -compact 142.It Xr uark 4 143Arkmicro Technologies ARK3116 based USB serial adapters 144.It Xr ubsa 4 145Belkin USB serial adapter 146.It Xr uchcom 4 147WinChipHead CH341/340 based USB serial adapter 148.It Xr ucom 4 149USB tty support 150.It Xr ucycom 4 151Cypress microcontroller based USB serial adapter 152.It Xr uftdi 4 153FT8U100AX USB serial adapter 154.It Xr ugensa 4 155USB generic serial adapter 156.It Xr uipaq 4 157iPAQ USB units 158.It Xr ukyopon 4 159USB Kyocera AIR-EDGE PHONE device 160.It Xr ulpt 4 161USB printer support 162.It Xr umct 4 163MCT USB-RS232 USB serial adapter 164.It Xr umodem 4 165USB modem support 166.It Xr uplcom 4 167Prolific PL-2303 USB serial adapter 168.It Xr uslsa 4 169Silicon Laboratories CP2101/CP2102 based USB serial adapter 170.It Xr uvisor 4 171USB Handspring Visor 172.It Xr uvscom 4 173SUNTAC Slipper U VS-10U USB serial adapter 174.It Xr uxrcom 4 175Exar XR21V141x USB serial adapter 176.El 177.Ss Cellular WAN interfaces 178.Bl -tag -width 12n -offset ind -compact 179.It Xr u3g 4 180USB 3G modems 181.It Xr uhmodem 4 182Huawei 3G wireless modems 183.It Xr uhso 4 184Option N.V. Wireless WAN modems 185.It Xr umb 4 186USB Mobile Broadband Interface Model (MBIM) devices 187.El 188.Ss Audio devices 189.Bl -tag -width 12n -offset ind -compact 190.It Xr uaudio 4 191USB audio devices 192.It Xr umidi 4 193USB MIDI devices 194.El 195.Ss Video devices 196.Bl -tag -width 12n -offset ind -compact 197.It Xr pseye 4 198Sony PlayStation Eye webcam device driver 199.It Xr udl 4 200DisplayLink DL-1x0/1x5 USB display devices 201.It Xr uvideo 4 202USB video class devices (e.g. webcams, capture cards) 203.El 204.Ss Radio receiver devices 205.Bl -tag -width 12n -offset ind -compact 206.It Xr slurm 4 207Silicon Labs USB FM radios 208.It Xr udsbr 4 209D-Link DSB-R100 USB radio device 210.El 211.Ss Human Interface Devices 212.Bl -tag -width 12n -offset ind -compact 213.It Xr uatp 4 214Apple trackpads 215.It Xr uep 4 216eGalax touch panel controllers 217.It Xr uhid 4 218Generic driver for Human Interface Devices 219.It Xr uhidev 4 220Base driver for all Human Interface Devices 221.It Xr uintuos 4 222Wacom Intuos drawing tablets 223.It Xr ukbd 4 224USB keyboards that follow the boot protocol 225.It Xr ums 4 226USB mouse devices 227.It Xr uthum 4 228TEMPer and TEMPerHUM temperature and humidity sensors 229.It Xr uts 4 230Generic driver for touchscreens and touch digitizers 231.El 232.Ss Miscellaneous devices 233.Bl -tag -width 12n -offset ind -compact 234.It Xr stuirda 4 235Sigmaltel 4116/4220 USB-IrDA bridge 236.It Xr ualea 4 237USB Araneus Alea I/II random number generators 238.It Xr uberry 4 239Battery charging RIM BlackBerry phones via USB 240.\" .It Xr udsir 4 241.\" KingSun/DonShine USB IrDA bridge 242.It Xr ugen 4 243USB generic devices 244.It Xr uipad 4 245Battery charging iOS devices via USB 246.It Xr uirda 4 247USB IrDA bridges 248.It Xr upl 4 249Prolific based host-to-host adapters 250.It Xr usscanner 4 251SCSI-over-USB scanners 252.It Xr ustir 4 253SigmaTel STIr4200 USB IrDA bridges 254.It Xr utoppy 4 255Topfield TF5000PVR range of digital video recorders 256.El 257.Sh INTRODUCTION TO USB 258The USB 1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 259USB 2.x handles 480 Mb/s. 260Each USB has 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 USB bus proceeds in several steps: 319.Bl -enum 320.It 321Any device specific driver can attach to the device. 322.It 323If none is found, any device class specific driver can attach. 324.It 325If none is found, all configurations are iterated over. 326For each configuration all the interface are iterated over and interface 327drivers can attach. 328If any interface driver attached in a certain 329configuration the iteration over configurations is stopped. 330.It 331If still no drivers have been found, the generic USB driver can attach. 332.El 333.Sh USB CONTROLLER INTERFACE 334Use the following to get access to the USB specific structures and defines. 335.Bd -literal 336#include <dev/usb/usb.h> 337.Ed 338.Pp 339The 340.Pa /dev/usbN 341can be opened and a few operations can be performed on it. 342The 343.Xr poll 2 344system call will say that I/O is possible on the controller device when a 345USB device has been connected or disconnected to the bus. 346.Pp 347The following 348.Xr ioctl 2 349commands are supported on the controller device: 350.Bl -tag -width xxxxxx 351.\" .It Dv USB_DISCOVER 352.\" This command will cause a complete bus discovery to be initiated. 353.\" If any devices attached or detached from the bus they will be 354.\" processed during this command. 355.\" This is the only way that new devices are found on the bus. 356.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 357This command can be used to retrieve some information about a device 358on the bus. 359The 360.Va addr 361field should be filled before the call and the other fields will 362be filled by information about the device on that address. 363Should no such device exist an error is reported. 364.Bd -literal 365struct usb_device_info { 366 uint8_t udi_bus; 367 uint8_t udi_addr; 368 usb_event_cookie_t udi_cookie; 369 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 370 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 371 char udi_release[8]; 372 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 373 uint16_t udi_productNo; 374 uint16_t udi_vendorNo; 375 uint16_t udi_releaseNo; 376 uint8_t udi_class; 377 uint8_t udi_subclass; 378 uint8_t udi_protocol; 379 uint8_t udi_config; 380 uint8_t udi_speed; 381#define USB_SPEED_LOW 1 382#define USB_SPEED_FULL 2 383#define USB_SPEED_HIGH 3 384 int udi_power; 385 int udi_nports; 386 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 387 uint8_t udi_ports[16]; 388#define USB_PORT_ENABLED 0xff 389#define USB_PORT_SUSPENDED 0xfe 390#define USB_PORT_POWERED 0xfd 391#define USB_PORT_DISABLED 0xfc 392}; 393.Ed 394.Pp 395The 396.Va product , 397.Va vendor , 398.Va release , 399and 400.Va serial 401fields contain self-explanatory descriptions of the device. 402.Pp 403The 404.Va class 405field contains the device class. 406.Pp 407The 408.Va config 409field shows the current configuration of the device. 410.Pp 411The 412.Va lowspeed 413field 414is set if the device is a USB low speed device. 415.Pp 416The 417.Va power 418field shows the power consumption in milli-amps drawn at 5 volts, 419or zero if the device is self powered. 420.Pp 421If the device is a hub the 422.Va nports 423field is non-zero and the 424.Va ports 425field contains the addresses of the connected devices. 426If no device is connected to a port one of the 427.Va USB_PORT_* 428values indicates its status. 429.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 430This command retrieves statistics about the controller. 431.Bd -literal 432struct usb_device_stats { 433 u_long uds_requests[4]; 434}; 435.Ed 436.Pp 437The 438.Va requests 439field is indexed by the transfer kind, i.e. 440.Va UE_* , 441and indicates how many transfers of each kind have been completed 442by the controller. 443.It Dv USB_REQUEST Fa "struct usb_ctl_request" 444This command can be used to execute arbitrary requests on the control pipe. 445This is 446.Em DANGEROUS 447and should be used with great care since it 448can destroy the bus integrity. 449.El 450.Pp 451The include file 452.In dev/usb/usb.h 453contains definitions for the types used by the various 454.Xr ioctl 2 455calls. 456The naming convention of the fields for the various USB 457descriptors exactly follows the naming in the USB specification. 458Byte sized fields can be accessed directly, but word (16 bit) 459sized fields must be access by the 460.Fn UGETW field 461and 462.Fn USETW field value 463macros to handle byte order and alignment properly. 464.Pp 465The include file 466.In dev/usb/usbhid.h 467similarly contains the definitions for 468Human Interface Devices (HID). 469.Sh USB EVENT INTERFACE 470All USB events are reported via the 471.Pa /dev/usb 472device. 473This devices can be opened for reading and each 474.Xr read 2 475will yield an event record (if something has happened). 476The 477.Xr poll 2 478system call can be used to determine if an event record is available 479for reading. 480.Pp 481The event record has the following definition: 482.Bd -literal 483struct usb_event { 484 int ue_type; 485#define USB_EVENT_CTRLR_ATTACH 1 486#define USB_EVENT_CTRLR_DETACH 2 487#define USB_EVENT_DEVICE_ATTACH 3 488#define USB_EVENT_DEVICE_DETACH 4 489#define USB_EVENT_DRIVER_ATTACH 5 490#define USB_EVENT_DRIVER_DETACH 6 491 struct timespec ue_time; 492 union { 493 struct { 494 int ue_bus; 495 } ue_ctrlr; 496 struct usb_device_info ue_device; 497 struct { 498 usb_event_cookie_t ue_cookie; 499 char ue_devname[16]; 500 } ue_driver; 501 } u; 502}; 503.Ed 504.Pp 505The 506.Va ue_type 507field identifies the type of event that is described. 508The possible events are attach/detach of a host controller, 509a device, or a device driver. 510The union contains information 511pertinent to the different types of events. 512.Pp 513The 514.Va ue_bus 515contains the number of the USB bus for host controller events. 516.Pp 517The 518.Va ue_device 519record contains information about the device in a device event event. 520.Pp 521The 522.Va ue_cookie 523is an opaque value that uniquely determines which 524device a device driver has been attached to (i.e., it equals 525the cookie value in the device that the driver attached to). 526The 527.Va ue_devname 528contains the name of the device (driver) as seen in, e.g., 529kernel messages. 530.Pp 531Note that there is a separation between device and device 532driver events. 533A device event is generated when a physical 534USB device is attached or detached. 535A single USB device may 536have zero, one, or many device drivers associated with it. 537.Sh KERNEL THREADS 538For each USB bus, i.e., for each host controller, there is 539a kernel thread that handles attach and detach of devices on 540that bus. 541The thread is named 542.Va usbN 543where 544.Va N 545is the bus number. 546.Pp 547In addition there is a kernel thread, 548.Va usbtask , 549which handles various minor tasks that are initiated from 550an interrupt context, but need to sleep, e.g., time-out 551abort of transfers. 552.Sh SEE ALSO 553.Xr usbhidaction 1 , 554.Xr usbhidctl 1 , 555.Xr cardbus 4 , 556.Xr ehci 4 , 557.Xr isa 4 , 558.Xr ohci 4 , 559.Xr pci 4 , 560.Xr pcmcia 4 , 561.Xr slhci 4 , 562.Xr uhci 4 , 563.Xr xhci 4 , 564.Xr usbdevs 8 565.Rs 566.%T Universal Serial Bus Specifications Documents 567.%U http://www.usb.org/developers/docs/ 568.Re 569.Sh HISTORY 570The 571.Nm 572driver 573appeared in 574.Nx 1.4 . 575.Sh BUGS 576There should be a serial number locator, but 577.Nx 578does not have string valued locators. 579