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