Commit | Line | Data |
---|---|---|
d80b5005 MCC |
1 | ====== |
2 | usbmon | |
3 | ====== | |
4 | ||
5 | Introduction | |
6 | ============ | |
1da177e4 LT |
7 | |
8 | The name "usbmon" in lowercase refers to a facility in kernel which is | |
9 | used to collect traces of I/O on the USB bus. This function is analogous | |
10 | to a packet socket used by network monitoring tools such as tcpdump(1) | |
11 | or Ethereal. Similarly, it is expected that a tool such as usbdump or | |
12 | USBMon (with uppercase letters) is used to examine raw traces produced | |
13 | by usbmon. | |
14 | ||
15 | The usbmon reports requests made by peripheral-specific drivers to Host | |
16 | Controller Drivers (HCD). So, if HCD is buggy, the traces reported by | |
17 | usbmon may not correspond to bus transactions precisely. This is the same | |
18 | situation as with tcpdump. | |
19 | ||
d25bc4db PZ |
20 | Two APIs are currently implemented: "text" and "binary". The binary API |
21 | is available through a character device in /dev namespace and is an ABI. | |
22 | The text API is deprecated since 2.6.35, but available for convenience. | |
23 | ||
d80b5005 MCC |
24 | How to use usbmon to collect raw text traces |
25 | ============================================ | |
1da177e4 LT |
26 | |
27 | Unlike the packet socket, usbmon has an interface which provides traces | |
28 | in a text format. This is used for two purposes. First, it serves as a | |
f1c9e30b | 29 | common trace exchange format for tools while more sophisticated formats |
1da177e4 LT |
30 | are finalized. Second, humans can read it in case tools are not available. |
31 | ||
32 | To collect a raw text trace, execute following steps. | |
33 | ||
34 | 1. Prepare | |
d80b5005 | 35 | ---------- |
1da177e4 LT |
36 | |
37 | Mount debugfs (it has to be enabled in your kernel configuration), and | |
38 | load the usbmon module (if built as module). The second step is skipped | |
d80b5005 | 39 | if usbmon is built into the kernel:: |
1da177e4 | 40 | |
d80b5005 MCC |
41 | # mount -t debugfs none_debugs /sys/kernel/debug |
42 | # modprobe usbmon | |
43 | # | |
1da177e4 | 44 | |
788183a6 | 45 | Verify that bus sockets are present:: |
1da177e4 | 46 | |
d80b5005 MCC |
47 | # ls /sys/kernel/debug/usb/usbmon |
48 | 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u | |
49 | # | |
1da177e4 | 50 | |
aacf4a01 PZ |
51 | Now you can choose to either use the socket '0u' (to capture packets on all |
52 | buses), and skip to step #3, or find the bus used by your device with step #2. | |
53 | This allows to filter away annoying devices that talk continuously. | |
092a212e | 54 | |
1da177e4 | 55 | 2. Find which bus connects to the desired device |
d80b5005 | 56 | ------------------------------------------------ |
1da177e4 | 57 | |
d8cae98c AS |
58 | Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds |
59 | to the device. Usually you do it by looking for the vendor string. If you have | |
60 | many similar devices, unplug one and compare the two | |
61 | /sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. | |
1da177e4 | 62 | |
d80b5005 MCC |
63 | Example:: |
64 | ||
65 | T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 | |
66 | D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 | |
67 | P: Vendor=0557 ProdID=2004 Rev= 1.00 | |
68 | S: Manufacturer=ATEN | |
69 | S: Product=UC100KM V2.00 | |
1da177e4 | 70 | |
d8cae98c AS |
71 | "Bus=03" means it's bus 3. Alternatively, you can look at the output from |
72 | "lsusb" and get the bus number from the appropriate line. Example: | |
73 | ||
74 | Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 | |
1da177e4 LT |
75 | |
76 | 3. Start 'cat' | |
d80b5005 MCC |
77 | -------------- |
78 | ||
79 | :: | |
1da177e4 | 80 | |
d80b5005 | 81 | # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out |
1da177e4 | 82 | |
d80b5005 | 83 | to listen on a single bus, otherwise, to listen on all buses, type:: |
092a212e | 84 | |
d80b5005 | 85 | # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out |
092a212e | 86 | |
7690037d | 87 | This process will read until it is killed. Naturally, the output can be |
1da177e4 LT |
88 | redirected to a desirable location. This is preferred, because it is going |
89 | to be quite long. | |
90 | ||
91 | 4. Perform the desired operation on the USB bus | |
d80b5005 | 92 | ----------------------------------------------- |
1da177e4 LT |
93 | |
94 | This is where you do something that creates the traffic: plug in a flash key, | |
95 | copy files, control a webcam, etc. | |
96 | ||
97 | 5. Kill cat | |
d80b5005 | 98 | ----------- |
1da177e4 LT |
99 | |
100 | Usually it's done with a keyboard interrupt (Control-C). | |
101 | ||
102 | At this point the output file (/tmp/1.mon.out in this example) can be saved, | |
103 | sent by e-mail, or inspected with a text editor. In the last case make sure | |
104 | that the file size is not excessive for your favourite editor. | |
105 | ||
d80b5005 MCC |
106 | Raw text data format |
107 | ==================== | |
1da177e4 | 108 | |
f1c9e30b PZ |
109 | Two formats are supported currently: the original, or '1t' format, and |
110 | the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' | |
111 | format adds a few fields, such as ISO frame descriptors, interval, etc. | |
112 | It produces slightly longer lines, but otherwise is a perfect superset | |
113 | of '1t' format. | |
114 | ||
115 | If it is desired to recognize one from the other in a program, look at the | |
116 | "address" word (see below), where '1u' format adds a bus number. If 2 colons | |
117 | are present, it's the '1t' format, otherwise '1u'. | |
118 | ||
119 | Any text format data consists of a stream of events, such as URB submission, | |
1da177e4 | 120 | URB callback, submission error. Every event is a text line, which consists |
6f23ee1f | 121 | of whitespace separated words. The number or position of words may depend |
1da177e4 LT |
122 | on the event type, but there is a set of words, common for all types. |
123 | ||
124 | Here is the list of words, from left to right: | |
f1c9e30b | 125 | |
aacf4a01 PZ |
126 | - URB Tag. This is used to identify URBs, and is normally an in-kernel address |
127 | of the URB structure in hexadecimal, but can be a sequence number or any | |
128 | other unique string, within reason. | |
f1c9e30b | 129 | |
1da177e4 LT |
130 | - Timestamp in microseconds, a decimal number. The timestamp's resolution |
131 | depends on available clock, and so it can be much worse than a microsecond | |
132 | (if the implementation uses jiffies, for example). | |
f1c9e30b | 133 | |
1da177e4 LT |
134 | - Event Type. This type refers to the format of the event, not URB type. |
135 | Available types are: S - submission, C - callback, E - submission error. | |
f1c9e30b PZ |
136 | |
137 | - "Address" word (formerly a "pipe"). It consists of four fields, separated by | |
138 | colons: URB type and direction, Bus number, Device address, Endpoint number. | |
1da177e4 | 139 | Type and direction are encoded with two bytes in the following manner: |
d80b5005 MCC |
140 | |
141 | == == ============================= | |
1da177e4 LT |
142 | Ci Co Control input and output |
143 | Zi Zo Isochronous input and output | |
144 | Ii Io Interrupt input and output | |
145 | Bi Bo Bulk input and output | |
d80b5005 MCC |
146 | == == ============================= |
147 | ||
f1c9e30b PZ |
148 | Bus number, Device address, and Endpoint are decimal numbers, but they may |
149 | have leading zeros, for the sake of human readers. | |
150 | ||
151 | - URB Status word. This is either a letter, or several numbers separated | |
152 | by colons: URB status, interval, start frame, and error count. Unlike the | |
153 | "address" word, all fields save the status are optional. Interval is printed | |
154 | only for interrupt and isochronous URBs. Start frame is printed only for | |
155 | isochronous URBs. Error count is printed only for isochronous callback | |
156 | events. | |
157 | ||
158 | The status field is a decimal number, sometimes negative, which represents | |
159 | a "status" field of the URB. This field makes no sense for submissions, but | |
160 | is present anyway to help scripts with parsing. When an error occurs, the | |
161 | field contains the error code. | |
162 | ||
163 | In case of a submission of a Control packet, this field contains a Setup Tag | |
164 | instead of an group of numbers. It is easy to tell whether the Setup Tag is | |
165 | present because it is never a number. Thus if scripts find a set of numbers | |
166 | in this word, they proceed to read Data Length (except for isochronous URBs). | |
167 | If they find something else, like a letter, they read the setup packet before | |
168 | reading the Data Length or isochronous descriptors. | |
169 | ||
ae0d6cce PZ |
170 | - Setup packet, if present, consists of 5 words: one of each for bmRequestType, |
171 | bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. | |
172 | These words are safe to decode if Setup Tag was 's'. Otherwise, the setup | |
173 | packet was present, but not captured, and the fields contain filler. | |
f1c9e30b PZ |
174 | |
175 | - Number of isochronous frame descriptors and descriptors themselves. | |
176 | If an Isochronous transfer event has a set of descriptors, a total number | |
177 | of them in an URB is printed first, then a word per descriptor, up to a | |
178 | total of 5. The word consists of 3 colon-separated decimal numbers for | |
179 | status, offset, and length respectively. For submissions, initial length | |
180 | is reported. For callbacks, actual length is reported. | |
181 | ||
d9ac2cfc PZ |
182 | - Data Length. For submissions, this is the requested length. For callbacks, |
183 | this is the actual length. | |
f1c9e30b | 184 | |
1da177e4 | 185 | - Data tag. The usbmon may not always capture data, even if length is nonzero. |
d9ac2cfc | 186 | The data words are present only if this tag is '='. |
f1c9e30b | 187 | |
1da177e4 LT |
188 | - Data words follow, in big endian hexadecimal format. Notice that they are |
189 | not machine words, but really just a byte stream split into words to make | |
190 | it easier to read. Thus, the last word may contain from one to four bytes. | |
191 | The length of collected data is limited and can be less than the data length | |
d25bc4db PZ |
192 | reported in the Data Length word. In the case of an Isochronous input (Zi) |
193 | completion where the received data is sparse in the buffer, the length of | |
194 | the collected data can be greater than the Data Length value (because Data | |
195 | Length counts only the bytes that were received whereas the Data words | |
196 | contain the entire transfer buffer). | |
1da177e4 | 197 | |
1da177e4 LT |
198 | Examples: |
199 | ||
d80b5005 | 200 | An input control transfer to get a port status:: |
1da177e4 | 201 | |
d80b5005 MCC |
202 | d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < |
203 | d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 | |
1da177e4 | 204 | |
2e8dc2f2 | 205 | An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte |
d80b5005 | 206 | Bulk wrapper to a storage device at address 5:: |
1da177e4 | 207 | |
d80b5005 MCC |
208 | dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 |
209 | dd65f0e8 4128379808 C Bo:1:005:2 0 31 > | |
1da177e4 | 210 | |
d80b5005 MCC |
211 | Raw binary format and API |
212 | ========================= | |
1da177e4 | 213 | |
6f23ee1f PZ |
214 | The overall architecture of the API is about the same as the one above, |
215 | only the events are delivered in binary format. Each event is sent in | |
d80b5005 | 216 | the following structure (its name is made up, so that we can refer to it):: |
6f23ee1f | 217 | |
d80b5005 | 218 | struct usbmon_packet { |
6f23ee1f PZ |
219 | u64 id; /* 0: URB ID - from submission to callback */ |
220 | unsigned char type; /* 8: Same as text; extensible. */ | |
221 | unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ | |
222 | unsigned char epnum; /* Endpoint number and transfer direction */ | |
223 | unsigned char devnum; /* Device address */ | |
224 | u16 busnum; /* 12: Bus number */ | |
225 | char flag_setup; /* 14: Same as text */ | |
226 | char flag_data; /* 15: Same as text; Binary zero is OK. */ | |
227 | s64 ts_sec; /* 16: gettimeofday */ | |
228 | s32 ts_usec; /* 24: gettimeofday */ | |
229 | int status; /* 28: */ | |
230 | unsigned int length; /* 32: Length of data (submitted or actual) */ | |
231 | unsigned int len_cap; /* 36: Delivered length */ | |
471c604d PZ |
232 | union { /* 40: */ |
233 | unsigned char setup[SETUP_LEN]; /* Only for Control S-type */ | |
234 | struct iso_rec { /* Only for ISO */ | |
235 | int error_count; | |
236 | int numdesc; | |
237 | } iso; | |
238 | } s; | |
239 | int interval; /* 48: Only for Interrupt and ISO */ | |
240 | int start_frame; /* 52: For ISO */ | |
241 | unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ | |
242 | unsigned int ndesc; /* 60: Actual number of ISO descriptors */ | |
d80b5005 | 243 | }; /* 64 total length */ |
6f23ee1f PZ |
244 | |
245 | These events can be received from a character device by reading with read(2), | |
471c604d PZ |
246 | with an ioctl(2), or by accessing the buffer with mmap. However, read(2) |
247 | only returns first 48 bytes for compatibility reasons. | |
6f23ee1f PZ |
248 | |
249 | The character device is usually called /dev/usbmonN, where N is the USB bus | |
250 | number. Number zero (/dev/usbmon0) is special and means "all buses". | |
471c604d | 251 | Note that specific naming policy is set by your Linux distribution. |
6f23ee1f PZ |
252 | |
253 | If you create /dev/usbmon0 by hand, make sure that it is owned by root | |
11a6322a | 254 | and has mode 0600. Otherwise, unprivileged users will be able to snoop |
6f23ee1f PZ |
255 | keyboard traffic. |
256 | ||
257 | The following ioctl calls are available, with MON_IOC_MAGIC 0x92: | |
258 | ||
259 | MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) | |
260 | ||
261 | This call returns the length of data in the next event. Note that majority of | |
262 | events contain no data, so if this call returns zero, it does not mean that | |
263 | no events are available. | |
264 | ||
265 | MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) | |
266 | ||
d80b5005 | 267 | The argument is a pointer to the following structure:: |
6f23ee1f | 268 | |
d80b5005 | 269 | struct mon_bin_stats { |
6f23ee1f PZ |
270 | u32 queued; |
271 | u32 dropped; | |
d80b5005 | 272 | }; |
6f23ee1f PZ |
273 | |
274 | The member "queued" refers to the number of events currently queued in the | |
275 | buffer (and not to the number of events processed since the last reset). | |
276 | ||
277 | The member "dropped" is the number of events lost since the last call | |
278 | to MON_IOCG_STATS. | |
279 | ||
280 | MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) | |
281 | ||
282 | This call sets the buffer size. The argument is the size in bytes. | |
283 | The size may be rounded down to the next chunk (or page). If the requested | |
284 | size is out of [unspecified] bounds for this kernel, the call fails with | |
285 | -EINVAL. | |
286 | ||
287 | MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) | |
288 | ||
289 | This call returns the current size of the buffer in bytes. | |
290 | ||
291 | MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) | |
471c604d | 292 | MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg) |
6f23ee1f | 293 | |
471c604d PZ |
294 | These calls wait for events to arrive if none were in the kernel buffer, |
295 | then return the first event. The argument is a pointer to the following | |
d80b5005 | 296 | structure:: |
6f23ee1f | 297 | |
d80b5005 | 298 | struct mon_get_arg { |
6f23ee1f PZ |
299 | struct usbmon_packet *hdr; |
300 | void *data; | |
301 | size_t alloc; /* Length of data (can be zero) */ | |
d80b5005 | 302 | }; |
6f23ee1f PZ |
303 | |
304 | Before the call, hdr, data, and alloc should be filled. Upon return, the area | |
305 | pointed by hdr contains the next event structure, and the data buffer contains | |
306 | the data, if any. The event is removed from the kernel buffer. | |
307 | ||
f4e2332c | 308 | The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes. |
471c604d | 309 | |
6f23ee1f PZ |
310 | MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) |
311 | ||
312 | This ioctl is primarily used when the application accesses the buffer | |
d80b5005 | 313 | with mmap(2). Its argument is a pointer to the following structure:: |
6f23ee1f | 314 | |
d80b5005 | 315 | struct mon_mfetch_arg { |
6f23ee1f PZ |
316 | uint32_t *offvec; /* Vector of events fetched */ |
317 | uint32_t nfetch; /* Number of events to fetch (out: fetched) */ | |
318 | uint32_t nflush; /* Number of events to flush */ | |
d80b5005 | 319 | }; |
6f23ee1f PZ |
320 | |
321 | The ioctl operates in 3 stages. | |
322 | ||
323 | First, it removes and discards up to nflush events from the kernel buffer. | |
324 | The actual number of events discarded is returned in nflush. | |
325 | ||
326 | Second, it waits for an event to be present in the buffer, unless the pseudo- | |
327 | device is open with O_NONBLOCK. | |
328 | ||
329 | Third, it extracts up to nfetch offsets into the mmap buffer, and stores | |
330 | them into the offvec. The actual number of event offsets is stored into | |
331 | the nfetch. | |
332 | ||
333 | MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) | |
334 | ||
335 | This call removes a number of events from the kernel buffer. Its argument | |
336 | is the number of events to remove. If the buffer contains fewer events | |
337 | than requested, all events present are removed, and no error is reported. | |
338 | This works when no events are available too. | |
339 | ||
340 | FIONBIO | |
341 | ||
342 | The ioctl FIONBIO may be implemented in the future, if there's a need. | |
343 | ||
344 | In addition to ioctl(2) and read(2), the special file of binary API can | |
345 | be polled with select(2) and poll(2). But lseek(2) does not work. | |
346 | ||
347 | * Memory-mapped access of the kernel buffer for the binary API | |
348 | ||
349 | The basic idea is simple: | |
350 | ||
351 | To prepare, map the buffer by getting the current size, then using mmap(2). | |
d80b5005 | 352 | Then, execute a loop similar to the one written in pseudo-code below:: |
6f23ee1f PZ |
353 | |
354 | struct mon_mfetch_arg fetch; | |
355 | struct usbmon_packet *hdr; | |
356 | int nflush = 0; | |
357 | for (;;) { | |
358 | fetch.offvec = vec; // Has N 32-bit words | |
359 | fetch.nfetch = N; // Or less than N | |
360 | fetch.nflush = nflush; | |
361 | ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too | |
362 | nflush = fetch.nfetch; // This many packets to flush when done | |
363 | for (i = 0; i < nflush; i++) { | |
364 | hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; | |
365 | if (hdr->type == '@') // Filler packet | |
366 | continue; | |
367 | caddr_t data = &mmap_area[vec[i]] + 64; | |
368 | process_packet(hdr, data); | |
369 | } | |
370 | } | |
371 | ||
372 | Thus, the main idea is to execute only one ioctl per N events. | |
373 | ||
374 | Although the buffer is circular, the returned headers and data do not cross | |
375 | the end of the buffer, so the above pseudo-code does not need any gathering. |