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