Based on kernel version 4.10.8. Page generated on 2017-04-01 14:44 EST.
1 /proc/bus/usb filesystem output 2 =============================== 3 (version 2010.09.13) 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 In many modern systems the usbfs filesystem isn't used at all. Instead 11 USB 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 39 For more information on mounting the usbfs file system, see the 40 "USB Device Filesystem" section of the USB Guide. The latest copy 41 of the USB Guide can be found at http://www.linux-usb.org/ 42 43 44 THE /proc/bus/usb/BBB/DDD FILES: 45 -------------------------------- 46 Each connected USB device has one file. The BBB indicates the bus 47 number. The DDD indicates the device address on that bus. Both 48 of these numbers are assigned sequentially, and can be reused, so 49 you can't rely on them for stable access to devices. For example, 50 it's relatively common for devices to re-enumerate while they are 51 still connected (perhaps someone jostled their power supply, hub, 52 or USB cable), so a device might be 002/027 when you first connect 53 it and 002/048 sometime later. 54 55 These files can be read as binary data. The binary data consists 56 of first the device descriptor, then the descriptors for each 57 configuration of the device. Multi-byte fields in the device descriptor 58 are converted to host endianness by the kernel. The configuration 59 descriptors are in bus endian format! The configuration descriptor 60 are wTotalLength bytes apart. If a device returns less configuration 61 descriptor data than indicated by wTotalLength there will be a hole in 62 the file for the missing bytes. This information is also shown 63 in text form by the /proc/bus/usb/devices file, described later. 64 65 These files may also be used to write user-level drivers for the USB 66 devices. You would open the /proc/bus/usb/BBB/DDD file read/write, 67 read its descriptors to make sure it's the device you expect, and then 68 bind to an interface (or perhaps several) using an ioctl call. You 69 would issue more ioctls to the device to communicate to it using 70 control, bulk, or other kinds of USB transfers. The IOCTLs are 71 listed in the <linux/usbdevice_fs.h> file, and at this writing the 72 source code (linux/drivers/usb/core/devio.c) is the primary reference 73 for how to access devices through those files. 74 75 Note that since by default these BBB/DDD files are writable only by 76 root, only root can write such user mode drivers. You can selectively 77 grant read/write permissions to other users by using "chmod". Also, 78 usbfs mount options such as "devmode=0666" may be helpful. 79 80 81 82 THE /proc/bus/usb/devices FILE: 83 ------------------------------- 84 In /proc/bus/usb/devices, each device's output has multiple 85 lines of ASCII output. 86 I made it ASCII instead of binary on purpose, so that someone 87 can obtain some useful data from it without the use of an 88 auxiliary program. However, with an auxiliary program, the numbers 89 in the first 4 columns of each "T:" line (topology info: 90 Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram. 91 92 Each line is tagged with a one-character ID for that line: 93 94 T = Topology (etc.) 95 B = Bandwidth (applies only to USB host controllers, which are 96 virtualized as root hubs) 97 D = Device descriptor info. 98 P = Product ID info. (from Device descriptor, but they won't fit 99 together on one line) 100 S = String descriptors. 101 C = Configuration descriptor info. (* = active configuration) 102 I = Interface descriptor info. 103 E = Endpoint descriptor info. 104 105 ======================================================================= 106 107 /proc/bus/usb/devices output format: 108 109 Legend: 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 115 Topology info: 116 117 T: 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 139 Bandwidth info: 140 B: 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 158 Device descriptor info & Product ID info: 159 160 D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd 161 P: Vendor=xxxx ProdID=xxxx Rev=xx.xx 162 163 where 164 D: 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 173 where 174 P: 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 181 String descriptor info: 182 183 S: 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 190 S: 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 197 S: 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 206 Configuration descriptor info: 207 208 C:* #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 229 Interface descriptor info (can be multiple per Config): 230 231 I:* 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 253 Endpoint descriptor info (can be multiple per Interface): 254 255 E: 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 279 If a user or script is interested only in Topology info, for 280 example, use something like "grep ^T: /proc/bus/usb/devices" 281 for only the Topology lines. A command like 282 "grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list 283 only the lines that begin with the characters in square brackets, 284 where the valid characters are TDPCIE. With a slightly more able 285 script, it can display any selected lines (for example, only T, D, 286 and P lines) and change their output format. (The "procusb" 287 Perl script is the beginning of this idea. It will list only 288 selected lines [selected from TBDPSCIE] or "All" lines from 289 /proc/bus/usb/devices.) 290 291 The Topology lines can be used to generate a graphic/pictorial 292 of the USB devices on a system's root hub. (See more below 293 on how to do this.) 294 295 The Interface lines can be used to determine what driver is 296 being used for each device, and which altsetting it activated. 297 298 The Configuration lines could be used to list maximum power 299 (in milliamps) that a system's USB devices are using. 300 For example, "grep ^C: /proc/bus/usb/devices". 301 302 303 Here's an example, from a system which has a UHCI root hub, 304 an external hub connected to the root hub, and a mouse and 305 a serial converter connected to the external hub. 306 307 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 308 B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 309 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 310 P: Vendor=0000 ProdID=0000 Rev= 0.00 311 S: Product=USB UHCI Root Hub 312 S: SerialNumber=dce0 313 C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA 314 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub 315 E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms 316 317 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 318 D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 319 P: Vendor=0451 ProdID=1446 Rev= 1.00 320 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA 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= 1 Ivl=255ms 323 324 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 325 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 326 P: Vendor=04b4 ProdID=0001 Rev= 0.00 327 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA 328 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse 329 E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms 330 331 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 332 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 333 P: Vendor=0565 ProdID=0001 Rev= 1.08 334 S: Manufacturer=Peracom Networks, Inc. 335 S: Product=Peracom USB to Serial Converter 336 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA 337 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial 338 E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms 339 E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms 340 E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms 341 342 343 Selecting only the "T:" and "I:" lines from this (for example, by using 344 "procusb ti"), we have: 345 346 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 347 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 348 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub 349 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 350 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse 351 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 352 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial 353 354 355 Physically 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 378 Or, in a more tree-like structure (ports [Connectors] without 379 connections could be omitted): 380 381 PC: 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 ###