1.\" $NetBSD: usb.4,v 1.10 1999/01/14 11:07:44 augustss Exp $ 2.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the NetBSD 17.\" Foundation, Inc. and its contributors. 18.\" 4. Neither the name of The NetBSD Foundation nor the names of its 19.\" contributors may be used to endorse or promote products derived 20.\" from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 26.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd July 12, 1998 35.Dt USB 4 36.Os 37.Sh NAME 38.Nm usb 39.Nd Universal Serial Bus driver 40.Sh SYNOPSIS 41.Cd "uhci* at pci? function ?" 42.Cd "ohci* at pci? function ?" 43.Cd "usb* at uhci?" 44.Cd "usb* at ohci?" 45.Cd "uhub* at usb?" 46.Cd "uhub* at uhub? port ? configuration ? interface ?" 47.Cd "XX* at uhub? port ? configuration ? interface ?" 48.Pp 49.Cd "#include <dev/usb/usb.h>" 50.Cd "#include <dev/usb/usbhid.h>" 51.Sh INTRODUCTION 52.Nx 53provides machine-independent bus support and drivers for 54.Tn USB 55devices. 56.Pp 57The 58.Nx 59.Nm 60driver has three layers (like 61.Xr scsi 4 62and 63.Xr pcmcia 4 ): 64the controller, the bus, and the device layer. 65The controller attaches to a physical bus (like 66.Xr pci 4 ). 67The 68.Tn USB 69bus attaches to the controller and the root hub attaches 70to the controller. 71Further devices, which may include further hubs, 72attach to other hubs. 73The attachment forms the same tree structure as the physical 74.Tn USB 75device tree. 76For each 77.Tn USB 78device there may be additional drivers attached to it. 79.Pp 80The 81.Cm uhub 82device controls 83.Tn USB 84hubs and must always be present since there is at least a root hub in any 85.Tn USB 86system. 87.Pp 88.Sh INTRODUCTION TO USB 89The 90.Tn USB 91is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 92Each 93.Tn USB 94has a host controller that is the master of the bus; 95all other devices on the bus only speak when spoken to. 96.Pp 97There can be up to 127 devices (apart from the host controller) 98on a bus, each with its own address. 99The addresses are assigned 100dynamically by the host when each device is attached to the bus. 101.Pp 102Within each device there can be up to 16 endpoints. 103Each endpoint 104is individually addressed and the addresses are static. 105Each of these endpoints will communicate in one of four different modes: 106control, isochronous, bulk, or interrupt. 107A device always has at least one endpoint. 108This endpoint has address 0 and is a control 109endpoint and is used to give commands to and extract basic data, 110such as descriptors, from the device. 111Each endpoint, except the control endpoint, is unidirectional. 112.Pp 113The endpoints in a device are grouped into interfaces. 114An interface is a logical unit within a device; e.g. 115a compound device with both a keyboard and a trackball would present 116one interface for each. 117An interface can sometimes be set into different modes, 118called alternate settings, which affects how it operates. 119Different alternate settings can have different endpoints 120within it. 121.Pp 122A device may operate in different configurations. 123Depending on the 124configuration the device may present different sets of endpoints 125and interfaces. 126.Pp 127Each device located on a hub has several 128.Xr config 8 129locators: 130.Bl -tag -compact -width xxxxxx 131.It Cd port 132this is the number of the port on closest upstream hub. 133.It Cd configuration 134this is the configuration the device must be in for this driver to attach. 135This locator does not set the configuration; it is iterated by the bus 136enumeration. 137.It Cd interface 138this is the interface number within a device that an interface driver 139attaches to. 140.El 141.Pp 142The bus enumeration of the 143.Tn USB 144bus proceeds in several steps: 145.Bl -enum 146.It 147Any device specific driver can to attach to the device. 148.It 149If none is found, any device class specific driver can attach. 150.It 151If none is found, all configurations are iterated over. 152For each configuration all the interface are iterated over and interface 153drivers can attach. 154If any interface driver attached in a certain 155configuration the iteration over configurations is stopped. 156.It 157If still no drivers have been found, the generic 158.Tn USB 159driver can attach. 160.El 161.Sh USB CONTROLLER INTERFACE 162Use the following to get access to the 163.Tn USB 164specific structurs and defines. 165.Bd -literal 166#include <sys/dev/usb.h> 167.Ed 168.Pp 169The 170.Pa /dev/usbN 171can be opened and a few operations can be performed on it. 172The 173.Xr poll 2 174system call will say that I/O is possible on the controller device when a 175.Tn USB 176device has been connected or disconnected to the bus. 177.Pp 178The following 179.Xr ioctl 2 180commands are supported on the controller device: 181.Bl -tag -width xxxxxx 182.It Dv USB_DISCOVER 183This command will cause a complete bus discovery to be initiated. 184If any devices attached or detached from the bus they will be 185processed during this command. 186This is the only way that new devices are found on the bus. 187.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 188This command can be used to retrieve some information about a device 189on the bus. 190The 191.Va addr 192field should be filled before the call and the other fields will 193be filled by information about the device on that address. 194Should no such device exist an error is reported. 195.Bd -literal 196struct usb_device_info { 197 uByte addr; /* device address */ 198 char product[USB_MAX_STRING_LEN]; 199 char vendor[USB_MAX_STRING_LEN]; 200 char revision[8]; 201 uByte class; 202 uByte config; 203 uByte lowspeed; 204 int power; 205 int nports; 206 uByte ports[16]; 207#define USB_PORT_ENABLED 0xff 208#define USB_PORT_SUSPENDED 0xfe 209#define USB_PORT_POWERED 0xfd 210#define USB_PORT_DISABLED 0xfc 211}; 212.Ed 213.Pp 214The 215.Va product , 216.Va vendor , 217and 218.Va revision 219fields contain self-explanatory descriptions of the device. 220.Pp 221The 222.Va class 223field contains the device class. 224.Pp 225The 226.Va config 227field shows the current configuration of the device. 228.Pp 229The 230.Va lowspeed 231field 232is set if the device is a 233.Tn USB 234low speed device. 235.Pp 236The 237.Va power 238field shows the power consumption in milli-amps drawn at 5 volts, 239or zero if the device is self powered. 240.Pp 241If the device is a hub the 242.Va nports 243field is non-zero and the 244.Va ports 245field contains the addresses of the connected devices. 246If no device is connected to a port one of the 247.Va USB_PORT_* 248values indicates its status. 249.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 250This command retrieves statistics about the controller. 251.Bd -literal 252struct usb_device_stats { 253 u_long requests[4]; 254}; 255.Ed 256.Pp 257The 258.Va requests 259field is indexed by the transfer kind, i.e. 260.Va UE_* , 261and indicates how many transfers of each kind that has been completed 262by the controller. 263.It Dv USB_REQUEST Fa "struct usb_ctl_request" 264This command can be used to execute arbitrary requests on the control pipe. 265This is 266.Em DANGEROUS 267and should be used with great care since it 268can destroy the bus integrity. 269.El 270.Pp 271The include file 272.Aq Pa dev/usb/usb.h 273contains definitions for the types used by the various 274.Xr ioctl 2 275calls. 276The naming convention of the fields for the various 277.Tn USB 278descriptors exactly follows the naming in the 279.Tn USB 280specification. 281Byte sized fields can be accessed directly, but word (16 bit) 282sized fields must be access by the 283.Fn UGETW field 284and 285.Fn USETW field value 286macros to handle byte order and alignment properly. 287.Pp 288The include file 289.Aq Pa dev/usb/usbhid.h 290similarly contains the definitions for 291Human Interface Devices 292.Pq Tn HID . 293.Sh SEE ALSO 294The 295.Tn USB 296specifications can be found at 297.Dv http://www.usb.org/developers/docs.htm . 298.Pp 299.Xr pci 4 , 300.Xr uaudio 4 , 301.Xr ugen 4 , 302.Xr uhid 4 , 303.Xr ukbd 4 , 304.Xr ulpt 4 , 305.Xr ums 4 , 306.Xr usbd 8 , 307.Xr usbdevs 8 308.Sh HISTORY 309The 310.Nm 311driver 312appeared in 313.Nx 1.4 . 314