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