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. Neither the name of the author nor the names of any co-contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 26.\" THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd February 21, 1999 31.Dt USB 4 32.Os 33.Sh NAME 34.Nm usb 35.Nd Universal Serial Bus 36.Sh SYNOPSIS 37.Cd "device usb" 38.Pp 39.In dev/usb/usb.h 40.In dev/usb/usbhid.h 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 60.Tn USB 61bus. 62.Pp 63The 64.Nm uhub 65device will always be present as it is needed for the 66root hub. 67.Sh INTRODUCTION TO USB 68The 69.Tn USB 70is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 71Each 72.Tn USB 73has a host controller that is the master of the bus; 74all other devices on the bus only speak when spoken to. 75.Pp 76There can be up to 127 devices (apart from the host controller) 77on a bus, each with its own address. 78The addresses are assigned 79dynamically by the host when each device is attached to the bus. 80.Pp 81Within each device there can be up to 16 endpoints. 82Each endpoint 83is individually addressed and the addresses are static. 84Each of these endpoints will communicate in one of four different modes: 85.Em control , isochronous , bulk , 86or 87.Em interrupt . 88A device always has at least one endpoint. 89This endpoint has address 0 and is a control 90endpoint and is used to give commands to and extract basic data, 91such as descriptors, from the device. 92Each endpoint, except the control endpoint, is unidirectional. 93.Pp 94The endpoints in a device are grouped into interfaces. 95An interface is a logical unit within a device; e.g.\& 96a compound device with both a keyboard and a trackball would present 97one interface for each. 98An interface can sometimes be set into different modes, 99called alternate settings, which affects how it operates. 100Different alternate settings can have different endpoints 101within it. 102.Pp 103A device may operate in different configurations. 104Depending on the 105configuration, the device may present different sets of endpoints 106and interfaces. 107.\" .Pp 108.\" Each device located on a hub has several 109.\" .Xr config 8 110.\" locators: 111.\" .Bl -tag -compact -width xxxxxx 112.\" .It Cd port 113.\" this is the number of the port on the closest upstream hub. 114.\" .It Cd configuration 115.\" this is the configuration the device must be in for this driver to attach. 116.\" This locator does not set the configuration; it is iterated by the bus 117.\" enumeration. 118.\" .It Cd interface 119.\" this is the interface number within a device that an interface driver 120.\" attaches to. 121.\" .It Cd vendor 122.\" this is the 16 bit vendor id of the device. 123.\" .It Cd product 124.\" this is the 16 bit product id of the device. 125.\" .It Cd release 126.\" this is the 16 bit release (revision) number of the device. 127.\" .El 128.\" The first locator can be used to pin down a particular device 129.\" according to its physical position in the device tree. 130.\" The last three locators can be used to pin down a particular 131.\" device according to what device it actually is. 132.Pp 133The bus enumeration of the 134.Tn USB 135bus proceeds in several steps: 136.Bl -enum 137.It 138Any device specific driver can attach to the device. 139.It 140If none is found, any device class specific driver can attach. 141.It 142If none is found, all configurations are iterated over. 143For each configuration, all the interfaces are iterated over, and interface 144drivers can attach. 145If any interface driver attached in a certain 146configuration, the iteration over configurations is stopped. 147.It 148If still no drivers have been found, the generic 149.Tn USB 150driver can attach. 151.El 152.Sh USB CONTROLLER INTERFACE 153Use the following to get access to the 154.Tn USB 155specific structures and defines. 156.Pp 157.In dev/usb/usb.h 158.Pp 159The 160.Pa /dev/usb Ns Ar N 161can be opened and a few operations can be performed on it. 162The 163.Xr poll 2 164system call will say that I/O is possible on the controller device when a 165.Tn USB 166device has been connected or disconnected to the bus. 167.Pp 168The following 169.Xr ioctl 2 170commands are supported on the controller device: 171.Bl -tag -width xxxxxx 172.It Dv USB_DISCOVER 173This command will cause a complete bus discovery to be initiated. 174If any devices attached or detached from the bus they will be 175processed during this command. 176This is the only way that new devices are found on the bus. 177.It Dv USB_DEVICEINFO Vt "struct usb_device_info" 178This command can be used to retrieve some information about a device 179on the bus. 180The 181.Va addr 182field should be filled before the call and the other fields will 183be filled by information about the device on that address. 184Should no such device exist, an error is reported. 185.Bd -literal 186struct usb_device_info { 187 u_int8_t bus; 188 u_int8_t addr; 189 usb_event_cookie_t cookie; 190 char product[USB_MAX_STRING_LEN]; 191 char vendor[USB_MAX_STRING_LEN]; 192 char release[8]; 193 u_int16_t productNo; 194 u_int16_t vendorNo; 195 u_int16_t releaseNo; 196 u_int8_t class; 197 u_int8_t subclass; 198 u_int8_t protocol; 199 u_int8_t config; 200 u_int8_t lowspeed; 201 int power; 202 int nports; 203 char devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 204 u_int8_t ports[16]; 205#define USB_PORT_ENABLED 0xff 206#define USB_PORT_SUSPENDED 0xfe 207#define USB_PORT_POWERED 0xfd 208#define USB_PORT_DISABLED 0xfc 209}; 210.Ed 211.Pp 212.Va bus 213and 214.Va addr 215contain the topological information for the device. 216.Va devnames 217contains the device names of the connected drivers. 218For example, the 219third 220.Tn USB 221Zip drive connected will be 222.Li umass2 . 223The 224.Va product , vendor 225and 226.Va release 227fields contain self-explanatory descriptions of the device. 228.Va productNo , vendorNo , releaseNo , class , subclass 229and 230.Va protocol 231contain the corresponding values from the device descriptors. 232The 233.Va config 234field shows the current configuration of the device. 235.Pp 236.Va lowspeed 237indicates whether the device is a full speed (0) or low speed (1) 238device. 239The 240.Va power 241field shows the power consumption in milli-amps drawn at 5 volts, 242or zero if the device is self powered. 243.Pp 244If the device is a hub, the 245.Va nports 246field is non-zero, and the 247.Va ports 248field contains the addresses of the connected devices. 249If no device is connected to a port, one of the 250.Dv USB_PORT_* 251values indicates its status. 252.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 253This command retrieves statistics about the controller. 254.Bd -literal 255struct usb_device_stats { 256 u_long requests[4]; 257}; 258.Ed 259.Pp 260The 261.Va requests 262field is indexed by the transfer kind, i.e.\& 263.Dv UE_* , 264and indicates how many transfers of each kind that has been completed 265by the controller. 266.It Dv USB_REQUEST Vt "struct usb_ctl_request" 267This command can be used to execute arbitrary requests on the control pipe. 268This is 269.Em DANGEROUS 270and should be used with great care since it 271can destroy the bus integrity. 272.El 273.Pp 274The include file 275.Aq Pa dev/usb/usb.h 276contains definitions for the types used by the various 277.Xr ioctl 2 278calls. 279The naming convention of the fields for the various 280.Tn USB 281descriptors exactly follows the naming in the 282.Tn USB 283specification. 284Byte sized fields can be accessed directly, but word (16 bit) 285sized fields must be access by the 286.Fn UGETW field 287and 288.Fn USETW field value 289macros to handle byte order and alignment properly. 290.Pp 291The include file 292.Aq Pa dev/usb/usbhid.h 293similarly contains the definitions for 294Human Interface Devices 295.Pq Tn HID . 296.Sh USB EVENT INTERFACE 297All 298.Tn USB 299events are reported via the 300.Pa /dev/usb 301device. 302This devices can be opened for reading and each 303.Xr read 2 304will yield an event record (if something has happened). 305The 306.Xr poll 2 307system call can be used to determine if an event record is available 308for reading. 309.Pp 310The event record has the following definition: 311.Bd -literal 312struct usb_event { 313 int ue_type; 314#define USB_EVENT_CTRLR_ATTACH 1 315#define USB_EVENT_CTRLR_DETACH 2 316#define USB_EVENT_DEVICE_ATTACH 3 317#define USB_EVENT_DEVICE_DETACH 4 318#define USB_EVENT_DRIVER_ATTACH 5 319#define USB_EVENT_DRIVER_DETACH 6 320 struct timespec ue_time; 321 union { 322 struct { 323 int ue_bus; 324 } ue_ctrlr; 325 struct usb_device_info ue_device; 326 struct { 327 usb_event_cookie_t ue_cookie; 328 char ue_devname[16]; 329 } ue_driver; 330 } u; 331}; 332.Ed 333The 334.Va ue_type 335field identifies the type of event that is described. 336The possible events are attach/detach of a host controller, 337a device, or a device driver. 338The union contains information 339pertinent to the different types of events. 340.Pp 341The 342.Va ue_bus 343contains the number of the 344.Tn USB 345bus for host controller events. 346.Pp 347The 348.Va ue_device 349record contains information about the device in a device event event. 350.Pp 351The 352.Va ue_cookie 353is an opaque value that uniquely determines which which 354device a device driver has been attached to (i.e., it equals 355the cookie value in the device that the driver attached to). 356.Pp 357The 358.Va ue_devname 359contains the name of the device (driver) as seen in, e.g., 360kernel messages. 361.Pp 362Note that there is a separation between device and device 363driver events. 364A device event is generated when a physical 365.Tn USB 366device is attached or detached. 367A single 368.Tn USB 369device may 370have zero, one, or many device drivers associated with it. 371.Sh SEE ALSO 372The 373.Tn USB 374specifications can be found at: 375.Pp 376.D1 Pa http://www.usb.org/developers/docs.html 377.Pp 378.Xr aue 4 , 379.Xr cue 4 , 380.Xr kue 4 , 381.Xr ohci 4 , 382.Xr pci 4 , 383.Xr ucom 4 , 384.Xr ugen 4 , 385.Xr uhci 4 , 386.Xr uhid 4 , 387.Xr ukbd 4 , 388.Xr ulpt 4 , 389.Xr umass 4 , 390.Xr ums 4 , 391.Xr uplcom 4 , 392.Xr urio 4 , 393.Xr uscanner 4 , 394.Xr uvscom 4 , 395.Xr usbd 8 , 396.Xr usbdevs 8 397.Sh HISTORY 398The 399.Nm 400driver first appeared in 401.Fx 3.0 . 402.Sh AUTHORS 403The 404.Nm 405driver was written by 406.An Lennart Augustsson Aq augustss@carlstedt.se 407for the 408.Nx 409project. 410