blob: afe596d5f201bfa4b7fc5a504a48bd020aaeeca1 [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
Alan Stern834e2312010-09-13 10:43:25 -040010In many modern systems the usbfs filsystem isn't used at all. Instead
11USB 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
Phil Endecott9a9fafb82008-12-01 10:22:33 -050057configuration of the device. Multi-byte fields in the device and
58configuration descriptors, but not other descriptors, are converted
59to host endianness by the kernel. This information is also shown
60in text form by the /proc/bus/usb/devices file, described later.
Linus Torvalds1da177e2005-04-16 15:20:36 -070061
62These files may also be used to write user-level drivers for the USB
63devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
64read its descriptors to make sure it's the device you expect, and then
65bind to an interface (or perhaps several) using an ioctl call. You
66would issue more ioctls to the device to communicate to it using
67control, bulk, or other kinds of USB transfers. The IOCTLs are
68listed in the <linux/usbdevice_fs.h> file, and at this writing the
Luiz Fernando N. Capitulino064e8752006-07-27 22:01:34 -030069source code (linux/drivers/usb/core/devio.c) is the primary reference
Linus Torvalds1da177e2005-04-16 15:20:36 -070070for how to access devices through those files.
71
72Note that since by default these BBB/DDD files are writable only by
73root, only root can write such user mode drivers. You can selectively
74grant read/write permissions to other users by using "chmod". Also,
75usbfs mount options such as "devmode=0666" may be helpful.
76
77
78
79THE /proc/bus/usb/devices FILE:
80-------------------------------
81In /proc/bus/usb/devices, each device's output has multiple
82lines of ASCII output.
83I made it ASCII instead of binary on purpose, so that someone
84can obtain some useful data from it without the use of an
85auxiliary program. However, with an auxiliary program, the numbers
86in the first 4 columns of each "T:" line (topology info:
87Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
88
89Each line is tagged with a one-character ID for that line:
90
91T = Topology (etc.)
92B = Bandwidth (applies only to USB host controllers, which are
93 virtualized as root hubs)
94D = Device descriptor info.
95P = Product ID info. (from Device descriptor, but they won't fit
96 together on one line)
97S = String descriptors.
98C = Configuration descriptor info. (* = active configuration)
99I = Interface descriptor info.
100E = Endpoint descriptor info.
101
102=======================================================================
103
104/proc/bus/usb/devices output format:
105
106Legend:
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
112Topology info:
113
Alan Stern834e2312010-09-13 10:43:25 -0400114T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
115| | | | | | | | |__MaxChildren
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116| | | | | | | |__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
Alan Stern834e2312010-09-13 10:43:25 -0400128 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)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700131
Alan Stern834e2312010-09-13 10:43:25 -0400132 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".
Linus Torvalds1da177e2005-04-16 15:20:36 -0700135
136Bandwidth info:
137B: 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).
Randy Dunlap5f980942005-09-08 21:56:56 -0700148
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149 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
155Device descriptor info & Product ID info:
156
157D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
158P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
159
160where
161D: 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
170where
171P: 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
178String descriptor info:
179
180S: 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
187S: 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
194S: 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
203Configuration descriptor info:
204
205C:* #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
Randy Dunlap5f980942005-09-08 21:56:56 -0700212
Linus Torvalds1da177e2005-04-16 15:20:36 -0700213 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
226Interface descriptor info (can be multiple per Config):
227
David Brownell2360e4a2006-12-13 13:07:10 -0800228I:* 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 " ")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238|__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.
Randy Dunlap5f980942005-09-08 21:56:56 -0700244
Linus Torvalds1da177e2005-04-16 15:20:36 -0700245 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
250Endpoint descriptor info (can be multiple per Interface):
251
252E: 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
276If a user or script is interested only in Topology info, for
277example, use something like "grep ^T: /proc/bus/usb/devices"
278for only the Topology lines. A command like
279"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
280only the lines that begin with the characters in square brackets,
281where the valid characters are TDPCIE. With a slightly more able
282script, it can display any selected lines (for example, only T, D,
283and P lines) and change their output format. (The "procusb"
284Perl script is the beginning of this idea. It will list only
285selected lines [selected from TBDPSCIE] or "All" lines from
286/proc/bus/usb/devices.)
287
288The Topology lines can be used to generate a graphic/pictorial
289of the USB devices on a system's root hub. (See more below
290on how to do this.)
291
292The Interface lines can be used to determine what driver is
David Brownell2360e4a2006-12-13 13:07:10 -0800293being used for each device, and which altsetting it activated.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700294
295The Configuration lines could be used to list maximum power
296(in milliamps) that a system's USB devices are using.
297For example, "grep ^C: /proc/bus/usb/devices".
298
299
300Here's an example, from a system which has a UHCI root hub,
301an external hub connected to the root hub, and a mouse and
302a serial converter connected to the external hub.
303
Alan Stern834e2312010-09-13 10:43:25 -0400304T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
Linus Torvalds1da177e2005-04-16 15:20:36 -0700305B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
306D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
307P: Vendor=0000 ProdID=0000 Rev= 0.00
308S: Product=USB UHCI Root Hub
309S: SerialNumber=dce0
310C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
311I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
312E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700313
Alan Stern834e2312010-09-13 10:43:25 -0400314T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
Linus Torvalds1da177e2005-04-16 15:20:36 -0700315D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
316P: Vendor=0451 ProdID=1446 Rev= 1.00
317C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
318I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
319E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700320
Alan Stern834e2312010-09-13 10:43:25 -0400321T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700322D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
323P: Vendor=04b4 ProdID=0001 Rev= 0.00
324C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
325I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
326E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
Randy Dunlap5f980942005-09-08 21:56:56 -0700327
Alan Stern834e2312010-09-13 10:43:25 -0400328T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700329D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
330P: Vendor=0565 ProdID=0001 Rev= 1.08
331S: Manufacturer=Peracom Networks, Inc.
332S: Product=Peracom USB to Serial Converter
333C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
334I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
335E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
336E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
337E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
338
339
340Selecting only the "T:" and "I:" lines from this (for example, by using
341"procusb ti"), we have:
342
Alan Stern834e2312010-09-13 10:43:25 -0400343T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
344T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
Linus Torvalds1da177e2005-04-16 15:20:36 -0700345I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
Alan Stern834e2312010-09-13 10:43:25 -0400346T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700347I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
Alan Stern834e2312010-09-13 10:43:25 -0400348T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700349I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
350
351
352Physically 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
375Or, in a more tree-like structure (ports [Connectors] without
376connections could be omitted):
377
378PC: 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 ###