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