About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / proc_usb_info.txt

Based on kernel version 2.6.26. Page generated on 2008-07-16 21:13 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.