1.\" $NetBSD: usb.4,v 1.98 2012/03/25 08:42:21 wiz Exp $ 2.\" 3.\" Copyright (c) 1999-2012 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 March 25, 2012 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 "slhci* at isa? port ? irq ?" 42.Cd "slhci* at pcmcia? function ?" 43.Cd "uhci* at cardbus? function ?" 44.Cd "uhci* at pci? dev ? function ?" 45.Cd "usb* at ehci? flags X" 46.Cd "usb* at ohci? flags X" 47.Cd "usb* at uhci? flags X" 48.Cd "usb* at slhci? flags X" 49.Cd "uhub* at usb?" 50.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 51.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 52.Pp 53.Cd options USBVERBOSE 54.Pp 55.In dev/usb/usb.h 56.In dev/usb/usbhid.h 57.Sh DESCRIPTION 58.Nx 59provides machine-independent bus support and drivers for 60.Tn USB 61devices. 62.Pp 63The 64.Nx 65.Nm 66driver has three layers (like 67.Xr scsi 4 68and 69.Xr pcmcia 4 ) : 70the controller, the bus, and the device layer. 71The controller attaches to a physical bus (like 72.Xr pci 4 ) . 73The 74.Tn USB 75bus attaches to the controller and the root hub attaches 76to the bus. 77Further devices, which may include further hubs, 78attach to other hubs. 79The attachment forms the same tree structure as the physical 80.Tn USB 81device tree. 82For each 83.Tn USB 84device there may be additional drivers attached to it. 85.Pp 86The 87.Cm uhub 88device controls 89.Tn USB 90hubs and must always be present since there is at least a root hub in any 91.Tn USB 92system. 93.Pp 94The 95.Va flags 96argument to the 97.Va usb 98device affects the order in which the device detection happens 99during cold boot. 100Normally, only the USB host controller and the 101.Va usb 102device are detected during the autoconfiguration when the 103machine is booted. 104The rest of the devices are detected once 105the system becomes functional and the kernel thread for the 106.Va usb 107device is started. 108Sometimes it is desirable to have a device detected early in the 109boot process, e.g., the console keyboard. 110To achieve this use a 111.Va flags 112value of 1. 113.Pp 114.Nx 115supports the following machine-independent 116.Tn USB 117drivers: 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 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 udav 4 137Davicom DM9601 10/100 USB Ethernet device 138.It Xr url 4 139Realtek RTL8150L 10/100 USB Ethernet device 140.El 141.Ss Wireless network interfaces 142.Bl -tag -width 12n -offset ind -compact 143.It Xr atu 4 144Atmel AT76C50x IEEE 802.11b wireless network device 145.It Xr ral 4 146Ralink Technology USB IEEE 802.11b/g wireless network device 147.It Xr rum 4 148Ralink Technology USB IEEE 802.11a/b/g wireless network device 149.It Xr ubt 4 150USB Bluetooth dongles 151.It Xr upgt 4 152Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device 153.It Xr urtwn 4 154Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device 155.It Xr zyd 4 156ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 157.El 158.Ss Serial and parallel interfaces 159.Bl -tag -width 12n -offset ind -compact 160.It Xr ubsa 4 161Belkin USB serial adapter 162.It Xr uchcom 4 163WinChipHead CH341/340 based USB serial adapter 164.It Xr ucom 4 165USB tty support 166.It Xr ucycom 4 167Cypress microcontroller based USB serial adapter 168.It Xr uftdi 4 169FT8U100AX USB serial adapter 170.It Xr ugensa 4 171USB generic serial adapter 172.It Xr uhmodem 4 173USB Huawei 3G wireless modem device 174.It Xr uipaq 4 175iPAQ USB units 176.It Xr ukyopon 4 177USB Kyocera AIR-EDGE PHONE device 178.It Xr ulpt 4 179USB printer support 180.It Xr umct 4 181MCT USB-RS232 USB serial adapter 182.It Xr umodem 4 183USB modem support 184.It Xr uplcom 4 185Prolific PL-2303 USB serial adapter 186.It Xr uslsa 4 187Silicon Laboratories CP2101/CP2102 based USB serial adapter 188.It Xr uvisor 4 189USB Handspring Visor 190.It Xr uvscom 4 191SUNTAC Slipper U VS-10U USB serial adapter 192.El 193.Ss Audio devices 194.Bl -tag -width 12n -offset ind -compact 195.It Xr uaudio 4 196USB audio devices 197.It Xr umidi 4 198USB MIDI devices 199.It Xr urio 4 200Diamond Multimedia Rio MP3 players 201.El 202.Ss Radio receiver devices 203.Bl -tag -width 12n -offset ind -compact 204.It Xr udsbr 4 205D-Link DSB-R100 USB radio device 206.El 207.Ss Human Interface Devices 208.Bl -tag -width 12n -offset ind -compact 209.It Xr uhid 4 210Generic driver for Human Interface Devices 211.It Xr uhidev 4 212Base driver for all Human Interface Devices 213.It Xr ukbd 4 214.Tn USB 215keyboards that follow the boot protocol 216.It Xr ums 4 217.Tn USB 218mouse devices 219.El 220.Ss Miscellaneous devices 221.Bl -tag -width 12n -offset ind -compact 222.It Xr stuirda 4 223Sigmaltel 4116/4220 USB-IrDA bridge 224.It Xr uep 4 225USB eGalax touch-panel 226.It Xr ugen 4 227USB generic devices 228.It Xr uirda 4 229USB IrDA bridges 230.It Xr upl 4 231Prolific based host-to-host adapters 232.It Xr uscanner 4 233USB scanner support 234.It Xr usscanner 4 235SCSI-over-USB scanners 236.It Xr ustir 4 237SigmaTel STIr4200 USB IrDA bridges 238.It Xr utoppy 4 239Topfield TF5000PVR range of digital video recorders 240.It Xr uyap 4 241USB YAP phone firmware loader 242.El 243.Sh INTRODUCTION TO USB 244The 245.Tn USB 2461.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 247.Tn USB 2482.x handles 480 Mb/s. 249Each 250.Tn USB 251has a host controller that is the master of the bus; 252all other devices on the bus only speak when spoken to. 253.Pp 254There can be up to 127 devices (apart from the host controller) 255on a bus, each with its own address. 256The addresses are assigned 257dynamically by the host when each device is attached to the bus. 258.Pp 259Within each device there can be up to 16 endpoints. 260Each endpoint 261is individually addressed and the addresses are static. 262Each of these endpoints will communicate in one of four different modes: 263control, isochronous, bulk, or interrupt. 264A device always has at least one endpoint. 265This endpoint has address 0 and is a control 266endpoint and is used to give commands to and extract basic data, 267such as descriptors, from the device. 268Each endpoint, except the control endpoint, is unidirectional. 269.Pp 270The endpoints in a device are grouped into interfaces. 271An interface is a logical unit within a device; e.g., 272a compound device with both a keyboard and a trackball would present 273one interface for each. 274An interface can sometimes be set into different modes, 275called alternate settings, which affects how it operates. 276Different alternate settings can have different endpoints 277within it. 278.Pp 279A device may operate in different configurations. 280Depending on the 281configuration the device may present different sets of endpoints 282and interfaces. 283.Pp 284Each device located on a hub has several 285.Xr config 1 286locators: 287.Bl -tag -compact -width xxxxxxxxx 288.It Cd port 289this is the number of the port on closest upstream hub. 290.It Cd configuration 291this is the configuration the device must be in for this driver to attach. 292This locator does not set the configuration; it is iterated by the bus 293enumeration. 294.It Cd interface 295this is the interface number within a device that an interface driver 296attaches to. 297.It Cd vendor 298this is the 16 bit vendor id of the device. 299.It Cd product 300this is the 16 bit product id of the device. 301.It Cd release 302this is the 16 bit release (revision) number of the device. 303.El 304The first locator can be used to pin down a particular device 305according to its physical position in the device tree. 306The last three locators can be used to pin down a particular 307device according to what device it actually is. 308.Pp 309The bus enumeration of the 310.Tn USB 311bus 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 325.Tn USB 326driver can attach. 327.El 328.Sh USB CONTROLLER INTERFACE 329Use the following to get access to the 330.Tn USB 331specific structures and defines. 332.Bd -literal 333#include \*[Lt]dev/usb/usb.h\*[Gt] 334.Ed 335.Pp 336The 337.Pa /dev/usbN 338can be opened and a few operations can be performed on it. 339The 340.Xr poll 2 341system call will say that I/O is possible on the controller device when a 342.Tn USB 343device has been connected or disconnected to the bus. 344.Pp 345The following 346.Xr ioctl 2 347commands are supported on the controller device: 348.Bl -tag -width xxxxxx 349.\" .It Dv USB_DISCOVER 350.\" This command will cause a complete bus discovery to be initiated. 351.\" If any devices attached or detached from the bus they will be 352.\" processed during this command. 353.\" This is the only way that new devices are found on the bus. 354.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 355This command can be used to retrieve some information about a device 356on the bus. 357The 358.Va addr 359field should be filled before the call and the other fields will 360be filled by information about the device on that address. 361Should no such device exist an error is reported. 362.Bd -literal 363struct usb_device_info { 364 uint8_t udi_bus; 365 uint8_t udi_addr; 366 usb_event_cookie_t udi_cookie; 367 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 368 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 369 char udi_release[8]; 370 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 371 uint16_t udi_productNo; 372 uint16_t udi_vendorNo; 373 uint16_t udi_releaseNo; 374 uint8_t udi_class; 375 uint8_t udi_subclass; 376 uint8_t udi_protocol; 377 uint8_t udi_config; 378 uint8_t udi_speed; 379#define USB_SPEED_LOW 1 380#define USB_SPEED_FULL 2 381#define USB_SPEED_HIGH 3 382 int udi_power; 383 int udi_nports; 384 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 385 uint8_t udi_ports[16]; 386#define USB_PORT_ENABLED 0xff 387#define USB_PORT_SUSPENDED 0xfe 388#define USB_PORT_POWERED 0xfd 389#define USB_PORT_DISABLED 0xfc 390}; 391.Ed 392.Pp 393The 394.Va product , 395.Va vendor , 396.Va release , 397and 398.Va serial 399fields contain self-explanatory descriptions of the device. 400.Pp 401The 402.Va class 403field contains the device class. 404.Pp 405The 406.Va config 407field shows the current configuration of the device. 408.Pp 409The 410.Va lowspeed 411field 412is set if the device is a 413.Tn USB 414low 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 457.Tn USB 458descriptors exactly follows the naming in the 459.Tn USB 460specification. 461Byte sized fields can be accessed directly, but word (16 bit) 462sized fields must be access by the 463.Fn UGETW field 464and 465.Fn USETW field value 466macros to handle byte order and alignment properly. 467.Pp 468The include file 469.In dev/usb/usbhid.h 470similarly contains the definitions for 471Human Interface Devices 472.Pq Tn HID . 473.Sh USB EVENT INTERFACE 474All 475.Tn USB 476events are reported via the 477.Pa /dev/usb 478device. 479This devices can be opened for reading and each 480.Xr read 2 481will yield an event record (if something has happened). 482The 483.Xr poll 2 484system call can be used to determine if an event record is available 485for reading. 486.Pp 487The event record has the following definition: 488.Bd -literal 489struct usb_event { 490 int ue_type; 491#define USB_EVENT_CTRLR_ATTACH 1 492#define USB_EVENT_CTRLR_DETACH 2 493#define USB_EVENT_DEVICE_ATTACH 3 494#define USB_EVENT_DEVICE_DETACH 4 495#define USB_EVENT_DRIVER_ATTACH 5 496#define USB_EVENT_DRIVER_DETACH 6 497 struct timespec ue_time; 498 union { 499 struct { 500 int ue_bus; 501 } ue_ctrlr; 502 struct usb_device_info ue_device; 503 struct { 504 usb_event_cookie_t ue_cookie; 505 char ue_devname[16]; 506 } ue_driver; 507 } u; 508}; 509.Ed 510.Pp 511The 512.Va ue_type 513field identifies the type of event that is described. 514The possible events are attach/detach of a host controller, 515a device, or a device driver. 516The union contains information 517pertinent to the different types of events. 518.Pp 519The 520.Va ue_bus 521contains the number of the 522.Tn USB 523bus for host controller events. 524.Pp 525The 526.Va ue_device 527record contains information about the device in a device event event. 528.Pp 529The 530.Va ue_cookie 531is an opaque value that uniquely determines which 532device a device driver has been attached to (i.e., it equals 533the cookie value in the device that the driver attached to). 534The 535.Va ue_devname 536contains the name of the device (driver) as seen in, e.g., 537kernel messages. 538.Pp 539Note that there is a separation between device and device 540driver events. 541A device event is generated when a physical 542USB device is attached or detached. 543A single USB device may 544have zero, one, or many device drivers associated with it. 545.Sh KERNEL THREADS 546For each USB bus, i.e., for each host controller, there is 547a kernel thread that handles attach and detach of devices on 548that bus. 549The thread is named 550.Va usbN 551where 552.Va N 553is the bus number. 554.Pp 555In addition there is a kernel thread, 556.Va usbtask , 557which handles various minor tasks that are initiated from 558an interrupt context, but need to sleep, e.g., time-out 559abort of transfers. 560.Sh SEE ALSO 561.Xr usbhidaction 1 , 562.Xr usbhidctl 1 , 563.Xr cardbus 4 , 564.Xr ehci 4 , 565.Xr isa 4 , 566.Xr ohci 4 , 567.Xr pci 4 , 568.Xr pcmcia 4 , 569.Xr slhci 4 , 570.Xr uhci 4 , 571.Xr usbdevs 8 572.Rs 573.%T Universal Serial Bus Specifications Documents 574.%U http://www.usb.org/developers/docs/ 575.Re 576.Sh HISTORY 577The 578.Nm 579driver 580appeared in 581.Nx 1.4 . 582.Sh BUGS 583There should be a serial number locator, but 584.Nx 585does not have string valued locators. 586