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