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