[linux-2.6-block.git] / Documentation / usb / proc_usb_info.txt

/proc/bus/usb filesystem output
===============================
(version 2003.05.30)


The usbfs filesystem for USB devices is traditionally mounted at
/proc/bus/usb.  It provides the /proc/bus/usb/devices file, as well as
the /proc/bus/usb/BBB/DDD files.


**NOTE**: If /proc/bus/usb appears empty, and a host controller
	  driver has been linked, then you need to mount the
	  filesystem.  Issue the command (as root):

      mount -t usbfs none /proc/bus/usb

	  An alternative and more permanent method would be to add

      none  /proc/bus/usb  usbfs  defaults  0  0

	  to /etc/fstab.  This will mount usbfs at each reboot.
	  You can then issue `cat /proc/bus/usb/devices` to extract
	  USB device information, and user mode drivers can use usbfs
	  to interact with USB devices.

	  There are a number of mount options supported by usbfs.
	  Consult the source code (linux/drivers/usb/core/inode.c) for
	  information about those options.

**NOTE**: The filesystem has been renamed from "usbdevfs" to
	  "usbfs", to reduce confusion with "devfs".  You may
	  still see references to the older "usbdevfs" name.

For more information on mounting the usbfs file system, see the
"USB Device Filesystem" section of the USB Guide. The latest copy
of the USB Guide can be found at http://www.linux-usb.org/


THE /proc/bus/usb/BBB/DDD FILES:
--------------------------------
Each connected USB device has one file.  The BBB indicates the bus
number.  The DDD indicates the device address on that bus.  Both
of these numbers are assigned sequentially, and can be reused, so
you can't rely on them for stable access to devices.  For example,
it's relatively common for devices to re-enumerate while they are
still connected (perhaps someone jostled their power supply, hub,
or USB cable), so a device might be 002/027 when you first connect
it and 002/048 sometime later.

These files can be read as binary data.  The binary data consists
of first the device descriptor, then the descriptors for each
configuration of the device.  Multi-byte fields in the device and
configuration descriptors, but not other descriptors, are converted
to host endianness by the kernel.  This information is also shown
in text form by the /proc/bus/usb/devices file, described later.

These files may also be used to write user-level drivers for the USB
devices.  You would open the /proc/bus/usb/BBB/DDD file read/write,
read its descriptors to make sure it's the device you expect, and then
bind to an interface (or perhaps several) using an ioctl call.  You
would issue more ioctls to the device to communicate to it using
control, bulk, or other kinds of USB transfers.  The IOCTLs are
listed in the <linux/usbdevice_fs.h> file, and at this writing the
source code (linux/drivers/usb/core/devio.c) is the primary reference
for how to access devices through those files.

Note that since by default these BBB/DDD files are writable only by
root, only root can write such user mode drivers.  You can selectively
grant read/write permissions to other users by using "chmod".  Also,
usbfs mount options such as "devmode=0666" may be helpful.


THE /proc/bus/usb/devices FILE:
-------------------------------
In /proc/bus/usb/devices, each device's output has multiple
lines of ASCII output.
I made it ASCII instead of binary on purpose, so that someone
can obtain some useful data from it without the use of an
auxiliary program.  However, with an auxiliary program, the numbers
in the first 4 columns of each "T:" line (topology info:
Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.

Each line is tagged with a one-character ID for that line:

T = Topology (etc.)
B = Bandwidth (applies only to USB host controllers, which are
    virtualized as root hubs)
D = Device descriptor info.
P = Product ID info. (from Device descriptor, but they won't fit
    together on one line)
S = String descriptors.
C = Configuration descriptor info. (* = active configuration)
I = Interface descriptor info.
E = Endpoint descriptor info.

=======================================================================

/proc/bus/usb/devices output format:

Legend:
  d = decimal number (may have leading spaces or 0's)
  x = hexadecimal number (may have leading spaces or 0's)
  s = string


Topology info:

T:  Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd
|   |      |      |       |       |      |        |       |__MaxChildren
|   |      |      |       |       |      |        |__Device Speed in Mbps
|   |      |      |       |       |      |__DeviceNumber
|   |      |      |       |       |__Count of devices at this level
|   |      |      |       |__Connector/Port on Parent for this device
|   |      |      |__Parent DeviceNumber
|   |      |__Level in topology for this bus
|   |__Bus number
|__Topology info tag

    Speed may be:
    	1.5	Mbit/s for low speed USB
	12	Mbit/s for full speed USB
	480	Mbit/s for high speed USB (added for USB 2.0)


Bandwidth info:
B:  Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
|   |                       |         |__Number of isochronous requests
|   |                       |__Number of interrupt requests
|   |__Total Bandwidth allocated to this bus
|__Bandwidth info tag

    Bandwidth allocation is an approximation of how much of one frame
    (millisecond) is in use.  It reflects only periodic transfers, which
    are the only transfers that reserve bandwidth.  Control and bulk
    transfers use all other bandwidth, including reserved bandwidth that
    is not used for transfers (such as for short packets).

    The percentage is how much of the "reserved" bandwidth is scheduled by
    those transfers.  For a low or full speed bus (loosely, "USB 1.1"),
    90% of the bus bandwidth is reserved.  For a high speed bus (loosely,
    "USB 2.0") 80% is reserved.


Device descriptor info & Product ID info:

D:  Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx

where
D:  Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
|   |        |             |      |       |       |__NumberConfigurations
|   |        |             |      |       |__MaxPacketSize of Default Endpoint
|   |        |             |      |__DeviceProtocol
|   |        |             |__DeviceSubClass
|   |        |__DeviceClass
|   |__Device USB version
|__Device info tag #1

where
P:  Vendor=xxxx ProdID=xxxx Rev=xx.xx
|   |           |           |__Product revision number
|   |           |__Product ID code
|   |__Vendor ID code
|__Device info tag #2


String descriptor info:

S:  Manufacturer=ssss
|   |__Manufacturer of this device as read from the device.
|      For USB host controller drivers (virtual root hubs) this may
|      be omitted, or (for newer drivers) will identify the kernel
|      version and the driver which provides this hub emulation.
|__String info tag

S:  Product=ssss
|   |__Product description of this device as read from the device.
|      For older USB host controller drivers (virtual root hubs) this
|      indicates the driver; for newer ones, it's a product (and vendor)
|      description that often comes from the kernel's PCI ID database.
|__String info tag

S:  SerialNumber=ssss
|   |__Serial Number of this device as read from the device.
|      For USB host controller drivers (virtual root hubs) this is
|      some unique ID, normally a bus ID (address or slot name) that
|      can't be shared with any other device.
|__String info tag


Configuration descriptor info:

C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
| | |       |       |      |__MaxPower in mA
| | |       |       |__Attributes
| | |       |__ConfiguratioNumber
| | |__NumberOfInterfaces
| |__ "*" indicates the active configuration (others are " ")
|__Config info tag

    USB devices may have multiple configurations, each of which act
    rather differently.  For example, a bus-powered configuration
    might be much less capable than one that is self-powered.  Only
    one device configuration can be active at a time; most devices
    have only one configuration.

    Each configuration consists of one or more interfaces.  Each
    interface serves a distinct "function", which is typically bound
    to a different USB device driver.  One common example is a USB
    speaker with an audio interface for playback, and a HID interface
    for use with software volume control.


Interface descriptor info (can be multiple per Config):

I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
| | |      |      |       |             |      |       |__Driver name
| | |      |      |       |             |      |          or "(none)"
| | |      |      |       |             |      |__InterfaceProtocol
| | |      |      |       |             |__InterfaceSubClass
| | |      |      |       |__InterfaceClass
| | |      |      |__NumberOfEndpoints
| | |      |__AlternateSettingNumber
| | |__InterfaceNumber
| |__ "*" indicates the active altsetting (others are " ")
|__Interface info tag

    A given interface may have one or more "alternate" settings.
    For example, default settings may not use more than a small
    amount of periodic bandwidth.  To use significant fractions
    of bus bandwidth, drivers must select a non-default altsetting.

    Only one setting for an interface may be active at a time, and
    only one driver may bind to an interface at a time.  Most devices
    have only one alternate setting per interface.


Endpoint descriptor info (can be multiple per Interface):

E:  Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
|   |        |            |         |__Interval (max) between transfers
|   |        |            |__EndpointMaxPacketSize
|   |        |__Attributes(EndpointType)
|   |__EndpointAddress(I=In,O=Out)
|__Endpoint info tag

    The interval is nonzero for all periodic (interrupt or isochronous)
    endpoints.  For high speed endpoints the transfer interval may be
    measured in microseconds rather than milliseconds.

    For high speed periodic endpoints, the "MaxPacketSize" reflects
    the per-microframe data transfer size.  For "high bandwidth"
    endpoints, that can reflect two or three packets (for up to
    3KBytes every 125 usec) per endpoint.

    With the Linux-USB stack, periodic bandwidth reservations use the
    transfer intervals and sizes provided by URBs, which can be less
    than those found in endpoint descriptor.


=======================================================================


If a user or script is interested only in Topology info, for
example, use something like "grep ^T: /proc/bus/usb/devices"
for only the Topology lines.  A command like
"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
only the lines that begin with the characters in square brackets,
where the valid characters are TDPCIE.  With a slightly more able
script, it can display any selected lines (for example, only T, D,
and P lines) and change their output format.  (The "procusb"
Perl script is the beginning of this idea.  It will list only
selected lines [selected from TBDPSCIE] or "All" lines from
/proc/bus/usb/devices.)

The Topology lines can be used to generate a graphic/pictorial
of the USB devices on a system's root hub.  (See more below
on how to do this.)

The Interface lines can be used to determine what driver is
being used for each device, and which altsetting it activated.

The Configuration lines could be used to list maximum power
(in milliamps) that a system's USB devices are using.
For example, "grep ^C: /proc/bus/usb/devices".


Here's an example, from a system which has a UHCI root hub,
an external hub connected to the root hub, and a mouse and
a serial converter connected to the external hub.

T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
B:  Alloc= 28/900 us ( 3%), #Int=  2, #Iso=  0
D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0000 ProdID=0000 Rev= 0.00
S:  Product=USB UHCI Root Hub
S:  SerialNumber=dce0
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms

T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 4
D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0451 ProdID=1446 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   1 Ivl=255ms

T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=04b4 ProdID=0001 Rev= 0.00
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
E:  Ad=81(I) Atr=03(Int.) MxPS=   3 Ivl= 10ms

T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12  MxCh= 0
D:  Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0565 ProdID=0001 Rev= 1.08
S:  Manufacturer=Peracom Networks, Inc.
S:  Product=Peracom USB to Serial Converter
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
E:  Ad=81(I) Atr=02(Bulk) MxPS=  64 Ivl= 16ms
E:  Ad=01(O) Atr=02(Bulk) MxPS=  16 Ivl= 16ms
E:  Ad=82(I) Atr=03(Int.) MxPS=   8 Ivl=  8ms


Selecting only the "T:" and "I:" lines from this (for example, by using
"procusb ti"), we have:

T:  Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
T:  Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 4
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
T:  Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=01 Prot=02 Driver=mouse
T:  Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#=  4 Spd=12  MxCh= 0
I:  If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial


Physically this looks like (or could be converted to):

                      +------------------+
                      |  PC/root_hub (12)|   Dev# = 1
                      +------------------+   (nn) is Mbps.
    Level 0           |  CN.0   |  CN.1  |   [CN = connector/port #]
                      +------------------+
                          /
                         /
            +-----------------------+
  Level 1   | Dev#2: 4-port hub (12)|
            +-----------------------+
            |CN.0 |CN.1 |CN.2 |CN.3 |
            +-----------------------+
                \           \____________________
                 \_____                          \
                       \                          \
               +--------------------+      +--------------------+
  Level 2      | Dev# 3: mouse (1.5)|      | Dev# 4: serial (12)|
               +--------------------+      +--------------------+


Or, in a more tree-like structure (ports [Connectors] without
connections could be omitted):

PC:  Dev# 1, root hub, 2 ports, 12 Mbps
|_ CN.0:  Dev# 2, hub, 4 ports, 12 Mbps
     |_ CN.0:  Dev #3, mouse, 1.5 Mbps
     |_ CN.1:
     |_ CN.2:  Dev #4, serial, 12 Mbps
     |_ CN.3:
|_ CN.1:


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