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 -a Force the binary API version to use: '0' for the legacy API in
51 kernel 2.6.20 and up, '1' for the newer API in kernels after
52 2.6.22. Selection of output format may force the API to the
53 minimum required to support the format. In general, this option
54 is only used when testing the kernel component of usbmon.
55
58 The output of usbmon contains one text line per an event. The event
59 corresponds to I/O operations on the boundary of Host Controller Driver
60 (HCD). This includes events of the following types: Submission, Call‐
61 back, Error. Every line consists of whitespace separated words. The
62 number or position of words may depend on the event type, but there is
63 a set of words, common for all types.
64 Most commonly used format is the human-readable format. Its words, from
66 left to right, are:
67 - URB Tag. A single URB generates several monitoring events during its
69 life cycle. The tag allows to corellate events with the URB. Tag is
70 usually derived from a kernel mode address. Human-readable format
71 shortens the tag to make the output more readable, so it's not the com‐
72 plete address.
73 - Timestamp. It consistes of the number of seconds, period, and the
75 fraction in microseconds.
76 - Event Type. This type refers to the format of the event, not URB
78 type. Available types are: S - submission, C - callback, E - submis‐
79 sion error.
80 - "Pipe word" (the name is historical and has nothing to do with
82 pipes). This is a composite word. It consists of four fields, sepa‐
83 rated by colons: URB type and direction, Bus number, Device address,
84 Endpoint number. Type and direction are encoded with two bytes in the
85 following manner:
86 Ci Co Control input and output
88 Zi Zo Isochronous input and output
89 Ii Io Interrupt input and output
90 Bi Bo Bulk input and output
91 The address information fields may contain leading zeros. If the bus is
93 specified with -i, the Bus number field is redundant, but is kept for
94 the ease of parsing.
95 - Status word. This word may have several fields, depending on the
97 transfer type. Most transfers only have the status field. Interrupt and
98 Isochronous transfers add an interval. For Isochronous, start frame and
99 error count may be present. For callback and error events, the status
100 field contains an integer number, which represents a "status" field of
101 the URB. For a submission event, status makes no sense, so the field
102 contains a single dash.
103 Control submissions are an exception, because they may have a setup
105 packet. In such case, the event contains a letter in place of the sta‐
106 tus word. The letter is called "setup tag".
107 - Setup packet, if present, consists of 5 words: one of each for bmRe‐
109 questType, bRequest, wValue, wIndex, wLength, as specified by the USB
110 Specification 2.0. These words are safe to decode if Setup Tag was
111 's'. Otherwise, the setup packet was present, but not captured, and the
112 fields contain filler.
113 - The number of isochronous frame descriptors (optional).
115 - Isochronous descriptors (optional). This is a new feature of usbmon,
117 poorly understood, and poorly documented. XXX
118 - Data Tag
120 - Data (if Data Tag is '=')
122 The following is the list of words for the legacy format, from left to
125 right:
126 - URB Tag. This is normally a kernel mode address of the URB structure.
128 - Timestamp in microseconds, a decimal number. The timestamp's resolu‐
130 tion depends on available clock, and so it can be much worse than a
131 microsecond (if the implementation uses jiffies, for example). The
132 number of microseconds is usually truncated, so it can wrap if usbmon
133 runs long enough.
134 - Event Type. This type refers to the format of the event, not URB
136 type. Available types are: S - submission, C - callback, E - submis‐
137 sion error.
138 - "Pipe". The pipe concept is deprecated. This is a composite word,
140 used to be derived from information in pipes. It consists of three
141 fields, separated by colons: URB type and direction, Device address,
142 Endpoint number. Type and direction are encoded with two bytes in the
143 following manner:
144 Ci Co Control input and output
146 Zi Zo Isochronous input and output
147 Ii Io Interrupt input and output
148 Bi Bo Bulk input and output
149 Device address and Endpoint number are 3-digit and 2-digit (respec‐
151 tively) decimal numbers, with leading zeroes.
152 - URB Status. In most cases, this field contains a number, sometimes
154 negative, which represents a "status" field of the URB. This field
155 makes no sense for submissions, but is present anyway to help scripts
156 with parsing. When an error occurs, the field contains the error code.
157 In case of a submission of a Control packet, this field contains a Set‐
158 up Tag instead of an error code. It is easy to tell whether the Setup
159 Tag is present because it is never a number. Thus if scripts find a
160 number in this field, they proceed to read Data Length. If they find
161 something else, like a letter, they read the setup packet before read‐
162 ing the Data Length.
163 - Setup packet, if present, consists of 5 words: one of each for bmRe‐
165 questType, bRequest, wValue, wIndex, wLength, as specified by the USB
166 Specification 2.0. These words are safe to decode if Setup Tag was
167 's'. Otherwise, the setup packet was present, but not captured, and the
168 fields contain filler.
169 - Data Length. For submissions, this is the requested length. For call‐
171 backs, this is the actual length.
172 - Data tag. The usbmon may not always capture data, even if length is
174 nonzero. The data words are present only if this tag is '='.
175 - Data words follow, in big endian hexadecimal format. Notice that they
177 are not machine words, but really just a byte stream split into words
178 to make it easier to read. Thus, the last word may contain from one to
179 four bytes. The length of collected data is limited (see the -s param‐
180 eter) and can be less than the data length report in the Data Length
181 word.
182
185 /proc/devices
186 This file is read to determine the major of /dev/usbmonN if such
187 node does not exist in the system.
188 /dev/usbmonN
190 The usbmon attempts to open /dev/usbmon{N}, where N is the bus
191 number. If the node does not exist, usbmon creates it.
192
195 lsusb(8)
196
199 Pete Zaitcev, <zaitcev@redhat.com>.
200 10 April 2007 usbmon(8)