<commit_before>* Introduction

The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.

The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.

* How to use usbmon to collect raw text traces

Unlike the packet socket, usbmon has an interface which provides traces
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.

1. Prepare

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.

# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
#

Verify that bus sockets are present.

# ls /sys/kernel/debug/usbmon
1s  1t  1u  2s  2t  2u  3s  3t  3u  4s  4t  4u
#

2. Find which bus connects to the desired device

Run "cat /proc/bus/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 two /proc/bus/usb/devices outputs.
The T-line will have a bus number. 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
P:  Vendor=0557 ProdID=2004 Rev= 1.00
S:  Manufacturer=ATEN
S:  Product=UC100KM V2.00

Bus=03 means it's bus 3.

3. Start 'cat'

# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out

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

This is where you do something that creates the traffic: plug in a flash key,<commit_msg>USB: usbmon doc update - mention new wildcard ('0') bus<commit_after>* Introduction

The name "usbmon" in lowercase refers to a facility in kernel which is
used to collect traces of I/O on the USB bus. This function is analogous
to a packet socket used by network monitoring tools such as tcpdump(1)
or Ethereal. Similarly, it is expected that a tool such as usbdump or
USBMon (with uppercase letters) is used to examine raw traces produced
by usbmon.

The usbmon reports requests made by peripheral-specific drivers to Host
Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
usbmon may not correspond to bus transactions precisely. This is the same
situation as with tcpdump.

* How to use usbmon to collect raw text traces

Unlike the packet socket, usbmon has an interface which provides traces
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.

1. Prepare

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.

# mount -t debugfs none_debugs /sys/kernel/debug
# modprobe usbmon
#

Verify that bus sockets are present.

# ls /sys/kernel/debug/usbmon
0s  0t  0u  1s  1t  1u  2s  2t  2u  3s  3t  3u  4s  4t  4u
#

Now you can choose to either use the sockets numbered '0' (to capture packets on
all buses), and skip to step #3, or find the bus used by your device with step #2.

2. Find which bus connects to the desired device

Run "cat /proc/bus/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 two /proc/bus/usb/devices outputs.
The T-line will have a bus number. 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
P:  Vendor=0557 ProdID=2004 Rev= 1.00
S:  Manufacturer=ATEN
S:  Product=UC100KM V2.00

Bus=03 means it's bus 3.

3. Start 'cat'

# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out

to listen on a single bus, otherwise, to listen on all buses, type:

# cat /sys/kernel/debug/usbmon/0u > /tmp/1.mon.out

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

This is where you do something that creates the traffic: plug in a flash key,
{'fraction_non_alphanumeric': 0.05824088748019018, 'fraction_numerical': 0.02713946117274168, 'mean_word_length': 3.822349570200573, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 8, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5689832', 'n_tokens_mistral': 1602, 'n_tokens_neox': 1525, 'n_words': 817}