blob: fafcd47232600a1a80351fcd5dfc79492e6ce8e9 [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
Phil Endecott9a9fafb82008-12-01 10:22:33 -050052configuration 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070056
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
Luiz Fernando N. Capitulino064e8752006-07-27 22:01:34 -030064source code (linux/drivers/usb/core/devio.c) is the primary reference
Linus Torvalds1da177e2005-04-16 15:20:36 -070065for 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).
Randy Dunlap5f980942005-09-08 21:56:56 -0700138
Linus Torvalds1da177e2005-04-16 15:20:36 -0700139 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
Randy Dunlap5f980942005-09-08 21:56:56 -0700202
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203 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
David Brownell2360e4a2006-12-13 13:07:10 -0800218I:* 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 " ")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700228|__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.
Randy Dunlap5f980942005-09-08 21:56:56 -0700234
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235 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
David Brownell2360e4a2006-12-13 13:07:10 -0800283being used for each device, and which altsetting it activated.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700284
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
Randy Dunlap5f980942005-09-08 21:56:56 -0700303
Linus Torvalds1da177e2005-04-16 15:20:36 -0700304T: 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
Randy Dunlap5f980942005-09-08 21:56:56 -0700310
Linus Torvalds1da177e2005-04-16 15:20:36 -0700311T: 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
Randy Dunlap5f980942005-09-08 21:56:56 -0700317
Linus Torvalds1da177e2005-04-16 15:20:36 -0700318T: 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 ###