1.\" $OpenBSD: usb.4,v 1.25 2003/05/05 13:51:58 jmc Exp $ 2.\" $NetBSD: usb.4,v 1.15 1999/07/29 14:20:32 augustss Exp $ 3.\" 4.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Lennart Augustsson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd July 12, 1998 39.Dt USB 4 40.Os 41.Sh NAME 42.Nm usb 43.Nd introduction to Universal Serial Bus support 44.Sh SYNOPSIS 45.Cd "uhci* at pci? function ?" 46.Cd "ohci* at pci? function ?" 47.Cd "usb* at uhci? flags 0x00" 48.Cd "usb* at ohci? flags 0x00" 49.Cd "uhub* at usb?" 50.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ?" 51.Pp 52.Fd "#include <dev/usb/usb.h>" 53.Fd "#include <dev/usb/usbhid.h>" 54.Sh DESCRIPTION 55.Ox 56provides machine-independent bus support and drivers for Universal Serial Bus 57.Pq Tn USB 58devices. 59.Pp 60The 61.Ox 62.Nm 63driver has three layers (like 64.Xr scsi 4 65and 66.Xr pcmcia 4 ) : 67the controller, the bus, and the device layer. 68The controller attaches to a physical bus (like 69.Xr pci 4 ) . 70The 71.Tn USB 72bus attaches to the controller and the root hub attaches 73to the controller. 74Further devices, which may include further hubs, 75attach to other hubs. 76The attachment forms the same tree structure as the physical 77.Tn USB 78device tree. 79For each 80.Tn USB 81device there may be additional drivers attached to it. 82.Pp 83The 84.Cm uhub 85device controls 86.Tn USB 87hubs and must always be present since there is at least one root hub in any 88.Tn USB 89system. 90.Pp 91The 92.Cm flags 93are used to specify if the devices on the 94.Tn USB 95bus should be probed 96early in the boot process. 97If the 98.Cm flags 99are specified with a value of 1, the 100.Tn USB 101bus will be probed when the 102.Tn USB 103host device is attached instead of waiting 104until kernel processes start running. 105This is useful for 106.Tn USB 107console keyboards so that the keyboard is attached 108before getting the root prompt on 109.Dq boot -a . 110.Sh SUPPORTED DEVICES 111.Ox 112includes machine-independent 113.Tn USB 114drivers, sorted by device type and driver name: 115.Ss Storage devices 116.Bl -tag -width 12n -offset ind -compact 117.It Xr umass 4 118.Tn USB 119Mass Storage Devices, e.g., external disk drives. 120.El 121.Ss Ethernet adapters 122.Bl -tag -width 12n -offset ind -compact 123.It Xr aue 4 124ADMtek AN986 / ADM8511 Pegasus family USB Ethernet. 125.It Xr cue 4 126CATC USB-EL1201A-based Ethernet interfaces. 127.It Xr kue 4 128Kawasaki LSI KL5KUSB101B-based Ethernet interfaces. 129.It Xr url 4 130Realtek RTL8150L-based Ethernet interfaces. 131.El 132.Ss Serial and parallel interfaces 133.Bl -tag -width 12n -offset ind -compact 134.It Xr ubsa 4 135Belkin serial adapters. 136.It Xr ucom 4 137Serial port-like devices. 138.It Xr uftdi 4 139FTDI FT8U100AX-based serial adapters. 140.It Xr ulpt 4 141.Tn USB 142Printers. 143.It Xr umct 4 144MCT USB-RS232 serial adapters. 145.It Xr umodem 4 146.Tn USB 147Modems. 148.It Xr uplcom 4 149Prolific PL-2303 serial adapters. 150.It Xr uvscom 4 151SUNTAC Slipper U VS-10U serial adapters. 152.El 153.Ss Audio devices 154.Bl -tag -width 12n -offset ind -compact 155.It Xr uaudio 4 156Audio devices. 157.It Xr umidi 4 158.Tn USB 159MIDI devices. 160.It Xr urio 4 161Diamond Multimedia Rio MP3 players. 162.El 163.Ss Radio receiver devices 164.Bl -tag -width 12n -offset ind -compact 165.It Xr udsbr 4 166D-Link DSB-R100 USB radio. 167.El 168.Ss Human Interface Devices 169.Bl -tag -width 12n -offset ind -compact 170.It Xr uhid 4 171Generic driver for Human Interface Devices. 172.It Xr uhidev 4 173Base driver for all Human Interface Devices. 174.It Xr ukbd 4 175.Tn USB 176keyboards that follow the boot protocol. 177.It Xr ums 4 178.Tn USB 179mouse devices. 180.El 181.Ss Miscellaneous devices 182.Bl -tag -width 12n -offset ind -compact 183.It Xr ugen 4 184Generic driver for unknown 185.Tn USB 186devices. 187.It Xr upl 4 188Prolific based host-to-host adapters. 189.It Xr uscanner 4 190.Tn USB 191scanners. 192.It Xr usscanner 4 193SCSI-over-USB scanners. 194.It Xr uvisor 4 195Handspring Visor. 196.It Xr uyap 4 197YAP phone firmware loader. 198.El 199.Sh INTRODUCTION TO USB 200The 201.Tn USB 202is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 203Each 204.Tn USB 205has a host controller that is the master of the bus; 206all other devices on the bus only speak when spoken to. 207.Pp 208There can be up to 127 devices (apart from the host controller) 209on a bus, each with its own address. 210The addresses are assigned 211dynamically by the host when each device is attached to the bus. 212.Pp 213Within each device there can be up to 16 endpoints. 214Each endpoint 215is individually addressed and the addresses are static. 216Each of these endpoints will communicate in one of four different modes: 217control, isochronous, bulk, or interrupt. 218A device always has at least one endpoint. 219This is a control endpoint at address 0 220and is used to give commands to the device and extract basic data, 221such as descriptors, from the device. 222Each endpoint, except the control endpoint, is unidirectional. 223.Pp 224The endpoints in a device are grouped into interfaces. 225An interface is a logical unit within a device; e.g., 226a compound device with both a keyboard and a trackball would present 227one interface for each. 228An interface can sometimes be set into different modes, 229called alternate settings, which affects how it operates. 230Different alternate settings can have different endpoints 231within it. 232.Pp 233A device may operate in different configurations. 234Depending on the 235configuration the device may present different sets of endpoints 236and interfaces. 237.Pp 238Each device located on a hub has several 239.Xr config 8 240locators: 241.Pp 242.Bl -tag -width configuration -compact 243.It Cd port 244Number of the port on closest upstream hub. 245.It Cd configuration 246Configuration the device must be in for this driver to attach. 247This locator does not set the configuration; it is iterated by the bus 248enumeration. 249.It Cd interface 250Interface number within a device that an interface driver attaches to. 251.It Cd vendor 25216-bit vendor ID of the device. 253.It Cd product 25416-bit product ID of the device. 255.It Cd release 25616-bit release (revision) number of the device. 257.El 258.Pp 259The first locator can be used to pin down a particular device 260according to its physical position in the device tree. 261The last three locators can be used to pin down a particular 262device according to what device it actually is. 263.Pp 264The bus enumeration of the 265.Tn USB 266bus proceeds in several steps: 267.Bl -enum 268.It 269Any device-specific driver can attach to the device. 270.It 271If none is found, any device class specific driver can attach. 272.It 273If none is found, all configurations are iterated over. 274For each configuration all the interfaces are iterated over and interface 275drivers can attach. 276If any interface driver attached in a certain 277configuration, the iteration over configurations is stopped. 278.It 279If still no drivers have been found, the generic 280.Tn USB 281driver can attach. 282.El 283.Sh USB CONTROLLER INTERFACE 284Use the following to get access to the 285.Tn USB 286specific structures and defines. 287.Fd #include <sys/dev/usb.h> 288.Pp 289The 290.Pa /dev/usbN 291device can be opened and a few operations can be performed on it. 292The 293.Xr poll 2 294system call will say that I/O is possible on the controller device when a 295.Tn USB 296device has been connected or disconnected to the bus. 297.Pp 298The following 299.Xr ioctl 2 300commands are supported on the controller device: 301.Bl -tag -width xxxxxx 302.\" .It Dv USB_DISCOVER 303.\" This command will cause a complete bus discovery to be initiated. 304.\" If any devices attached or detached from the bus they will be 305.\" processed during this command. 306.\" This is the only way that new devices are found on the bus. 307.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 308This command can be used to retrieve some information about a device 309on the bus. 310The 311.Va addr 312field should be filled before the call and the other fields will 313be filled by information about the device on that address. 314Should no such device exist an error is reported. 315.Bd -literal 316struct usb_device_info { 317 uByte addr; /* device address */ 318 char product[USB_MAX_STRING_LEN]; 319 char vendor[USB_MAX_STRING_LEN]; 320 char release[8]; 321 uByte class; 322 uByte config; 323 uByte lowspeed; 324 int power; 325 int nports; 326 uByte ports[16]; 327#define USB_PORT_ENABLED 0xff 328#define USB_PORT_SUSPENDED 0xfe 329#define USB_PORT_POWERED 0xfd 330#define USB_PORT_DISABLED 0xfc 331}; 332.Ed 333.Pp 334The 335.Va product , 336.Va vendor , 337and 338.Va release 339fields contain self-explanatory descriptions of the device. 340.Pp 341The 342.Va class 343field contains the device class. 344.Pp 345The 346.Va config 347field shows the current configuration of the device. 348.Pp 349The 350.Va lowspeed 351field 352is set if the device is a 353.Tn USB 354low speed device. 355.Pp 356The 357.Va power 358field shows the power consumption in milli-amps drawn at 5 volts, 359or zero if the device is self powered. 360.Pp 361If the device is a hub the 362.Va nports 363field is non-zero and the 364.Va ports 365field contains the addresses of the connected devices. 366If no device is connected to a port one of the 367.Va USB_PORT_* 368values indicates its status. 369.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 370This command retrieves statistics about the controller. 371.Bd -literal 372struct usb_device_stats { 373 u_long requests[4]; 374}; 375.Ed 376.Pp 377The 378.Va requests 379field is indexed by the transfer kind, i.e. 380.Va UE_* , 381and indicates how many transfers of each kind that has been completed 382by the controller. 383.It Dv USB_REQUEST Fa "struct usb_ctl_request" 384This command can be used to execute arbitrary requests on the control pipe. 385This is 386.Em DANGEROUS 387and should be used with great care since it 388can destroy the bus integrity. 389.El 390.Pp 391The include file 392.Aq Pa dev/usb/usb.h 393contains definitions for the types used by the various 394.Xr ioctl 2 395calls. 396The naming convention of the fields for the various 397.Tn USB 398descriptors exactly follows the naming in the 399.Tn USB 400specification. 401Byte sized fields can be accessed directly, but word (16-bit) 402sized fields must be accessed by the 403.Fn UGETW field 404and 405.Fn USETW field value 406macros to handle byte order and alignment properly. 407.Pp 408The include file 409.Aq Pa dev/usb/usbhid.h 410similarly contains the definitions for 411Human Interface Devices 412.Pq Tn HID . 413.Sh SEE ALSO 414.Xr aue 4 , 415.Xr cardbus 4 , 416.Xr cue 4 , 417.Xr eisa 4 , 418.Xr intro 4 , 419.Xr isa 4 , 420.Xr isapnp 4 , 421.Xr kue 4 , 422.Xr pci 4 , 423.Xr pcmcia 4 , 424.Xr uaudio 4 , 425.Xr ubsa 4 , 426.Xr ucom 4 , 427.Xr udsbr 4 , 428.Xr uftdi 4 , 429.Xr ugen 4 , 430.Xr uhid 4 , 431.Xr uhidev 4 , 432.Xr uhub 4 , 433.Xr ukbd 4 , 434.Xr ulpt 4 , 435.Xr umass 4 , 436.Xr umct 4 , 437.Xr umidi 4 , 438.Xr umodem 4 , 439.Xr ums 4 , 440.Xr upl 4 , 441.Xr uplcom 4 , 442.Xr urio 4 , 443.Xr url 4 , 444.Xr uscanner 4 , 445.Xr usscanner 4 , 446.Xr uvisor 4 , 447.Xr uvscom 4 , 448.Xr uyap 4 , 449.Xr usbdevs 8 450.Pp 451The 452.Tn USB 453specifications can be found at: 454.Pp 455.Dl http://www.usb.org/developers/docs/ 456.Sh HISTORY 457The 458.Nm 459driver 460appeared in 461.Ox 2.6 . 462.Sh BUGS 463There should be a serial number locator, but 464.Ox 465does not have string valued locators. 466