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 April 24, 2012
  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 i Ar ifname
  37 .Op Fl r Ar file
  38 .Op Fl s Ar snaplen
  39 .Op Fl v
  40 .Op Fl w Ar file
  41 .Op Fl f Ar filter
  42 .Op Fl b Ar file
  43 .Op Fl h
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility provides a way to dump USB packets on host controllers.
  48 .Pp
  49 The following options are accepted:
  50 .Bl -tag -width ".Fl f Ar file"
  51 .It Fl b Ar file
  52 Store data part of the USB trace in binary format to the given
  53 .Ar file .
  54 This option also works with the -r and -f options.
  55 .It Fl i Ar ifname
  56 Listen on USB bus interface
  57 .Ar ifname .
  58 .It Fl r Ar file
  59 Read the raw packets from
  60 .Ar file .
  61 This option also works with the -f option.
  62 .It Fl s Ar snaplen
  63 Snapshot
  64 .Ar snaplen
  65 bytes from each packet.
  66 .It Fl v
  67 Enable debugging messages.
  68 When defined multiple times the verbosity level increases.
  69 .It Fl w Ar file
  70 Write the raw packets to
  71 .Ar file .
  72 This option also works with the -s and -v options.
  73 .It Fl f Ar filter
  74 The filter argument consists of either one or two numbers separated by a dot.
  75 The first indicates the device unit number which should be traced.
  76 The second number which is optional indicates the endpoint which should be traced.
  77 To get all traffic for the control endpoint, two filters should be
  78 created, one for endpoint 0 and one for endpoint 128.
  79 If 128 is added to the endpoint number that means IN direction, else OUT direction is implied.
  80 A device unit or endpoint value of -1 means ignore this field.
  81 If no filters are specified, all packets are passed through using the default -1,-1 filter.
  82 This option can be specified multiple times.
  83 .It Fl h
  84 This option displays a summary of the command line options.
  85 .El
  86 .Sh EXAMPLES
  87 Capture the USB raw packets on usbus2:
  88 .Pp
  89 .Dl "usbdump -i usbus2 -s 256 -v"
  90 .Pp
  91 Dump the USB raw packets of usbus2 into the file without packet
  92 size limit:
  93 .Pp
  94 .Dl "usbdump -i usbus2 -s 0 -w /tmp/dump_pkts"
  95 .Pp
  96 Dump the USB raw packets of usbus2, but only the control endpoint traffic
  97 of device unit number 3:
  98 .Pp
  99 .Dl "usbdump -i usbus2 -s 0 -f 3.0 -f 3.128 -w /tmp/dump_pkts"
 100 .Pp
 101 Read and display the USB raw packets from previous file:
 102 .Pp
 103 .Dl "usbdump -r /tmp/dump_pkts -v"
 104 .Sh OUTPUT FORMAT
 105 The output format of
 106 .Nm
 107 is as follows:
 108 .Pp
 109 .Dl "<time> <bus>.<addr> <ep> <xfertype> <S/D> (<frames>/<length>) <...>"
 110 .Pp
 111 The meaning of the output format elements is as follows:
 112 .Bl -tag -width "<xfertype>"
 113 .It <time>
 114 A timestamp preceding all output lines.
 115 The timestamp has the format "hh:mm:ss.frac" and is as accurate as
 116 the kernel's clock.
 117 .It <bus>
 118 The USB host controller's bus unit number.
 119 .It <addr>
 120 The unique number of the USB device as allocated by the host controller driver.
 121 .It <ep>
 122 The USB endpoint address that indicates whether the address is
 123 .Dv OUT
 124 or
 125 .Dv IN .
 126 .It <xfertype>
 127 The USB transfer type.
 128 Can be
 129 .Dv CTRL ,
 130 .Dv ISOC ,
 131 .Dv BULK
 132 or
 133 .Dv INTR .
 134 .It <S/D>
 135 `S' indicates a USB submit.
 136 `D' indicates a USB transfer done.
 137 .It <frames>
 138 Numbers of frames in this packets.
 139 If this is a USB submit, its value is
 140 .Li xfer->nframes
 141 which means how many frames are acceptable or registered to transfer.
 142 If this is a USB done,
 143 .Li xfer->aframes
 144 is the actual number of frames.
 145 .It <length>
 146 Total packet size.
 147 If this is a USB submit, its value is
 148 .Li xfer->sumlen .
 149 If this is a USB done, its value is
 150 .Li xfer->actlen .
 151 .It <...>
 152 Optional field used for printing an error string if the packet is from USB done.
 153 .El
 154 .Sh SEE ALSO
 155 .Xr usbconfig 8
 156 .Sh AUTHORS
 157 .An Weongyo Jeong
 158 .Aq weongyo@FreeBSD.org