1usbmon(8)                   System Manager's Manual                  usbmon(8)
2
3
4

NAME

6       usbmon - monitor USB traffic
7

SYNOPSIS

9       usbmon [ -i bus_num ] [ -s length ] [ -f0 | -fu | -fh ] [ -a0 | -a1 ]
10

DESCRIPTION

12       usbmon allows to capture USB traffic for analysis in the manner similar
13       to tcpdump (8).
14
15       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
19

OPTIONS

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
28              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
34
35       -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
40
41       -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
46              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
49              The human-readable format is not  intended  for  a  programmatic
50              parsing, and so changes from release to release.
51
52
53       -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
59

OUTPUT FORMAT

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
68       Most commonly used format is the human-readable format. Its words, from
69       left to right, are:
70
71       - 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
77       -  Timestamp.  It  consistes  of the number of seconds, period, and the
78       fraction in microseconds.
79
80       - 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
84       - "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
90           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
95       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
99       - 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
107       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
111       - 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
117       - The number of isochronous frame descriptors (optional).
118
119       - Isochronous  descriptors  (optional).  Like  the  "pipe  word",  each
120       descriptor  contains  fields  separated  by colons: status, offset, and
121       length.
122
123       - Data Tag
124
125       - Data (if Data Tag is '=')
126
127       Data stream and its ASCII  representation  follow  on  separate  lines.
128       Each line starts with a space for the ease of identification.
129
130
131       The  following is the list of words for the legacy format, from left to
132       right:
133
134       - URB Tag. This is normally a kernel mode address of the URB structure.
135
136       - 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
142       - 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
146       - "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
152           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
157       Device address and Endpoint number are  3-digit  and  2-digit  (respec‐
158       tively) decimal numbers, with leading zeroes.
159
160       -  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
171       - 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
177       - Data Length. For submissions, this is the requested length. For call‐
178       backs, this is the actual length.
179
180       -  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
183       - 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
190

FILES

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
196       /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
200

SEE ALSO

202       lsusb(8)
203
204

AUTHOR

206       Pete Zaitcev, <zaitcev@redhat.com>.
207
208
209
210                                 10 April 2007                       usbmon(8)
Impressum