share/man/man4/usb.4

   1 .\" Copyright (c) 1997, 1998
   2 .\"     Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the author nor the names of any co-contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"   without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  26 .\" THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/share/man/man4/usb.4,v 1.32 2005/04/20 07:33:09 simon Exp $
  29 .\" $DragonFly: src/share/man/man4/usb.4,v 1.7 2008/02/11 19:57:30 swildner Exp $
  30 .\"
  31 .Dd January 26, 2008
  32 .Dt USB 4
  33 .Os
  34 .Sh NAME
  35 .Nm usb
  36 .Nd Universal Serial Bus
  37 .Sh SYNOPSIS
  38 .Cd "device usb"
  39 .Pp
  40 .In bus/usb/usb.h
  41 .In bus/usb/usbhid.h
  42 .Sh DESCRIPTION
  43 .Dx
  44 provides machine-independent bus support and drivers for
  45 .Tn USB
  46 devices.
  47 .Pp
  48 The
  49 .Nm
  50 driver has three layers: the controller, the bus, and the
  51 device layer.
  52 The controller attaches to a physical bus
  53 (like
  54 .Xr pci 4 ) .
  55 The
  56 .Tn USB
  57 bus attaches to the controller, and the root hub attaches
  58 to the controller.
  59 Any devices attached to the bus will attach to the root hub
  60 or another hub attached to the
  61 .Tn USB
  62 bus.
  63 .Pp
  64 The
  65 .Nm uhub
  66 device will always be present as it is needed for the
  67 root hub.
  68 .Ss Storage devices
  69 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
  70 .\".It Xr natausb 4
  71 .\"...
  72 .It Xr umass 4
  73 Mass Storage Devices, e.g., external disk drives
  74 .El
  75 .Ss Wired network interfaces
  76 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
  77 .It Xr aue 4
  78 ADMtek AN986 Pegasus Ethernet driver
  79 .It Xr axe 4
  80 ASIX Electronics AX88172 Ethernet driver
  81 .It Xr cue 4
  82 CATC USB-EL1210A Ethernet driver
  83 .It Xr kue 4
  84 Kawasaki LSI KL5KUSB101B Ethernet driver
  85 .It Xr rue 4
  86 RealTek RTL8150 Ethernet driver
  87 .El
  88 .Ss Wireless network interfaces
  89 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
  90 .It Xr rum 4
  91 Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver
  92 .It Xr ubt 4
  93 Bluetooth adapters
  94 .It Xr ural 4
  95 Ralink Technology RT2500USB IEEE 802.11 driver
  96 .El
  97 .Ss Serial and parallel interfaces
  98 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
  99 .It Xr moscom 4
 100 MosChip Semiconductor MCS7703 based serial adapters
 101 .It Xr uark 4
 102 Arkmicro Technologies ARK3116 based serial adapters
 103 .It Xr ubsa 4
 104 Belkin serial adapters
 105 .It Xr uchcom 4
 106 WinChipHead CH341/CH340 serial adapters
 107 .It Xr ucom 4
 108 tty support
 109 .It Xr uftdi 4
 110 serial devices based on the FTDI chips
 111 .It Xr ugensa 4
 112 generic serial device
 113 .It Xr ulpt 4
 114 printer support
 115 .It Xr umct 4
 116 Magic Control Technology USB-232 based serial adapters
 117 .It Xr uplcom 4
 118 Prolific PL-2303/2303X/2303HX serial adapters
 119 .It Xr uslcom 4
 120 Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge
 121 .It Xr uticom 4
 122 Texas Instruments TUSB3410 RS232 to USB converter
 123 .It Xr uvisor 4
 124 support for the Handspring Visor, a Palmpilot compatible PDA
 125 .It Xr uvscom 4
 126 SUNTAC Slipper U VS-10U serial adapters
 127 .El
 128 .Ss Audio devices
 129 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
 130 .It Xr snd_uaudio 4
 131 audio device driver
 132 .It Xr urio 4
 133 driver for the Rio500 MP3 player
 134 .El
 135 .Ss Radio receiver devices
 136 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
 137 .It Xr ufm 4
 138 Cypress Semiconductor FM Radio
 139 .El
 140 .Ss Human Interface Devices
 141 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
 142 .It Xr uhid 4
 143 generic driver for Human Interface Devices
 144 .It Xr uhidev 4
 145 base driver for all Human Interface Devices
 146 .It Xr ukbd 4
 147 keyboards that follow the boot protocol
 148 .It Xr ums 4
 149 mouse devices
 150 .El
 151 .Ss Miscellaneous devices
 152 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
 153 .It Xr ugen 4
 154 generic device support
 155 .It Xr uscanner 4
 156 scanner support
 157 .El
 158 .Sh INTRODUCTION TO USB
 159 The
 160 .Tn USB
 161 is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
 162 Each
 163 .Tn USB
 164 has a host controller that is the master of the bus;
 165 all other devices on the bus only speak when spoken to.
 166 .Pp
 167 There can be up to 127 devices (apart from the host controller)
 168 on a bus, each with its own address.
 169 The addresses are assigned
 170 dynamically by the host when each device is attached to the bus.
 171 .Pp
 172 Within each device there can be up to 16 endpoints.
 173 Each endpoint
 174 is individually addressed and the addresses are static.
 175 Each of these endpoints will communicate in one of four different modes:
 176 .Em control , isochronous , bulk ,
 177 or
 178 .Em interrupt .
 179 A device always has at least one endpoint.
 180 This endpoint has address 0 and is a control
 181 endpoint and is used to give commands to and extract basic data,
 182 such as descriptors, from the device.
 183 Each endpoint, except the control endpoint, is unidirectional.
 184 .Pp
 185 The endpoints in a device are grouped into interfaces.
 186 An interface is a logical unit within a device; e.g.\&
 187 a compound device with both a keyboard and a trackball would present
 188 one interface for each.
 189 An interface can sometimes be set into different modes,
 190 called alternate settings, which affects how it operates.
 191 Different alternate settings can have different endpoints
 192 within it.
 193 .Pp
 194 A device may operate in different configurations.
 195 Depending on the
 196 configuration, the device may present different sets of endpoints
 197 and interfaces.
 198 .\".Pp
 199 .\"Each device located on a hub has several
 200 .\".Xr config 8
 201 .\"locators:
 202 .\".Bl -tag -compact -width xxxxxx
 203 .\".It Cd port
 204 .\"this is the number of the port on the closest upstream hub.
 205 .\".It Cd configuration
 206 .\"this is the configuration the device must be in for this driver to attach.
 207 .\"This locator does not set the configuration; it is iterated by the bus
 208 .\"enumeration.
 209 .\".It Cd interface
 210 .\"this is the interface number within a device that an interface driver
 211 .\"attaches to.
 212 .\".It Cd vendor
 213 .\"this is the 16 bit vendor id of the device.
 214 .\".It Cd product
 215 .\"this is the 16 bit product id of the device.
 216 .\".It Cd release
 217 .\"this is the 16 bit release (revision) number of the device.
 218 .\".El
 219 .\"The first locator can be used to pin down a particular device
 220 .\"according to its physical position in the device tree.
 221 .\"The last three locators can be used to pin down a particular
 222 .\"device according to what device it actually is.
 223 .Pp
 224 The bus enumeration of the
 225 .Tn USB
 226 bus proceeds in several steps:
 227 .Bl -enum
 228 .It
 229 Any device specific driver can attach to the device.
 230 .It
 231 If none is found, any device class specific driver can attach.
 232 .It
 233 If none is found, all configurations are iterated over.
 234 For each configuration, all the interfaces are iterated over, and interface
 235 drivers can attach.
 236 If any interface driver attached in a certain
 237 configuration, the iteration over configurations is stopped.
 238 .It
 239 If still no drivers have been found, the generic
 240 .Tn USB
 241 driver can attach.
 242 .El
 243 .Sh USB CONTROLLER INTERFACE
 244 Use the following to get access to the
 245 .Tn USB
 246 specific structures and defines.
 247 .Pp
 248 .In bus/usb/usb.h
 249 .Pp
 250 The
 251 .Pa /dev/usb Ns Ar N
 252 can be opened and a few operations can be performed on it.
 253 The
 254 .Xr poll 2
 255 system call will say that I/O is possible on the controller device when a
 256 .Tn USB
 257 device has been connected or disconnected to the bus.
 258 .Pp
 259 The following
 260 .Xr ioctl 2
 261 commands are supported on the controller device:
 262 .Bl -tag -width xxxxxx
 263 .It Dv USB_DISCOVER
 264 This command will cause a complete bus discovery to be initiated.
 265 If any devices attached or detached from the bus they will be
 266 processed during this command.
 267 This is the only way that new devices are found on the bus.
 268 .It Dv USB_DEVICEINFO Vt "struct usb_device_info"
 269 This command can be used to retrieve some information about a device
 270 on the bus.
 271 The
 272 .Va udi_addr
 273 field should be filled before the call and the other fields will
 274 be filled by information about the device on that address.
 275 Should no such device exist, an error is reported.
 276 .Bd -literal
 277 #define USB_MAX_DEVNAMES 4
 278 #define USB_MAX_DEVNAMELEN 16
 279 struct usb_device_info {
 280         u_int8_t        udi_bus;
 281         u_int8_t        udi_addr;       /* device address */
 282         usb_event_cookie_t udi_cookie;
 283         char            udi_product[USB_MAX_STRING_LEN];
 284         char            udi_vendor[USB_MAX_STRING_LEN];
 285         char            udi_release[8];
 286         u_int16_t       udi_productNo;
 287         u_int16_t       udi_vendorNo;
 288         u_int16_t       udi_releaseNo;
 289         u_int8_t        udi_class;
 290         u_int8_t        udi_subclass;
 291         u_int8_t        udi_protocol;
 292         u_int8_t        udi_config;
 293         u_int8_t        udi_speed;
 294 #define USB_SPEED_LOW  1
 295 #define USB_SPEED_FULL 2
 296 #define USB_SPEED_HIGH 3
 297         int             udi_power;      /* power consumption in mA, 0 if selfpowered */
 298         int             udi_nports;
 299         char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
 300         u_int8_t        udi_ports[16];/* hub only: addresses of devices on ports */
 301 #define USB_PORT_ENABLED 0xff
 302 #define USB_PORT_SUSPENDED 0xfe
 303 #define USB_PORT_POWERED 0xfd
 304 #define USB_PORT_DISABLED 0xfc
 305 };
 306 .Ed
 307 .Pp
 308 .Va udi_bus
 309 and
 310 .Va udi_addr
 311 contain the topological information for the device.
 312 .Va udi_devnames
 313 contains the device names of the connected drivers.
 314 For example, the
 315 third
 316 .Tn USB
 317 Zip drive connected will be
 318 .Li umass2 .
 319 The
 320 .Va udi_product , udi_vendor
 321 and
 322 .Va udi_release
 323 fields contain self-explanatory descriptions of the device.
 324 .Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
 325 and
 326 .Va udi_protocol
 327 contain the corresponding values from the device descriptors.
 328 The
 329 .Va udi_config
 330 field shows the current configuration of the device.
 331 .Pp
 332 .Va udi_speed
 333 indicates whether the device is at low speed
 334 .Pq Dv USB_SPEED_LOW ,
 335 full speed
 336 .Pq Dv USB_SPEED_FULL
 337 or high speed
 338 .Pq Dv USB_SPEED_HIGH .
 339 The
 340 .Va udi_power
 341 field shows the power consumption in milli-amps drawn at 5 volts,
 342 or zero if the device is self powered.
 343 .Pp
 344 If the device is a hub, the
 345 .Va udi_nports
 346 field is non-zero, and the
 347 .Va udi_ports
 348 field contains the addresses of the connected devices.
 349 If no device is connected to a port, one of the
 350 .Dv USB_PORT_*
 351 values indicates its status.
 352 .It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
 353 This command retrieves statistics about the controller.
 354 .Bd -literal
 355 struct usb_device_stats {
 356         u_long  uds_requests[4];
 357 };
 358 .Ed
 359 .Pp
 360 The
 361 .Va uds_requests
 362 field is indexed by the transfer kind, i.e.\&
 363 .Dv UE_* ,
 364 and indicates how many transfers of each kind that has been completed
 365 by the controller.
 366 .It Dv USB_REQUEST Vt "struct usb_ctl_request"
 367 This command can be used to execute arbitrary requests on the control pipe.
 368 This is
 369 .Em DANGEROUS
 370 and should be used with great care since it
 371 can destroy the bus integrity.
 372 .El
 373 .Pp
 374 The include file
 375 .In bus/usb/usb.h
 376 contains definitions for the types used by the various
 377 .Xr ioctl 2
 378 calls.
 379 The naming convention of the fields for the various
 380 .Tn USB
 381 descriptors exactly follows the naming in the
 382 .Tn USB
 383 specification.
 384 Byte sized fields can be accessed directly, but word (16 bit)
 385 sized fields must be access by the
 386 .Fn UGETW field
 387 and
 388 .Fn USETW field value
 389 macros to handle byte order and alignment properly.
 390 .Pp
 391 The include file
 392 .In bus/usb/usbhid.h
 393 similarly contains the definitions for
 394 Human Interface Devices
 395 .Pq Tn HID .
 396 .Sh USB EVENT INTERFACE
 397 All
 398 .Tn USB
 399 events are reported via the
 400 .Pa /dev/usb
 401 device.
 402 This devices can be opened for reading and each
 403 .Xr read 2
 404 will yield an event record (if something has happened).
 405 The
 406 .Xr poll 2
 407 system call can be used to determine if an event record is available
 408 for reading.
 409 .Pp
 410 The event record has the following definition:
 411 .Bd -literal
 412 struct usb_event {
 413         int                                 ue_type;
 414 #define USB_EVENT_CTRLR_ATTACH 1
 415 #define USB_EVENT_CTRLR_DETACH 2
 416 #define USB_EVENT_DEVICE_ATTACH 3
 417 #define USB_EVENT_DEVICE_DETACH 4
 418 #define USB_EVENT_DRIVER_ATTACH 5
 419 #define USB_EVENT_DRIVER_DETACH 6
 420         struct timespec                     ue_time;
 421         union {
 422                 struct {
 423                         int                 ue_bus;
 424                 } ue_ctrlr;
 425                 struct usb_device_info      ue_device;
 426                 struct {
 427                         usb_event_cookie_t  ue_cookie;
 428                         char                ue_devname[16];
 429                 } ue_driver;
 430         } u;
 431 };
 432 .Ed
 433 The
 434 .Va ue_type
 435 field identifies the type of event that is described.
 436 The possible events are attach/detach of a host controller,
 437 a device, or a device driver.
 438 The union contains information
 439 pertinent to the different types of events.
 440 Macros,
 441 .Fn USB_EVENT_IS_ATTACH "ue_type"
 442 and
 443 .Fn USB_EVENT_IS_DETACH "ue_type"
 444 can be used to determine if an event was an
 445 .Dq attach
 446 or a
 447 .Dq detach
 448 request.
 449 .Pp
 450 The
 451 .Va ue_bus
 452 contains the number of the
 453 .Tn USB
 454 bus for host controller events.
 455 .Pp
 456 The
 457 .Va ue_device
 458 record contains information about the device in a device event event.
 459 .Pp
 460 The
 461 .Va ue_cookie
 462 is an opaque value that uniquely determines which
 463 device a device driver has been attached to (i.e., it equals
 464 the cookie value in the device that the driver attached to).
 465 .Pp
 466 The
 467 .Va ue_devname
 468 contains the name of the device (driver) as seen in, e.g.,
 469 kernel messages.
 470 .Pp
 471 Note that there is a separation between device and device
 472 driver events.
 473 A device event is generated when a physical
 474 .Tn USB
 475 device is attached or detached.
 476 A single
 477 .Tn USB
 478 device may
 479 have zero, one, or many device drivers associated with it.
 480 .Sh SEE ALSO
 481 The
 482 .Tn USB
 483 specifications can be found at:
 484 .Pp
 485 .D1 Pa http://www.usb.org/developers/docs/
 486 .Pp
 487 .Xr ehci 4 ,
 488 .Xr ohci 4 ,
 489 .Xr pci 4 ,
 490 .Xr uhci 4 ,
 491 .Xr usbd 8 ,
 492 .Xr usbdevs 8
 493 .Sh HISTORY
 494 The
 495 .Nm
 496 driver first appeared in
 497 .Fx 3.0 .
 498 .Sh AUTHORS
 499 The
 500 .Nm
 501 driver was written by
 502 .An Lennart Augustsson Aq augustss@carlstedt.se
 503 for the
 504 .Nx
 505 project.