1.\" $NetBSD: usb.4,v 1.88 2008/04/30 13:10:54 martin 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.\" 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, 2008 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. The rest of the devices are detected once 104the system becomes functional and the kernel thread for the 105.Va usb 106device is started. 107Sometimes it is desirable to have a device detected early in the 108boot process, e.g., the console keyboard. To achieve this use 109a 110.Va flags 111value of 1. 112.Pp 113.Nx 114supports the following machine-independent 115.Tn USB 116drivers: 117.Ss Storage devices 118.Bl -tag -width 12n -offset ind -compact 119.It Xr umass 4 120.Tn USB 121Mass Storage Devices, e.g., external disk drives 122.El 123.Ss Wired network interfaces 124.Bl -tag -width 12n -offset ind -compact 125.It Xr aue 4 126ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device 127.It Xr axe 4 128ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device 129.It Xr cdce 4 130USB Communication Device Class Ethernet device 131.It Xr cue 4 132CATC USB-EL1201A USB Ethernet device 133.It Xr kue 4 134Kawasaki LSI KL5KUSB101B USB Ethernet device 135.It Xr udav 4 136Davicom DM9601 10/100 USB Ethernet device 137.It Xr url 4 138Realtek RTL8150L 10/100 USB Ethernet device 139.El 140.Ss Wireless network interfaces 141.Bl -tag -width 12n -offset ind -compact 142.It Xr atu 4 143Atmel AT76C50x IEEE 802.11b wireless network device 144.It Xr ral 4 145Ralink Technology USB IEEE 802.11b/g wireless network device 146.It Xr rum 4 147Ralink Technology USB IEEE 802.11a/b/g wireless network device 148.It Xr ubt 4 149USB Bluetooth dongles 150.It Xr zyd 4 151ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device 152.El 153.Ss Serial and parallel interfaces 154.Bl -tag -width 12n -offset ind -compact 155.It Xr ubsa 4 156Belkin USB serial adapter 157.It Xr uchcom 4 158WinChipHead CH341/340 based USB serial adapter 159.It Xr ucom 4 160USB tty support 161.It Xr ucycom 4 162Cypress microcontroller based USB serial adapter 163.It Xr uftdi 4 164FT8U100AX USB serial adapter 165.It Xr ugensa 4 166USB generic serial adapter 167.It Xr uhmodem 4 168USB Huawei 3G wireless modem device 169.It Xr uipaq 4 170iPAQ USB units 171.It Xr ukyopon 4 172USB Kyocera AIR-EDGE PHONE device 173.It Xr ulpt 4 174USB printer support 175.It Xr umct 4 176MCT USB-RS232 USB serial adapter 177.It Xr umodem 4 178USB modem support 179.It Xr uplcom 4 180Prolific PL-2303 USB serial adapter 181.It Xr uslsa 4 182Silicon Laboratories CP2101/CP2102 based USB serial adapter 183.It Xr uvisor 4 184USB Handspring Visor 185.It Xr uvscom 4 186SUNTAC Slipper U VS-10U USB serial adapter 187.El 188.Ss Audio devices 189.Bl -tag -width 12n -offset ind -compact 190.It Xr uaudio 4 191USB audio devices 192.It Xr umidi 4 193USB MIDI devices 194.It Xr urio 4 195Diamond Multimedia Rio MP3 players 196.El 197.Ss Radio receiver devices 198.Bl -tag -width 12n -offset ind -compact 199.It Xr udsbr 4 200D-Link DSB-R100 USB radio device 201.El 202.Ss Human Interface Devices 203.Bl -tag -width 12n -offset ind -compact 204.It Xr uhid 4 205Generic driver for Human Interface Devices 206.It Xr uhidev 4 207Base driver for all Human Interface Devices 208.It Xr ukbd 4 209.Tn USB 210keyboards that follow the boot protocol 211.It Xr ums 4 212.Tn USB 213mouse devices 214.El 215.Ss Miscellaneous devices 216.Bl -tag -width 12n -offset ind -compact 217.It Xr stuirda 4 218Sigmaltel 4116/4220 USB-IrDA bridge 219.It Xr uep 4 220USB eGalax touch-panel 221.It Xr ugen 4 222USB generic devices 223.It Xr uirda 4 224USB IrDA bridges 225.It Xr upl 4 226Prolific based host-to-host adapters 227.It Xr uscanner 4 228USB scanner support 229.It Xr usscanner 4 230SCSI-over-USB scanners 231.It Xr ustir 4 232SigmaTel STIr4200 USB IrDA bridges 233.It Xr utoppy 4 234Topfield TF5000PVR range of digital video recorders 235.It Xr uyap 4 236USB YAP phone firmware loader 237.El 238.Sh INTRODUCTION TO USB 239The 240.Tn USB 2411.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 242.Tn USB 2432.x handles 480 Mb/s. 244Each 245.Tn USB 246has a host controller that is the master of the bus; 247all other devices on the bus only speak when spoken to. 248.Pp 249There can be up to 127 devices (apart from the host controller) 250on a bus, each with its own address. 251The addresses are assigned 252dynamically by the host when each device is attached to the bus. 253.Pp 254Within each device there can be up to 16 endpoints. 255Each endpoint 256is individually addressed and the addresses are static. 257Each of these endpoints will communicate in one of four different modes: 258control, isochronous, bulk, or interrupt. 259A device always has at least one endpoint. 260This endpoint has address 0 and is a control 261endpoint and is used to give commands to and extract basic data, 262such as descriptors, from the device. 263Each endpoint, except the control endpoint, is unidirectional. 264.Pp 265The endpoints in a device are grouped into interfaces. 266An interface is a logical unit within a device; e.g., 267a compound device with both a keyboard and a trackball would present 268one interface for each. 269An interface can sometimes be set into different modes, 270called alternate settings, which affects how it operates. 271Different alternate settings can have different endpoints 272within it. 273.Pp 274A device may operate in different configurations. 275Depending on the 276configuration the device may present different sets of endpoints 277and interfaces. 278.Pp 279Each device located on a hub has several 280.Xr config 1 281locators: 282.Bl -tag -compact -width xxxxxxxxx 283.It Cd port 284this is the number of the port on closest upstream hub. 285.It Cd configuration 286this is the configuration the device must be in for this driver to attach. 287This locator does not set the configuration; it is iterated by the bus 288enumeration. 289.It Cd interface 290this is the interface number within a device that an interface driver 291attaches to. 292.It Cd vendor 293this is the 16 bit vendor id of the device. 294.It Cd product 295this is the 16 bit product id of the device. 296.It Cd release 297this is the 16 bit release (revision) number of the device. 298.El 299The first locator can be used to pin down a particular device 300according to its physical position in the device tree. 301The last three locators can be used to pin down a particular 302device according to what device it actually is. 303.Pp 304The bus enumeration of the 305.Tn USB 306bus proceeds in several steps: 307.Bl -enum 308.It 309Any device specific driver can to attach to the device. 310.It 311If none is found, any device class specific driver can attach. 312.It 313If none is found, all configurations are iterated over. 314For each configuration all the interface are iterated over and interface 315drivers can attach. 316If any interface driver attached in a certain 317configuration the iteration over configurations is stopped. 318.It 319If still no drivers have been found, the generic 320.Tn USB 321driver can attach. 322.El 323.Sh USB CONTROLLER INTERFACE 324Use the following to get access to the 325.Tn USB 326specific structures and defines. 327.Bd -literal 328#include \*[Lt]dev/usb/usb.h\*[Gt] 329.Ed 330.Pp 331The 332.Pa /dev/usbN 333can be opened and a few operations can be performed on it. 334The 335.Xr poll 2 336system call will say that I/O is possible on the controller device when a 337.Tn USB 338device has been connected or disconnected to the bus. 339.Pp 340The following 341.Xr ioctl 2 342commands are supported on the controller device: 343.Bl -tag -width xxxxxx 344.\" .It Dv USB_DISCOVER 345.\" This command will cause a complete bus discovery to be initiated. 346.\" If any devices attached or detached from the bus they will be 347.\" processed during this command. 348.\" This is the only way that new devices are found on the bus. 349.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 350This command can be used to retrieve some information about a device 351on the bus. 352The 353.Va addr 354field should be filled before the call and the other fields will 355be filled by information about the device on that address. 356Should no such device exist an error is reported. 357.Bd -literal 358struct usb_device_info { 359 uint8_t udi_bus; 360 uint8_t udi_addr; 361 usb_event_cookie_t udi_cookie; 362 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 363 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 364 char udi_release[8]; 365 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 366 uint16_t udi_productNo; 367 uint16_t udi_vendorNo; 368 uint16_t udi_releaseNo; 369 uint8_t udi_class; 370 uint8_t udi_subclass; 371 uint8_t udi_protocol; 372 uint8_t udi_config; 373 uint8_t udi_speed; 374#define USB_SPEED_LOW 1 375#define USB_SPEED_FULL 2 376#define USB_SPEED_HIGH 3 377 int udi_power; 378 int udi_nports; 379 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 380 uint8_t udi_ports[16]; 381#define USB_PORT_ENABLED 0xff 382#define USB_PORT_SUSPENDED 0xfe 383#define USB_PORT_POWERED 0xfd 384#define USB_PORT_DISABLED 0xfc 385}; 386.Ed 387.Pp 388The 389.Va product , 390.Va vendor , 391.Va release , 392and 393.Va serial 394fields contain self-explanatory descriptions of the device. 395.Pp 396The 397.Va class 398field contains the device class. 399.Pp 400The 401.Va config 402field shows the current configuration of the device. 403.Pp 404The 405.Va lowspeed 406field 407is set if the device is a 408.Tn USB 409low speed device. 410.Pp 411The 412.Va power 413field shows the power consumption in milli-amps drawn at 5 volts, 414or zero if the device is self powered. 415.Pp 416If the device is a hub the 417.Va nports 418field is non-zero and the 419.Va ports 420field contains the addresses of the connected devices. 421If no device is connected to a port one of the 422.Va USB_PORT_* 423values indicates its status. 424.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 425This command retrieves statistics about the controller. 426.Bd -literal 427struct usb_device_stats { 428 u_long uds_requests[4]; 429}; 430.Ed 431.Pp 432The 433.Va requests 434field is indexed by the transfer kind, i.e. 435.Va UE_* , 436and indicates how many transfers of each kind that has been completed 437by the controller. 438.It Dv USB_REQUEST Fa "struct usb_ctl_request" 439This command can be used to execute arbitrary requests on the control pipe. 440This is 441.Em DANGEROUS 442and should be used with great care since it 443can destroy the bus integrity. 444.El 445.Pp 446The include file 447.Aq Pa dev/usb/usb.h 448contains definitions for the types used by the various 449.Xr ioctl 2 450calls. 451The naming convention of the fields for the various 452.Tn USB 453descriptors exactly follows the naming in the 454.Tn USB 455specification. 456Byte sized fields can be accessed directly, but word (16 bit) 457sized fields must be access by the 458.Fn UGETW field 459and 460.Fn USETW field value 461macros to handle byte order and alignment properly. 462.Pp 463The include file 464.Aq Pa dev/usb/usbhid.h 465similarly contains the definitions for 466Human Interface Devices 467.Pq Tn HID . 468.Sh USB EVENT INTERFACE 469All 470.Tn USB 471events are reported via the 472.Pa /dev/usb 473device. This devices can be opened for reading and each 474.Xr read 2 475will yield an event record (if something has happened). 476The 477.Xr poll 2 478system call can be used to determine if an event record is available 479for reading. 480.Pp 481The event record has the following definition: 482.Bd -literal 483struct usb_event { 484 int ue_type; 485#define USB_EVENT_CTRLR_ATTACH 1 486#define USB_EVENT_CTRLR_DETACH 2 487#define USB_EVENT_DEVICE_ATTACH 3 488#define USB_EVENT_DEVICE_DETACH 4 489#define USB_EVENT_DRIVER_ATTACH 5 490#define USB_EVENT_DRIVER_DETACH 6 491 struct timespec ue_time; 492 union { 493 struct { 494 int ue_bus; 495 } ue_ctrlr; 496 struct usb_device_info ue_device; 497 struct { 498 usb_event_cookie_t ue_cookie; 499 char ue_devname[16]; 500 } ue_driver; 501 } u; 502}; 503.Ed 504The 505.Va ue_type 506field identifies the type of event that is described. 507The possible events are attach/detach of a host controller, 508a device, or a device driver. The union contains information 509pertinent to the different types of events. 510.br 511The 512.Va ue_bus 513contains the number of the 514.Tn USB 515bus for host controller events. 516.br 517The 518.Va ue_device 519record contains information about the device in a device event event. 520.br 521The 522.Va ue_cookie 523is an opaque value that uniquely determines which 524device a device driver has been attached to (i.e., it equals 525the cookie value in the device that the driver attached to). 526The 527.Va ue_devname 528contains the name of the device (driver) as seen in, e.g., 529kernel messages. 530.Pp 531Note that there is a separation between device and device 532driver events. A device event is generated when a physical 533USB device is attached or detached. A single USB device may 534have zero, one, or many device drivers associated with it. 535.Sh KERNEL THREADS 536For each USB bus, i.e., for each host controller, there is 537a kernel thread that handles attach and detach of devices on 538that bus. 539The thread is named 540.Va usbN 541where 542.Va N 543is the bus number. 544.Pp 545In addition there is a kernel thread, 546.Va usbtask , 547which handles various minor tasks that are initiated from 548an interrupt context, but need to sleep, e.g., time-out 549abort of transfers. 550.Sh SEE ALSO 551The 552.Tn USB 553specifications can be found at: 554.D1 http://www.usb.org/developers/docs/ 555.Pp 556.Xr usbhidaction 1 , 557.Xr usbhidctl 1 , 558.Xr cardbus 4 , 559.Xr ehci 4 , 560.Xr isa 4 , 561.Xr ohci 4 , 562.Xr pci 4 , 563.Xr pcmcia 4 , 564.Xr slhci 4 , 565.Xr uhci 4 , 566.Xr usbdevs 8 567.Sh HISTORY 568The 569.Nm 570driver 571appeared in 572.Nx 1.4 . 573.Sh BUGS 574There should be a serial number locator, but 575.Nx 576does not have string valued locators. 577