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