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