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 35.Os FreeBSD 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. 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 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. For example the 206third USB Zip drive connected will be 207.Li umass2 . 208The 209.Va product , vendor 210and 211.Va release 212fields contain self-explanatory descriptions of the device. 213.Va productNo , vendorNo , releaseNo , class , subclass 214and 215.Va protocol 216contain the corresponding values from the device descriptors. 217The 218.Va config 219field shows the current configuration of the device. 220.Pp 221.Va lowspeed 222indicates whether the device is a full speed (0) or low speed (1) 223device. The 224.Va power 225field shows the power consumption in milli-amps drawn at 5 volts, 226or zero if the device is self powered. 227.Pp 228If the device is a hub the 229.Va nports 230field is non-zero and the 231.Va ports 232field contains the addresses of the connected devices. 233If no device is connected to a port one of the 234.Va USB_PORT_* 235values indicates its status. 236.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 237This command retrieves statistics about the controller. 238.Bd -literal 239struct usb_device_stats { 240 u_long requests[4]; 241}; 242.Ed 243.Pp 244The 245.Va requests 246field is indexed by the transfer kind, i.e. 247.Va UE_* , 248and indicates how many transfers of each kind that has been completed 249by the controller. 250.It Dv USB_REQUEST Fa "struct usb_ctl_request" 251This command can be used to execute arbitrary requests on the control pipe. 252This is 253.Em DANGEROUS 254and should be used with great care since it 255can destroy the bus integrity. 256.El 257.Pp 258The include file 259.Aq Pa dev/usb/usb.h 260contains definitions for the types used by the various 261.Xr ioctl 2 262calls. 263The naming convention of the fields for the various 264.Tn USB 265descriptors exactly follows the naming in the 266.Tn USB 267specification. 268Byte sized fields can be accessed directly, but word (16 bit) 269sized fields must be access by the 270.Fn UGETW field 271and 272.Fn USETW field value 273macros to handle byte order and alignment properly. 274.Pp 275The include file 276.Aq Pa dev/usb/usbhid.h 277similarly contains the definitions for 278Human Interface Devices 279.Pq Tn HID . 280.Sh SEE ALSO 281The 282.Tn USB 283specifications can be found at 284.Dv http://www.usb.org/developers/docs.htm . 285.Pp 286.Xr pci 4 , 287.Xr ohci 4 , 288.Xr ugen 4 , 289.Xr uhci 4 , 290.Xr uhid 4 , 291.Xr ukbd 4 , 292.Xr ulpt 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