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