1.\" $OpenBSD: usb.4,v 1.183 2017/03/22 06:09:31 jmc Exp $ 2.\" $NetBSD: usb.4,v 1.15 1999/07/29 14:20:32 augustss Exp $ 3.\" 4.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Lennart Augustsson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: March 22 2017 $ 32.Dt USB 4 33.Os 34.Sh NAME 35.Nm usb , 36.Nm uhub 37.Nd introduction to Universal Serial Bus support 38.Sh SYNOPSIS 39.Cd "# octeon specific" 40.Cd "dwctwo0 at iobus? irq 56" 41.Cd "# all architectures" 42.Cd "ehci* at cardbus?" 43.Cd "ohci* at cardbus?" 44.Cd "uhci* at cardbus?" 45.Cd "ehci* at pci?" 46.Cd "ohci* at pci?" 47.Cd "uhci* at pci?" 48.Cd "xhci* at pci?" 49.Cd "usb* at dwctwo?" 50.Cd "usb* at ehci? flags 0x00" 51.Cd "usb* at ohci? flags 0x00" 52.Cd "usb* at uhci? flags 0x00" 53.Cd "usb* at xhci? flags 0x00" 54.Cd "uhub* at usb?" 55.Cd "uhub* at uhub?" 56.Pp 57.Cd option USBVERBOSE 58.Pp 59.In dev/usb/usb.h 60.In dev/usb/usbhid.h 61.Sh DESCRIPTION 62.Ox 63provides machine-independent bus support and drivers for Universal Serial Bus 64.Pq Tn USB 65devices. 66.Pp 67The 68.Ox 69.Nm 70driver has three layers (like 71.Xr scsi 4 72and 73.Xr pcmcia 4 ) : 74the controller, the bus, and the device layer. 75The controller attaches to a physical bus (like 76.Xr pci 4 77or 78.Xr cardbus 4 ) . 79The 80.Tn USB 81bus attaches to the controller and the root hub attaches to the 82.Tn USB 83bus. 84Devices, which may include further hubs, attach to the root hub. 85The attachment forms the same tree structure as the physical 86.Tn USB 87device tree. 88For each 89.Tn USB 90device there may be additional drivers attached to it. 91.Pp 92The 93.Cm uhub 94driver controls 95.Tn USB 96hubs and must always be present since there is at least one root hub in any 97.Tn USB 98system. 99.Pp 100The 101.Cm flags 102are used to specify if the devices on the 103.Tn USB 104bus should be probed 105early in the boot process. 106If the 107.Cm flags 108are specified with a value of 1, the 109.Tn USB 110bus will be probed when the 111.Tn USB 112host device is attached instead of waiting 113until kernel processes start running. 114.Pp 115.Ox 116provides support for the following devices. 117Note that not all architectures support all devices. 118.Ss Storage devices 119.Bl -tag -width 12n -offset ind -compact 120.It Xr umass 4 121.Tn USB 122Mass Storage Devices, e.g., external disk drives 123.El 124.Ss Wired network interfaces 125.Bl -tag -width 12n -offset ind -compact 126.It Xr aue 4 127ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 128.It Xr axe 4 129ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 130.It Xr axen 4 131ASIX Electronics AX88179 10/100/Gigabit USB Ethernet device 132.It Xr cdce 4 133USB Communication Device Class Ethernet device 134.It Xr cue 4 135CATC USB-EL1201A USB Ethernet device 136.It Xr kue 4 137Kawasaki LSI KL5KUSB101B USB Ethernet device 138.It Xr mos 4 139MosChip MCS7730/7830/7832 10/100 USB Ethernet device 140.It Xr smsc 4 141SMSC LAN95xx 10/100 USB Ethernet device 142.It Xr udav 4 143Davicom DM9601 10/100 USB Ethernet device 144.It Xr ure 4 145RealTek RTL8152/RTL8153 10/100/Gigabit USB Ethernet device 146.It Xr url 4 147Realtek RTL8150L 10/100 USB Ethernet device 148.It Xr urndis 4 149USB Remote NDIS Ethernet device 150.El 151.Ss Wireless network interfaces 152.Bl -tag -width 12n -offset ind -compact 153.It Xr athn 4 154Atheros IEEE 802.11a/b/g/n wireless network device 155.It Xr atu 4 156Atmel AT76C50x IEEE 802.11b wireless network device 157.It Xr otus 4 158Atheros USB IEEE 802.11a/b/g/n wireless network device 159.It Xr rsu 4 160Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device 161.It Xr rum 4 162Ralink Technology/MediaTek USB IEEE 802.11a/b/g wireless network device 163.It Xr run 4 164Ralink Technology/MediaTek USB IEEE 802.11a/b/g/n wireless network device 165.It Xr uath 4 166Atheros USB IEEE 802.11a/b/g wireless network device 167.It Xr upgt 4 168Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network device 169.It Xr ural 4 170Ralink Technology/MediaTek USB IEEE 802.11b/g wireless network device 171.It Xr urtw 4 172Realtek RTL8187L/RTL8187B USB IEEE 802.11b/g wireless network device 173.It Xr urtwn 4 174Realtek RTL8188CU/RTL8188EU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 175.It Xr wi 4 176Intersil PRISM 2-3 IEEE 802.11b wireless network device 177.It Xr zyd 4 178ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 179.El 180.Ss Serial and parallel interfaces 181.Bl -tag -width 12n -offset ind -compact 182.It Xr moscom 4 183MosChip Semiconductor MCS7703 based USB serial adapter 184.It Xr uark 4 185Arkmicro Technologies ARK3116 based USB serial adapter 186.It Xr ubsa 4 187Belkin USB serial adapter 188.It Xr uchcom 4 189WinChipHead CH341/340 based USB serial adapter 190.It Xr ucom 4 191USB tty support 192.It Xr ucycom 4 193Cypress microcontroller based USB serial adapter 194.It Xr uftdi 4 195FTDI USB serial adapter 196.It Xr uipaq 4 197iPAQ USB units 198.It Xr ulpt 4 199USB printer support 200.It Xr umcs 4 201MosChip Semiconductor based USB multiport serial adapter 202.It Xr umct 4 203MCT USB-RS232 USB serial adapter 204.It Xr umodem 4 205USB modem support 206.It Xr umsm 4 207Qualcomm MSM modem device 208.It Xr uplcom 4 209Prolific PL-2303 USB serial adapter 210.It Xr uscom 4 211simple USB serial adapters 212.It Xr uslcom 4 213Silicon Laboratories CP210x based USB serial adapter 214.It Xr uslhcom 4 215Silicon Laboratories CP2110 based USB serial adapter 216.It Xr uticom 4 217Texas Instruments TUSB3410 USB serial adapter 218.It Xr uvisor 4 219USB Handspring Visor 220.It Xr uvscom 4 221SUNTAC Slipper U VS-10U USB serial adapter 222.El 223.Ss Audio devices 224.Bl -tag -width 12n -offset ind -compact 225.It Xr uaudio 4 226USB audio devices 227.It Xr umidi 4 228USB MIDI devices 229.El 230.Ss Video devices 231.Bl -tag -width 12n -offset ind -compact 232.It Xr udl 4 233DisplayLink DL-120 / DL-160 USB display devices 234.It Xr utvfu 4 235USB Fushicai USBTV007 audio/video capture device 236.It Xr uvideo 4 237USB video devices 238.El 239.Ss Time receiver devices 240.Bl -tag -width 12n -offset ind -compact 241.It Xr udcf 4 242Gude ADS Expert mouseCLOCK USB timedelta sensor 243.It Xr umbg 4 244Meinberg Funkuhren USB5131 timedelta sensor 245.El 246.Ss Radio receiver devices 247.Bl -tag -width 12n -offset ind -compact 248.It Xr udsbr 4 249D-Link DSB-R100 USB radio device 250.El 251.Ss Human Interface Devices 252.Bl -tag -width 12n -offset ind -compact 253.It Xr ubcmtp 4 254Broadcom trackpad mouse 255.It Xr uhid 4 256Generic driver for Human Interface Devices 257.It Xr uhidev 4 258Base driver for all Human Interface Devices 259.It Xr ukbd 4 260.Tn USB 261keyboards that follow the boot protocol 262.It Xr ums 4 263.Tn USB 264HID mouse, touchscreen and digitiser devices 265.It Xr uoaklux 4 266Toradex OAK USB illuminance sensor 267.It Xr uoakrh 4 268Toradex OAK USB temperature and relative humidity sensor 269.It Xr uoakv 4 270Toradex OAK USB +/-10V 8channel ADC interface 271.It Xr upd 4 272USB Power Devices sensor 273.It Xr uthum 4 274TEMPer HID thermometer and hygrometer 275.It Xr utpms 4 276Apple touchpad mouse 277.It Xr utrh 4 278USBRH temperature and humidity sensor 279.It Xr utwitch 4 280YUREX USB twitch/jiggle of knee sensor 281.It Xr uwacom 4 282Wacom USB tablets 283.El 284.Ss WAN network devices 285.Bl -tag -width 12n -offset ind -compact 286.It Xr umb 4 287USB Mobile Broadband Interface Model (MBIM) 288.El 289.Ss Miscellaneous devices 290.Bl -tag -width 12n -offset ind -compact 291.It Xr ualea 4 292Araneus Alea II USB TRNG 293.It Xr uberry 4 294Research In Motion BlackBerry 295.It Xr ugen 4 296USB generic device support 297.It Xr ugl 4 298Genesys Logic based host-to-host adapters 299.It Xr ugold 4 300TEMPer gold HID thermometer and hygrometer 301.It Xr uonerng 4 302Moonbase Otago OneRNG TRNG 303.It Xr uow 4 304Maxim/Dallas DS2490 USB 1-Wire adapter 305.It Xr upl 4 306Prolific based host-to-host adapters 307.It Xr usps 4 308USPS composite AC power and temperature sensor 309.It Xr uts 4 310USB touchscreen support 311.El 312.Sh INTRODUCTION TO USB 313There are different versions of the 314.Tn USB 315which provide different speeds. 316.Tn USB 3173 can operate up to 5.0Gb/s. 318.Tn USB 3192 operates at 480Mb/s, while 320.Tn USB 321versions 1 and 1.1 operate at 12 Mb/s and 1.5 Mb/s for low speed devices. 322Each 323.Tn USB 324has a host controller that is the master of the bus; 325all other devices on the bus only speak when spoken to. 326.Pp 327There can be up to 127 devices (apart from the host controller) 328on a bus, each with its own address. 329The addresses are assigned 330dynamically by the host when each device is attached to the bus. 331.Pp 332Within each device there can be up to 16 endpoints. 333Each endpoint 334is individually addressed and the addresses are static. 335Each of these endpoints will communicate in one of four different modes: 336control, isochronous, bulk, or interrupt. 337A device always has at least one endpoint. 338This is a control endpoint at address 0 339and is used to give commands to the device and extract basic data, 340such as descriptors, from the device. 341Each endpoint, except the control endpoint, is unidirectional. 342.Pp 343The endpoints in a device are grouped into interfaces. 344An interface is a logical unit within a device; e.g., 345a compound device with both a keyboard and a trackball would present 346one interface for each. 347An interface can sometimes be set into different modes, 348called alternate settings, which affects how it operates. 349Different alternate settings can have different endpoints 350within it. 351.Pp 352A device may operate in different configurations. 353Depending on the 354configuration the device may present different sets of endpoints 355and interfaces. 356.Pp 357Each device located on a hub has several 358.Xr config 8 359locators: 360.Pp 361.Bl -tag -width configuration -compact 362.It Cd port 363Number of the port on closest upstream hub. 364.It Cd configuration 365Configuration the device must be in for this driver to attach. 366This locator does not set the configuration; it is iterated by the bus 367enumeration. 368.It Cd interface 369Interface number within a device that an interface driver attaches to. 370.It Cd vendor 37116-bit vendor ID of the device. 372.It Cd product 37316-bit product ID of the device. 374.It Cd release 37516-bit release (revision) number of the device. 376.El 377.Pp 378The first locator can be used to pin down a particular device 379according to its physical position in the device tree. 380The last three locators can be used to pin down a particular 381device according to what device it actually is. 382.Pp 383The bus enumeration of the 384.Tn USB 385bus proceeds in several steps: 386.Bl -enum 387.It 388Any device-specific driver can attach to the device. 389.It 390If none is found, any device class specific driver can attach. 391.It 392If none is found, all configurations are iterated over. 393For each configuration all the interfaces are iterated over and interface 394drivers can attach. 395If any interface driver attached in a certain 396configuration, the iteration over configurations is stopped. 397.It 398If still no drivers have been found, the generic 399.Tn USB 400driver can attach. 401.El 402.Sh USB CONTROLLER INTERFACE 403Use the following to get access to the 404.Tn USB 405specific structures and defines: 406.Bd -literal -offset indent 407#include <dev/usb/usb.h> 408.Ed 409.Pp 410The 411.Pa /dev/usbN 412device can be opened and a few operations can be performed on it. 413The 414.Xr poll 2 415system call will say that I/O is possible on the controller device when a 416.Tn USB 417device has been connected or disconnected to the bus. 418.Pp 419The following 420.Xr ioctl 2 421commands are supported on the controller device: 422.Bl -tag -width xxxxxx 423.It Dv USB_DEVICEINFO (struct usb_device_info *) 424This command can be used to retrieve some information about a device 425on the bus. 426The 427.Va udi_addr 428field should be filled before the call and the other fields will 429be filled by information about the device on that address. 430Should no such device exist, an error is reported. 431.Bd -literal 432#define USB_MAX_DEVNAMES 4 433#define USB_MAX_DEVNAMELEN 16 434struct usb_device_info { 435 u_int8_t udi_bus; 436 u_int8_t udi_addr; /* device address */ 437 char udi_product[USB_MAX_STRING_LEN]; 438 char udi_vendor[USB_MAX_STRING_LEN]; 439 char udi_release[8]; 440 u_int16_t udi_productNo; 441 u_int16_t udi_vendorNo; 442 u_int16_t udi_releaseNo; 443 u_int8_t udi_class; 444 u_int8_t udi_subclass; 445 u_int8_t udi_protocol; 446 u_int8_t udi_config; 447 u_int8_t udi_speed; 448#define USB_SPEED_LOW 1 449#define USB_SPEED_FULL 2 450#define USB_SPEED_HIGH 3 451 int udi_power; /* power consumption */ 452 int udi_nports; 453 char udi_devnames[USB_MAX_DEVNAMES] 454 [USB_MAX_DEVNAMELEN]; 455 u_int8_t udi_ports[16]; /* hub only */ 456#define USB_PORT_ENABLED 0xff 457#define USB_PORT_SUSPENDED 0xfe 458#define USB_PORT_POWERED 0xfd 459#define USB_PORT_DISABLED 0xfc 460 char udi_serial[USB_MAX_STRING_LEN]; 461}; 462.Ed 463.Pp 464The 465.Va udi_bus 466field contains the device unit number of the device. 467.Pp 468The 469.Va udi_product , 470.Va udi_vendor , 471and 472.Va udi_release 473fields contain self-explanatory descriptions of the device. 474The 475.Va udi_productNo , 476.Va udi_vendorNo , 477and 478.Va udi_releaseNo 479fields contain numeric identifiers for the device. 480.Pp 481The 482.Va udi_class 483and 484.Va udi_subclass 485fields contain the device class and subclass. 486.Pp 487The 488.Va udi_config 489field shows the current configuration of the device. 490.Pp 491The 492.Va udi_protocol 493field contains the device protocol as given from the device. 494.Pp 495The 496.Va udi_speed 497field 498contains the speed of the device. 499.Pp 500The 501.Va udi_power 502field shows the power consumption in milli-amps drawn at 5 volts 503or is zero if the device is self powered. 504.Pp 505The 506.Va udi_devnames 507field contains the names and instance numbers of the device drivers 508for the devices attached to this device. 509.Pp 510If the device is a hub, the 511.Va udi_nports 512field is non-zero and the 513.Va udi_ports 514field contains the addresses of the connected devices. 515If no device is connected to a port, one of the 516.Dv USB_PORT_* 517values indicates its status. 518.It Dv USB_DEVICESTATS (struct usb_device_stats *) 519This command retrieves statistics about the controller. 520.Bd -unfilled 521struct usb_device_stats { 522 u_long uds_requests[4]; 523}; 524.Ed 525.Pp 526The 527.Va uds_requests 528field is indexed by the transfer kind, i.e.\& 529.Dv UE_* , 530and indicates how many transfers of each kind have been completed 531by the controller. 532.It Dv USB_DEVICE_GET_DDESC (struct usb_device_ddesc *) 533This command can be used to retrieve the device descriptor 534of a device on the bus. 535The 536.Va udd_addr 537field needs to be filled with the bus device address: 538.Bd -literal 539struct usb_device_ddesc { 540 u_int8_t udd_bus; 541 u_int8_t udd_addr; /* device address */ 542 usb_device_descriptor_t udd_desc; 543}; 544.Ed 545.Pp 546The 547.Va udd_bus 548field contains the device unit number. 549.Pp 550The 551.Va udd_desc 552field contains the device descriptor structure. 553.It Dv USB_DEVICE_GET_CDESC (struct usb_device_cdesc *) 554This command can be used to retrieve the configuration descriptor for the 555given configuration of a device on the bus. 556The 557.Va udc_addr 558field needs to be filled with the bus device address. 559The 560.Va udc_config_index 561field needs to be filled with the configuration index for the 562relevant configuration descriptor. 563For convenience the current configuration can be specified by 564.Dv USB_CURRENT_CONFIG_INDEX : 565.Bd -literal 566struct usb_device_cdesc { 567 u_int8_t udc_bus; 568 u_int8_t udc_addr; /* device address */ 569 int udc_config_index; 570 usb_config_descriptor_t udc_desc; 571}; 572.Ed 573.Pp 574The 575.Va udc_bus 576field contains the device unit number. 577.Pp 578The 579.Va udc_desc 580field contains the configuration descriptor structure. 581.It Dv USB_DEVICE_GET_FDESC (struct usb_device_fdesc *) 582This command can be used to retrieve all descriptors for the 583given configuration of a device on the bus. 584The 585.Va udf_addr 586field needs to be filled with the bus device address. 587The 588.Va udf_config_index 589field needs to be filled with the configuration index for the 590relevant configuration descriptor. 591For convenience the current configuration can be specified by 592.Dv USB_CURRENT_CONFIG_INDEX . 593The 594.Va udf_data 595field needs to point to a memory area of the size given in the 596.Va udf_size 597field. 598The proper size can be determined by first issuing a 599.Dv USB_DEVICE_GET_CDESC 600command and inspecting the 601.Va wTotalLength 602field: 603.Bd -literal 604struct usb_device_fdesc { 605 u_int8_t udf_bus; 606 u_int8_t udf_addr; /* device address */ 607 int udf_config_index; 608 u_int udf_size; 609 u_char *udf_data; 610}; 611.Ed 612.Pp 613The 614.Va udf_bus 615field contains the device unit number. 616.Pp 617The 618.Va udf_data 619field contains all descriptors. 620.It Dv USB_REQUEST (struct usb_ctl_request *) 621This command can be used to execute arbitrary requests on the control pipe. 622This is 623.Em DANGEROUS 624and should be used with great care since it 625can destroy the bus integrity. 626.Pp 627The 628.Vt usb_ctl_request 629structure has the following definition: 630.Bd -literal 631typedef struct { 632 uByte bmRequestType; 633 uByte bRequest; 634 uWord wValue; 635 uWord wIndex; 636 uWord wLength; 637} __packed usb_device_request_t; 638 639struct usb_ctl_request { 640 int ucr_addr; 641 usb_device_request_t ucr_request; 642 void *ucr_data; 643 int ucr_flags; 644#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 645 int ucr_actlen; /* actual length transferred */ 646}; 647.Ed 648.Pp 649The 650.Va ucr_addr 651field identifies the device on which to perform the request. 652The 653.Va ucr_request 654field identifies parameters of the request, such as length and type. 655The 656.Va ucr_data 657field contains the location where data will be read from or written to. 658The 659.Va ucr_flags 660field specifies options for the request, and the 661.Va ucr_actlen 662field contains the actual length transferred as the result of the request. 663.El 664.Pp 665The include file 666.In dev/usb/usb.h 667contains definitions for the types used by the various 668.Xr ioctl 2 669calls. 670The naming convention of the fields for the various 671.Tn USB 672descriptors exactly follows the naming in the 673.Tn USB 674specification. 675Byte sized fields can be accessed directly, but word (16-bit) 676sized fields must be accessed by the 677.Fn UGETW field 678and 679.Fn USETW field value 680macros and double word (32-bit) sized fields must be accessed by the 681.Fn UGETDW field 682and 683.Fn USETDW field value 684macros to handle byte order and alignment properly. 685.Pp 686The include file 687.In dev/usb/usbhid.h 688similarly contains the definitions for 689Human Interface Devices 690.Pq Tn HID . 691.Sh SEE ALSO 692.Xr usbhidaction 1 , 693.Xr usbhidctl 1 , 694.Xr ioctl 2 , 695.Xr dwctwo 4 , 696.Xr ehci 4 , 697.Xr ohci 4 , 698.Xr uhci 4 , 699.Xr xhci 4 , 700.Xr config 8 , 701.Xr usbdevs 8 702.Pp 703The 704.Tn USB 705specifications can be found at 706.Lk http://www.usb.org/developers/docs/ 707.Sh HISTORY 708The 709.Nm 710driver 711appeared in 712.Ox 2.6 . 713