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