blob: 98be91982677e89bef390162440c0a90a479eb46 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/proc/bus/usb filesystem output
2===============================
Alan Stern834e2312010-09-13 10:43:25 -04003(version 2010.09.13)
Linus Torvalds1da177e2005-04-16 15:20:36 -07004
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
Masanari Iida67748df2012-02-17 23:42:34 +090010In many modern systems the usbfs filesystem isn't used at all. Instead
Alan Stern834e2312010-09-13 10:43:25 -040011USB 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070015
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
Randy Dunlap5f980942005-09-08 21:56:56 -070028 USB device information, and user mode drivers can use usbfs
Linus Torvalds1da177e2005-04-16 15:20:36 -070029 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
39For more information on mounting the usbfs file system, see the
Randy Dunlap5f980942005-09-08 21:56:56 -070040"USB Device Filesystem" section of the USB Guide. The latest copy
Linus Torvalds1da177e2005-04-16 15:20:36 -070041of the USB Guide can be found at http://www.linux-usb.org/
42
43
44THE /proc/bus/usb/BBB/DDD FILES:
45--------------------------------
46Each connected USB device has one file. The BBB indicates the bus
47number. The DDD indicates the device address on that bus. Both
48of these numbers are assigned sequentially, and can be reused, so
49you can't rely on them for stable access to devices. For example,
50it's relatively common for devices to re-enumerate while they are
51still connected (perhaps someone jostled their power supply, hub,
52or USB cable), so a device might be 002/027 when you first connect
53it and 002/048 sometime later.
54
55These files can be read as binary data. The binary data consists
56of first the device descriptor, then the descriptors for each
Hans de Goede21a96312013-08-03 16:37:49 +020057configuration of the device. Multi-byte fields in the device descriptor
58are converted to host endianness by the kernel. The configuration
59descriptors are in bus endian format! The configuration descriptor
60are wTotalLength bytes apart. If a device returns less configuration
61descriptor data than indicated by wTotalLength there will be a hole in
62the file for the missing bytes. This information is also shown
Phil Endecott9a9fafb82008-12-01 10:22:33 -050063in text form by the /proc/bus/usb/devices file, described later.
Linus Torvalds1da177e2005-04-16 15:20:36 -070064
65These files may also be used to write user-level drivers for the USB
66devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
67read its descriptors to make sure it's the device you expect, and then
68bind to an interface (or perhaps several) using an ioctl call. You
69would issue more ioctls to the device to communicate to it using
70control, bulk, or other kinds of USB transfers. The IOCTLs are
71listed in the <linux/usbdevice_fs.h> file, and at this writing the
Luiz Fernando N. Capitulino064e8752006-07-27 22:01:34 -030072source code (linux/drivers/usb/core/devio.c) is the primary reference
Linus Torvalds1da177e2005-04-16 15:20:36 -070073for how to access devices through those files.
74
75Note that since by default these BBB/DDD files are writable only by
76root, only root can write such user mode drivers. You can selectively
77grant read/write permissions to other users by using "chmod". Also,
78usbfs mount options such as "devmode=0666" may be helpful.
79
80
81
82THE /proc/bus/usb/devices FILE:
83-------------------------------
84In /proc/bus/usb/devices, each device's output has multiple
85lines of ASCII output.
86I made it ASCII instead of binary on purpose, so that someone
87can obtain some useful data from it without the use of an
88auxiliary program. However, with an auxiliary program, the numbers
89in the first 4 columns of each "T:" line (topology info:
90Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
91
92Each line is tagged with a one-character ID for that line:
93
94T = Topology (etc.)
95B = Bandwidth (applies only to USB host controllers, which are
96 virtualized as root hubs)
97D = Device descriptor info.
98P = Product ID info. (from Device descriptor, but they won't fit
99 together on one line)
100S = String descriptors.
101C = Configuration descriptor info. (* = active configuration)
102I = Interface descriptor info.
103E = Endpoint descriptor info.
104
105=======================================================================
106
107/proc/bus/usb/devices output format:
108
109Legend:
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
115Topology info:
116
Alan Stern834e2312010-09-13 10:43:25 -0400117T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
118| | | | | | | | |__MaxChildren
Linus Torvalds1da177e2005-04-16 15:20:36 -0700119| | | | | | | |__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
Alan Stern834e2312010-09-13 10:43:25 -0400131 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)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700134
Alan Stern834e2312010-09-13 10:43:25 -0400135 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".
Linus Torvalds1da177e2005-04-16 15:20:36 -0700138
139Bandwidth info:
140B: 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).
Randy Dunlap5f980942005-09-08 21:56:56 -0700151
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152 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
158Device descriptor info & Product ID info:
159
160D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
161P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
162
163where
164D: 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
173where
174P: 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
181String descriptor info:
182
183S: 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
190S: 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
197S: 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
206Configuration descriptor info:
207
208C:* #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
Randy Dunlap5f980942005-09-08 21:56:56 -0700215
Linus Torvalds1da177e2005-04-16 15:20:36 -0700216 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
229Interface descriptor info (can be multiple per Config):
230
David Brownell2360e4a2006-12-13 13:07:10 -0800231I:* 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 " ")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700241|__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.
Randy Dunlap5f980942005-09-08 21:56:56 -0700247
Linus Torvalds1da177e2005-04-16 15:20:36 -0700248 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
253Endpoint descriptor info (can be multiple per Interface):
254
255E: 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
279If a user or script is interested only in Topology info, for
280example, use something like "grep ^T: /proc/bus/usb/devices"
281for only the Topology lines. A command like
282"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
283only the lines that begin with the characters in square brackets,
284where the valid characters are TDPCIE. With a slightly more able
285script, it can display any selected lines (for example, only T, D,
286and P lines) and change their output format. (The "procusb"
287Perl script is the beginning of this idea. It will list only
288selected lines [selected from TBDPSCIE] or "All" lines from
289/proc/bus/usb/devices.)
290
291The Topology lines can be used to generate a graphic/pictorial
292of the USB devices on a system's root hub. (See more below
293on how to do this.)
294
295The Interface lines can be used to determine what driver is
David Brownell2360e4a2006-12-13 13:07:10 -0800296being used for each device, and which altsetting it activated.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700297
298The Configuration lines could be used to list maximum power
299(in milliamps) that a system's USB devices are using.
300For example, "grep ^C: /proc/bus/usb/devices".
301
302
303Here's an example, from a system which has a UHCI root hub,
304an external hub connected to the root hub, and a mouse and
305a serial converter connected to the external hub.
306
Alan Stern834e2312010-09-13 10:43:25 -0400307T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
309D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
310P: Vendor=0000 ProdID=0000 Rev= 0.00
311S: Product=USB UHCI Root Hub
312S: SerialNumber=dce0
313C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
314I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
315E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700316
Alan Stern834e2312010-09-13 10:43:25 -0400317T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
Linus Torvalds1da177e2005-04-16 15:20:36 -0700318D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
319P: Vendor=0451 ProdID=1446 Rev= 1.00
320C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
321I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
322E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700323
Alan Stern834e2312010-09-13 10:43:25 -0400324T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700325D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
326P: Vendor=04b4 ProdID=0001 Rev= 0.00
327C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
328I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
329E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700330
Alan Stern834e2312010-09-13 10:43:25 -0400331T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700332D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
333P: Vendor=0565 ProdID=0001 Rev= 1.08
334S: Manufacturer=Peracom Networks, Inc.
335S: Product=Peracom USB to Serial Converter
336C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
337I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
338E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
339E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
340E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
341
342
343Selecting only the "T:" and "I:" lines from this (for example, by using
344"procusb ti"), we have:
345
Alan Stern834e2312010-09-13 10:43:25 -0400346T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
347T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
Linus Torvalds1da177e2005-04-16 15:20:36 -0700348I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
Alan Stern834e2312010-09-13 10:43:25 -0400349T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700350I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
Alan Stern834e2312010-09-13 10:43:25 -0400351T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700352I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
353
354
355Physically 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
378Or, in a more tree-like structure (ports [Connectors] without
379connections could be omitted):
380
381PC: 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 ###