Documentation/usb/proc_usb_info.txt

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