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