Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | |
5f980948 | 23 | USB device information, and user mode drivers can use usbfs |
1da177e4 LT |
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 | |
5f980948 | 35 | "USB Device Filesystem" section of the USB Guide. The latest copy |
1da177e4 LT |
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/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). | |
5f980948 | 136 | |
1da177e4 LT |
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 | |
5f980948 | 200 | |
1da177e4 LT |
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 | |__Interface info tag | |
226 | ||
227 | A given interface may have one or more "alternate" settings. | |
228 | For example, default settings may not use more than a small | |
229 | amount of periodic bandwidth. To use significant fractions | |
230 | of bus bandwidth, drivers must select a non-default altsetting. | |
5f980948 | 231 | |
1da177e4 LT |
232 | Only one setting for an interface may be active at a time, and |
233 | only one driver may bind to an interface at a time. Most devices | |
234 | have only one alternate setting per interface. | |
235 | ||
236 | ||
237 | Endpoint descriptor info (can be multiple per Interface): | |
238 | ||
239 | E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss | |
240 | | | | | |__Interval (max) between transfers | |
241 | | | | |__EndpointMaxPacketSize | |
242 | | | |__Attributes(EndpointType) | |
243 | | |__EndpointAddress(I=In,O=Out) | |
244 | |__Endpoint info tag | |
245 | ||
246 | The interval is nonzero for all periodic (interrupt or isochronous) | |
247 | endpoints. For high speed endpoints the transfer interval may be | |
248 | measured in microseconds rather than milliseconds. | |
249 | ||
250 | For high speed periodic endpoints, the "MaxPacketSize" reflects | |
251 | the per-microframe data transfer size. For "high bandwidth" | |
252 | endpoints, that can reflect two or three packets (for up to | |
253 | 3KBytes every 125 usec) per endpoint. | |
254 | ||
255 | With the Linux-USB stack, periodic bandwidth reservations use the | |
256 | transfer intervals and sizes provided by URBs, which can be less | |
257 | than those found in endpoint descriptor. | |
258 | ||
259 | ||
260 | ======================================================================= | |
261 | ||
262 | ||
263 | If a user or script is interested only in Topology info, for | |
264 | example, use something like "grep ^T: /proc/bus/usb/devices" | |
265 | for only the Topology lines. A command like | |
266 | "grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list | |
267 | only the lines that begin with the characters in square brackets, | |
268 | where the valid characters are TDPCIE. With a slightly more able | |
269 | script, it can display any selected lines (for example, only T, D, | |
270 | and P lines) and change their output format. (The "procusb" | |
271 | Perl script is the beginning of this idea. It will list only | |
272 | selected lines [selected from TBDPSCIE] or "All" lines from | |
273 | /proc/bus/usb/devices.) | |
274 | ||
275 | The Topology lines can be used to generate a graphic/pictorial | |
276 | of the USB devices on a system's root hub. (See more below | |
277 | on how to do this.) | |
278 | ||
279 | The Interface lines can be used to determine what driver is | |
280 | being used for each device. | |
281 | ||
282 | The Configuration lines could be used to list maximum power | |
283 | (in milliamps) that a system's USB devices are using. | |
284 | For example, "grep ^C: /proc/bus/usb/devices". | |
285 | ||
286 | ||
287 | Here's an example, from a system which has a UHCI root hub, | |
288 | an external hub connected to the root hub, and a mouse and | |
289 | a serial converter connected to the external hub. | |
290 | ||
291 | T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 | |
292 | B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 | |
293 | D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
294 | P: Vendor=0000 ProdID=0000 Rev= 0.00 | |
295 | S: Product=USB UHCI Root Hub | |
296 | S: SerialNumber=dce0 | |
297 | C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA | |
298 | I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub | |
299 | E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms | |
5f980948 | 300 | |
1da177e4 LT |
301 | T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 |
302 | D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
303 | P: Vendor=0451 ProdID=1446 Rev= 1.00 | |
304 | C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA | |
305 | I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub | |
306 | E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms | |
5f980948 | 307 | |
1da177e4 LT |
308 | T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 |
309 | D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
310 | P: Vendor=04b4 ProdID=0001 Rev= 0.00 | |
311 | C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA | |
312 | I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse | |
313 | E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms | |
5f980948 | 314 | |
1da177e4 LT |
315 | T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 |
316 | D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
317 | P: Vendor=0565 ProdID=0001 Rev= 1.08 | |
318 | S: Manufacturer=Peracom Networks, Inc. | |
319 | S: Product=Peracom USB to Serial Converter | |
320 | C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA | |
321 | I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial | |
322 | E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms | |
323 | E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms | |
324 | E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms | |
325 | ||
326 | ||
327 | Selecting only the "T:" and "I:" lines from this (for example, by using | |
328 | "procusb ti"), we have: | |
329 | ||
330 | T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 | |
331 | T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 | |
332 | I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub | |
333 | T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 | |
334 | I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse | |
335 | T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 | |
336 | I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial | |
337 | ||
338 | ||
339 | Physically this looks like (or could be converted to): | |
340 | ||
341 | +------------------+ | |
342 | | PC/root_hub (12)| Dev# = 1 | |
343 | +------------------+ (nn) is Mbps. | |
344 | Level 0 | CN.0 | CN.1 | [CN = connector/port #] | |
345 | +------------------+ | |
346 | / | |
347 | / | |
348 | +-----------------------+ | |
349 | Level 1 | Dev#2: 4-port hub (12)| | |
350 | +-----------------------+ | |
351 | |CN.0 |CN.1 |CN.2 |CN.3 | | |
352 | +-----------------------+ | |
353 | \ \____________________ | |
354 | \_____ \ | |
355 | \ \ | |
356 | +--------------------+ +--------------------+ | |
357 | Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)| | |
358 | +--------------------+ +--------------------+ | |
359 | ||
360 | ||
361 | ||
362 | Or, in a more tree-like structure (ports [Connectors] without | |
363 | connections could be omitted): | |
364 | ||
365 | PC: Dev# 1, root hub, 2 ports, 12 Mbps | |
366 | |_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps | |
367 | |_ CN.0: Dev #3, mouse, 1.5 Mbps | |
368 | |_ CN.1: | |
369 | |_ CN.2: Dev #4, serial, 12 Mbps | |
370 | |_ CN.3: | |
371 | |_ CN.1: | |
372 | ||
373 | ||
374 | ### END ### |