blob: 22c5331260ca05bb17be0c647a7d98d595ce0cd7 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/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
Randy Dunlap5f980942005-09-08 21:56:56 -070023 USB device information, and user mode drivers can use usbfs
Linus Torvalds1da177e2005-04-16 15:20:36 -070024 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
Randy Dunlap5f980942005-09-08 21:56:56 -070035"USB Device Filesystem" section of the USB Guide. The latest copy
Linus Torvalds1da177e2005-04-16 15:20:36 -070036of 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. That information is also shown in
53text form by the /proc/bus/usb/devices file, described later.
54
55These files may also be used to write user-level drivers for the USB
56devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
57read its descriptors to make sure it's the device you expect, and then
58bind to an interface (or perhaps several) using an ioctl call. You
59would issue more ioctls to the device to communicate to it using
60control, bulk, or other kinds of USB transfers. The IOCTLs are
61listed in the <linux/usbdevice_fs.h> file, and at this writing the
Luiz Fernando N. Capitulino064e8752006-07-27 22:01:34 -030062source code (linux/drivers/usb/core/devio.c) is the primary reference
Linus Torvalds1da177e2005-04-16 15:20:36 -070063for how to access devices through those files.
64
65Note that since by default these BBB/DDD files are writable only by
66root, only root can write such user mode drivers. You can selectively
67grant read/write permissions to other users by using "chmod". Also,
68usbfs mount options such as "devmode=0666" may be helpful.
69
70
71
72THE /proc/bus/usb/devices FILE:
73-------------------------------
74In /proc/bus/usb/devices, each device's output has multiple
75lines of ASCII output.
76I made it ASCII instead of binary on purpose, so that someone
77can obtain some useful data from it without the use of an
78auxiliary program. However, with an auxiliary program, the numbers
79in the first 4 columns of each "T:" line (topology info:
80Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
81
82Each line is tagged with a one-character ID for that line:
83
84T = Topology (etc.)
85B = Bandwidth (applies only to USB host controllers, which are
86 virtualized as root hubs)
87D = Device descriptor info.
88P = Product ID info. (from Device descriptor, but they won't fit
89 together on one line)
90S = String descriptors.
91C = Configuration descriptor info. (* = active configuration)
92I = Interface descriptor info.
93E = Endpoint descriptor info.
94
95=======================================================================
96
97/proc/bus/usb/devices output format:
98
99Legend:
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
105Topology info:
106
107T: 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
124Bandwidth info:
125B: 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).
Randy Dunlap5f980942005-09-08 21:56:56 -0700136
Linus Torvalds1da177e2005-04-16 15:20:36 -0700137 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
143Device descriptor info & Product ID info:
144
145D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
146P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
147
148where
149D: 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
158where
159P: 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
166String descriptor info:
167
168S: 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
175S: 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
182S: 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
191Configuration descriptor info:
192
193C:* #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
Randy Dunlap5f980942005-09-08 21:56:56 -0700200
Linus Torvalds1da177e2005-04-16 15:20:36 -0700201 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
214Interface descriptor info (can be multiple per Config):
215
216I: 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.
Randy Dunlap5f980942005-09-08 21:56:56 -0700231
Linus Torvalds1da177e2005-04-16 15:20:36 -0700232 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
237Endpoint descriptor info (can be multiple per Interface):
238
239E: 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
263If a user or script is interested only in Topology info, for
264example, use something like "grep ^T: /proc/bus/usb/devices"
265for only the Topology lines. A command like
266"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
267only the lines that begin with the characters in square brackets,
268where the valid characters are TDPCIE. With a slightly more able
269script, it can display any selected lines (for example, only T, D,
270and P lines) and change their output format. (The "procusb"
271Perl script is the beginning of this idea. It will list only
272selected lines [selected from TBDPSCIE] or "All" lines from
273/proc/bus/usb/devices.)
274
275The Topology lines can be used to generate a graphic/pictorial
276of the USB devices on a system's root hub. (See more below
277on how to do this.)
278
279The Interface lines can be used to determine what driver is
280being used for each device.
281
282The Configuration lines could be used to list maximum power
283(in milliamps) that a system's USB devices are using.
284For example, "grep ^C: /proc/bus/usb/devices".
285
286
287Here's an example, from a system which has a UHCI root hub,
288an external hub connected to the root hub, and a mouse and
289a serial converter connected to the external hub.
290
291T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
292B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
293D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
294P: Vendor=0000 ProdID=0000 Rev= 0.00
295S: Product=USB UHCI Root Hub
296S: SerialNumber=dce0
297C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
298I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
299E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700300
Linus Torvalds1da177e2005-04-16 15:20:36 -0700301T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
302D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
303P: Vendor=0451 ProdID=1446 Rev= 1.00
304C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
305I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
306E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700307
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
309D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
310P: Vendor=04b4 ProdID=0001 Rev= 0.00
311C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
312I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
313E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700314
Linus Torvalds1da177e2005-04-16 15:20:36 -0700315T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
316D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
317P: Vendor=0565 ProdID=0001 Rev= 1.08
318S: Manufacturer=Peracom Networks, Inc.
319S: Product=Peracom USB to Serial Converter
320C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
321I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
322E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
323E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
324E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
325
326
327Selecting only the "T:" and "I:" lines from this (for example, by using
328"procusb ti"), we have:
329
330T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
331T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
332I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
333T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
334I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
335T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
336I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
337
338
339Physically 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
362Or, in a more tree-like structure (ports [Connectors] without
363connections could be omitted):
364
365PC: 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 ###