| * 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 most 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 2s 2t 3s 3t 4s 4t | |
| # | |
| 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/3t > /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, | |
| copy files, control a webcam, etc. | |
| 5. Kill cat | |
| 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, | |
| 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. | |
| * Raw text data format | |
| The '1t' type data consists of a stream of events, such as URB submission, | |
| URB callback, submission error. Every event is a text line, which consists | |
| of whitespace separated words. The number of position of words may depend | |
| on the event type, but there is a set of words, common for all types. | |
| Here is the list of words, from left to right: | |
| - URB Tag. This is used to identify URBs is normally a kernel mode address | |
| of the URB structure in hexadecimal. | |
| - Timestamp in microseconds, a decimal number. The timestamp's resolution | |
| depends on available clock, and so it can be much worse than a microsecond | |
| (if the implementation uses jiffies, for example). | |
| - Event Type. This type refers to the format of the event, not URB type. | |
| Available types are: S - submission, C - callback, E - submission error. | |
| - "Pipe". The pipe concept is deprecated. This is a composite word, used to | |
| be derived from information in pipes. It consists of three fields, separated | |
| by colons: URB type and direction, Device address, Endpoint number. | |
| Type and direction are encoded with two bytes in the following manner: | |
| Ci Co Control input and output | |
| Zi Zo Isochronous input and output | |
| Ii Io Interrupt input and output | |
| Bi Bo Bulk input and output | |
| Device address and Endpoint number are 3-digit and 2-digit (respectively) | |
| decimal numbers, with leading zeroes. | |
| - URB Status. In most cases, this field contains a number, sometimes negative, | |
| which represents a "status" field of the URB. This field makes no sense for | |
| submissions, but is present anyway to help scripts with parsing. When an | |
| error occurs, the field contains the error code. In case of a submission of | |
| a Control packet, this field contains a Setup Tag instead of an error code. | |
| It is easy to tell whether the Setup Tag is present because it is never a | |
| number. Thus if scripts find a number in this field, they proceed to read | |
| Data Length. If they find something else, like a letter, they read the setup | |
| packet before reading the Data Length. | |
| - Setup packet, if present, consists of 5 words: one of each for bmRequestType, | |
| bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. | |
| These words are safe to decode if Setup Tag was 's'. Otherwise, the setup | |
| packet was present, but not captured, and the fields contain filler. | |
| - Data Length. For submissions, this is the requested length. For callbacks, | |
| this is the actual length. | |
| - Data tag. The usbmon may not always capture data, even if length is nonzero. | |
| The data words are present only if this tag is '='. | |
| - Data words follow, in big endian hexadecimal format. Notice that they are | |
| not machine words, but really just a byte stream split into words to make | |
| it easier to read. Thus, the last word may contain from one to four bytes. | |
| The length of collected data is limited and can be less than the data length | |
| report in Data Length word. | |
| Here is an example of code to read the data stream in a well known programming | |
| language: | |
| class ParsedLine { | |
| int data_len; /* Available length of data */ | |
| byte data[]; | |
| void parseData(StringTokenizer st) { | |
| int availwords = st.countTokens(); | |
| data = new byte[availwords * 4]; | |
| data_len = 0; | |
| while (st.hasMoreTokens()) { | |
| String data_str = st.nextToken(); | |
| int len = data_str.length() / 2; | |
| int i; | |
| int b; // byte is signed, apparently?! XXX | |
| for (i = 0; i < len; i++) { | |
| // data[data_len] = Byte.parseByte( | |
| // data_str.substring(i*2, i*2 + 2), | |
| // 16); | |
| b = Integer.parseInt( | |
| data_str.substring(i*2, i*2 + 2), | |
| 16); | |
| if (b >= 128) | |
| b *= -1; | |
| data[data_len] = (byte) b; | |
| data_len++; | |
| } | |
| } | |
| } | |
| } | |
| This format may be changed in the future. | |
| Examples: | |
| An input control transfer to get a port status. | |
| d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 < | |
| d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000 | |
| An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper | |
| to a storage device at address 5: | |
| dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 | |
| dd65f0e8 4128379808 C Bo:005:02 0 31 > | |
| * Raw binary format and API | |
| TBD |