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