About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / proc_usb_info.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:15 EST.

1	/proc/bus/usb filesystem output
2	===============================
3	(version 2010.09.13)
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	In many modern systems the usbfs filesystem isn't used at all.  Instead
11	USB device nodes are created under /dev/usb/ or someplace similar.  The
12	"devices" file is available in debugfs, typically as
13	/sys/kernel/debug/usb/devices.
14	
15	
16	**NOTE**: If /proc/bus/usb appears empty, and a host controller
17		  driver has been linked, then you need to mount the
18		  filesystem.  Issue the command (as root):
19	
20	      mount -t usbfs none /proc/bus/usb
21	
22		  An alternative and more permanent method would be to add
23	
24	      none  /proc/bus/usb  usbfs  defaults  0  0
25	
26		  to /etc/fstab.  This will mount usbfs at each reboot.
27		  You can then issue `cat /proc/bus/usb/devices` to extract
28		  USB device information, and user mode drivers can use usbfs
29		  to interact with USB devices.
30	
31		  There are a number of mount options supported by usbfs.
32		  Consult the source code (linux/drivers/usb/core/inode.c) for
33		  information about those options.
34	
35	**NOTE**: The filesystem has been renamed from "usbdevfs" to
36		  "usbfs", to reduce confusion with "devfs".  You may
37		  still see references to the older "usbdevfs" name.
38	
39	For more information on mounting the usbfs file system, see the
40	"USB Device Filesystem" section of the USB Guide. The latest copy
41	of the USB Guide can be found at http://www.linux-usb.org/
42	
43	
44	THE /proc/bus/usb/BBB/DDD FILES:
45	--------------------------------
46	Each connected USB device has one file.  The BBB indicates the bus
47	number.  The DDD indicates the device address on that bus.  Both
48	of these numbers are assigned sequentially, and can be reused, so
49	you can't rely on them for stable access to devices.  For example,
50	it's relatively common for devices to re-enumerate while they are
51	still connected (perhaps someone jostled their power supply, hub,
52	or USB cable), so a device might be 002/027 when you first connect
53	it and 002/048 sometime later.
54	
55	These files can be read as binary data.  The binary data consists
56	of first the device descriptor, then the descriptors for each
57	configuration of the device.  Multi-byte fields in the device and
58	configuration descriptors, but not other descriptors, are converted
59	to host endianness by the kernel.  This information is also shown
60	in text form by the /proc/bus/usb/devices file, described later.
61	
62	These files may also be used to write user-level drivers for the USB
63	devices.  You would open the /proc/bus/usb/BBB/DDD file read/write,
64	read its descriptors to make sure it's the device you expect, and then
65	bind to an interface (or perhaps several) using an ioctl call.  You
66	would issue more ioctls to the device to communicate to it using
67	control, bulk, or other kinds of USB transfers.  The IOCTLs are
68	listed in the <linux/usbdevice_fs.h> file, and at this writing the
69	source code (linux/drivers/usb/core/devio.c) is the primary reference
70	for how to access devices through those files.
71	
72	Note that since by default these BBB/DDD files are writable only by
73	root, only root can write such user mode drivers.  You can selectively
74	grant read/write permissions to other users by using "chmod".  Also,
75	usbfs mount options such as "devmode=0666" may be helpful.
76	
77	
78	
79	THE /proc/bus/usb/devices FILE:
80	-------------------------------
81	In /proc/bus/usb/devices, each device's output has multiple
82	lines of ASCII output.
83	I made it ASCII instead of binary on purpose, so that someone
84	can obtain some useful data from it without the use of an
85	auxiliary program.  However, with an auxiliary program, the numbers
86	in the first 4 columns of each "T:" line (topology info:
87	Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
88	
89	Each line is tagged with a one-character ID for that line:
90	
91	T = Topology (etc.)
92	B = Bandwidth (applies only to USB host controllers, which are
93	    virtualized as root hubs)
94	D = Device descriptor info.
95	P = Product ID info. (from Device descriptor, but they won't fit
96	    together on one line)
97	S = String descriptors.
98	C = Configuration descriptor info. (* = active configuration)
99	I = Interface descriptor info.
100	E = Endpoint descriptor info.
101	
102	=======================================================================
103	
104	/proc/bus/usb/devices output format:
105	
106	Legend:
107	  d = decimal number (may have leading spaces or 0's)
108	  x = hexadecimal number (may have leading spaces or 0's)
109	  s = string
110	
111	
112	Topology info:
113	
114	T:  Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
115	|   |      |      |       |       |      |        |        |__MaxChildren
116	|   |      |      |       |       |      |        |__Device Speed in Mbps
117	|   |      |      |       |       |      |__DeviceNumber
118	|   |      |      |       |       |__Count of devices at this level
119	|   |      |      |       |__Connector/Port on Parent for this device
120	|   |      |      |__Parent DeviceNumber
121	|   |      |__Level in topology for this bus
122	|   |__Bus number
123	|__Topology info tag
124	
125	    Speed may be:
126	    	1.5	Mbit/s for low speed USB
127		12	Mbit/s for full speed USB
128		480	Mbit/s for high speed USB (added for USB 2.0);
129			  also used for Wireless USB, which has no fixed speed
130		5000	Mbit/s for SuperSpeed USB (added for USB 3.0)
131	
132	    For reasons lost in the mists of time, the Port number is always
133	    too low by 1.  For example, a device plugged into port 4 will
134	    show up with "Port=03".
135	
136	Bandwidth info:
137	B:  Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
138	|   |                       |         |__Number of isochronous requests
139	|   |                       |__Number of interrupt requests
140	|   |__Total Bandwidth allocated to this bus
141	|__Bandwidth info tag
142	
143	    Bandwidth allocation is an approximation of how much of one frame
144	    (millisecond) is in use.  It reflects only periodic transfers, which
145	    are the only transfers that reserve bandwidth.  Control and bulk
146	    transfers use all other bandwidth, including reserved bandwidth that
147	    is not used for transfers (such as for short packets).
148	
149	    The percentage is how much of the "reserved" bandwidth is scheduled by
150	    those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
151	    90% of the bus bandwidth is reserved.  For a high speed bus (loosely,
152	    "USB 2.0") 80% is reserved.
153	
154	
155	Device descriptor info & Product ID info:
156	
157	D:  Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
158	P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
159	
160	where
161	D:  Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
162	|   |        |             |      |       |       |__NumberConfigurations
163	|   |        |             |      |       |__MaxPacketSize of Default Endpoint
164	|   |        |             |      |__DeviceProtocol
165	|   |        |             |__DeviceSubClass
166	|   |        |__DeviceClass
167	|   |__Device USB version
168	|__Device info tag #1
169	
170	where
171	P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
172	|   |           |           |__Product revision number
173	|   |           |__Product ID code
174	|   |__Vendor ID code
175	|__Device info tag #2
176	
177	
178	String descriptor info:
179	
180	S:  Manufacturer=ssss
181	|   |__Manufacturer of this device as read from the device.
182	|      For USB host controller drivers (virtual root hubs) this may
183	|      be omitted, or (for newer drivers) will identify the kernel
184	|      version and the driver which provides this hub emulation.
185	|__String info tag
186	
187	S:  Product=ssss
188	|   |__Product description of this device as read from the device.
189	|      For older USB host controller drivers (virtual root hubs) this
190	|      indicates the driver; for newer ones, it's a product (and vendor)
191	|      description that often comes from the kernel's PCI ID database.
192	|__String info tag
193	
194	S:  SerialNumber=ssss
195	|   |__Serial Number of this device as read from the device.
196	|      For USB host controller drivers (virtual root hubs) this is
197	|      some unique ID, normally a bus ID (address or slot name) that
198	|      can't be shared with any other device.
199	|__String info tag
200	
201	
202	
203	Configuration descriptor info:
204	
205	C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
206	| | |       |       |      |__MaxPower in mA
207	| | |       |       |__Attributes
208	| | |       |__ConfiguratioNumber
209	| | |__NumberOfInterfaces
210	| |__ "*" indicates the active configuration (others are " ")
211	|__Config info tag
212	
213	    USB devices may have multiple configurations, each of which act
214	    rather differently.  For example, a bus-powered configuration
215	    might be much less capable than one that is self-powered.  Only
216	    one device configuration can be active at a time; most devices
217	    have only one configuration.
218	
219	    Each configuration consists of one or more interfaces.  Each
220	    interface serves a distinct "function", which is typically bound
221	    to a different USB device driver.  One common example is a USB
222	    speaker with an audio interface for playback, and a HID interface
223	    for use with software volume control.
224	
225	
226	Interface descriptor info (can be multiple per Config):
227	
228	I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
229	| | |      |      |       |             |      |       |__Driver name
230	| | |      |      |       |             |      |          or "(none)"
231	| | |      |      |       |             |      |__InterfaceProtocol
232	| | |      |      |       |             |__InterfaceSubClass
233	| | |      |      |       |__InterfaceClass
234	| | |      |      |__NumberOfEndpoints
235	| | |      |__AlternateSettingNumber
236	| | |__InterfaceNumber
237	| |__ "*" indicates the active altsetting (others are " ")
238	|__Interface info tag
239	
240	    A given interface may have one or more "alternate" settings.
241	    For example, default settings may not use more than a small
242	    amount of periodic bandwidth.  To use significant fractions
243	    of bus bandwidth, drivers must select a non-default altsetting.
244	
245	    Only one setting for an interface may be active at a time, and
246	    only one driver may bind to an interface at a time.  Most devices
247	    have only one alternate setting per interface.
248	
249	
250	Endpoint descriptor info (can be multiple per Interface):
251	
252	E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
253	|   |        |            |         |__Interval (max) between transfers
254	|   |        |            |__EndpointMaxPacketSize
255	|   |        |__Attributes(EndpointType)
256	|   |__EndpointAddress(I=In,O=Out)
257	|__Endpoint info tag
258	
259	    The interval is nonzero for all periodic (interrupt or isochronous)
260	    endpoints.  For high speed endpoints the transfer interval may be
261	    measured in microseconds rather than milliseconds.
262	
263	    For high speed periodic endpoints, the "MaxPacketSize" reflects
264	    the per-microframe data transfer size.  For "high bandwidth"
265	    endpoints, that can reflect two or three packets (for up to
266	    3KBytes every 125 usec) per endpoint.
267	
268	    With the Linux-USB stack, periodic bandwidth reservations use the
269	    transfer intervals and sizes provided by URBs, which can be less
270	    than those found in endpoint descriptor.
271	
272	
273	=======================================================================
274	
275	
276	If a user or script is interested only in Topology info, for
277	example, use something like "grep ^T: /proc/bus/usb/devices"
278	for only the Topology lines.  A command like
279	"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
280	only the lines that begin with the characters in square brackets,
281	where the valid characters are TDPCIE.  With a slightly more able
282	script, it can display any selected lines (for example, only T, D,
283	and P lines) and change their output format.  (The "procusb"
284	Perl script is the beginning of this idea.  It will list only
285	selected lines [selected from TBDPSCIE] or "All" lines from
286	/proc/bus/usb/devices.)
287	
288	The Topology lines can be used to generate a graphic/pictorial
289	of the USB devices on a system's root hub.  (See more below
290	on how to do this.)
291	
292	The Interface lines can be used to determine what driver is
293	being used for each device, and which altsetting it activated.
294	
295	The Configuration lines could be used to list maximum power
296	(in milliamps) that a system's USB devices are using.
297	For example, "grep ^C: /proc/bus/usb/devices".
298	
299	
300	Here's an example, from a system which has a UHCI root hub,
301	an external hub connected to the root hub, and a mouse and
302	a serial converter connected to the external hub.
303	
304	T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12   MxCh= 2
305	B:  Alloc= 28/900 us ( 3%), #Int=  2, #Iso=  0
306	D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
307	P:  Vendor=0000 ProdID=0000 Rev= 0.00
308	S:  Product=USB UHCI Root Hub
309	S:  SerialNumber=dce0
310	C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
311	I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
312	E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
313	
314	T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12   MxCh= 4
315	D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
316	P:  Vendor=0451 ProdID=1446 Rev= 1.00
317	C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
318	I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
319	E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms
320	
321	T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5  MxCh= 0
322	D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
323	P:  Vendor=04b4 ProdID=0001 Rev= 0.00
324	C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
325	I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
326	E:  Ad=81(I) Atr=03(Int.) MxPS=   3 Ivl= 10ms
327	
328	T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12   MxCh= 0
329	D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
330	P:  Vendor=0565 ProdID=0001 Rev= 1.08
331	S:  Manufacturer=Peracom Networks, Inc.
332	S:  Product=Peracom USB to Serial Converter
333	C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
334	I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
335	E:  Ad=81(I) Atr=02(Bulk) MxPS=  64 Ivl= 16ms
336	E:  Ad=01(O) Atr=02(Bulk) MxPS=  16 Ivl= 16ms
337	E:  Ad=82(I) Atr=03(Int.) MxPS=   8 Ivl=  8ms
338	
339	
340	Selecting only the "T:" and "I:" lines from this (for example, by using
341	"procusb ti"), we have:
342	
343	T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12   MxCh= 2
344	T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12   MxCh= 4
345	I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
346	T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5  MxCh= 0
347	I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
348	T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12   MxCh= 0
349	I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
350	
351	
352	Physically this looks like (or could be converted to):
353	
354	                      +------------------+
355	                      |  PC/root_hub (12)|   Dev# = 1
356	                      +------------------+   (nn) is Mbps.
357	    Level 0           |  CN.0   |  CN.1  |   [CN = connector/port #]
358	                      +------------------+
359	                          /
360	                         /
361	            +-----------------------+
362	  Level 1   | Dev#2: 4-port hub (12)|
363	            +-----------------------+
364	            |CN.0 |CN.1 |CN.2 |CN.3 |
365	            +-----------------------+
366	                \           \____________________
367	                 \_____                          \
368	                       \                          \
369	               +--------------------+      +--------------------+
370	  Level 2      | Dev# 3: mouse (1.5)|      | Dev# 4: serial (12)|
371	               +--------------------+      +--------------------+
372	
373	
374	
375	Or, in a more tree-like structure (ports [Connectors] without
376	connections could be omitted):
377	
378	PC:  Dev# 1, root hub, 2 ports, 12 Mbps
379	|_ CN.0:  Dev# 2, hub, 4 ports, 12 Mbps
380	     |_ CN.0:  Dev #3, mouse, 1.5 Mbps
381	     |_ CN.1:
382	     |_ CN.2:  Dev #4, serial, 12 Mbps
383	     |_ CN.3:
384	|_ CN.1:
385	
386	
387	                         ### 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.