1.\" $NetBSD: usb.4,v 1.87 2008/03/25 19:53:13 apb Exp $ 2.\" 3.\" Copyright (c) 1999-2008 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 25, 2008 38.Dt USB 4 39.Os 40.Sh NAME 41.Nm usb 42.Nd Universal Serial Bus driver 43.Sh SYNOPSIS 44.Cd "ehci* at cardbus? function ?" 45.Cd "ehci* at pci? dev ? function ?" 46.Cd "ohci* at cardbus? function ?" 47.Cd "ohci* at pci? dev ? function ?" 48.Cd "slhci* at isa? port ? irq ?" 49.Cd "slhci* at pcmcia? function ? 50.Cd "uhci* at cardbus? function ?" 51.Cd "uhci* at pci? dev ? function ?" 52.Cd "usb* at ehci? flags X" 53.Cd "usb* at ohci? flags X" 54.Cd "usb* at uhci? flags X" 55.Cd "usb* at slhci? flags X" 56.Cd "uhub* at usb?" 57.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 58.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 59.Pp 60.Cd options USBVERBOSE 61.Pp 62.In dev/usb/usb.h 63.In dev/usb/usbhid.h 64.Sh DESCRIPTION 65.Nx 66provides machine-independent bus support and drivers for 67.Tn USB 68devices. 69.Pp 70The 71.Nx 72.Nm 73driver has three layers (like 74.Xr scsi 4 75and 76.Xr pcmcia 4 ) : 77the controller, the bus, and the device layer. 78The controller attaches to a physical bus (like 79.Xr pci 4 ) . 80The 81.Tn USB 82bus attaches to the controller and the root hub attaches 83to the bus. 84Further devices, which may include further hubs, 85attach to other hubs. 86The attachment forms the same tree structure as the physical 87.Tn USB 88device tree. 89For each 90.Tn USB 91device there may be additional drivers attached to it. 92.Pp 93The 94.Cm uhub 95device controls 96.Tn USB 97hubs and must always be present since there is at least a root hub in any 98.Tn USB 99system. 100.Pp 101The 102.Va flags 103argument to the 104.Va usb 105device affects the order in which the device detection happens 106during cold boot. 107Normally, only the USB host controller and the 108.Va usb 109device are detected during the autoconfiguration when the 110machine is booted. The rest of the devices are detected once 111the system becomes functional and the kernel thread for the 112.Va usb 113device is started. 114Sometimes it is desirable to have a device detected early in the 115boot process, e.g., the console keyboard. To achieve this use 116a 117.Va flags 118value of 1. 119.Pp 120.Nx 121supports the following machine-independent 122.Tn USB 123drivers: 124.Ss Storage devices 125.Bl -tag -width 12n -offset ind -compact 126.It Xr umass 4 127.Tn USB 128Mass Storage Devices, e.g., external disk drives 129.El 130.Ss Wired network interfaces 131.Bl -tag -width 12n -offset ind -compact 132.It Xr aue 4 133ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 134.It Xr axe 4 135ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 136.It Xr cdce 4 137USB Communication Device Class Ethernet device 138.It Xr cue 4 139CATC USB-EL1201A USB Ethernet device 140.It Xr kue 4 141Kawasaki LSI KL5KUSB101B USB Ethernet device 142.It Xr udav 4 143Davicom DM9601 10/100 USB Ethernet device 144.It Xr url 4 145Realtek RTL8150L 10/100 USB Ethernet device 146.El 147.Ss Wireless network interfaces 148.Bl -tag -width 12n -offset ind -compact 149.It Xr atu 4 150Atmel AT76C50x IEEE 802.11b wireless network device 151.It Xr ral 4 152Ralink Technology USB IEEE 802.11b/g wireless network device 153.It Xr rum 4 154Ralink Technology USB IEEE 802.11a/b/g wireless network device 155.It Xr ubt 4 156USB Bluetooth dongles 157.It Xr zyd 4 158ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 159.El 160.Ss Serial and parallel interfaces 161.Bl -tag -width 12n -offset ind -compact 162.It Xr ubsa 4 163Belkin USB serial adapter 164.It Xr uchcom 4 165WinChipHead CH341/340 based USB serial adapter 166.It Xr ucom 4 167USB tty support 168.It Xr ucycom 4 169Cypress microcontroller based USB serial adapter 170.It Xr uftdi 4 171FT8U100AX USB serial adapter 172.It Xr ugensa 4 173USB generic serial adapter 174.It Xr uhmodem 4 175USB Huawei 3G wireless modem device 176.It Xr uipaq 4 177iPAQ USB units 178.It Xr ukyopon 4 179USB Kyocera AIR-EDGE PHONE device 180.It Xr ulpt 4 181USB printer support 182.It Xr umct 4 183MCT USB-RS232 USB serial adapter 184.It Xr umodem 4 185USB modem support 186.It Xr uplcom 4 187Prolific PL-2303 USB serial adapter 188.It Xr uslsa 4 189Silicon Laboratories CP2101/CP2102 based USB serial adapter 190.It Xr uvisor 4 191USB Handspring Visor 192.It Xr uvscom 4 193SUNTAC Slipper U VS-10U USB serial adapter 194.El 195.Ss Audio devices 196.Bl -tag -width 12n -offset ind -compact 197.It Xr uaudio 4 198USB audio devices 199.It Xr umidi 4 200USB MIDI devices 201.It Xr urio 4 202Diamond Multimedia Rio MP3 players 203.El 204.Ss Radio receiver devices 205.Bl -tag -width 12n -offset ind -compact 206.It Xr udsbr 4 207D-Link DSB-R100 USB radio device 208.El 209.Ss Human Interface Devices 210.Bl -tag -width 12n -offset ind -compact 211.It Xr uhid 4 212Generic driver for Human Interface Devices 213.It Xr uhidev 4 214Base driver for all Human Interface Devices 215.It Xr ukbd 4 216.Tn USB 217keyboards that follow the boot protocol 218.It Xr ums 4 219.Tn USB 220mouse devices 221.El 222.Ss Miscellaneous devices 223.Bl -tag -width 12n -offset ind -compact 224.It Xr stuirda 4 225Sigmaltel 4116/4220 USB-IrDA bridge 226.It Xr uep 4 227USB eGalax touch-panel 228.It Xr ugen 4 229USB generic devices 230.It Xr uirda 4 231USB IrDA bridges 232.It Xr upl 4 233Prolific based host-to-host adapters 234.It Xr uscanner 4 235USB scanner support 236.It Xr usscanner 4 237SCSI-over-USB scanners 238.It Xr ustir 4 239SigmaTel STIr4200 USB IrDA bridges 240.It Xr utoppy 4 241Topfield TF5000PVR range of digital video recorders 242.It Xr uyap 4 243USB YAP phone firmware loader 244.El 245.Sh INTRODUCTION TO USB 246The 247.Tn USB 2481.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 249.Tn USB 2502.x handles 480 Mb/s. 251Each 252.Tn USB 253has 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 312.Tn USB 313bus proceeds in several steps: 314.Bl -enum 315.It 316Any device specific driver can to attach to the device. 317.It 318If none is found, any device class specific driver can attach. 319.It 320If none is found, all configurations are iterated over. 321For each configuration all the interface are iterated over and interface 322drivers can attach. 323If any interface driver attached in a certain 324configuration the iteration over configurations is stopped. 325.It 326If still no drivers have been found, the generic 327.Tn USB 328driver can attach. 329.El 330.Sh USB CONTROLLER INTERFACE 331Use the following to get access to the 332.Tn USB 333specific structures and defines. 334.Bd -literal 335#include \*[Lt]dev/usb/usb.h\*[Gt] 336.Ed 337.Pp 338The 339.Pa /dev/usbN 340can be opened and a few operations can be performed on it. 341The 342.Xr poll 2 343system call will say that I/O is possible on the controller device when a 344.Tn USB 345device has been connected or disconnected to the bus. 346.Pp 347The following 348.Xr ioctl 2 349commands are supported on the controller device: 350.Bl -tag -width xxxxxx 351.\" .It Dv USB_DISCOVER 352.\" This command will cause a complete bus discovery to be initiated. 353.\" If any devices attached or detached from the bus they will be 354.\" processed during this command. 355.\" This is the only way that new devices are found on the bus. 356.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 357This command can be used to retrieve some information about a device 358on the bus. 359The 360.Va addr 361field should be filled before the call and the other fields will 362be filled by information about the device on that address. 363Should no such device exist an error is reported. 364.Bd -literal 365struct usb_device_info { 366 uint8_t udi_bus; 367 uint8_t udi_addr; 368 usb_event_cookie_t udi_cookie; 369 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 370 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 371 char udi_release[8]; 372 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 373 uint16_t udi_productNo; 374 uint16_t udi_vendorNo; 375 uint16_t udi_releaseNo; 376 uint8_t udi_class; 377 uint8_t udi_subclass; 378 uint8_t udi_protocol; 379 uint8_t udi_config; 380 uint8_t udi_speed; 381#define USB_SPEED_LOW 1 382#define USB_SPEED_FULL 2 383#define USB_SPEED_HIGH 3 384 int udi_power; 385 int udi_nports; 386 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 387 uint8_t udi_ports[16]; 388#define USB_PORT_ENABLED 0xff 389#define USB_PORT_SUSPENDED 0xfe 390#define USB_PORT_POWERED 0xfd 391#define USB_PORT_DISABLED 0xfc 392}; 393.Ed 394.Pp 395The 396.Va product , 397.Va vendor , 398.Va release , 399and 400.Va serial 401fields contain self-explanatory descriptions of the device. 402.Pp 403The 404.Va class 405field contains the device class. 406.Pp 407The 408.Va config 409field shows the current configuration of the device. 410.Pp 411The 412.Va lowspeed 413field 414is set if the device is a 415.Tn USB 416low speed device. 417.Pp 418The 419.Va power 420field shows the power consumption in milli-amps drawn at 5 volts, 421or zero if the device is self powered. 422.Pp 423If the device is a hub the 424.Va nports 425field is non-zero and the 426.Va ports 427field contains the addresses of the connected devices. 428If no device is connected to a port one of the 429.Va USB_PORT_* 430values indicates its status. 431.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 432This command retrieves statistics about the controller. 433.Bd -literal 434struct usb_device_stats { 435 u_long uds_requests[4]; 436}; 437.Ed 438.Pp 439The 440.Va requests 441field is indexed by the transfer kind, i.e. 442.Va UE_* , 443and indicates how many transfers of each kind that has been completed 444by the controller. 445.It Dv USB_REQUEST Fa "struct usb_ctl_request" 446This command can be used to execute arbitrary requests on the control pipe. 447This is 448.Em DANGEROUS 449and should be used with great care since it 450can destroy the bus integrity. 451.El 452.Pp 453The include file 454.Aq Pa dev/usb/usb.h 455contains definitions for the types used by the various 456.Xr ioctl 2 457calls. 458The naming convention of the fields for the various 459.Tn USB 460descriptors exactly follows the naming in the 461.Tn USB 462specification. 463Byte sized fields can be accessed directly, but word (16 bit) 464sized fields must be access by the 465.Fn UGETW field 466and 467.Fn USETW field value 468macros to handle byte order and alignment properly. 469.Pp 470The include file 471.Aq Pa dev/usb/usbhid.h 472similarly contains the definitions for 473Human Interface Devices 474.Pq Tn HID . 475.Sh USB EVENT INTERFACE 476All 477.Tn USB 478events are reported via the 479.Pa /dev/usb 480device. This devices can be opened for reading and each 481.Xr read 2 482will yield an event record (if something has happened). 483The 484.Xr poll 2 485system call can be used to determine if an event record is available 486for reading. 487.Pp 488The event record has the following definition: 489.Bd -literal 490struct usb_event { 491 int ue_type; 492#define USB_EVENT_CTRLR_ATTACH 1 493#define USB_EVENT_CTRLR_DETACH 2 494#define USB_EVENT_DEVICE_ATTACH 3 495#define USB_EVENT_DEVICE_DETACH 4 496#define USB_EVENT_DRIVER_ATTACH 5 497#define USB_EVENT_DRIVER_DETACH 6 498 struct timespec ue_time; 499 union { 500 struct { 501 int ue_bus; 502 } ue_ctrlr; 503 struct usb_device_info ue_device; 504 struct { 505 usb_event_cookie_t ue_cookie; 506 char ue_devname[16]; 507 } ue_driver; 508 } u; 509}; 510.Ed 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. The union contains information 516pertinent to the different types of events. 517.br 518The 519.Va ue_bus 520contains the number of the 521.Tn USB 522bus for host controller events. 523.br 524The 525.Va ue_device 526record contains information about the device in a device event event. 527.br 528The 529.Va ue_cookie 530is an opaque value that uniquely determines which 531device a device driver has been attached to (i.e., it equals 532the cookie value in the device that the driver attached to). 533The 534.Va ue_devname 535contains the name of the device (driver) as seen in, e.g., 536kernel messages. 537.Pp 538Note that there is a separation between device and device 539driver events. A device event is generated when a physical 540USB device is attached or detached. A single USB device may 541have zero, one, or many device drivers associated with it. 542.Sh KERNEL THREADS 543For each USB bus, i.e., for each host controller, there is 544a kernel thread that handles attach and detach of devices on 545that bus. 546The thread is named 547.Va usbN 548where 549.Va N 550is the bus number. 551.Pp 552In addition there is a kernel thread, 553.Va usbtask , 554which handles various minor tasks that are initiated from 555an interrupt context, but need to sleep, e.g., time-out 556abort of transfers. 557.Sh SEE ALSO 558The 559.Tn USB 560specifications can be found at: 561.D1 http://www.usb.org/developers/docs/ 562.Pp 563.Xr usbhidaction 1 , 564.Xr usbhidctl 1 , 565.Xr cardbus 4 , 566.Xr ehci 4 , 567.Xr isa 4 , 568.Xr ohci 4 , 569.Xr pci 4 , 570.Xr pcmcia 4 , 571.Xr slhci 4 , 572.Xr uhci 4 , 573.Xr usbdevs 8 574.Sh HISTORY 575The 576.Nm 577driver 578appeared in 579.Nx 1.4 . 580.Sh BUGS 581There should be a serial number locator, but 582.Nx 583does not have string valued locators. 584