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