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