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