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