Documentation/usb/proc_usb_info.txt

   1 /proc/bus/usb filesystem output
   2 ===============================
   3 (version 2003.05.30)
   4
   5
   6 The usbfs filesystem for USB devices is traditionally mounted at
   7 /proc/bus/usb.  It provides the /proc/bus/usb/devices file, as well as
   8 the /proc/bus/usb/BBB/DDD files.
   9
  10
  11 **NOTE**: If /proc/bus/usb appears empty, and a host controller
  12           driver has been linked, then you need to mount the
  13           filesystem.  Issue the command (as root):
  14
  15       mount -t usbfs none /proc/bus/usb
  16
  17           An alternative and more permanent method would be to add
  18
  19       none  /proc/bus/usb  usbfs  defaults  0  0
  20
  21           to /etc/fstab.  This will mount usbfs at each reboot.
  22           You can then issue `cat /proc/bus/usb/devices` to extract
  23           USB device information, and user mode drivers can use usbfs
  24           to interact with USB devices.
  25
  26           There are a number of mount options supported by usbfs.
  27           Consult the source code (linux/drivers/usb/core/inode.c) for
  28           information about those options.
  29
  30 **NOTE**: The filesystem has been renamed from "usbdevfs" to
  31           "usbfs", to reduce confusion with "devfs".  You may
  32           still see references to the older "usbdevfs" name.
  33
  34 For more information on mounting the usbfs file system, see the
  35 "USB Device Filesystem" section of the USB Guide. The latest copy
  36 of the USB Guide can be found at http://www.linux-usb.org/
  37
  38
  39 THE /proc/bus/usb/BBB/DDD FILES:
  40 --------------------------------
  41 Each connected USB device has one file.  The BBB indicates the bus
  42 number.  The DDD indicates the device address on that bus.  Both
  43 of these numbers are assigned sequentially, and can be reused, so
  44 you can't rely on them for stable access to devices.  For example,
  45 it's relatively common for devices to re-enumerate while they are
  46 still connected (perhaps someone jostled their power supply, hub,
  47 or USB cable), so a device might be 002/027 when you first connect
  48 it and 002/048 sometime later.
  49
  50 These files can be read as binary data.  The binary data consists
  51 of first the device descriptor, then the descriptors for each
  52 configuration of the device.  That information is also shown in
  53 text form by the /proc/bus/usb/devices file, described later.
  54
  55 These files may also be used to write user-level drivers for the USB
  56 devices.  You would open the /proc/bus/usb/BBB/DDD file read/write,
  57 read its descriptors to make sure it's the device you expect, and then
  58 bind to an interface (or perhaps several) using an ioctl call.  You
  59 would issue more ioctls to the device to communicate to it using
  60 control, bulk, or other kinds of USB transfers.  The IOCTLs are
  61 listed in the <linux/usbdevice_fs.h> file, and at this writing the
  62 source code (linux/drivers/usb/core/devio.c) is the primary reference
  63 for how to access devices through those files.
  64
  65 Note that since by default these BBB/DDD files are writable only by
  66 root, only root can write such user mode drivers.  You can selectively
  67 grant read/write permissions to other users by using "chmod".  Also,
  68 usbfs mount options such as "devmode=0666" may be helpful.
  69
  70
  71
  72 THE /proc/bus/usb/devices FILE:
  73 -------------------------------
  74 In /proc/bus/usb/devices, each device's output has multiple
  75 lines of ASCII output.
  76 I made it ASCII instead of binary on purpose, so that someone
  77 can obtain some useful data from it without the use of an
  78 auxiliary program.  However, with an auxiliary program, the numbers
  79 in the first 4 columns of each "T:" line (topology info:
  80 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
  81
  82 Each line is tagged with a one-character ID for that line:
  83
  84 T = Topology (etc.)
  85 B = Bandwidth (applies only to USB host controllers, which are
  86     virtualized as root hubs)
  87 D = Device descriptor info.
  88 P = Product ID info. (from Device descriptor, but they won't fit
  89     together on one line)
  90 S = String descriptors.
  91 C = Configuration descriptor info. (* = active configuration)
  92 I = Interface descriptor info.
  93 E = Endpoint descriptor info.
  94
  95 =======================================================================
  96
  97 /proc/bus/usb/devices output format:
  98
  99 Legend:
 100   d = decimal number (may have leading spaces or 0's)
 101   x = hexadecimal number (may have leading spaces or 0's)
 102   s = string
 103
 104
 105 Topology info:
 106
 107 T:  Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd
 108 |   |      |      |       |       |      |        |       |__MaxChildren
 109 |   |      |      |       |       |      |        |__Device Speed in Mbps
 110 |   |      |      |       |       |      |__DeviceNumber
 111 |   |      |      |       |       |__Count of devices at this level
 112 |   |      |      |       |__Connector/Port on Parent for this device
 113 |   |      |      |__Parent DeviceNumber
 114 |   |      |__Level in topology for this bus
 115 |   |__Bus number
 116 |__Topology info tag
 117
 118     Speed may be:
 119         1.5     Mbit/s for low speed USB
 120         12      Mbit/s for full speed USB
 121         480     Mbit/s for high speed USB (added for USB 2.0)
 122
 123
 124 Bandwidth info:
 125 B:  Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
 126 |   |                       |         |__Number of isochronous requests
 127 |   |                       |__Number of interrupt requests
 128 |   |__Total Bandwidth allocated to this bus
 129 |__Bandwidth info tag
 130
 131     Bandwidth allocation is an approximation of how much of one frame
 132     (millisecond) is in use.  It reflects only periodic transfers, which
 133     are the only transfers that reserve bandwidth.  Control and bulk
 134     transfers use all other bandwidth, including reserved bandwidth that
 135     is not used for transfers (such as for short packets).
 136
 137     The percentage is how much of the "reserved" bandwidth is scheduled by
 138     those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
 139     90% of the bus bandwidth is reserved.  For a high speed bus (loosely,
 140     "USB 2.0") 80% is reserved.
 141
 142
 143 Device descriptor info & Product ID info:
 144
 145 D:  Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
 146 P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
 147
 148 where
 149 D:  Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
 150 |   |        |             |      |       |       |__NumberConfigurations
 151 |   |        |             |      |       |__MaxPacketSize of Default Endpoint
 152 |   |        |             |      |__DeviceProtocol
 153 |   |        |             |__DeviceSubClass
 154 |   |        |__DeviceClass
 155 |   |__Device USB version
 156 |__Device info tag #1
 157
 158 where
 159 P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
 160 |   |           |           |__Product revision number
 161 |   |           |__Product ID code
 162 |   |__Vendor ID code
 163 |__Device info tag #2
 164
 165
 166 String descriptor info:
 167
 168 S:  Manufacturer=ssss
 169 |   |__Manufacturer of this device as read from the device.
 170 |      For USB host controller drivers (virtual root hubs) this may
 171 |      be omitted, or (for newer drivers) will identify the kernel
 172 |      version and the driver which provides this hub emulation.
 173 |__String info tag
 174
 175 S:  Product=ssss
 176 |   |__Product description of this device as read from the device.
 177 |      For older USB host controller drivers (virtual root hubs) this
 178 |      indicates the driver; for newer ones, it's a product (and vendor)
 179 |      description that often comes from the kernel's PCI ID database.
 180 |__String info tag
 181
 182 S:  SerialNumber=ssss
 183 |   |__Serial Number of this device as read from the device.
 184 |      For USB host controller drivers (virtual root hubs) this is
 185 |      some unique ID, normally a bus ID (address or slot name) that
 186 |      can't be shared with any other device.
 187 |__String info tag
 188
 189
 190
 191 Configuration descriptor info:
 192
 193 C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
 194 | | |       |       |      |__MaxPower in mA
 195 | | |       |       |__Attributes
 196 | | |       |__ConfiguratioNumber
 197 | | |__NumberOfInterfaces
 198 | |__ "*" indicates the active configuration (others are " ")
 199 |__Config info tag
 200
 201     USB devices may have multiple configurations, each of which act
 202     rather differently.  For example, a bus-powered configuration
 203     might be much less capable than one that is self-powered.  Only
 204     one device configuration can be active at a time; most devices
 205     have only one configuration.
 206
 207     Each configuration consists of one or more interfaces.  Each
 208     interface serves a distinct "function", which is typically bound
 209     to a different USB device driver.  One common example is a USB
 210     speaker with an audio interface for playback, and a HID interface
 211     for use with software volume control.
 212
 213
 214 Interface descriptor info (can be multiple per Config):
 215
 216 I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
 217 | | |      |      |       |             |      |       |__Driver name
 218 | | |      |      |       |             |      |          or "(none)"
 219 | | |      |      |       |             |      |__InterfaceProtocol
 220 | | |      |      |       |             |__InterfaceSubClass
 221 | | |      |      |       |__InterfaceClass
 222 | | |      |      |__NumberOfEndpoints
 223 | | |      |__AlternateSettingNumber
 224 | | |__InterfaceNumber
 225 | |__ "*" indicates the active altsetting (others are " ")
 226 |__Interface info tag
 227
 228     A given interface may have one or more "alternate" settings.
 229     For example, default settings may not use more than a small
 230     amount of periodic bandwidth.  To use significant fractions
 231     of bus bandwidth, drivers must select a non-default altsetting.
 232
 233     Only one setting for an interface may be active at a time, and
 234     only one driver may bind to an interface at a time.  Most devices
 235     have only one alternate setting per interface.
 236
 237
 238 Endpoint descriptor info (can be multiple per Interface):
 239
 240 E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
 241 |   |        |            |         |__Interval (max) between transfers
 242 |   |        |            |__EndpointMaxPacketSize
 243 |   |        |__Attributes(EndpointType)
 244 |   |__EndpointAddress(I=In,O=Out)
 245 |__Endpoint info tag
 246
 247     The interval is nonzero for all periodic (interrupt or isochronous)
 248     endpoints.  For high speed endpoints the transfer interval may be
 249     measured in microseconds rather than milliseconds.
 250
 251     For high speed periodic endpoints, the "MaxPacketSize" reflects
 252     the per-microframe data transfer size.  For "high bandwidth"
 253     endpoints, that can reflect two or three packets (for up to
 254     3KBytes every 125 usec) per endpoint.
 255
 256     With the Linux-USB stack, periodic bandwidth reservations use the
 257     transfer intervals and sizes provided by URBs, which can be less
 258     than those found in endpoint descriptor.
 259
 260
 261 =======================================================================
 262
 263
 264 If a user or script is interested only in Topology info, for
 265 example, use something like "grep ^T: /proc/bus/usb/devices"
 266 for only the Topology lines.  A command like
 267 "grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
 268 only the lines that begin with the characters in square brackets,
 269 where the valid characters are TDPCIE.  With a slightly more able
 270 script, it can display any selected lines (for example, only T, D,
 271 and P lines) and change their output format.  (The "procusb"
 272 Perl script is the beginning of this idea.  It will list only
 273 selected lines [selected from TBDPSCIE] or "All" lines from
 274 /proc/bus/usb/devices.)
 275
 276 The Topology lines can be used to generate a graphic/pictorial
 277 of the USB devices on a system's root hub.  (See more below
 278 on how to do this.)
 279
 280 The Interface lines can be used to determine what driver is
 281 being used for each device, and which altsetting it activated.
 282
 283 The Configuration lines could be used to list maximum power
 284 (in milliamps) that a system's USB devices are using.
 285 For example, "grep ^C: /proc/bus/usb/devices".
 286
 287
 288 Here's an example, from a system which has a UHCI root hub,
 289 an external hub connected to the root hub, and a mouse and
 290 a serial converter connected to the external hub.
 291
 292 T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
 293 B:  Alloc= 28/900 us ( 3%), #Int=  2, #Iso=  0
 294 D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 295 P:  Vendor=0000 ProdID=0000 Rev= 0.00
 296 S:  Product=USB UHCI Root Hub
 297 S:  SerialNumber=dce0
 298 C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
 299 I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
 300 E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
 301
 302 T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 4
 303 D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 304 P:  Vendor=0451 ProdID=1446 Rev= 1.00
 305 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
 306 I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
 307 E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms
 308
 309 T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
 310 D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 311 P:  Vendor=04b4 ProdID=0001 Rev= 0.00
 312 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
 313 I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
 314 E:  Ad=81(I) Atr=03(Int.) MxPS=   3 Ivl= 10ms
 315
 316 T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12  MxCh= 0
 317 D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 318 P:  Vendor=0565 ProdID=0001 Rev= 1.08
 319 S:  Manufacturer=Peracom Networks, Inc.
 320 S:  Product=Peracom USB to Serial Converter
 321 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
 322 I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
 323 E:  Ad=81(I) Atr=02(Bulk) MxPS=  64 Ivl= 16ms
 324 E:  Ad=01(O) Atr=02(Bulk) MxPS=  16 Ivl= 16ms
 325 E:  Ad=82(I) Atr=03(Int.) MxPS=   8 Ivl=  8ms
 326
 327
 328 Selecting only the "T:" and "I:" lines from this (for example, by using
 329 "procusb ti"), we have:
 330
 331 T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
 332 T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 4
 333 I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
 334 T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
 335 I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
 336 T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12  MxCh= 0
 337 I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
 338
 339
 340 Physically this looks like (or could be converted to):
 341
 342                       +------------------+
 343                       |  PC/root_hub (12)|   Dev# = 1
 344                       +------------------+   (nn) is Mbps.
 345     Level 0           |  CN.0   |  CN.1  |   [CN = connector/port #]
 346                       +------------------+
 347                           /
 348                          /
 349             +-----------------------+
 350   Level 1   | Dev#2: 4-port hub (12)|
 351             +-----------------------+
 352             |CN.0 |CN.1 |CN.2 |CN.3 |
 353             +-----------------------+
 354                 \           \____________________
 355                  \_____                          \
 356                        \                          \
 357                +--------------------+      +--------------------+
 358   Level 2      | Dev# 3: mouse (1.5)|      | Dev# 4: serial (12)|
 359                +--------------------+      +--------------------+
 360
 361
 362
 363 Or, in a more tree-like structure (ports [Connectors] without
 364 connections could be omitted):
 365
 366 PC:  Dev# 1, root hub, 2 ports, 12 Mbps
 367 |_ CN.0:  Dev# 2, hub, 4 ports, 12 Mbps
 368      |_ CN.0:  Dev #3, mouse, 1.5 Mbps
 369      |_ CN.1:
 370      |_ CN.2:  Dev #4, serial, 12 Mbps
 371      |_ CN.3:
 372 |_ CN.1:
 373
 374
 375                          ### END ###