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