1usbmon(8) System Manager's Manual usbmon(8)
2
6 usbmon - monitor USB traffic
7
9 usbmon [ -i bus_num ] [ -s length ] [ -f0 | -fu | -fh ] [ -a0 | -a1 ]
10
12 usbmon allows to capture USB traffic for analysis in the manner similar
13 to tcpdump (8).
14 To make use of this program, you need to have a Linux kernel which sup‐
16 ports the binary "usbmon" interface (e.g., Linux kernel 2.6.20 or
17 newer).
18
21 -i Listen on bus_num. If unspecified, usbmon attempts to listen on
22 the pseudo-bus number zero, which is supposed to capture all
23 packets on all buses. The default is a convenient mode because
24 the user does not have to figure out the bus number where a spe‐
25 cific device is attached. Also, listening on pseudo-bus zero
26 allows to capture events which happen when a bus is initialized.
27 However, it may be necessary to specify a specific bus number to
29 tap. Kernels before 2.6.22 do not implement the pseudo-bus zero
30 at all. Performance of USB stack and the usbmon is greater when
31 a specific bus is monitored. In such case, the desired bus num‐
32 ber may be determined by examining the output of lsusb(8).
33 -s Set the maximum length of USB data to print. The default is to
36 print 32 bytes just like the kernel's text interface would. The
37 capture size is automatically adjusted to match unless set
38 explicitly.
39 -f Select the output format as one of: '0' for legacy format, 'u'
42 for so-called "1u" format, 'h' for "human-readable" format. The
43 human-readable format is the default. Also, it changes over
44 time, so programs should parse the "1u" format.
45 Selecting the 1u format forces usbmon to use the API which may
47 not be available in the kernel before version 2.6.22.
48 The human-readable format is not intended for a programmatic
50 parsing, and so changes from release to release.
51 -a Force the binary API version to use: '0' for the legacy API in
54 kernel 2.6.20 and up, '1' for the newer API in kernels after
55 2.6.22. Selection of output format may force the API to the
56 minimum required to support the format. In general, this option
57 is only used when testing the kernel component of usbmon.
58
61 The output of usbmon contains one text line per an event. The event
62 corresponds to I/O operations on the boundary of Host Controller Driver
63 (HCD). This includes events of the following types: Submission, Call‐
64 back, Error. Every line consists of whitespace separated words. The
65 number or position of words may depend on the event type, but there is
66 a set of words, common for all types.
67 Most commonly used format is the human-readable format. Its words, from
69 left to right, are:
70 - URB Tag. A single URB generates several monitoring events during its
72 life cycle. The tag allows to corellate events with the URB. Tag is
73 usually derived from a kernel mode address. Human-readable format
74 shortens the tag to make the output more readable, so it's not the com‐
75 plete address.
76 - Timestamp. It consistes of the number of seconds, period, and the
78 fraction in microseconds.
79 - Event Type. This type refers to the format of the event, not URB
81 type. Available types are: S - submission, C - callback, E - submis‐
82 sion error.
83 - "Pipe word" (the name is historical and has nothing to do with
85 pipes). This is a composite word. It consists of four fields, sepa‐
86 rated by colons: URB type and direction, Bus number, Device address,
87 Endpoint number. Type and direction are encoded with two bytes in the
88 following manner:
89 Ci Co Control input and output
91 Zi Zo Isochronous input and output
92 Ii Io Interrupt input and output
93 Bi Bo Bulk input and output
94 The address information fields may contain leading zeros. If the bus is
96 specified with -i, the Bus number field is redundant, but is kept for
97 the ease of parsing.
98 - Status word. This word may have several fields, depending on the
100 transfer type. Most transfers only have the status field. Interrupt and
101 Isochronous transfers add an interval. For Isochronous, start frame and
102 error count may be present. For callback and error events, the status
103 field contains an integer number, which represents a "status" field of
104 the URB. For a submission event, status makes no sense, so the field
105 contains a single dash.
106 Control submissions are an exception, because they may have a setup
108 packet. In such case, the event contains a letter in place of the sta‐
109 tus word. The letter is called "setup tag".
110 - Setup packet, if present, consists of 5 words: one of each for bmRe‐
112 questType, bRequest, wValue, wIndex, wLength, as specified by the USB
113 Specification 2.0. These words are safe to decode if Setup Tag was
114 's'. Otherwise, the setup packet was present, but not captured, and the
115 fields contain filler.
116 - The number of isochronous frame descriptors (optional).
118 - Isochronous descriptors (optional). Like the "pipe word", each
120 descriptor contains fields separated by colons: status, offset, and
121 length.
122 - Data Tag
124 - Data (if Data Tag is '=')
126 Data stream and its ASCII representation follow on separate lines.
128 Each line starts with a space for the ease of identification.
129 The following is the list of words for the legacy format, from left to
132 right:
133 - URB Tag. This is normally a kernel mode address of the URB structure.
135 - Timestamp in microseconds, a decimal number. The timestamp's resolu‐
137 tion depends on available clock, and so it can be much worse than a
138 microsecond (if the implementation uses jiffies, for example). The
139 number of microseconds is usually truncated, so it can wrap if usbmon
140 runs long enough.
141 - Event Type. This type refers to the format of the event, not URB
143 type. Available types are: S - submission, C - callback, E - submis‐
144 sion error.
145 - "Pipe". The pipe concept is deprecated. This is a composite word,
147 used to be derived from information in pipes. It consists of three
148 fields, separated by colons: URB type and direction, Device address,
149 Endpoint number. Type and direction are encoded with two bytes in the
150 following manner:
151 Ci Co Control input and output
153 Zi Zo Isochronous input and output
154 Ii Io Interrupt input and output
155 Bi Bo Bulk input and output
156 Device address and Endpoint number are 3-digit and 2-digit (respec‐
158 tively) decimal numbers, with leading zeroes.
159 - URB Status. In most cases, this field contains a number, sometimes
161 negative, which represents a "status" field of the URB. This field
162 makes no sense for submissions, but is present anyway to help scripts
163 with parsing. When an error occurs, the field contains the error code.
164 In case of a submission of a Control packet, this field contains a Set‐
165 up Tag instead of an error code. It is easy to tell whether the Setup
166 Tag is present because it is never a number. Thus if scripts find a
167 number in this field, they proceed to read Data Length. If they find
168 something else, like a letter, they read the setup packet before read‐
169 ing the Data Length.
170 - Setup packet, if present, consists of 5 words: one of each for bmRe‐
172 questType, bRequest, wValue, wIndex, wLength, as specified by the USB
173 Specification 2.0. These words are safe to decode if Setup Tag was
174 's'. Otherwise, the setup packet was present, but not captured, and the
175 fields contain filler.
176 - Data Length. For submissions, this is the requested length. For call‐
178 backs, this is the actual length.
179 - Data tag. The usbmon may not always capture data, even if length is
181 nonzero. The data words are present only if this tag is '='.
182 - Data words follow, in big endian hexadecimal format. Notice that they
184 are not machine words, but really just a byte stream split into words
185 to make it easier to read. Thus, the last word may contain from one to
186 four bytes. The length of collected data is limited (see the -s param‐
187 eter) and can be less than the data length report in the Data Length
188 word.
189
192 /proc/devices
193 This file is read to determine the major of /dev/usbmonN if such
194 node does not exist in the system.
195 /dev/usbmonN
197 The usbmon attempts to open /dev/usbmon{N}, where N is the bus
198 number. If the node does not exist, usbmon creates it.
199
202 lsusb(8)
203
206 Pete Zaitcev, <zaitcev@redhat.com>.
207 10 April 2007 usbmon(8)