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