1.\" Copyright (c) 1997, 1998 2.\" Nick Hibma <hibma@skylink.it>. 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 i386 35.Os FreeBSD 36.Sh NAME 37.Nm usb 38.Nd Universal Serial Bus 39.Sh SYNOPSIS 40.Cd "controller usb0" 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. The controller attaches to a physical bus 51(like 52.Xr pci 4 ). 53The 54.Tn USB 55bus attaches to the controller and the root hub attaches 56to the controller. 57Any devices attached to the bus will attach to the root hub 58or another hub attached to the USB bus. 59.Pp 60The 61.Nm uhub 62device will always be present as it is needed for the 63root hub. 64.Pp 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 uByte addr; /* device address */ 175 char product[USB_MAX_STRING_LEN]; 176 char vendor[USB_MAX_STRING_LEN]; 177 char revision[8]; 178 uByte class; 179 uByte config; 180 uByte lowspeed; 181 int power; 182 int nports; 183 uByte ports[16]; 184#define USB_PORT_ENABLED 0xff 185#define USB_PORT_SUSPENDED 0xfe 186#define USB_PORT_POWERED 0xfd 187#define USB_PORT_DISABLED 0xfc 188}; 189.Ed 190.Pp 191The 192.Va product , 193.Va vendor , 194and 195.Va revision 196fields contain self-explanatory descriptions of the device. 197.Pp 198The 199.Va class 200field contains the device class. 201.Pp 202The 203.Va config 204field shows the current configuration of the device. 205.Pp 206The 207.Va lowspeed 208field 209is set if the device is a 210.Tn USB 211low speed device. 212.Pp 213The 214.Va power 215field shows the power consumption in milli-amps drawn at 5 volts, 216or zero if the device is self powered. 217.Pp 218If the device is a hub the 219.Va nports 220field is non-zero and the 221.Va ports 222field contains the addresses of the connected devices. 223If no device is connected to a port one of the 224.Va USB_PORT_* 225values indicates its status. 226.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 227This command retrieves statistics about the controller. 228.Bd -literal 229struct usb_device_stats { 230 u_long requests[4]; 231}; 232.Ed 233.Pp 234The 235.Va requests 236field is indexed by the transfer kind, i.e. 237.Va UE_* , 238and indicates how many transfers of each kind that has been completed 239by the controller. 240.It Dv USB_REQUEST Fa "struct usb_ctl_request" 241This command can be used to execute arbitrary requests on the control pipe. 242This is 243.Em DANGEROUS 244and should be used with great care since it 245can destroy the bus integrity. 246.El 247.Pp 248The include file 249.Aq Pa dev/usb/usb.h 250contains definitions for the types used by the various 251.Xr ioctl 2 252calls. 253The naming convention of the fields for the various 254.Tn USB 255descriptors exactly follows the naming in the 256.Tn USB 257specification. 258Byte sized fields can be accessed directly, but word (16 bit) 259sized fields must be access by the 260.Fn UGETW field 261and 262.Fn USETW field value 263macros to handle byte order and alignment properly. 264.Pp 265The include file 266.Aq Pa dev/usb/usbhid.h 267similarly contains the definitions for 268Human Interface Devices 269.Pq Tn HID . 270.Sh SEE ALSO 271The 272.Tn USB 273specifications can be found at 274.Dv http://www.usb.org/developers/docs.htm . 275.Pp 276.Xr pci 4 , 277.Xr ohci 4 , 278.Xr ugen 4 , 279.Xr uhci 4 , 280.Xr uhid 4 , 281.Xr ukbd 4 , 282.Xr ulpt 4 , 283.Xr ums 4 , 284.Xr usbd 8 , 285.Xr usbdevs 8 286.Sh HISTORY 287The 288.Nm 289driver first appeared in 290.Fx 3.0 . 291.Sh AUTHORS 292The 293.Nm 294driver was written by 295.An Lennart Augustsson Aq augustss@carlstedt.se 296for the 297.Nx 298project. 299