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.9.2.10 2002/12/19 20:48:25 trhodes Exp $ 29.\" $DragonFly: src/share/man/man4/usb.4,v 1.3 2004/03/11 12:28:55 hmp Exp $ 30.\" 31.Dd February 21, 1999 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 dev/usb/usb.h 41.In dev/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 109Each device located on a hub has several 110.Xr config 8 111locators: 112.Bl -tag -compact -width xxxxxx 113.It Cd port 114this is the number of the port on the closest upstream hub. 115.It Cd configuration 116this is the configuration the device must be in for this driver to attach. 117This locator does not set the configuration; it is iterated by the bus 118enumeration. 119.It Cd interface 120this is the interface number within a device that an interface driver 121attaches to. 122.It Cd vendor 123this is the 16 bit vendor id of the device. 124.It Cd product 125this is the 16 bit product id of the device. 126.It Cd release 127this is the 16 bit release (revision) number of the device. 128.El 129The first locator can be used to pin down a particular device 130according to its physical position in the device tree. 131The last three locators can be used to pin down a particular 132device 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 dev/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 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 187struct usb_device_info { 188 u_int8_t bus; 189 u_int8_t addr; 190 usb_event_cookie_t cookie; 191 char product[USB_MAX_STRING_LEN]; 192 char vendor[USB_MAX_STRING_LEN]; 193 char release[8]; 194 u_int16_t productNo; 195 u_int16_t vendorNo; 196 u_int16_t releaseNo; 197 u_int8_t class; 198 u_int8_t subclass; 199 u_int8_t protocol; 200 u_int8_t config; 201 u_int8_t lowspeed; 202 int power; 203 int nports; 204 char devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 205 u_int8_t ports[16]; 206#define USB_PORT_ENABLED 0xff 207#define USB_PORT_SUSPENDED 0xfe 208#define USB_PORT_POWERED 0xfd 209#define USB_PORT_DISABLED 0xfc 210}; 211.Ed 212.Pp 213.Va bus 214and 215.Va addr 216contain the topological information for the device. 217.Va devnames 218contains the device names of the connected drivers. 219For example, the 220third 221.Tn USB 222Zip drive connected will be 223.Li umass2 . 224The 225.Va product , vendor 226and 227.Va release 228fields contain self-explanatory descriptions of the device. 229.Va productNo , vendorNo , releaseNo , class , subclass 230and 231.Va protocol 232contain the corresponding values from the device descriptors. 233The 234.Va config 235field shows the current configuration of the device. 236.Pp 237.Va lowspeed 238indicates whether the device is a full speed (0) or low speed (1) 239device. 240The 241.Va power 242field shows the power consumption in milli-amps drawn at 5 volts, 243or zero if the device is self powered. 244.Pp 245If the device is a hub, the 246.Va nports 247field is non-zero, and the 248.Va ports 249field contains the addresses of the connected devices. 250If no device is connected to a port, one of the 251.Dv USB_PORT_* 252values indicates its status. 253.It Dv USB_DEVICESTATS Vt "struct usb_device_stats" 254This command retrieves statistics about the controller. 255.Bd -literal 256struct usb_device_stats { 257 u_long requests[4]; 258}; 259.Ed 260.Pp 261The 262.Va requests 263field is indexed by the transfer kind, i.e.\& 264.Dv UE_* , 265and indicates how many transfers of each kind that has been completed 266by the controller. 267.It Dv USB_REQUEST Vt "struct usb_ctl_request" 268This command can be used to execute arbitrary requests on the control pipe. 269This is 270.Em DANGEROUS 271and should be used with great care since it 272can destroy the bus integrity. 273.El 274.Pp 275The include file 276.Aq Pa dev/usb/usb.h 277contains definitions for the types used by the various 278.Xr ioctl 2 279calls. 280The naming convention of the fields for the various 281.Tn USB 282descriptors exactly follows the naming in the 283.Tn USB 284specification. 285Byte sized fields can be accessed directly, but word (16 bit) 286sized fields must be access by the 287.Fn UGETW field 288and 289.Fn USETW field value 290macros to handle byte order and alignment properly. 291.Pp 292The include file 293.Aq Pa dev/usb/usbhid.h 294similarly contains the definitions for 295Human Interface Devices 296.Pq Tn HID . 297.Sh USB EVENT INTERFACE 298All 299.Tn USB 300events are reported via the 301.Pa /dev/usb 302device. 303This devices can be opened for reading and each 304.Xr read 2 305will yield an event record (if something has happened). 306The 307.Xr poll 2 308system call can be used to determine if an event record is available 309for reading. 310.Pp 311The event record has the following definition: 312.Bd -literal 313struct usb_event { 314 int ue_type; 315#define USB_EVENT_CTRLR_ATTACH 1 316#define USB_EVENT_CTRLR_DETACH 2 317#define USB_EVENT_DEVICE_ATTACH 3 318#define USB_EVENT_DEVICE_DETACH 4 319#define USB_EVENT_DRIVER_ATTACH 5 320#define USB_EVENT_DRIVER_DETACH 6 321 struct timespec ue_time; 322 union { 323 struct { 324 int ue_bus; 325 } ue_ctrlr; 326 struct usb_device_info ue_device; 327 struct { 328 usb_event_cookie_t ue_cookie; 329 char ue_devname[16]; 330 } ue_driver; 331 } u; 332}; 333.Ed 334The 335.Va ue_type 336field identifies the type of event that is described. 337The possible events are attach/detach of a host controller, 338a device, or a device driver. 339The union contains information 340pertinent to the different types of events. 341.Pp 342The 343.Va ue_bus 344contains the number of the 345.Tn USB 346bus for host controller events. 347.Pp 348The 349.Va ue_device 350record contains information about the device in a device event event. 351.Pp 352The 353.Va ue_cookie 354is an opaque value that uniquely determines which which 355device a device driver has been attached to (i.e., it equals 356the cookie value in the device that the driver attached to). 357.Pp 358The 359.Va ue_devname 360contains the name of the device (driver) as seen in, e.g., 361kernel messages. 362.Pp 363Note that there is a separation between device and device 364driver events. 365A device event is generated when a physical 366.Tn USB 367device is attached or detached. 368A single 369.Tn USB 370device may 371have zero, one, or many device drivers associated with it. 372.Sh SEE ALSO 373The 374.Tn USB 375specifications can be found at: 376.Pp 377.D1 Pa http://www.usb.org/developers/docs.html 378.Pp 379.Xr aue 4 , 380.Xr cue 4 , 381.Xr kue 4 , 382.Xr ohci 4 , 383.Xr pci 4 , 384.Xr ucom 4 , 385.Xr ugen 4 , 386.Xr uhci 4 , 387.Xr uhid 4 , 388.Xr ukbd 4 , 389.Xr ulpt 4 , 390.Xr umass 4 , 391.Xr ums 4 , 392.Xr urio 4 , 393.Xr uscanner 4 , 394.Xr usbd 8 , 395.Xr usbdevs 8 396.Sh HISTORY 397The 398.Nm 399driver first appeared in 400.Fx 3.0 . 401.Sh AUTHORS 402The 403.Nm 404driver was written by 405.An Lennart Augustsson Aq augustss@carlstedt.se 406for the 407.Nx 408project. 409