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