1.\" $OpenBSD: usb.4,v 1.11 2001/08/08 22:12:30 jsyn 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?" 48.Cd "usb* at ohci?" 49.Cd "uhub* at usb?" 50.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 51.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 52.Pp 53.Cd "#include <dev/usb/usb.h>" 54.Cd "#include <dev/usb/usbhid.h>" 55.Sh DESCRIPTION 56.Ox 57provides machine-independent bus support and drivers for Universal Serial Bus 58.Pq Tn USB 59devices. 60.Pp 61The 62.Ox 63.Nm 64driver has three layers (like 65.Xr scsi 4 66and 67.Xr pcmcia 4 ): 68the controller, the bus, and the device layer. 69The controller attaches to a physical bus (like 70.Xr pci 4 ). 71The 72.Tn USB 73bus attaches to the controller and the root hub attaches 74to the controller. 75Further devices, which may include further hubs, 76attach to other hubs. 77The attachment forms the same tree structure as the physical 78.Tn USB 79device tree. 80For each 81.Tn USB 82device there may be additional drivers attached to it. 83.Pp 84The 85.Cm uhub 86device controls 87.Tn USB 88hubs and must always be present since there is at least one root hub in any 89.Tn USB 90system. 91.Sh SUPPORTED DEVICES 92.Ox 93includes machine-independent 94.Tn USB 95drivers, sorted by driver name: 96.Pp 97.Bl -tag -width speakerxx -offset ind -compact 98.It Xr aue 4 99AN986 Pegasus-based Ethernet interfaces. 100.It Xr cue 4 101CATC USB-EL1201A-based Ethernet interfaces. 102.It Xr kue 4 103Kawasaki LSI KL5KUSB101B-based Ethernet interfaces. 104.It Xr uaudio 4 105Audio devices. 106.It Xr ugen 4 107Generic driver for unknown 108.Tn USB 109devices. 110.It Xr uhid 4 111Generic driver for Human Interface Devices. 112.It Xr ulpt 4 113.Tn USB 114Printers. 115.It Xr umass 4 116.Tn USB 117Mass Storage Devices, i.e., external disk drives. 118.It Xr umodem 4 119.Tn USB 120Modems. 121.El 122.Sh INTRODUCTION TO USB 123The 124.Tn USB 125is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 126Each 127.Tn USB 128has a host controller that is the master of the bus; 129all other devices on the bus only speak when spoken to. 130.Pp 131There can be up to 127 devices (apart from the host controller) 132on a bus, each with its own address. 133The addresses are assigned 134dynamically by the host when each device is attached to the bus. 135.Pp 136Within each device there can be up to 16 endpoints. 137Each endpoint 138is individually addressed and the addresses are static. 139Each of these endpoints will communicate in one of four different modes: 140control, isochronous, bulk, or interrupt. 141A device always has at least one endpoint. 142This is a control endpoint at address 0 143and is used to give commands to the device and extract basic data, 144such as descriptors, from the device. 145Each endpoint, except the control endpoint, is unidirectional. 146.Pp 147The endpoints in a device are grouped into interfaces. 148An interface is a logical unit within a device; e.g., 149a compound device with both a keyboard and a trackball would present 150one interface for each. 151An interface can sometimes be set into different modes, 152called alternate settings, which affects how it operates. 153Different alternate settings can have different endpoints 154within it. 155.Pp 156A device may operate in different configurations. 157Depending on the 158configuration the device may present different sets of endpoints 159and interfaces. 160.Pp 161Each device located on a hub has several 162.Xr config 8 163locators: 164.Pp 165.Bl -tag -width configuration -compact 166.It Cd port 167Number of the port on closest upstream hub. 168.It Cd configuration 169Configuration the device must be in for this driver to attach. 170This locator does not set the configuration; it is iterated by the bus 171enumeration. 172.It Cd interface 173Interface number within a device that an interface driver attaches to. 174.It Cd vendor 17516-bit vendor ID of the device. 176.It Cd product 17716-bit product ID of the device. 178.It Cd release 17916-bit release (revision) number of the device. 180.El 181.Pp 182The first locator can be used to pin down a particular device 183according to its physical position in the device tree. 184The last three locators can be used to pin down a particular 185device according to what device it actually is. 186.Pp 187The bus enumeration of the 188.Tn USB 189bus proceeds in several steps: 190.Bl -enum 191.It 192Any device-specific driver can attach to the device. 193.It 194If none is found, any device class specific driver can attach. 195.It 196If none is found, all configurations are iterated over. 197For each configuration all the interface are iterated over and interface 198drivers can attach. 199If any interface driver attached in a certain 200configuration the iteration over configurations is stopped. 201.It 202If still no drivers have been found, the generic 203.Tn USB 204driver can attach. 205.El 206.Sh USB CONTROLLER INTERFACE 207Use the following to get access to the 208.Tn USB 209specific structures and defines. 210.Bd -literal 211#include <sys/dev/usb.h> 212.Ed 213.Pp 214The 215.Pa /dev/usbN 216device can be opened and a few operations can be performed on it. 217The 218.Xr poll 2 219system call will say that I/O is possible on the controller device when a 220.Tn USB 221device has been connected or disconnected to the bus. 222.Pp 223The following 224.Xr ioctl 2 225commands are supported on the controller device: 226.Bl -tag -width xxxxxx 227.\" .It Dv USB_DISCOVER 228.\" This command will cause a complete bus discovery to be initiated. 229.\" If any devices attached or detached from the bus they will be 230.\" processed during this command. 231.\" This is the only way that new devices are found on the bus. 232.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 233This command can be used to retrieve some information about a device 234on the bus. 235The 236.Va addr 237field should be filled before the call and the other fields will 238be filled by information about the device on that address. 239Should no such device exist an error is reported. 240.Bd -literal 241struct usb_device_info { 242 uByte addr; /* device address */ 243 char product[USB_MAX_STRING_LEN]; 244 char vendor[USB_MAX_STRING_LEN]; 245 char release[8]; 246 uByte class; 247 uByte config; 248 uByte lowspeed; 249 int power; 250 int nports; 251 uByte ports[16]; 252#define USB_PORT_ENABLED 0xff 253#define USB_PORT_SUSPENDED 0xfe 254#define USB_PORT_POWERED 0xfd 255#define USB_PORT_DISABLED 0xfc 256}; 257.Ed 258.Pp 259The 260.Va product , 261.Va vendor , 262and 263.Va release 264fields contain self-explanatory descriptions of the device. 265.Pp 266The 267.Va class 268field contains the device class. 269.Pp 270The 271.Va config 272field shows the current configuration of the device. 273.Pp 274The 275.Va lowspeed 276field 277is set if the device is a 278.Tn USB 279low speed device. 280.Pp 281The 282.Va power 283field shows the power consumption in milli-amps drawn at 5 volts, 284or zero if the device is self powered. 285.Pp 286If the device is a hub the 287.Va nports 288field is non-zero and the 289.Va ports 290field contains the addresses of the connected devices. 291If no device is connected to a port one of the 292.Va USB_PORT_* 293values indicates its status. 294.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 295This command retrieves statistics about the controller. 296.Bd -literal 297struct usb_device_stats { 298 u_long requests[4]; 299}; 300.Ed 301.Pp 302The 303.Va requests 304field is indexed by the transfer kind, i.e. 305.Va UE_* , 306and indicates how many transfers of each kind that has been completed 307by the controller. 308.It Dv USB_REQUEST Fa "struct usb_ctl_request" 309This command can be used to execute arbitrary requests on the control pipe. 310This is 311.Em DANGEROUS 312and should be used with great care since it 313can destroy the bus integrity. 314.El 315.Pp 316The include file 317.Aq Pa dev/usb/usb.h 318contains definitions for the types used by the various 319.Xr ioctl 2 320calls. 321The naming convention of the fields for the various 322.Tn USB 323descriptors exactly follows the naming in the 324.Tn USB 325specification. 326Byte sized fields can be accessed directly, but word (16-bit) 327sized fields must be access by the 328.Fn UGETW field 329and 330.Fn USETW field value 331macros to handle byte order and alignment properly. 332.Pp 333The include file 334.Aq Pa dev/usb/usbhid.h 335similarly contains the definitions for 336Human Interface Devices 337.Pq Tn HID . 338.Sh SEE ALSO 339.Xr cardbus 4 , 340.Xr intro 4 , 341.Xr isa 4 , 342.Xr isapnp 4 , 343.Xr pci 4 , 344.Xr pcmcia 4 , 345.Xr usbdevs 8 346.Pp 347The 348.Tn USB 349specifications can be found at: 350.Pp 351.Dl http://www.usb.org/developers/docs.html 352.Sh HISTORY 353The 354.Nm 355driver 356appeared in 357.Ox 2.6 . 358.Sh BUGS 359There should be a serial number locator, but 360.Ox 361does not have string valued locators. 362