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 .\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
  29 .\"
  30 .\" Redistribution and use in source and binary forms, with or without
  31 .\" modification, are permitted provided that the following conditions
  32 .\" are met:
  33 .\" 1. Redistributions of source code must retain the above copyright
  34 .\"    notice, this list of conditions and the following disclaimer.
  35 .\" 2. Redistributions in binary form must reproduce the above copyright
  36 .\"    notice, this list of conditions and the following disclaimer in the
  37 .\"    documentation and/or other materials provided with the distribution.
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  40 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  42 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  43 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  44 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  45 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  47 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  48 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  49 .\" SUCH DAMAGE.
  50 .\"
  51 .\" $FreeBSD$
  52 .\"
  53 .Dd May 20, 2009
  54 .Dt USB 4
  55 .Os
  56 .Sh NAME
  57 .Nm usb
  58 .Nd Universal Serial Bus
  59 .Sh SYNOPSIS
  60 To compile this driver into the kernel,
  61 place the following line in your
  62 kernel configuration file:
  63 .Bd -ragged -offset indent
  64 .Cd "device usb"
  65 .Ed
  66 .Pp
  67 Alternatively, to load the driver as a
  68 module at boot time, place the following line in
  69 .Xr loader.conf 5 :
  70 .Bd -literal -offset indent
  71 usb_load="YES"
  72 .Ed
  73 .Sh USERLAND PROGRAMMING
  74 USB functions can be accessed from userland through the libusb library.
  75 See
  76 .Xr libusb 3
  77 for more information.
  78 .Sh DESCRIPTION
  79 .Fx
  80 provides machine-independent bus support and drivers for
  81 .Tn USB
  82 devices in host and device side mode.
  83 .Pp
  84 The
  85 .Nm
  86 driver has three layers:
  87 .Bl -tag
  88 .It USB Controller (Bus)
  89 .It USB Device
  90 .It USB Driver
  91 .El
  92 .Pp
  93 The controller attaches to a physical bus
  94 like
  95 .Xr pci 4 .
  96 The
  97 .Tn USB
  98 bus attaches to the controller, and the root hub attaches
  99 to the controller.
 100 Any devices attached to the bus will attach to the root hub
 101 or another hub attached to the
 102 .Tn USB
 103 bus.
 104 .Pp
 105 The
 106 .Nm uhub
 107 device will always be present as it is needed for the
 108 root hub.
 109 .Sh INTRODUCTION TO USB
 110 The
 111 .Tn USB
 112 is a system where external devices can be connected to a PC.
 113 The most common USB speeds are:
 114 .Bl -tag
 115 .It Low Speed (1.5MBit/sec)
 116 .It Full Speed (12MBit/sec)
 117 .It High Speed (480MBit/sec)
 118 .El
 119 .Pp
 120 Each
 121 .Tn USB
 122 has a USB controller that is the master of the bus.
 123 The physical communication is simplex which means the host controller only communicates with one USB device at a time.
 124 .Pp
 125 There can be up to 127 devices connected to an USB HUB tree.
 126 The addresses are assigned
 127 dynamically by the host when each device is attached to the bus.
 128 .Pp
 129 Within each device there can be up to 16 endpoints.
 130 Each endpoint
 131 is individually addressed and the addresses are static.
 132 Each of these endpoints will communicate in one of four different modes:
 133 .Em control , isochronous , bulk ,
 134 or
 135 .Em interrupt .
 136 A device always has at least one endpoint.
 137 This endpoint has address 0 and is a control
 138 endpoint and is used to give commands to and extract basic data,
 139 such as descriptors, from the device.
 140 Each endpoint, except the control endpoint, is unidirectional.
 141 .Pp
 142 The endpoints in a device are grouped into interfaces.
 143 An interface is a logical unit within a device; e.g.\&
 144 a compound device with both a keyboard and a trackball would present
 145 one interface for each.
 146 An interface can sometimes be set into different modes,
 147 called alternate settings, which affects how it operates.
 148 Different alternate settings can have different endpoints
 149 within it.
 150 .Pp
 151 A device may operate in different configurations.
 152 Depending on the
 153 configuration, the device may present different sets of endpoints
 154 and interfaces.
 155 .Pp
 156 The bus enumeration of the
 157 .Tn USB
 158 bus proceeds in several steps:
 159 .Bl -enum
 160 .It
 161 Any interface specific driver can attach to the device.
 162 .It
 163 If none is found, generic interface class drivers can attach.
 164 .El
 165 .Sh SEE ALSO
 166 The
 167 .Tn USB
 168 specifications can be found at:
 169 .Pp
 170 .D1 Pa http://www.usb.org/developers/docs/
 171 .Pp
 172 .Xr libusb 3 ,
 173 .Xr usbdi 9 ,
 174 .Xr aue 4 ,
 175 .Xr axe 4 ,
 176 .Xr cue 4 ,
 177 .Xr ehci 4 ,
 178 .Xr kue 4 ,
 179 .Xr ohci 4 ,
 180 .Xr pci 4 ,
 181 .Xr rue 4 ,
 182 .Xr ucom 4 ,
 183 .Xr udav 4 ,
 184 .Xr uhci 4 ,
 185 .Xr uhid 4 ,
 186 .Xr ukbd 4 ,
 187 .Xr ulpt 4 ,
 188 .Xr umass 4 ,
 189 .Xr ums 4 ,
 190 .Xr uplcom 4 ,
 191 .Xr urio 4 ,
 192 .Xr uvscom 4 ,
 193 .Xr usbconfig 8 ,
 194 .Xr xhci 4
 195 .Sh STANDARDS
 196 The
 197 .Nm
 198 module complies with the USB 2.0 standard.
 199 .Sh HISTORY
 200 The
 201 .Nm
 202 module has been inspired by the NetBSD USB stack initially written by
 203 Lennart Augustsson. The
 204 .Nm
 205 module was written by
 206 .An Hans Petter Selasky Aq hselasky@freebsd.org .