Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | * Introduction |
2 | ||
3 | The name "usbmon" in lowercase refers to a facility in kernel which is | |
4 | used to collect traces of I/O on the USB bus. This function is analogous | |
5 | to a packet socket used by network monitoring tools such as tcpdump(1) | |
6 | or Ethereal. Similarly, it is expected that a tool such as usbdump or | |
7 | USBMon (with uppercase letters) is used to examine raw traces produced | |
8 | by usbmon. | |
9 | ||
10 | The usbmon reports requests made by peripheral-specific drivers to Host | |
11 | Controller Drivers (HCD). So, if HCD is buggy, the traces reported by | |
12 | usbmon may not correspond to bus transactions precisely. This is the same | |
13 | situation as with tcpdump. | |
14 | ||
15 | * How to use usbmon to collect raw text traces | |
16 | ||
17 | Unlike the packet socket, usbmon has an interface which provides traces | |
18 | in a text format. This is used for two purposes. First, it serves as a | |
19 | common trace exchange format for tools while most sophisticated formats | |
20 | are finalized. Second, humans can read it in case tools are not available. | |
21 | ||
22 | To collect a raw text trace, execute following steps. | |
23 | ||
24 | 1. Prepare | |
25 | ||
26 | Mount debugfs (it has to be enabled in your kernel configuration), and | |
27 | load the usbmon module (if built as module). The second step is skipped | |
28 | if usbmon is built into the kernel. | |
29 | ||
30 | # mount -t debugfs none_debugs /sys/kernel/debug | |
31 | # modprobe usbmon | |
32 | ||
33 | Verify that bus sockets are present. | |
34 | ||
35 | [root@lembas zaitcev]# ls /sys/kernel/debug/usbmon | |
36 | 1s 1t 2s 2t 3s 3t 4s 4t | |
37 | [root@lembas zaitcev]# | |
38 | ||
39 | # ls /sys/kernel | |
40 | ||
41 | 2. Find which bus connects to the desired device | |
42 | ||
43 | Run "cat /proc/bus/usb/devices", and find the T-line which corresponds to | |
44 | the device. Usually you do it by looking for the vendor string. If you have | |
45 | many similar devices, unplug one and compare two /proc/bus/usb/devices outputs. | |
46 | The T-line will have a bus number. Example: | |
47 | ||
48 | T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 | |
49 | D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
50 | P: Vendor=0557 ProdID=2004 Rev= 1.00 | |
51 | S: Manufacturer=ATEN | |
52 | S: Product=UC100KM V2.00 | |
53 | ||
54 | Bus=03 means it's bus 3. | |
55 | ||
56 | 3. Start 'cat' | |
57 | ||
58 | # cat /sys/kernel/debug/usbmon/3t > /tmp/1.mon.out | |
59 | ||
60 | This process will be reading until killed. Naturally, the output can be | |
61 | redirected to a desirable location. This is preferred, because it is going | |
62 | to be quite long. | |
63 | ||
64 | 4. Perform the desired operation on the USB bus | |
65 | ||
66 | This is where you do something that creates the traffic: plug in a flash key, | |
67 | copy files, control a webcam, etc. | |
68 | ||
69 | 5. Kill cat | |
70 | ||
71 | Usually it's done with a keyboard interrupt (Control-C). | |
72 | ||
73 | At this point the output file (/tmp/1.mon.out in this example) can be saved, | |
74 | sent by e-mail, or inspected with a text editor. In the last case make sure | |
75 | that the file size is not excessive for your favourite editor. | |
76 | ||
77 | * Raw text data format | |
78 | ||
79 | The '0t' type data consists of a stream of events, such as URB submission, | |
80 | URB callback, submission error. Every event is a text line, which consists | |
81 | of whitespace separated words. The number of position of words may depend | |
82 | on the event type, but there is a set of words, common for all types. | |
83 | ||
84 | Here is the list of words, from left to right: | |
85 | - URB Tag. This is used to identify URBs is normally a kernel mode address | |
86 | of the URB structure in hexadecimal. | |
87 | - Timestamp in microseconds, a decimal number. The timestamp's resolution | |
88 | depends on available clock, and so it can be much worse than a microsecond | |
89 | (if the implementation uses jiffies, for example). | |
90 | - Event Type. This type refers to the format of the event, not URB type. | |
91 | Available types are: S - submission, C - callback, E - submission error. | |
92 | - "Pipe". The pipe concept is deprecated. This is a composite word, used to | |
93 | be derived from information in pipes. It consists of three fields, separated | |
94 | by colons: URB type and direction, Device address, Endpoint number. | |
95 | Type and direction are encoded with two bytes in the following manner: | |
96 | Ci Co Control input and output | |
97 | Zi Zo Isochronous input and output | |
98 | Ii Io Interrupt input and output | |
99 | Bi Bo Bulk input and output | |
100 | Device address and Endpoint number are decimal numbers with leading zeroes | |
101 | or 3 and 2 positions, correspondingly. | |
102 | - URB Status. This field makes no sense for submissions, but is present | |
103 | to help scripts with parsing. In error case, it contains the error code. | |
ae0d6cce | 104 | In case of a setup packet, it contains a Setup Tag. If scripts read a number |
003ba515 | 105 | in this field, they proceed to read Data Length. Otherwise, they read |
ae0d6cce PZ |
106 | the setup packet before reading the Data Length. |
107 | - Setup packet, if present, consists of 5 words: one of each for bmRequestType, | |
108 | bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. | |
109 | These words are safe to decode if Setup Tag was 's'. Otherwise, the setup | |
110 | packet was present, but not captured, and the fields contain filler. | |
1da177e4 LT |
111 | - Data Length. This is the actual length in the URB. |
112 | - Data tag. The usbmon may not always capture data, even if length is nonzero. | |
113 | Only if tag is '=', the data words are present. | |
114 | - Data words follow, in big endian hexadecimal format. Notice that they are | |
115 | not machine words, but really just a byte stream split into words to make | |
116 | it easier to read. Thus, the last word may contain from one to four bytes. | |
117 | The length of collected data is limited and can be less than the data length | |
118 | report in Data Length word. | |
119 | ||
120 | Here is an example of code to read the data stream in a well known programming | |
121 | language: | |
122 | ||
123 | class ParsedLine { | |
124 | int data_len; /* Available length of data */ | |
125 | byte data[]; | |
126 | ||
127 | void parseData(StringTokenizer st) { | |
128 | int availwords = st.countTokens(); | |
129 | data = new byte[availwords * 4]; | |
130 | data_len = 0; | |
131 | while (st.hasMoreTokens()) { | |
132 | String data_str = st.nextToken(); | |
133 | int len = data_str.length() / 2; | |
134 | int i; | |
ae0d6cce | 135 | int b; // byte is signed, apparently?! XXX |
1da177e4 | 136 | for (i = 0; i < len; i++) { |
ae0d6cce PZ |
137 | // data[data_len] = Byte.parseByte( |
138 | // data_str.substring(i*2, i*2 + 2), | |
139 | // 16); | |
140 | b = Integer.parseInt( | |
141 | data_str.substring(i*2, i*2 + 2), | |
142 | 16); | |
143 | if (b >= 128) | |
144 | b *= -1; | |
145 | data[data_len] = (byte) b; | |
1da177e4 LT |
146 | data_len++; |
147 | } | |
148 | } | |
149 | } | |
150 | } | |
151 | ||
ae0d6cce | 152 | This format may be changed in the future. |
1da177e4 LT |
153 | |
154 | Examples: | |
155 | ||
ae0d6cce | 156 | An input control transfer to get a port status. |
1da177e4 | 157 | |
ae0d6cce PZ |
158 | d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 < |
159 | d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000 | |
1da177e4 LT |
160 | |
161 | An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper | |
162 | to a storage device at address 5: | |
163 | ||
164 | dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 | |
165 | dd65f0e8 4128379808 C Bo:005:02 0 31 > | |
166 | ||
167 | * Raw binary format and API | |
168 | ||
169 | TBD |