usr.sbin/usbdump/usbdump.8

   1 .\"
   2 .\" Copyright (c) 2010 Weongyo Jeong.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd May 14, 2021
  29 .Dt USBDUMP 8
  30 .Os
  31 .Sh NAME
  32 .Nm usbdump
  33 .Nd "dump traffic on USB host controller"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl d Ar [ugen]B
  37 .Op Fl d Ar [ugen]B.D
  38 .Op Fl d Ar [ugen]B.D.E
  39 .Op Fl i Ar ifname
  40 .Op Fl r Ar file
  41 .Op Fl s Ar snaplen
  42 .Op Fl v
  43 .Op Fl w Ar file
  44 .Op Fl f Ar filter
  45 .Op Fl b Ar file
  46 .Op Fl h
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility provides a way to dump USB packets on host controllers.
  51 .Pp
  52 The following options are accepted:
  53 .Bl -tag -width ".Fl f Ar file"
  54 .It Fl d Ar [ugen]bus
  55 Shortcut for
  56 .Fl i
  57 option.
  58 The argument may be prefixed by "ugen".
  59 The option may be specified multiple times, but the bus specified must
  60 be the same.
  61 .It Fl d Ar [ugen]bus.device
  62 Shortcut for
  63 .Fl i
  64 and
  65 .Fl f
  66 options.
  67 The argument may be prefixed by "ugen".
  68 The option may be specified multiple times, but the bus specified must
  69 be the same.
  70 .It Fl d Ar [ugen]bus.device.endpoint
  71 Shortcut for
  72 .Fl i
  73 and
  74 .Fl f
  75 options.
  76 The argument may be prefixed by "ugen".
  77 The option may be specified multiple times, but the bus specified must
  78 be the same.
  79 .It Fl b Ar file
  80 Store data part of the USB trace in binary format to the given
  81 .Ar file .
  82 This option also works with the -r and -f options.
  83 .It Fl i Ar ifname
  84 Listen on USB bus interface
  85 .Ar ifname .
  86 .It Fl r Ar file
  87 Read the raw packets from
  88 .Ar file .
  89 This option also works with the -f option.
  90 .It Fl s Ar snaplen
  91 Snapshot
  92 .Ar snaplen
  93 bytes from each packet.
  94 .It Fl v
  95 Enable debugging messages.
  96 When defined multiple times the verbosity level increases.
  97 .It Fl w Ar file
  98 Write the raw packets to
  99 .Ar file .
 100 This option also works with the -s and -v options.
 101 .It Fl f Ar filter
 102 The filter argument consists of either one or two numbers separated by a dot.
 103 The first indicates the device unit number which should be traced.
 104 The second number which is optional indicates the endpoint which should be traced.
 105 To get all traffic for the control endpoint, two filters should be
 106 created, one for endpoint 0 and one for endpoint 128.
 107 If 128 is added to the endpoint number that means IN direction, else OUT direction is implied.
 108 A device unit or endpoint value of -1 means ignore this field.
 109 If no filters are specified, all packets are passed through using the default -1,-1 filter.
 110 This option can be specified multiple times.
 111 .It Fl h
 112 This option displays a summary of the command line options.
 113 .El
 114 .Sh EXAMPLES
 115 Capture the USB raw packets on usbus2:
 116 .Pp
 117 .Dl "usbdump -i usbus2 -s 256 -v"
 118 .Pp
 119 Dump the USB raw packets of usbus2 into the file without packet
 120 size limit:
 121 .Pp
 122 .Dl "usbdump -i usbus2 -s 0 -w /tmp/dump_pkts"
 123 .Pp
 124 Dump the USB raw packets of usbus2, but only the control endpoint traffic
 125 of device unit number 3:
 126 .Pp
 127 .Dl "usbdump -i usbus2 -s 0 -f 3.0 -f 3.128 -w /tmp/dump_pkts"
 128 .Pp
 129 Read and display the USB raw packets from previous file:
 130 .Pp
 131 .Dl "usbdump -r /tmp/dump_pkts -v"
 132 .Sh OUTPUT FORMAT
 133 The output format of
 134 .Nm
 135 is as follows:
 136 .Pp
 137 .Dl "<time> <bus>.<addr> <ep> <xfertype> <S/D> (<frames>/<length>) <...>"
 138 .Pp
 139 The meaning of the output format elements is as follows:
 140 .Bl -tag -width "<xfertype>"
 141 .It <time>
 142 A timestamp preceding all output lines.
 143 The timestamp has the format "hh:mm:ss.frac" and is as accurate as
 144 the kernel's clock.
 145 .It <bus>
 146 The USB host controller's bus unit number.
 147 .It <addr>
 148 The unique number of the USB device as allocated by the host controller driver.
 149 .It <ep>
 150 The USB endpoint address that indicates whether the address is
 151 .Dv OUT
 152 or
 153 .Dv IN .
 154 .It <xfertype>
 155 The USB transfer type.
 156 Can be
 157 .Dv CTRL ,
 158 .Dv ISOC ,
 159 .Dv BULK
 160 or
 161 .Dv INTR .
 162 .It <S/D>
 163 `S' indicates a USB submit.
 164 `D' indicates a USB transfer done.
 165 .It <frames>
 166 Numbers of frames in this packets.
 167 If this is a USB submit, its value is
 168 .Li xfer->nframes
 169 which means how many frames are acceptable or registered to transfer.
 170 If this is a USB done,
 171 .Li xfer->aframes
 172 is the actual number of frames.
 173 .It <length>
 174 Total packet size.
 175 If this is a USB submit, its value is
 176 .Li xfer->sumlen .
 177 If this is a USB done, its value is
 178 .Li xfer->actlen .
 179 .It <...>
 180 Optional field used for printing an error string if the packet is from USB done.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr usbconfig 8
 184 .Sh AUTHORS
 185 .An Weongyo Jeong Aq Mt weongyo@FreeBSD.org