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