manpagez: man pages & more
man usbdump(1)
Home | html | info | man

usbdump(1)                BSD General Commands Manual               usbdump(1)


NAME

     usbdump -- dump traffic on USB host controller


SYNOPSIS

     usbdump [-i ifname] [-r file] [-s snaplen] [-v] [-w file] [-f filter]
             [-l location] [-b file] [-h]


DESCRIPTION

     The usbdump utility provides a way to dump USB packets on host con-
     trollers.

     The following options are accepted:

     -b file  Store data part of the USB trace in binary format to the given
              file.  This option also works with the -r and -f options.

     -i ifname
              Listen on USB bus interface ifname.  This is specified by con-
              troller type prefix and location.  The controller type prefix
              must be one of: UHC, OHC, EHC, XHC.  The location is the most
              significant byte of the controller's location as shown in the
              IORegistry.  For example: the ifname of EHC1@1d000000 would be
              EHC29.

     -r file  Read the raw packets from file.  This option also works with the
              -f option.

     -s snaplen
              Snapshot snaplen bytes from each packet.

     -v       Enable debugging messages.  When defined multiple times the ver-
              bosity level increases.

     -w file  Write the raw packets to file.  This option also works with the
              -s and -v options.

     -f filter
              The filter argument consists of either one or two numbers sepa-
              rated by a dot.  The first indicates the device address which
              should be traced.  The second number, which is optional, indi-
              cates the endpoint address which should be traced.  A device
              address or endpoint value of -1 means ignore this field.  If no
              filters are specified, all packets are passed through using the
              default -1,-1 filter.  This option can be specified multiple
              times.

     -l location
              The filter argument consists of either one or two numbers sepa-
              rated by a dot.  The first indicates the locationID which should
              be traced and must be provided in hexidecimal.  The second num-
              ber, which is optional, indicates the endpoint address which
              should be traced.  This option can be specified multiple times.

     -h       This option displays a summary of the command line options.


EXAMPLES

     Capture the USB raw packets on XHC1:

           usbdump -i XHC1 -s 256 -v

     Dump the USB raw packets of EHC1 into the file without packet size limit:

           usbdump -i EHC1 -s 0 -w /tmp/dump_pkts

     Dump the USB raw packets of OHC1, but only the control endpoint traffic
     of device at address 3, endpoint 0x81:

           usbdump -i OHC1 -s 0 -f 3.129 -w /tmp/dump_pkts

     Read and display the USB raw packets from previous file:

           usbdump -r /tmp/dump_pkts -v


OUTPUT FORMAT

     The output format of usbdump is as follows:

           <time> <controller> <device> <endpoint> <type> <speed> <state> <id>
           <frames> <length> <status>

     The meaning of the output format elements is as follows:

     <time>        A timestamp preceding all output lines.  The timestamp has
                   the format "hh:mm:ss.frac" and is as accurate as the ker-
                   nel's clock.

     <controller>  The USB host controller's name.

     <device>      The address of the USB device as allocated by the host con-
                   troller driver.

     <endpoint>    The USB endpoint address that indicates whether the address
                   is OUT or IN.

     <type>        The USB transfer type.  Can be control, isoc, bulk or
                   interrupt.

     <speed>       The operating speed of the device.  Can be full, high,
                   super, or super+.

     <state>       The state of the I/O.  `submitted' indicates the I/O has
                   been submitted. `completed' indicates a USB transfer done.

     <id>          The unique ID of this I/O request.

     <frames>      Numbers of frames in this packets.  Only applicable to isoc
                   transfers.q

     <length>      Total amount of data that was transferred.

     <status>      IOReturn status for the request


AUTHORS

     Based on work from Weongyo Jeong <weongyo@FreeBSD.org>

BSD                               May 4, 2016                              BSD

Mac OS X 10.12.3 - Generated Sat Feb 4 18:20:32 CST 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.