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