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