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