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