[net-next-2.6.git] / Documentation / usb / proc_usb_info.txt

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


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.

In many modern systems the usbfs filsystem isn't used at all.  Instead
USB device nodes are created under /dev/usb/ or someplace similar.  The
"devices" file is available in debugfs, typically as
/sys/kernel/debug/usb/devices.


**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=dddd 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);
		  also used for Wireless USB, which has no fixed speed
	5000	Mbit/s for SuperSpeed USB (added for USB 3.0)

    For reasons lost in the mists of time, the Port number is always
    too low by 1.  For example, a device plugged into port 4 will
    show up with "Port=03".

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
1da177e4 LT	2	===============================
834e2312	3	(version 2010.09.13)
1da177e4 LT	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
834e2312 AS	10	In many modern systems the usbfs filsystem 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
1da177e4 LT	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
5f980948	28	USB device information, and user mode drivers can use usbfs
1da177e4 LT	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
5f980948	40	"USB Device Filesystem" section of the USB Guide. The latest copy
1da177e4 LT	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
9a9fafb8 PE	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.
1da177e4 LT	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
064e875a	69	source code (linux/drivers/usb/core/devio.c) is the primary reference
1da177e4 LT	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
834e2312 AS	114	T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
834e2312 AS	115	\| \| \| \| \| \| \| \| \|__MaxChildren
1da177e4 LT	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
834e2312 AS	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)
1da177e4	131
834e2312 AS	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".
1da177e4 LT	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).
5f980948	148
1da177e4 LT	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
5f980948	212
1da177e4 LT	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
2360e4aa DB	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 " ")
1da177e4 LT	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.
5f980948	244
1da177e4 LT	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
2360e4aa	293	being used for each device, and which altsetting it activated.
1da177e4 LT	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
834e2312	304	T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
1da177e4 LT	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
5f980948	313
834e2312	314	T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
1da177e4 LT	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
5f980948	320
834e2312	321	T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
1da177e4 LT	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
5f980948	327
834e2312	328	T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
1da177e4 LT	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
834e2312 AS	343	T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
834e2312 AS	344	T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
1da177e4	345	I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
834e2312	346	T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
1da177e4	347	I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
834e2312	348	T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
1da177e4 LT	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 ###