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