1.\" $NetBSD: usb.4,v 1.122 2022/07/10 19:49:24 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 July 10, 2022 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 Radio receiver devices 196.Bl -tag -width 12n -offset ind -compact 197.It Xr slurm 4 198Silicon Labs USB FM radios 199.It Xr udsbr 4 200D-Link DSB-R100 USB radio device 201.El 202.Ss Human Interface Devices 203.Bl -tag -width 12n -offset ind -compact 204.It Xr uatp 4 205Apple trackpads 206.It Xr uep 4 207eGalax touch panel controllers 208.It Xr uhid 4 209Generic driver for Human Interface Devices 210.It Xr uhidev 4 211Base driver for all Human Interface Devices 212.It Xr uintuos 4 213Wacom Intuos drawing tablets 214.It Xr ukbd 4 215USB keyboards that follow the boot protocol 216.It Xr ums 4 217USB mouse devices 218.It Xr uthum 4 219TEMPer and TEMPerHUM temperature and humidity sensors 220.It Xr uts 4 221Generic driver for touchscreens and touch digitizers 222.El 223.Ss Miscellaneous devices 224.Bl -tag -width 12n -offset ind -compact 225.It Xr stuirda 4 226Sigmaltel 4116/4220 USB-IrDA bridge 227.It Xr ualea 4 228USB Araneus Alea I/II random number generators 229.It Xr uberry 4 230Battery charging RIM BlackBerry phones via USB 231.It Xr udl 4 232DisplayLink DL-1x0/1x5 USB display devices 233.\" .It Xr udsir 4 234.\" KingSun/DonShine USB IrDA bridge 235.It Xr ugen 4 236USB generic devices 237.It Xr uipad 4 238Battery charging iOS devices via USB 239.It Xr uirda 4 240USB IrDA bridges 241.It Xr upl 4 242Prolific based host-to-host adapters 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.El 250.Sh INTRODUCTION TO USB 251The USB 1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 252USB 2.x handles 480 Mb/s. 253Each USB has a host controller that is the master of the bus; 254all other devices on the bus only speak when spoken to. 255.Pp 256There can be up to 127 devices (apart from the host controller) 257on a bus, each with its own address. 258The addresses are assigned 259dynamically by the host when each device is attached to the bus. 260.Pp 261Within each device there can be up to 16 endpoints. 262Each endpoint 263is individually addressed and the addresses are static. 264Each of these endpoints will communicate in one of four different modes: 265control, isochronous, bulk, or interrupt. 266A device always has at least one endpoint. 267This endpoint has address 0 and is a control 268endpoint and is used to give commands to and extract basic data, 269such as descriptors, from the device. 270Each endpoint, except the control endpoint, is unidirectional. 271.Pp 272The endpoints in a device are grouped into interfaces. 273An interface is a logical unit within a device; e.g., 274a compound device with both a keyboard and a trackball would present 275one interface for each. 276An interface can sometimes be set into different modes, 277called alternate settings, which affects how it operates. 278Different alternate settings can have different endpoints 279within it. 280.Pp 281A device may operate in different configurations. 282Depending on the 283configuration the device may present different sets of endpoints 284and interfaces. 285.Pp 286Each device located on a hub has several 287.Xr config 1 288locators: 289.Bl -tag -compact -width xxxxxxxxx 290.It Cd port 291this is the number of the port on closest upstream hub. 292.It Cd configuration 293this is the configuration the device must be in for this driver to attach. 294This locator does not set the configuration; it is iterated by the bus 295enumeration. 296.It Cd interface 297this is the interface number within a device that an interface driver 298attaches to. 299.It Cd vendor 300this is the 16 bit vendor id of the device. 301.It Cd product 302this is the 16 bit product id of the device. 303.It Cd release 304this is the 16 bit release (revision) number of the device. 305.El 306The first locator can be used to pin down a particular device 307according to its physical position in the device tree. 308The last three locators can be used to pin down a particular 309device according to what device it actually is. 310.Pp 311The bus enumeration of the USB bus proceeds in several steps: 312.Bl -enum 313.It 314Any device specific driver can attach to the device. 315.It 316If none is found, any device class specific driver can attach. 317.It 318If none is found, all configurations are iterated over. 319For each configuration all the interface are iterated over and interface 320drivers can attach. 321If any interface driver attached in a certain 322configuration the iteration over configurations is stopped. 323.It 324If still no drivers have been found, the generic USB driver can attach. 325.El 326.Sh USB CONTROLLER INTERFACE 327Use the following to get access to the USB specific structures and defines. 328.Bd -literal 329#include <dev/usb/usb.h> 330.Ed 331.Pp 332The 333.Pa /dev/usbN 334can be opened and a few operations can be performed on it. 335The 336.Xr poll 2 337system call will say that I/O is possible on the controller device when a 338USB device has been connected or disconnected to the bus. 339.Pp 340The following 341.Xr ioctl 2 342commands are supported on the controller device: 343.Bl -tag -width xxxxxx 344.\" .It Dv USB_DISCOVER 345.\" This command will cause a complete bus discovery to be initiated. 346.\" If any devices attached or detached from the bus they will be 347.\" processed during this command. 348.\" This is the only way that new devices are found on the bus. 349.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 350This command can be used to retrieve some information about a device 351on the bus. 352The 353.Va addr 354field should be filled before the call and the other fields will 355be filled by information about the device on that address. 356Should no such device exist an error is reported. 357.Bd -literal 358struct usb_device_info { 359 uint8_t udi_bus; 360 uint8_t udi_addr; 361 usb_event_cookie_t udi_cookie; 362 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 363 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 364 char udi_release[8]; 365 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 366 uint16_t udi_productNo; 367 uint16_t udi_vendorNo; 368 uint16_t udi_releaseNo; 369 uint8_t udi_class; 370 uint8_t udi_subclass; 371 uint8_t udi_protocol; 372 uint8_t udi_config; 373 uint8_t udi_speed; 374#define USB_SPEED_LOW 1 375#define USB_SPEED_FULL 2 376#define USB_SPEED_HIGH 3 377 int udi_power; 378 int udi_nports; 379 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 380 uint8_t udi_ports[16]; 381#define USB_PORT_ENABLED 0xff 382#define USB_PORT_SUSPENDED 0xfe 383#define USB_PORT_POWERED 0xfd 384#define USB_PORT_DISABLED 0xfc 385}; 386.Ed 387.Pp 388The 389.Va product , 390.Va vendor , 391.Va release , 392and 393.Va serial 394fields contain self-explanatory descriptions of the device. 395.Pp 396The 397.Va class 398field contains the device class. 399.Pp 400The 401.Va config 402field shows the current configuration of the device. 403.Pp 404The 405.Va lowspeed 406field 407is set if the device is a USB low speed device. 408.Pp 409The 410.Va power 411field shows the power consumption in milli-amps drawn at 5 volts, 412or zero if the device is self powered. 413.Pp 414If the device is a hub the 415.Va nports 416field is non-zero and the 417.Va ports 418field contains the addresses of the connected devices. 419If no device is connected to a port one of the 420.Va USB_PORT_* 421values indicates its status. 422.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 423This command retrieves statistics about the controller. 424.Bd -literal 425struct usb_device_stats { 426 u_long uds_requests[4]; 427}; 428.Ed 429.Pp 430The 431.Va requests 432field is indexed by the transfer kind, i.e. 433.Va UE_* , 434and indicates how many transfers of each kind have been completed 435by the controller. 436.It Dv USB_REQUEST Fa "struct usb_ctl_request" 437This command can be used to execute arbitrary requests on the control pipe. 438This is 439.Em DANGEROUS 440and should be used with great care since it 441can destroy the bus integrity. 442.El 443.Pp 444The include file 445.In dev/usb/usb.h 446contains definitions for the types used by the various 447.Xr ioctl 2 448calls. 449The naming convention of the fields for the various USB 450descriptors exactly follows the naming in the USB specification. 451Byte sized fields can be accessed directly, but word (16 bit) 452sized fields must be access by the 453.Fn UGETW field 454and 455.Fn USETW field value 456macros to handle byte order and alignment properly. 457.Pp 458The include file 459.In dev/usb/usbhid.h 460similarly contains the definitions for 461Human Interface Devices (HID). 462.Sh USB EVENT INTERFACE 463All USB events are reported via the 464.Pa /dev/usb 465device. 466This devices can be opened for reading and each 467.Xr read 2 468will yield an event record (if something has happened). 469The 470.Xr poll 2 471system call can be used to determine if an event record is available 472for reading. 473.Pp 474The event record has the following definition: 475.Bd -literal 476struct usb_event { 477 int ue_type; 478#define USB_EVENT_CTRLR_ATTACH 1 479#define USB_EVENT_CTRLR_DETACH 2 480#define USB_EVENT_DEVICE_ATTACH 3 481#define USB_EVENT_DEVICE_DETACH 4 482#define USB_EVENT_DRIVER_ATTACH 5 483#define USB_EVENT_DRIVER_DETACH 6 484 struct timespec ue_time; 485 union { 486 struct { 487 int ue_bus; 488 } ue_ctrlr; 489 struct usb_device_info ue_device; 490 struct { 491 usb_event_cookie_t ue_cookie; 492 char ue_devname[16]; 493 } ue_driver; 494 } u; 495}; 496.Ed 497.Pp 498The 499.Va ue_type 500field identifies the type of event that is described. 501The possible events are attach/detach of a host controller, 502a device, or a device driver. 503The union contains information 504pertinent to the different types of events. 505.Pp 506The 507.Va ue_bus 508contains the number of the USB bus for host controller events. 509.Pp 510The 511.Va ue_device 512record contains information about the device in a device event event. 513.Pp 514The 515.Va ue_cookie 516is an opaque value that uniquely determines which 517device a device driver has been attached to (i.e., it equals 518the cookie value in the device that the driver attached to). 519The 520.Va ue_devname 521contains the name of the device (driver) as seen in, e.g., 522kernel messages. 523.Pp 524Note that there is a separation between device and device 525driver events. 526A device event is generated when a physical 527USB device is attached or detached. 528A single USB device may 529have zero, one, or many device drivers associated with it. 530.Sh KERNEL THREADS 531For each USB bus, i.e., for each host controller, there is 532a kernel thread that handles attach and detach of devices on 533that bus. 534The thread is named 535.Va usbN 536where 537.Va N 538is the bus number. 539.Pp 540In addition there is a kernel thread, 541.Va usbtask , 542which handles various minor tasks that are initiated from 543an interrupt context, but need to sleep, e.g., time-out 544abort of transfers. 545.Sh SEE ALSO 546.Xr usbhidaction 1 , 547.Xr usbhidctl 1 , 548.Xr cardbus 4 , 549.Xr ehci 4 , 550.Xr isa 4 , 551.Xr ohci 4 , 552.Xr pci 4 , 553.Xr pcmcia 4 , 554.Xr slhci 4 , 555.Xr uhci 4 , 556.Xr xhci 4 , 557.Xr usbdevs 8 558.Rs 559.%T Universal Serial Bus Specifications Documents 560.%U http://www.usb.org/developers/docs/ 561.Re 562.Sh HISTORY 563The 564.Nm 565driver 566appeared in 567.Nx 1.4 . 568.Sh BUGS 569There should be a serial number locator, but 570.Nx 571does not have string valued locators. 572