1.\" $OpenBSD: usb.4,v 1.180 2016/06/28 06:31:30 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: June 28 2016 $ 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 "# zaurus specific" 42.Cd "ohci0 at pxaip?" 43.Cd "# all architectures" 44.Cd "ehci* at cardbus?" 45.Cd "ohci* at cardbus?" 46.Cd "uhci* at cardbus?" 47.Cd "ehci* at pci?" 48.Cd "ohci* at pci?" 49.Cd "uhci* at pci?" 50.Cd "xhci* at pci?" 51.Cd "usb* at dwctwo?" 52.Cd "usb* at ehci? flags 0x00" 53.Cd "usb* at ohci? flags 0x00" 54.Cd "usb* at uhci? flags 0x00" 55.Cd "usb* at xhci? flags 0x00" 56.Cd "uhub* at usb?" 57.Cd "uhub* at uhub?" 58.Pp 59.Cd option USBVERBOSE 60.Pp 61.In dev/usb/usb.h 62.In dev/usb/usbhid.h 63.Sh DESCRIPTION 64.Ox 65provides machine-independent bus support and drivers for Universal Serial Bus 66.Pq Tn USB 67devices. 68.Pp 69The 70.Ox 71.Nm 72driver has three layers (like 73.Xr scsi 4 74and 75.Xr pcmcia 4 ) : 76the controller, the bus, and the device layer. 77The controller attaches to a physical bus (like 78.Xr pci 4 79or 80.Xr cardbus 4 ) . 81The 82.Tn USB 83bus attaches to the controller and the root hub attaches to the 84.Tn USB 85bus. 86Devices, which may include further hubs, attach to the root hub. 87The attachment forms the same tree structure as the physical 88.Tn USB 89device tree. 90For each 91.Tn USB 92device there may be additional drivers attached to it. 93.Pp 94The 95.Cm uhub 96driver controls 97.Tn USB 98hubs and must always be present since there is at least one root hub in any 99.Tn USB 100system. 101.Pp 102The 103.Cm flags 104are used to specify if the devices on the 105.Tn USB 106bus should be probed 107early in the boot process. 108If the 109.Cm flags 110are specified with a value of 1, the 111.Tn USB 112bus will be probed when the 113.Tn USB 114host device is attached instead of waiting 115until kernel processes start running. 116.Pp 117.Ox 118provides support for the following devices. 119Note that not all architectures support all devices. 120.Ss Storage devices 121.Bl -tag -width 12n -offset ind -compact 122.It Xr umass 4 123.Tn USB 124Mass Storage Devices, e.g., external disk drives 125.El 126.Ss Wired network interfaces 127.Bl -tag -width 12n -offset ind -compact 128.It Xr aue 4 129ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 130.It Xr axe 4 131ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 132.It Xr axen 4 133ASIX Electronics AX88179 10/100/Gigabit USB Ethernet device 134.It Xr cdce 4 135USB Communication Device Class Ethernet device 136.It Xr cue 4 137CATC USB-EL1201A USB Ethernet device 138.It Xr kue 4 139Kawasaki LSI KL5KUSB101B USB Ethernet device 140.It Xr mos 4 141MosChip MCS7730/7830/7832 10/100 USB Ethernet device 142.It Xr smsc 4 143SMSC LAN95xx 10/100 USB Ethernet device 144.It Xr udav 4 145Davicom DM9601 10/100 USB Ethernet device 146.It Xr ure 4 147RealTek RTL8152 10/100 USB Ethernet device 148.It Xr url 4 149Realtek RTL8150L 10/100 USB Ethernet device 150.It Xr urndis 4 151USB Remote NDIS Ethernet device 152.El 153.Ss Wireless network interfaces 154.Bl -tag -width 12n -offset ind -compact 155.It Xr athn 4 156Atheros IEEE 802.11a/b/g/n wireless network device 157.It Xr atu 4 158Atmel AT76C50x IEEE 802.11b wireless network device 159.It Xr otus 4 160Atheros USB IEEE 802.11a/b/g/n wireless network device 161.It Xr rsu 4 162Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device 163.It Xr rum 4 164Ralink Technology/MediaTek USB IEEE 802.11a/b/g wireless network device 165.It Xr run 4 166Ralink Technology/MediaTek USB IEEE 802.11a/b/g/n wireless network device 167.It Xr uath 4 168Atheros USB IEEE 802.11a/b/g wireless network device 169.It Xr upgt 4 170Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network device 171.It Xr ural 4 172Ralink Technology/MediaTek USB IEEE 802.11b/g wireless network device 173.It Xr urtw 4 174Realtek RTL8187L/RTL8187B USB IEEE 802.11b/g wireless network device 175.It Xr urtwn 4 176Realtek RTL8188CU/RTL8188EU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 177.It Xr wi 4 178Intersil PRISM 2-3 IEEE 802.11b wireless network device 179.It Xr zyd 4 180ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 181.El 182.Ss Serial and parallel interfaces 183.Bl -tag -width 12n -offset ind -compact 184.It Xr moscom 4 185MosChip Semiconductor MCS7703 based USB serial adapter 186.It Xr uark 4 187Arkmicro Technologies ARK3116 based USB serial adapter 188.It Xr ubsa 4 189Belkin USB serial adapter 190.It Xr uchcom 4 191WinChipHead CH341/340 based USB serial adapter 192.It Xr ucom 4 193USB tty support 194.It Xr ucycom 4 195Cypress microcontroller based USB serial adapter 196.It Xr uftdi 4 197FTDI USB serial adapter 198.It Xr uipaq 4 199iPAQ USB units 200.It Xr ulpt 4 201USB printer support 202.It Xr umcs 4 203MosChip Semiconductor based USB multiport serial adapter 204.It Xr umct 4 205MCT USB-RS232 USB serial adapter 206.It Xr umodem 4 207USB modem support 208.It Xr umsm 4 209Qualcomm MSM modem device 210.It Xr uplcom 4 211Prolific PL-2303 USB serial adapter 212.It Xr uscom 4 213simple USB serial adapters 214.It Xr uslcom 4 215Silicon Laboratories CP210x based USB serial adapter 216.It Xr uslhcom 4 217Silicon Laboratories CP2110 based USB serial adapter 218.It Xr uticom 4 219Texas Instruments TUSB3410 USB serial adapter 220.It Xr uvisor 4 221USB Handspring Visor 222.It Xr uvscom 4 223SUNTAC Slipper U VS-10U USB serial adapter 224.El 225.Ss Audio devices 226.Bl -tag -width 12n -offset ind -compact 227.It Xr uaudio 4 228USB audio devices 229.It Xr umidi 4 230USB MIDI devices 231.El 232.Ss Video devices 233.Bl -tag -width 12n -offset ind -compact 234.It Xr udl 4 235DisplayLink DL-120 / DL-160 USB display devices 236.It Xr utvfu 4 237USB Fushicai USBTV007 audio/video capture device 238.It Xr uvideo 4 239USB video devices 240.El 241.Ss Time receiver devices 242.Bl -tag -width 12n -offset ind -compact 243.It Xr udcf 4 244Gude ADS Expert mouseCLOCK USB timedelta sensor 245.It Xr umbg 4 246Meinberg Funkuhren USB5131 timedelta sensor 247.El 248.Ss Radio receiver devices 249.Bl -tag -width 12n -offset ind -compact 250.It Xr udsbr 4 251D-Link DSB-R100 USB radio device 252.El 253.Ss Human Interface Devices 254.Bl -tag -width 12n -offset ind -compact 255.It Xr ubcmtp 4 256Broadcom trackpad mouse 257.It Xr uhid 4 258Generic driver for Human Interface Devices 259.It Xr uhidev 4 260Base driver for all Human Interface Devices 261.It Xr ukbd 4 262.Tn USB 263keyboards that follow the boot protocol 264.It Xr ums 4 265.Tn USB 266HID mouse, touchscreen and digitiser devices 267.It Xr uoaklux 4 268Toradex OAK USB illuminance sensor 269.It Xr uoakrh 4 270Toradex OAK USB temperature and relative humidity sensor 271.It Xr uoakv 4 272Toradex OAK USB +/-10V 8channel ADC interface 273.It Xr upd 4 274USB Power Devices sensor 275.It Xr uthum 4 276TEMPer HID thermometer and hygrometer 277.It Xr utpms 4 278Apple touchpad mouse 279.It Xr utrh 4 280USBRH temperature and humidity sensor 281.It Xr utwitch 4 282YUREX USB twitch/jiggle of knee sensor 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