usbmon-6/usbmon.8

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