[PATCH usb-next] USB: Improve documentation for usbmon
From: Sedat Dilek
Date: Sun Apr 28 2013 - 09:18:41 EST
This is a give-back to USB folks who helped me in a USB debug issue.
Signed-off-by: Sedat Dilek <sedat.dilek@xxxxxxxxx>
Documentation/usb/usbmon.txt | 87 ++++++++++++++++++++++++++++----------------
1 file changed, 55 insertions(+), 32 deletions(-)
diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt
index c42bb9c..02f5845 100644
@@ -23,35 +23,53 @@ in a text format. This is used for two purposes. First, it serves as a
common trace exchange format for tools while more sophisticated formats
are finalized. Second, humans can read it in case tools are not available.
-To collect a raw text trace, execute following steps.
+To collect a (raw text) usbmon trace, execute the following steps.
+Step #1: Prerequisites and preperation
-Mount debugfs (it has to be enabled in your kernel configuration), and
-load the usbmon module (if built as module). The second step is skipped
-if usbmon is built into the kernel.
+You should enable the following kernel-config options:
-# mount -t debugfs none_debugs /sys/kernel/debug
-# modprobe usbmon
+CONFIG_DEBUG_FS=y <--- Enable DebugFS
+CONFIG_USB_DEBUG=y <--- Enable USB debugging
+CONFIG_USB_MON=m <--- Build usbmon as kernel-module
-Verify that bus sockets are present.
+Mount debugfs and load usbmon module:
-# ls /sys/kernel/debug/usb/usbmon
-0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
+ # mount -t debugfs none_debugs /sys/kernel/debug
-Now you can choose to either use the socket '0u' (to capture packets on all
+ # modprobe -v usbmon
+ insmod /lib/modules/$(uname -r)/kernel/drivers/usb/mon/usbmon.ko
+The second step is skipped if usbmon is built into the kernel.
+Verify that the bus sockets are present:
+ # ls /sys/kernel/debug/usb/usbmon
+ 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
+Now, you can choose to either use the socket '0u' (to capture packets on all
buses), and skip to step #3, or find the bus used by your device with step #2.
This allows to filter away annoying devices that talk continuously.
-2. Find which bus connects to the desired device
+NOTE: The 'lsusb' utiliy might be helpful for hardware diagnosis.
+Step #2: Find which bus connects to the desired/affected USB device
+How to find the bus which corresponds to the device?
+Usually, you do it by looking for the vendor and product string.
+ # dmesg | grep usb | egrep -i 'vendor|product'
-Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
-to the device. Usually you do it by looking for the vendor string. If you have
-many similar devices, unplug one and compare the two
-/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.
+All USB devices are listed here:
+ # cat /sys/kernel/debug/usb/devices
+The T-line will have a bus number.
+If you have many similar devices, unplug one and compare the two
T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
@@ -59,33 +77,38 @@ P: Vendor=0557 ProdID=2004 Rev= 1.00
S: Product=UC100KM V2.00
-"Bus=03" means it's bus 3. Alternatively, you can look at the output from
-"lsusb" and get the bus number from the appropriate line. Example:
+"Bus=03" in the T-line means it's bus 3.
+Alternatively, you can look at the output from "lsusb" and get the bus number
+from the appropriate line.
Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
-3. Start 'cat'
+Step #3: Start a usbmon tracing session
+To listen on a single bus (here: 3), run:
-# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
+ # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/usbmon-3u.txt
-to listen on a single bus, otherwise, to listen on all buses, type:
+Otherwise, to listen on all buses, type:
-# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
+ # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/usbmon-all.txt
This process will be reading until killed. Naturally, the output can be
redirected to a desirable location. This is preferred, because it is going
to be quite long.
-4. Perform the desired operation on the USB bus
+Step #4: Perform the desired operation on the USB bus
-This is where you do something that creates the traffic: plug in a flash key,
-copy files, control a webcam, etc.
+This is where you do something that creates traffic in the logs:
+Plug in a flash key, copy files, control a webcam, do a suspend-and-resume etc.
-5. Kill cat
+Step #5: Stop the usbmon tracing session
-Usually it's done with a keyboard interrupt (Control-C).
+Usually, it's done with a keyboard interrupt (Control-C).
-At this point the output file (/tmp/1.mon.out in this example) can be saved,
+At this point the output file (/tmp/usbmon-3u.txt in this example) can be saved,
sent by e-mail, or inspected with a text editor. In the last case make sure
that the file size is not excessive for your favourite editor.
@@ -176,7 +199,7 @@ Here is the list of words, from left to right:
Length counts only the bytes that were received whereas the Data words
contain the entire transfer buffer).
An input control transfer to get a port status.
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/