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