1.\" $NetBSD: usb.4,v 1.80 2005/12/26 19:48:12 perry 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 August 29, 2005 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 uvisor 189Handspring Visor driver. 190.It uvscom 191driver for SUNTAC Slipper U VS-10U serial adapter. 192.El 193.Sh INTRODUCTION TO USB 194The 195.Tn USB 1961.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. 197.Tn USB 1982.x handles 480 Mb/s. 199Each 200.Tn USB 201has a host controller that is the master of the bus; 202all other devices on the bus only speak when spoken to. 203.Pp 204There can be up to 127 devices (apart from the host controller) 205on a bus, each with its own address. 206The addresses are assigned 207dynamically by the host when each device is attached to the bus. 208.Pp 209Within each device there can be up to 16 endpoints. 210Each endpoint 211is individually addressed and the addresses are static. 212Each of these endpoints will communicate in one of four different modes: 213control, isochronous, bulk, or interrupt. 214A device always has at least one endpoint. 215This endpoint has address 0 and is a control 216endpoint and is used to give commands to and extract basic data, 217such as descriptors, from the device. 218Each endpoint, except the control endpoint, is unidirectional. 219.Pp 220The endpoints in a device are grouped into interfaces. 221An interface is a logical unit within a device; e.g., 222a compound device with both a keyboard and a trackball would present 223one interface for each. 224An interface can sometimes be set into different modes, 225called alternate settings, which affects how it operates. 226Different alternate settings can have different endpoints 227within it. 228.Pp 229A device may operate in different configurations. 230Depending on the 231configuration the device may present different sets of endpoints 232and interfaces. 233.Pp 234Each device located on a hub has several 235.Xr config 1 236locators: 237.Bl -tag -compact -width xxxxxxxxx 238.It Cd port 239this is the number of the port on closest upstream hub. 240.It Cd configuration 241this is the configuration the device must be in for this driver to attach. 242This locator does not set the configuration; it is iterated by the bus 243enumeration. 244.It Cd interface 245this is the interface number within a device that an interface driver 246attaches to. 247.It Cd vendor 248this is the 16 bit vendor id of the device. 249.It Cd product 250this is the 16 bit product id of the device. 251.It Cd release 252this is the 16 bit release (revision) number of the device. 253.El 254The first locator can be used to pin down a particular device 255according to its physical position in the device tree. 256The last three locators can be used to pin down a particular 257device according to what device it actually is. 258.Pp 259The bus enumeration of the 260.Tn USB 261bus proceeds in several steps: 262.Bl -enum 263.It 264Any device specific driver can to attach to the device. 265.It 266If none is found, any device class specific driver can attach. 267.It 268If none is found, all configurations are iterated over. 269For each configuration all the interface are iterated over and interface 270drivers can attach. 271If any interface driver attached in a certain 272configuration the iteration over configurations is stopped. 273.It 274If still no drivers have been found, the generic 275.Tn USB 276driver can attach. 277.El 278.Sh USB CONTROLLER INTERFACE 279Use the following to get access to the 280.Tn USB 281specific structures and defines. 282.Bd -literal 283#include \*[Lt]dev/usb/usb.h\*[Gt] 284.Ed 285.Pp 286The 287.Pa /dev/usbN 288can be opened and a few operations can be performed on it. 289The 290.Xr poll 2 291system call will say that I/O is possible on the controller device when a 292.Tn USB 293device has been connected or disconnected to the bus. 294.Pp 295The following 296.Xr ioctl 2 297commands are supported on the controller device: 298.Bl -tag -width xxxxxx 299.\" .It Dv USB_DISCOVER 300.\" This command will cause a complete bus discovery to be initiated. 301.\" If any devices attached or detached from the bus they will be 302.\" processed during this command. 303.\" This is the only way that new devices are found on the bus. 304.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 305This command can be used to retrieve some information about a device 306on the bus. 307The 308.Va addr 309field should be filled before the call and the other fields will 310be filled by information about the device on that address. 311Should no such device exist an error is reported. 312.Bd -literal 313struct usb_device_info { 314 uint8_t udi_bus; 315 uint8_t udi_addr; 316 usb_event_cookie_t udi_cookie; 317 char udi_product[USB_MAX_ENCODED_STRING_LEN]; 318 char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; 319 char udi_release[8]; 320 char udi_serial[USB_MAX_ENCODED_STRING_LEN]; 321 uint16_t udi_productNo; 322 uint16_t udi_vendorNo; 323 uint16_t udi_releaseNo; 324 uint8_t udi_class; 325 uint8_t udi_subclass; 326 uint8_t udi_protocol; 327 uint8_t udi_config; 328 uint8_t udi_speed; 329#define USB_SPEED_LOW 1 330#define USB_SPEED_FULL 2 331#define USB_SPEED_HIGH 3 332 int udi_power; 333 int udi_nports; 334 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 335 uint8_t udi_ports[16]; 336#define USB_PORT_ENABLED 0xff 337#define USB_PORT_SUSPENDED 0xfe 338#define USB_PORT_POWERED 0xfd 339#define USB_PORT_DISABLED 0xfc 340}; 341.Ed 342.Pp 343The 344.Va product , 345.Va vendor , 346.Va release , 347and 348.Va serial 349fields contain self-explanatory descriptions of the device. 350.Pp 351The 352.Va class 353field contains the device class. 354.Pp 355The 356.Va config 357field shows the current configuration of the device. 358.Pp 359The 360.Va lowspeed 361field 362is set if the device is a 363.Tn USB 364low speed device. 365.Pp 366The 367.Va power 368field shows the power consumption in milli-amps drawn at 5 volts, 369or zero if the device is self powered. 370.Pp 371If the device is a hub the 372.Va nports 373field is non-zero and the 374.Va ports 375field contains the addresses of the connected devices. 376If no device is connected to a port one of the 377.Va USB_PORT_* 378values indicates its status. 379.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 380This command retrieves statistics about the controller. 381.Bd -literal 382struct usb_device_stats { 383 u_long uds_requests[4]; 384}; 385.Ed 386.Pp 387The 388.Va requests 389field is indexed by the transfer kind, i.e. 390.Va UE_* , 391and indicates how many transfers of each kind that has been completed 392by the controller. 393.It Dv USB_REQUEST Fa "struct usb_ctl_request" 394This command can be used to execute arbitrary requests on the control pipe. 395This is 396.Em DANGEROUS 397and should be used with great care since it 398can destroy the bus integrity. 399.El 400.Pp 401The include file 402.Aq Pa dev/usb/usb.h 403contains definitions for the types used by the various 404.Xr ioctl 2 405calls. 406The naming convention of the fields for the various 407.Tn USB 408descriptors exactly follows the naming in the 409.Tn USB 410specification. 411Byte sized fields can be accessed directly, but word (16 bit) 412sized fields must be access by the 413.Fn UGETW field 414and 415.Fn USETW field value 416macros to handle byte order and alignment properly. 417.Pp 418The include file 419.Aq Pa dev/usb/usbhid.h 420similarly contains the definitions for 421Human Interface Devices 422.Pq Tn HID . 423.Sh USB EVENT INTERFACE 424All 425.Tn USB 426events are reported via the 427.Pa /dev/usb 428device. This devices can be opened for reading and each 429.Xr read 2 430will yield an event record (if something has happened). 431The 432.Xr poll 2 433system call can be used to determine if an event record is available 434for reading. 435.Pp 436The event record has the following definition: 437.Bd -literal 438struct usb_event { 439 int ue_type; 440#define USB_EVENT_CTRLR_ATTACH 1 441#define USB_EVENT_CTRLR_DETACH 2 442#define USB_EVENT_DEVICE_ATTACH 3 443#define USB_EVENT_DEVICE_DETACH 4 444#define USB_EVENT_DRIVER_ATTACH 5 445#define USB_EVENT_DRIVER_DETACH 6 446 struct timespec ue_time; 447 union { 448 struct { 449 int ue_bus; 450 } ue_ctrlr; 451 struct usb_device_info ue_device; 452 struct { 453 usb_event_cookie_t ue_cookie; 454 char ue_devname[16]; 455 } ue_driver; 456 } u; 457}; 458.Ed 459The 460.Va ue_type 461field identifies the type of event that is described. 462The possible events are attach/detach of a host controller, 463a device, or a device driver. The union contains information 464pertinent to the different types of events. 465.br 466The 467.Va ue_bus 468contains the number of the 469.Tn USB 470bus for host controller events. 471.br 472The 473.Va ue_device 474record contains information about the device in a device event event. 475.br 476The 477.Va ue_cookie 478is an opaque value that uniquely determines which 479device a device driver has been attached to (i.e., it equals 480the cookie value in the device that the driver attached to). 481The 482.Va ue_devname 483contains the name of the device (driver) as seen in, e.g., 484kernel messages. 485.Pp 486Note that there is a separation between device and device 487driver events. A device event is generated when a physical 488USB device is attached or detached. A single USB device may 489have zero, one, or many device drivers associated with it. 490.Sh KERNEL THREADS 491For each USB bus, i.e., for each host controller, there is 492a kernel thread that handles attach and detach of devices on 493that bus. 494The thread is named 495.Va usbN 496where 497.Va N 498is the bus number. 499.Pp 500In addition there is a kernel thread, 501.Va usbtask , 502which handles various minor tasks that are initiated from 503an interrupt context, but need to sleep, e.g., time-out 504abort of transfers. 505.Sh SEE ALSO 506The 507.Tn USB 508specifications can be found at: 509.D1 http://www.usb.org/developers/docs/ 510.Pp 511.Xr aue 4 , 512.Xr axe 4 , 513.Xr cardbus 4 , 514.Xr cdce 4 , 515.Xr cue 4 , 516.Xr ehci 4 , 517.Xr isa 4 , 518.Xr kue 4 , 519.Xr ohci 4 , 520.Xr pci 4 , 521.Xr slhci 4 , 522.Xr uaudio 4 , 523.Xr ubsa 4 , 524.Xr ucom 4 , 525.Xr ucycom 4 , 526.Xr udsbr 4 , 527.Xr uep 4 , 528.Xr ugen 4 , 529.Xr uhci 4 , 530.Xr uhid 4 , 531.Xr uhidev 4 , 532.Xr uirda 4 , 533.Xr ukbd 4 , 534.Xr ukyopon 4 , 535.Xr ulpt 4 , 536.Xr umass 4 , 537.Xr umct 4 , 538.Xr umidi 4 , 539.Xr ums 4 , 540.Xr upl 4 , 541.Xr urio 4 , 542.Xr url 4 , 543.Xr uscanner 4 , 544.Xr usscanner 4 , 545.Xr ustir 4 , 546.Xr uvisor 4 , 547.Xr usbdevs 8 548.Sh HISTORY 549The 550.Nm 551driver 552appeared in 553.Nx 1.4 . 554.Sh BUGS 555There should be a serial number locator, but 556.Nx 557does not have string valued locators. 558