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