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