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