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