i386/linux/linux-2.3.21/Documentation/proc_usb_info.txt

   1 /proc/bus/usb filesystem output
   2 ===============================
   3 (version 19990722)
   4
   5
   6 The /proc filesystem for USB devices generates
   7 /proc/bus/usb/drivers and /proc/bus/usb/devices.
   8
   9 /proc/bus/usb/drivers just lists the registered drivers,
  10 one per line.  Not very interesting or pretty.
  11
  12 In /proc/bus/usb/devices, each device's output has multiple
  13 lines (except for a root hub) of ASCII output.
  14 I made it ASCII instead of binary on purpose, so that someone
  15 can obtain some useful data from it without the use of an
  16 auxiliary program.  However, with an auxiliary program, the numbers
  17 in the first 4 columns of each "T:" line (topology info:
  18 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
  19 (I think.  I haven't proved this, but I have tested it with 3
  20 different topo/connections and it looked possible.)
  21
  22 Each line is tagged with a one-character ID for that line:
  23
  24 T = Topology (etc.)
  25 D = Device descriptor info.
  26 P = Product ID info. (from Device descriptor, but they won't fit
  27     together on one line)
  28 C = Configuration descriptor info. (* = active configuration)
  29 I = Interface descriptor info.
  30 E = Endpoint descriptor info.
  31
  32 =======================================================================
  33
  34 /proc/bus/usb/devices output format:
  35
  36 Legend:
  37   d = decimal number (may have leading spaces or 0's)
  38   x = hexadecimal number (may have leading spaces or 0's)
  39   s = string
  40
  41
  42 Topology info:
  43
  44 T:  Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd If#=ddd MxCh=dd Driver=%s
  45 |   |      |       |       |      |        |       |       |       |__DriverName
  46 |   |      |       |       |      |        |       |       |__MaxChildren
  47 |   |      |       |       |      |        |       |__Configured InterfaceNumber
  48 |   |      |       |       |      |        |__Device Speed in Mbps
  49 |   |      |       |       |      |__DeviceNumber
  50 |   |      |       |       |__Count of devices at this level
  51 |   |      |       |__Connector/Port on Parent for this device
  52 |   |      |__Parent DeviceNumber
  53 |   |__Level in topology
  54 |__Topology info tag
  55
  56
  57 Device descriptor info & Product ID info:
  58
  59 D:  Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
  60 P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
  61
  62 where
  63 D:  Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
  64 |   |        |             |      |       |       |__NumberConfigurations
  65 |   |        |             |      |       |__MaxPacketSize of Default Endpoint
  66 |   |        |             |      |__DeviceProtocol
  67 |   |        |             |__DeviceSubClass
  68 |   |        |__DeviceClass
  69 |   |__Device USB version
  70 |__Device info tag #1
  71
  72 where
  73 P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
  74 |   |           |           |__Product revision number
  75 |   |           |__Product ID code
  76 |   |__Vendor ID code
  77 |__Device info tag #2
  78
  79
  80 Configuration descriptor info:
  81
  82 C:  #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
  83 |   |       |       |      |__MaxPower in mA
  84 |   |       |       |__Attributes
  85 |   |       |__ConfiguratioNumber
  86 |   |__NumberOfInterfaces
  87 |__Config info tag
  88
  89
  90 Interface descriptor info (can be multiple per Config):
  91
  92 I:  If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx
  93 |   |      |      |       |             |      |__InterfaceProtocol
  94 |   |      |      |       |             |__InterfaceSubClass
  95 |   |      |      |       |__InterfaceClass
  96 |   |      |      |__NumberOfEndpoints
  97 |   |      |__AlternateSettingNumber
  98 |   |__InterfaceNumber
  99 |__Interface info tag
 100
 101
 102 Endpoint descriptor info (can be multiple per Interface):
 103
 104 E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddms
 105 E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddms
 106 |   |        |         |         |__Interval
 107 |   |        |         |__EndpointMaxPacketSize
 108 |   |        |__Attributes(EndpointType)
 109 |   |__EndpointAddress(I=In,O=Out)
 110 |__Endpoint info tag
 111
 112 =======================================================================
 113
 114
 115 If a user or script is interested only in Topology info, for
 116 example, use something like "grep ^T: /proc/bus/usb/devices"
 117 for only the Topology lines.  A command like
 118 "grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
 119 only the lines that begin with the characters in square brackets,
 120 where the valid characters are TDPCIE.  With a slightly more able
 121 script, it can display any selected lines (for example, only T, D,
 122 and P lines) and change their output format.  (The "procusb"
 123 Perl script is the beginning of this idea.  It will list only
 124 selected lines [selected from TDPCIE] or "All" lines from
 125 /proc/bus/usb/devices.)
 126
 127 The Topology lines can be used to generate a graphic/pictorial
 128 of the USB devices on a system's root hub.  (See more below
 129 on how to do this.)
 130
 131 The Configuration lines could be used to list maximum power
 132 (in milliamps) that a system's USB devices are using.
 133 For example, "grep ^C: /proc/bus/usb/devices".
 134
 135
 136 Here's an example, from a system which has a UHCI root hub,
 137 an external hub connected to the root hub, and a mouse and
 138 a video camera connected to the external hub.  [The video
 139 camera is listed as (none) since it is not recognized by
 140 any driver.]
 141
 142
 143 T:  Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= -1 Spd=12  If#=  0 MxCh= 2 Driver=(root hub)
 144 T:  Lev=01 Prnt=00 Port=00 Cnt=01 Dev#=  1 Spd=12  If#=  0 MxCh= 4 Driver=hub
 145 D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 146 P:  Vendor=0451 ProdID=1446 Rev= 1.00
 147 C:* #If= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
 148 I:  If#= 0 Alt= 0 #EP= 1 Cls=09(hub  ) Sub=00 Prot=00
 149 E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms
 150 T:  Lev=02 Prnt=01 Port=00 Cnt=01 Dev#=  3 Spd=1.5 If#=  0 MxCh= 0 Driver=mouse
 151 D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 152 P:  Vendor=0458 ProdID=0001 Rev= 0.00
 153 C:* #If= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
 154 I:  If#= 0 Alt= 0 #EP= 1 Cls=03(HID  ) Sub=01 Prot=02
 155 E:  Ad=81(I) Atr=03(Int.) MxPS=   3 Ivl= 10ms
 156 T:  Lev=02 Prnt=01 Port=02 Cnt=02 Dev#=  4 Spd=12  If#=  0 MxCh= 0 Driver=(none)
 157 D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
 158 P:  Vendor=04c8 ProdID=0720 Rev= 1.01
 159 C:* #If= 1 Cfg#= 1 Atr=80 MxPwr=500mA
 160 I:  If#= 0 Alt= 0 #EP= 2 Cls=0a(unk. ) Sub=ff Prot=00
 161 E:  Ad=81(I) Atr=01(Isoc) MxPS=   1 Ivl=  1ms
 162 E:  Ad=82(I) Atr=01(Isoc) MxPS= 384 Ivl=  1ms
 163 I:  If#= 0 Alt= 1 #EP= 2 Cls=0a(unk. ) Sub=ff Prot=00
 164 E:  Ad=81(I) Atr=01(Isoc) MxPS=   1 Ivl=  1ms
 165 E:  Ad=82(I) Atr=01(Isoc) MxPS= 240 Ivl=  1ms
 166 I:  If#= 0 Alt= 2 #EP= 2 Cls=0a(unk. ) Sub=ff Prot=00
 167 E:  Ad=81(I) Atr=01(Isoc) MxPS=   1 Ivl=  1ms
 168 E:  Ad=82(I) Atr=01(Isoc) MxPS= 576 Ivl=  1ms
 169 I:  If#= 0 Alt= 3 #EP= 2 Cls=0a(unk. ) Sub=ff Prot=00
 170 E:  Ad=81(I) Atr=01(Isoc) MxPS=   1 Ivl=  1ms
 171 E:  Ad=82(I) Atr=01(Isoc) MxPS= 464 Ivl=  1ms
 172 I:  If#= 0 Alt= 4 #EP= 2 Cls=0a(unk. ) Sub=ff Prot=00
 173 E:  Ad=81(I) Atr=01(Isoc) MxPS=   1 Ivl=  1ms
 174 E:  Ad=82(I) Atr=01(Isoc) MxPS= 688 Ivl=  1ms
 175
 176
 177 Selecting only the "T:" lines from this (for example, by using
 178 "procusb t"), we have:
 179
 180 T:  Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= -1 Spd=12  If#=  0 MxCh= 2 Driver=(root hub)
 181 T:  Lev=01 Prnt=00 Port=00 Cnt=01 Dev#=  1 Spd=12  If#=  0 MxCh= 4 Driver=hub
 182 T:  Lev=02 Prnt=01 Port=00 Cnt=01 Dev#=  3 Spd=1.5 If#=  0 MxCh= 0 Driver=mouse
 183 T:  Lev=02 Prnt=01 Port=02 Cnt=02 Dev#=  4 Spd=12  If#=  0 MxCh= 0 Driver=(none)
 184
 185
 186 Physically this looks like (or could be converted to):
 187
 188                       +------------------+
 189                       |  PC/root_hub (12)|   Dev# = -1
 190                       +------------------+   (nn) is Mbps.
 191     Level 0           |  CN.0   |  CN.1  |   [CN = connector/port #]
 192                       +------------------+
 193                           /
 194                          /
 195             +-----------------------+
 196   Level 1   | Dev#1: 4-port hub (12)|
 197             +-----------------------+
 198             |CN.0 |CN.1 |CN.2 |CN.3 |
 199             +-----------------------+
 200                 \           \____________________
 201                  \_____                          \
 202                        \                          \
 203                +--------------------+      +--------------------+
 204   Level 2      | Dev# 3: mouse (1.5)|      | Dev# 4: (none) (12)|
 205                +--------------------+      +--------------------+
 206
 207
 208
 209 Or, in a more tree-like structure (ports [Connectors] without
 210 connections could be omitted):
 211
 212 PC:  Dev# -1, root hub, 2 ports, 12 Mbps
 213 |_ CN.0:  Dev# 1, hub, 4 ports, 12 Mbps
 214      |_ CN.0:  Dev #3, mouse, 1.5 Mbps
 215      |_ CN.1:
 216      |_ CN.2:  Dev #4, (none), 12 Mbps  [or use "unknown" for (none)]
 217      |_ CN.3:
 218 |_ CN.1:
 219
 220
 221                          ### END ###