From owner-svn-src-all@FreeBSD.ORG  Thu Jan 13 16:37:12 2011
Return-Path: <owner-svn-src-all@FreeBSD.ORG>
Delivered-To: svn-src-all@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 93EBE106566B;
	Thu, 13 Jan 2011 16:37:12 +0000 (UTC)
	(envelope-from weongyo@FreeBSD.org)
Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c])
	by mx1.freebsd.org (Postfix) with ESMTP id 775A18FC0A;
	Thu, 13 Jan 2011 16:37:12 +0000 (UTC)
Received: from svn.freebsd.org (localhost [127.0.0.1])
	by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id p0DGbC6x056618;
	Thu, 13 Jan 2011 16:37:12 GMT (envelope-from weongyo@svn.freebsd.org)
Received: (from weongyo@localhost)
	by svn.freebsd.org (8.14.3/8.14.3/Submit) id p0DGbCkX056616;
	Thu, 13 Jan 2011 16:37:12 GMT (envelope-from weongyo@svn.freebsd.org)
Message-Id: <201101131637.p0DGbCkX056616@svn.freebsd.org>
From: Weongyo Jeong <weongyo@FreeBSD.org>
Date: Thu, 13 Jan 2011 16:37:12 +0000 (UTC)
To: src-committers@freebsd.org, svn-src-all@freebsd.org,
	svn-src-head@freebsd.org
X-SVN-Group: head
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Cc: 
Subject: svn commit: r217358 - head/usr.sbin/usbdump
X-BeenThere: svn-src-all@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: "SVN commit messages for the entire src tree \(except for &quot;
	user&quot; and &quot; projects&quot; \)" <svn-src-all.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/svn-src-all>,
	<mailto:svn-src-all-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/svn-src-all>
List-Post: <mailto:svn-src-all@freebsd.org>
List-Help: <mailto:svn-src-all-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/svn-src-all>,
	<mailto:svn-src-all-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 13 Jan 2011 16:37:12 -0000

Author: weongyo
Date: Thu Jan 13 16:37:12 2011
New Revision: 217358
URL: http://svn.freebsd.org/changeset/base/217358

Log:
  Documents OUTPUT formats.  While I'm here cleans up styles and words.
  
  Reviewed by:	brueffer@

Modified:
  head/usr.sbin/usbdump/usbdump.8

Modified: head/usr.sbin/usbdump/usbdump.8
==============================================================================
--- head/usr.sbin/usbdump/usbdump.8	Thu Jan 13 16:29:27 2011	(r217357)
+++ head/usr.sbin/usbdump/usbdump.8	Thu Jan 13 16:37:12 2011	(r217358)
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 14, 2010
+.Dd December 4, 2010
 .Dt usbdump 8
 .Os
 .Sh NAME
@@ -41,24 +41,29 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility provides a way to dump USB packets on each host controller.
+utility provides a way to dump USB packets on host controllers.
 .Pp
-The following options are accepted.
+The following options are accepted:
 .Bl -tag -width ".Fl f Ar file"
 .It Fl i Ar ifname
-Listen on USB bus interface.
+Listen on USB bus interface
+.Ar ifname .
 .It Fl r Ar file
-Read the raw packets from file.
+Read the raw packets from
+.Ar file .
 .It Fl s Ar snaplen
-Snapshot bytes from each packet.
+Snapshot
+.Ar snaplen
+bytes from each packet.
 .It Fl v
 Enable debugging messages.
-When it defined multiple times the verbose level increases.
+When defined multiple times the verbosity level increases.
 .It Fl w Ar file
-Write the raw packets to file.
+Write the raw packets to
+.Ar file .
 .El
 .Sh EXAMPLES
-Captures the USB raw packets alive on usbus2:
+Captures USB raw packets on usbus2:
 .Pp
 .Dl "usbdump -i usbus2 -s 256 -v"
 .Pp
@@ -67,11 +72,61 @@ size limit:
 .Pp
 .Dl "usbdump -i usbus2 -s 0 -w /tmp/dump_pkts"
 .Pp
-Read the USB raw packets from the file:
+Read the USB raw packets from previous file:
 .Pp
 .Dl "usbdump -r /tmp/dump_pkts -v"
+.Sh OUTPUT FORMAT
+The output format of
+.Nm
+is as follows:
+.Pp
+.Dl "<time> <bus>.<addr> <ep> <xfertype> <S/D> (<frames>/<length>) <...>"
+.Pp
+The meaning of the output format elements is as follows:
+.Bl -tag -width "<xfertype>"
+.It <time>
+A timestamp preceding all output lines.
+The timestamp has the format "hh:mm:ss.frac" and is as accurate as
+the kernel's clock.
+.It <bus>
+The USB host controller's bus unit number.
+.It <addr>
+The unique number of the USB device as allocated by the host controller driver.
+.It <ep>
+The USB endpoint address that indicates whether the address is
+.Dv OUT
+or
+.Dv IN .
+.It <xfertype>
+The USB transfer type.
+Can be
+.Dv CTRL ,
+.Dv ISOC ,
+.Dv BULK
+or
+.Dv INTR .
+.It <S/D>
+`S' indicates a USB submit.
+`D' indicates a USB transfer done.
+.It <frames>
+Numbers of frames in this packets.
+If this is a USB submit, its value is
+.Li xfer->nframes
+which means how many frames are acceptable or registered to transfer.
+If this is a USB done,
+.Li xfer->aframes
+is the actual number of frames.
+.It <length>
+Total packet size.
+If this is a USB submit, its value is
+.Li xfer->sumlen .
+If this is a USB done, its value is
+.Li xfer->actlen .
+.It <...>
+Optional field used for printing an error string if the packet is from USB done.
+.El
 .Sh SEE ALSO
 .Xr usbconfig 8
 .Sh AUTHORS
 .An Weongyo Jeong
-.Aq weongyo@FreeBSD.org .
+.Aq weongyo@FreeBSD.org