Documentation/usb/proc_usb_info.txt

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