USB: Improve documentation for usbmon
Subsystems (2)
PATCH 1/1 USB: Improve documentation for usbmon
This is a give-back to USB folks who helped me in a USB debug issue.
--- Documentation/usb/usbmon.txt | 87 ++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 32 deletions(-)
Documentation/usb/usbmon.txt +55 -32
@@ -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. -1. Prepare +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. -Example: +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 +/sys/kernel/debug/usb/devices outputs. + +EXAMPLE: 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: Manufacturer=ATEN 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. + +EXAMPLE: 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). -Examples: +EXAMPLES: An input control transfer to get a port status.
Signature · 1 line
1.8.2.2
Quoted 1 line · Sedat Dilek
This is a give-back to USB folks who helped me in a USB debug issue.
Thanks for sending this. Here are some suggestions for minor improvements.
Quoted 10 lines
Signed-off-by Sedat Dilek <[email protected]>--- Documentation/usb/usbmon.txt | 87 ++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 32 deletions(-)Documentation/usb/usbmon.txt +0
-0
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 26
Quoted 5 lines
Documentation/usb/usbmon.txt +1
-1@@ -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.
Might as well leave out the parentheses.
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 28
Quoted 3 lines
Documentation/usb/usbmon.txt +1
-1-1. Prepare +Step #1: Prerequisites and preperation
s/preperation/preparation/
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 33
Quoted 11 lines
Documentation/usb/usbmon.txt +3
-6-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
As far as I know, CONFIG_USB_DEBUG is not needed.
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 34
Quoted 1 line
Documentation/usb/usbmon.txt +1
-0+CONFIG_USB_MON=m <--- Build usbmon as kernel-module
This could be either 'm' or 'y'. Many distributions set it to 'y'.
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 38
Quoted 8 lines
Documentation/usb/usbmon.txt +2
-4-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
Distributions normally do this for you.
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 41
Quoted 4 lines
Documentation/usb/usbmon.txt +2
-1-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 complicated insmod command isn't needed; modprobe works perfectly well.
Documentation/usb/usbmon.txt in a text format. This is used for two purposes. First, it serves as a · line 43
Quoted 2 lines
Documentation/usb/usbmon.txt +2
-0+ +The second step is skipped if usbmon is built into the kernel.
This is unclear. "second step" sounds like it refers to Step #2 below.
Alan Stern