1.\" $NetBSD: usb.4,v 1.23 2000/01/16 11:07:40 augustss Exp $ 2.\" 3.\" Copyright (c) 1999 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 12, 1998 38.Dt USB 4 39.Os 40.Sh NAME 41.Nm usb 42.Nd Universal Serial Bus driver 43.Sh SYNOPSIS 44.Cd "uhci* at pci? dev ? function ?" 45.Cd "ohci* at cardbus? dev ? function ?" 46.Cd "ohci* at pci? dev ? function ?" 47.Cd "usb* at uhci? flags X" 48.Cd "usb* at ohci? flags X" 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 INTRODUCTION 56.Nx 57provides machine-independent bus support and drivers for 58.Tn USB 59devices. 60.Pp 61The 62.Nx 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 a root hub in any 89.Tn USB 90system. 91.Pp 92The 93.Va flags 94argument to the 95.Va usb 96device affects the order in which the device detection happens 97during cold boot. 98Normally, only the USB host controller and the 99.Va usb 100device are detected during the autoconfiguration when the 101machine is booted. The rest of the devices are detected once 102the system becomes functional and the kernel thread for the 103.Va usb 104device is started. 105Sometimes it is desirable to have a device detected early in the 106boot process, e.g., the console keyboard. To achieve this use 107a 108.Va flags 109value of 1. 110.Pp 111 112.Sh SUPPORTED DEVICES 113.Nx 114includes machine-independent 115.Tn USB 116drivers, sorted by driver name: 117.Bl -tag -width speaker -offset indent 118.It aue 119driver for ADMtek AN986 Pegasus USB Ethernet. 120.It cue 121driver for CATC USB-EL1201A USB Ethernet. 122.It kue 123driver for Kawasaki LSI KL5KUSB101B USB Ethernet. 124.It uaudio 125driver for audio devices. 126.It ugen 127generic driver for 128.Tn USB 129devices. 130.It uhid 131generic driver for Human Interface Devices. 132.It ukbd 133keyboard driver 134.It ulpt 135printer driver. 136.It umass 137driver for mass storage devices, such as disks. 138.It umodem 139driver for communication devices that use the Abstract Control Model. 140.It ums 141mouse driver 142.El 143 144.Sh INTRODUCTION TO USB 145The 146.Tn USB 147is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 148Each 149.Tn USB 150has a host controller that is the master of the bus; 151all other devices on the bus only speak when spoken to. 152.Pp 153There can be up to 127 devices (apart from the host controller) 154on a bus, each with its own address. 155The addresses are assigned 156dynamically by the host when each device is attached to the bus. 157.Pp 158Within each device there can be up to 16 endpoints. 159Each endpoint 160is individually addressed and the addresses are static. 161Each of these endpoints will communicate in one of four different modes: 162control, isochronous, bulk, or interrupt. 163A device always has at least one endpoint. 164This endpoint has address 0 and is a control 165endpoint and is used to give commands to and extract basic data, 166such as descriptors, from the device. 167Each endpoint, except the control endpoint, is unidirectional. 168.Pp 169The endpoints in a device are grouped into interfaces. 170An interface is a logical unit within a device; e.g., 171a compound device with both a keyboard and a trackball would present 172one interface for each. 173An interface can sometimes be set into different modes, 174called alternate settings, which affects how it operates. 175Different alternate settings can have different endpoints 176within it. 177.Pp 178A device may operate in different configurations. 179Depending on the 180configuration the device may present different sets of endpoints 181and interfaces. 182.Pp 183Each device located on a hub has several 184.Xr config 8 185locators: 186.Bl -tag -compact -width xxxxxxxxx 187.It Cd port 188this is the number of the port on closest upstream hub. 189.It Cd configuration 190this is the configuration the device must be in for this driver to attach. 191This locator does not set the configuration; it is iterated by the bus 192enumeration. 193.It Cd interface 194this is the interface number within a device that an interface driver 195attaches to. 196.It Cd vendor 197this is the 16 bit vendor id of the device. 198.It Cd product 199this is the 16 bit product id of the device. 200.It Cd release 201this is the 16 bit release (revision) number of the device. 202.El 203The first locator can be used to pin down a particular device 204according to its physical position in the device tree. 205The last three locators can be used to pin down a particular 206device according to what device it actually is. 207.Pp 208The bus enumeration of the 209.Tn USB 210bus proceeds in several steps: 211.Bl -enum 212.It 213Any device specific driver can to attach to the device. 214.It 215If none is found, any device class specific driver can attach. 216.It 217If none is found, all configurations are iterated over. 218For each configuration all the interface are iterated over and interface 219drivers can attach. 220If any interface driver attached in a certain 221configuration the iteration over configurations is stopped. 222.It 223If still no drivers have been found, the generic 224.Tn USB 225driver can attach. 226.El 227.Sh USB CONTROLLER INTERFACE 228Use the following to get access to the 229.Tn USB 230specific structurs and defines. 231.Bd -literal 232#include <sys/dev/usb.h> 233.Ed 234.Pp 235The 236.Pa /dev/usbN 237can be opened and a few operations can be performed on it. 238The 239.Xr poll 2 240system call will say that I/O is possible on the controller device when a 241.Tn USB 242device has been connected or disconnected to the bus. 243.Pp 244The following 245.Xr ioctl 2 246commands are supported on the controller device: 247.Bl -tag -width xxxxxx 248.\" .It Dv USB_DISCOVER 249.\" This command will cause a complete bus discovery to be initiated. 250.\" If any devices attached or detached from the bus they will be 251.\" processed during this command. 252.\" This is the only way that new devices are found on the bus. 253.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 254This command can be used to retrieve some information about a device 255on the bus. 256The 257.Va addr 258field should be filled before the call and the other fields will 259be filled by information about the device on that address. 260Should no such device exist an error is reported. 261.Bd -literal 262struct usb_device_info { 263 uByte addr; /* device address */ 264 char product[USB_MAX_STRING_LEN]; 265 char vendor[USB_MAX_STRING_LEN]; 266 char release[8]; 267 uByte class; 268 uByte config; 269 uByte lowspeed; 270 int power; 271 int nports; 272 uByte ports[16]; 273#define USB_PORT_ENABLED 0xff 274#define USB_PORT_SUSPENDED 0xfe 275#define USB_PORT_POWERED 0xfd 276#define USB_PORT_DISABLED 0xfc 277}; 278.Ed 279.Pp 280The 281.Va product , 282.Va vendor , 283and 284.Va release 285fields contain self-explanatory descriptions of the device. 286.Pp 287The 288.Va class 289field contains the device class. 290.Pp 291The 292.Va config 293field shows the current configuration of the device. 294.Pp 295The 296.Va lowspeed 297field 298is set if the device is a 299.Tn USB 300low speed device. 301.Pp 302The 303.Va power 304field shows the power consumption in milli-amps drawn at 5 volts, 305or zero if the device is self powered. 306.Pp 307If the device is a hub the 308.Va nports 309field is non-zero and the 310.Va ports 311field contains the addresses of the connected devices. 312If no device is connected to a port one of the 313.Va USB_PORT_* 314values indicates its status. 315.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 316This command retrieves statistics about the controller. 317.Bd -literal 318struct usb_device_stats { 319 u_long requests[4]; 320}; 321.Ed 322.Pp 323The 324.Va requests 325field is indexed by the transfer kind, i.e. 326.Va UE_* , 327and indicates how many transfers of each kind that has been completed 328by the controller. 329.It Dv USB_REQUEST Fa "struct usb_ctl_request" 330This command can be used to execute arbitrary requests on the control pipe. 331This is 332.Em DANGEROUS 333and should be used with great care since it 334can destroy the bus integrity. 335.El 336.Pp 337The include file 338.Aq Pa dev/usb/usb.h 339contains definitions for the types used by the various 340.Xr ioctl 2 341calls. 342The naming convention of the fields for the various 343.Tn USB 344descriptors exactly follows the naming in the 345.Tn USB 346specification. 347Byte sized fields can be accessed directly, but word (16 bit) 348sized fields must be access by the 349.Fn UGETW field 350and 351.Fn USETW field value 352macros to handle byte order and alignment properly. 353.Pp 354The include file 355.Aq Pa dev/usb/usbhid.h 356similarly contains the definitions for 357Human Interface Devices 358.Pq Tn HID . 359.Sh BUGS 360There should be a serial number locator, but 361.Nx 362does not have string valued locators. 363.Sh SEE ALSO 364The 365.Tn USB 366specifications can be found at 367.Dv http://www.usb.org/developers/docs.htm . 368.Pp 369.Xr aue 4 , 370.Xr cardbus 4 , 371.Xr cue 4 , 372.Xr kue 4 , 373.Xr pci 4 , 374.Xr uaudio 4 , 375.Xr ugen 4 , 376.Xr uhid 4 , 377.Xr ukbd 4 , 378.Xr ulpt 4 , 379.Xr umass 4 , 380.Xr ums 4 , 381.Xr usb 3 , 382.Xr usbdevs 8 383.Sh HISTORY 384The 385.Nm 386driver 387appeared in 388.Nx 1.4 . 389