1.\" $NetBSD: usb.4,v 1.36 2001/06/10 15:51:33 wiz Exp $ 2.\" 3.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd July 12, 1998 38.Dt USB 4 39.Os 40.Sh NAME 41.Nm usb 42.Nd Universal Serial Bus driver 43.Sh SYNOPSIS 44.Cd "uhci* at pci? dev ? function ?" 45.Cd "ohci* at cardbus? dev ? function ?" 46.Cd "ohci* at pci? dev ? function ?" 47.Cd "usb* at uhci? flags X" 48.Cd "usb* at ohci? flags X" 49.Cd "uhub* at usb?" 50.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 51.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" 52.Pp 53.Cd "#include <dev/usb/usb.h>" 54.Cd "#include <dev/usb/usbhid.h>" 55.Sh INTRODUCTION 56.Nx 57provides machine-independent bus support and drivers for 58.Tn USB 59devices. 60.Pp 61The 62.Nx 63.Nm 64driver has three layers (like 65.Xr scsi 4 66and 67.Xr pcmcia 4 ) : 68the controller, the bus, and the device layer. 69The controller attaches to a physical bus (like 70.Xr pci 4 ) . 71The 72.Tn USB 73bus attaches to the controller and the root hub attaches 74to the controller. 75Further devices, which may include further hubs, 76attach to other hubs. 77The attachment forms the same tree structure as the physical 78.Tn USB 79device tree. 80For each 81.Tn USB 82device there may be additional drivers attached to it. 83.Pp 84The 85.Cm uhub 86device controls 87.Tn USB 88hubs and must always be present since there is at least a root hub in any 89.Tn USB 90system. 91.Pp 92The 93.Va flags 94argument to the 95.Va usb 96device affects the order in which the device detection happens 97during cold boot. 98Normally, only the USB host controller and the 99.Va usb 100device are detected during the autoconfiguration when the 101machine is booted. The rest of the devices are detected once 102the system becomes functional and the kernel thread for the 103.Va usb 104device is started. 105Sometimes it is desirable to have a device detected early in the 106boot process, e.g., the console keyboard. To achieve this use 107a 108.Va flags 109value of 1. 110.Pp 111.Sh SUPPORTED DEVICES 112.Nx 113includes machine-independent 114.Tn USB 115drivers, sorted by driver name: 116.Bl -tag -width usscanner -offset indent 117.It aue 118driver for ADMtek AN986 Pegasus USB Ethernet. 119.It cue 120driver for CATC USB-EL1201A USB Ethernet. 121.It kue 122driver for Kawasaki LSI KL5KUSB101B USB Ethernet. 123.It uaudio 124driver for audio devices. 125.It uftdi 126driver for FTDI based serial adapters. 127.It ugen 128generic driver for 129.Tn USB 130devices. 131.It uhid 132generic driver for Human Interface Devices. 133.It ukbd 134keyboard driver. 135.It ulpt 136printer driver. 137.It umass 138driver for mass storage devices, such as disks. 139.It umidi 140driver for MIDI devices. 141.It umodem 142driver for communication devices that use the Abstract Control Model. 143.It ums 144mouse driver. 145.It upl 146driver for 147.Tn Prolific 148host-to-host adapter. 149.It uplcom 150driver for Prolific 2303 serial adapter. 151.It umct 152driver for MCT USB-RS232 serial adapter. 153.It urio 154driver for the 155.Tn Diamond 156Rio 500 MP3 player. 157.It uscanner 158driver for some USB scanners. 159.It usscanner 160driver for some SCSI-over-USB scanners. 161.It uvisor 162Handspring Visor driver. 163.El 164.Sh INTRODUCTION TO USB 165The 166.Tn USB 167is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). 168Each 169.Tn USB 170has a host controller that is the master of the bus; 171all other devices on the bus only speak when spoken to. 172.Pp 173There can be up to 127 devices (apart from the host controller) 174on a bus, each with its own address. 175The addresses are assigned 176dynamically by the host when each device is attached to the bus. 177.Pp 178Within each device there can be up to 16 endpoints. 179Each endpoint 180is individually addressed and the addresses are static. 181Each of these endpoints will communicate in one of four different modes: 182control, isochronous, bulk, or interrupt. 183A device always has at least one endpoint. 184This endpoint has address 0 and is a control 185endpoint and is used to give commands to and extract basic data, 186such as descriptors, from the device. 187Each endpoint, except the control endpoint, is unidirectional. 188.Pp 189The endpoints in a device are grouped into interfaces. 190An interface is a logical unit within a device; e.g., 191a compound device with both a keyboard and a trackball would present 192one interface for each. 193An interface can sometimes be set into different modes, 194called alternate settings, which affects how it operates. 195Different alternate settings can have different endpoints 196within it. 197.Pp 198A device may operate in different configurations. 199Depending on the 200configuration the device may present different sets of endpoints 201and interfaces. 202.Pp 203Each device located on a hub has several 204.Xr config 8 205locators: 206.Bl -tag -compact -width xxxxxxxxx 207.It Cd port 208this is the number of the port on closest upstream hub. 209.It Cd configuration 210this is the configuration the device must be in for this driver to attach. 211This locator does not set the configuration; it is iterated by the bus 212enumeration. 213.It Cd interface 214this is the interface number within a device that an interface driver 215attaches to. 216.It Cd vendor 217this is the 16 bit vendor id of the device. 218.It Cd product 219this is the 16 bit product id of the device. 220.It Cd release 221this is the 16 bit release (revision) number of the device. 222.El 223The first locator can be used to pin down a particular device 224according to its physical position in the device tree. 225The last three locators can be used to pin down a particular 226device according to what device it actually is. 227.Pp 228The bus enumeration of the 229.Tn USB 230bus proceeds in several steps: 231.Bl -enum 232.It 233Any device specific driver can to attach to the device. 234.It 235If none is found, any device class specific driver can attach. 236.It 237If none is found, all configurations are iterated over. 238For each configuration all the interface are iterated over and interface 239drivers can attach. 240If any interface driver attached in a certain 241configuration the iteration over configurations is stopped. 242.It 243If still no drivers have been found, the generic 244.Tn USB 245driver can attach. 246.El 247.Sh USB CONTROLLER INTERFACE 248Use the following to get access to the 249.Tn USB 250specific structures and defines. 251.Bd -literal 252#include <sys/dev/usb.h> 253.Ed 254.Pp 255The 256.Pa /dev/usbN 257can be opened and a few operations can be performed on it. 258The 259.Xr poll 2 260system call will say that I/O is possible on the controller device when a 261.Tn USB 262device has been connected or disconnected to the bus. 263.Pp 264The following 265.Xr ioctl 2 266commands are supported on the controller device: 267.Bl -tag -width xxxxxx 268.\" .It Dv USB_DISCOVER 269.\" This command will cause a complete bus discovery to be initiated. 270.\" If any devices attached or detached from the bus they will be 271.\" processed during this command. 272.\" This is the only way that new devices are found on the bus. 273.It Dv USB_DEVICEINFO Fa "struct usb_device_info" 274This command can be used to retrieve some information about a device 275on the bus. 276The 277.Va addr 278field should be filled before the call and the other fields will 279be filled by information about the device on that address. 280Should no such device exist an error is reported. 281.Bd -literal 282struct usb_device_info { 283 u_int8_t bus; 284 u_int8_t addr; 285 usb_event_cookie_t cookie; 286 char product[USB_MAX_STRING_LEN]; 287 char vendor[USB_MAX_STRING_LEN]; 288 char release[8]; 289 u_int16_t productNo; 290 u_int16_t vendorNo; 291 u_int16_t releaseNo; 292 u_int8_t class; 293 u_int8_t subclass; 294 u_int8_t protocol; 295 u_int8_t config; 296 u_int8_t lowspeed; 297 int power; 298 int nports; 299 char devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; 300 u_int8_t ports[16]; 301#define USB_PORT_ENABLED 0xff 302#define USB_PORT_SUSPENDED 0xfe 303#define USB_PORT_POWERED 0xfd 304#define USB_PORT_DISABLED 0xfc 305}; 306.Ed 307.Pp 308The 309.Va product , 310.Va vendor , 311and 312.Va release 313fields contain self-explanatory descriptions of the device. 314.Pp 315The 316.Va class 317field contains the device class. 318.Pp 319The 320.Va config 321field shows the current configuration of the device. 322.Pp 323The 324.Va lowspeed 325field 326is set if the device is a 327.Tn USB 328low speed device. 329.Pp 330The 331.Va power 332field shows the power consumption in milli-amps drawn at 5 volts, 333or zero if the device is self powered. 334.Pp 335If the device is a hub the 336.Va nports 337field is non-zero and the 338.Va ports 339field contains the addresses of the connected devices. 340If no device is connected to a port one of the 341.Va USB_PORT_* 342values indicates its status. 343.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" 344This command retrieves statistics about the controller. 345.Bd -literal 346struct usb_device_stats { 347 u_long requests[4]; 348}; 349.Ed 350.Pp 351The 352.Va requests 353field is indexed by the transfer kind, i.e. 354.Va UE_* , 355and indicates how many transfers of each kind that has been completed 356by the controller. 357.It Dv USB_REQUEST Fa "struct usb_ctl_request" 358This command can be used to execute arbitrary requests on the control pipe. 359This is 360.Em DANGEROUS 361and should be used with great care since it 362can destroy the bus integrity. 363.El 364.Pp 365The include file 366.Aq Pa dev/usb/usb.h 367contains definitions for the types used by the various 368.Xr ioctl 2 369calls. 370The naming convention of the fields for the various 371.Tn USB 372descriptors exactly follows the naming in the 373.Tn USB 374specification. 375Byte sized fields can be accessed directly, but word (16 bit) 376sized fields must be access by the 377.Fn UGETW field 378and 379.Fn USETW field value 380macros to handle byte order and alignment properly. 381.Pp 382The include file 383.Aq Pa dev/usb/usbhid.h 384similarly contains the definitions for 385Human Interface Devices 386.Pq Tn HID . 387.Sh USB EVENT INTERFACE 388All 389.Tn USB 390events are reported via the 391.Pa /dev/usb 392device. This devices can be opened for reading and each 393.Xr read 2 394will yield an event record (if something has happened). 395The 396.Xr poll 2 397system call can be used to determine if an event record is available 398for reading. 399.Pp 400The event record has the following definition: 401.Bd -literal 402struct usb_event { 403 int ue_type; 404#define USB_EVENT_CTRLR_ATTACH 1 405#define USB_EVENT_CTRLR_DETACH 2 406#define USB_EVENT_DEVICE_ATTACH 3 407#define USB_EVENT_DEVICE_DETACH 4 408#define USB_EVENT_DRIVER_ATTACH 5 409#define USB_EVENT_DRIVER_DETACH 6 410 struct timespec ue_time; 411 union { 412 struct { 413 int ue_bus; 414 } ue_ctrlr; 415 struct usb_device_info ue_device; 416 struct { 417 usb_event_cookie_t ue_cookie; 418 char ue_devname[16]; 419 } ue_driver; 420 } u; 421}; 422.Ed 423The 424.Va ue_type 425field identifies the type of event that is described. 426The possible events are attach/detach of a host controller, 427a device, or a device driver. The union contains information 428pertinent to the different types of events. 429.br 430The 431.Va ue_bus 432contains the number of the 433.Tn USB 434bus for host controller events. 435.br 436The 437.Va ue_device 438record contains information about the device in a device event event. 439.br 440The 441.Va ue_cookie 442is an opaque value that uniquely determines which which 443device a device driver has been attached to (i.e., it equals 444the cookie value in the device that the driver attached to). 445The 446.Va ue_devname 447contains the name of the device (driver) as seen in, e.g., 448kernel messages. 449.Pp 450Note that that there is a separation between device and device 451driver events. A driver event is generated when a physical 452USB device is attached or detached. A single USB device may 453have zero, one, or many device drivers associated with it. 454.Sh BUGS 455There should be a serial number locator, but 456.Nx 457does not have string valued locators. 458.Sh SEE ALSO 459The 460.Tn USB 461specifications can be found at: 462.D1 http://www.usb.org/developers/docs.html 463.Pp 464.Xr aue 4 , 465.Xr cardbus 4 , 466.Xr cue 4 , 467.Xr kue 4 , 468.Xr pci 4 , 469.Xr uaudio 4 , 470.Xr ugen 4 , 471.Xr uhid 4 , 472.Xr ukbd 4 , 473.Xr ulpt 4 , 474.Xr umass 4 , 475.Xr umidi 4 , 476.Xr ums 4 , 477.Xr upl 4 , 478.Xr urio 4 , 479.Xr uscanner 4 , 480.Xr uvisor 4 , 481.Xr usb 3 , 482.Xr usbdevs 8 483.Sh HISTORY 484The 485.Nm 486driver 487appeared in 488.Nx 1.4 . 489