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