About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / proc_usb_info.txt


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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog