Add description of table output to dpctl man page.

Adds a description of the output from the "dump-flows" and
"dump-aggregate" commands of dpctl.  Requested by NEC.

diff --git a/utilities/dpctl.8.in b/utilities/dpctl.8.in
index ffd9be754e961eaad1672bf5f693671d21367c34..4ddc48a9fd4e865f670e49f816686cbb2e33866f 100644 (file)
--- a/utilities/dpctl.8.in
+++ b/utilities/dpctl.8.in
@@ -209,7 +209,8 @@ spanning tree protocol is not in use.
 Prints to the console all flow entries in \fIswitch\fR's
 tables that match \fIflows\fR.  If \fIflows\fR is omitted, all flows
 in the switch are retrieved.  See \fBFlow Syntax\fR, below, for the
-syntax of \fIflows\fR.
+syntax of \fIflows\fR.  The output format is described in 
+\fBTable Entry Output\fR.
 
 .TP
 \fBdump-aggregate \fIswitch \fR[\fIflows\fR]
@@ -217,6 +218,7 @@ Prints to the console aggregate statistics for flows in
 \fIswitch\fR's tables that match \fIflows\fR.  If \fIflows\fR is omitted, 
 the statistics are aggregated across all flows in the switch's flow
 tables.  See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
+The output format is descrbed in \fBTable Entry Output\fR.
 
 .TP
 \fBadd-flow \fIswitch flow\fR
@@ -319,9 +321,8 @@ The following field assignments describe how a flow matches a packet.
 If any of these assignments is omitted from the flow syntax, the field
 is treated as a wildcard; thus, if all of them are omitted, the
 resulting flow matches all packets.  The string \fB*\fR or \fBANY\fR
-may be specified a value to explicitly mark any of these fields as a
-wildcard.  (\fB*\fR should be quoted to protect it from shell
-expansion.)
+may be specified to explicitly mark any of these fields as a wildcard.  
+(\fB*\fR should be quoted to protect it from shell expansion.)
 
 .IP \fBin_port=\fIport_no\fR
 Matches physical port \fIport_no\fR.  Switch ports are numbered as
@@ -334,45 +335,43 @@ otherwise, specify a number between 0 and 4095, inclusive, as the
 12-bit VLAN ID to match.
 
 .IP \fBdl_src=\fImac\fR
-Matches Ethernet source address \fImac\fR, which should be specified
-as 6 pairs of hexadecimal digits delimited by colons,
-e.g. \fB00:0A:E4:25:6B:B0\fR.
+Matches Ethernet source address \fImac\fR, which is specified as 6 pairs 
+of hexadecimal digits delimited by colons (e.g. \fB00:0A:E4:25:6B:B0\fR).
 
 .IP \fBdl_dst=\fImac\fR
 Matches Ethernet destination address \fImac\fR.
 
 .IP \fBdl_type=\fIethertype\fR
-Matches Ethernet protocol type \fIethertype\fR, which should be
-specified as a integer between 0 and 65535, inclusive, either in
-decimal or as a hexadecimal number prefixed by \fB0x\fR,
-e.g. \fB0x0806\fR to match ARP packets.
+Matches Ethernet protocol type \fIethertype\fR, which is specified as an
+integer between 0 and 65535, inclusive, either in decimal or as a 
+hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP 
+packets).
 
 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
-Matches IPv4 source address \fIip\fR, which should be specified as an
-IP address or host name, e.g. \fB192.168.1.1\fR or
-\fBwww.example.com\fR.  The optional \fInetmask\fR allows matching
-only on an IPv4 address prefix.  It may be specified as a dotted quad
-(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a count of bits
+Matches IPv4 source address \fIip\fR, which may be specified as an
+IP address or host name (e.g. \fB192.168.1.1\fR or
+\fBwww.example.com\fR).  The optional \fInetmask\fR allows restricting a
+match to an IPv4 address prefix.  The netmask may be specified as a dotted 
+quad (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block 
 (e.g. \fB192.168.1.0/24\fR).
 
 .IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
 Matches IPv4 destination address \fIip\fR.
 
 .IP \fBnw_proto=\fIproto\fR
-Matches IP protocol type \fIproto\fR, which should be specified as a
-decimal number between 0 and 255, inclusive, e.g. 6 to match TCP
-packets.
+Matches IP protocol type \fIproto\fR, which is specified as a decimal 
+number between 0 and 255, inclusive (e.g. 6 to match TCP packets).
 
 .IP \fBtp_src=\fIport\fR
-Matches UDP or TCP source port \fIport\fR, which should be specified
-as a decimal number between 0 and 65535, inclusive, e.g. 80 to match
-packets originating from a HTTP server.
+Matches UDP or TCP source port \fIport\fR, which is specified as a decimal 
+number between 0 and 65535, inclusive (e.g. 80 to match packets originating 
+from a HTTP server).
 
 .IP \fBtp_dst=\fIport\fR
 Matches UDP or TCP destination port \fIport\fR.
 
 .IP \fBicmp_type=\fItype\fR
-Matches ICMP message with \fItype\fR, which should be specified as a decimal 
+Matches ICMP message with \fItype\fR, which is specified as a decimal 
 number between 0 and 255, inclusive.
 
 .IP \fBicmp_code=\fIcode\fR
@@ -399,11 +398,12 @@ Same as \fBdl_type=0x0806\fR.
 .PP
 The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field:
 
-.IP \fBactions=\fItarget\fR[\fB,\fItarget\fR...]\fR
+.IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
 Specifies a comma-separated list of actions to take on a packet when the 
-flow entry matches.  The \fItarget\fR may be a decimal port number 
-designating the physical port on which to output the packet, or one of 
-the following keywords:
+flow entry matches.  If no \fItarget\fR is specified, then packets
+matching the flow are dropped.  The \fItarget\fR may be a decimal port 
+number designating the physical port on which to output the packet, or one 
+of the following keywords:
 
 .RS
 .IP \fBoutput\fR:\fIport\fR
@@ -465,9 +465,12 @@ The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands
 support an additional optional field:
 
 .IP \fBpriority=\fIvalue\fR
-Sets the priority of the flow to be added or deleted to \fIvalue\fR,
-which should be a number between 0 and 65535, inclusive.  If this
-field is not specified, it defaults to 32768.
+The priority at which a wildcarded entry will match in comparison to
+others.  \fIvalue\fR is a number between 0 and 65535, inclusive.  A higher 
+\fIvalue\fR will match before a lower one.  An exact-match entry will always 
+have priority over an entry containing wildcards, so it has an implicit 
+priority value of 65535.  When adding a flow, if the field is not specified, 
+the flow's priority will default to 32768.
 
 .PP
 The \fBadd-flow\fR and \fBadd-flows\fR commands support additional
@@ -504,6 +507,35 @@ as shown by the \fBdump-tables\fR command.
 If this field is not specified, or if \fInumber\fR is given as
 \fB255\fR, statistics are gathered about flows from all tables.
 
+.SS "Table Entry Output"
+
+The \fBdump-tables\fR and \fBdump-aggregate\fR commands print information 
+about the entries in a datapath's tables.  Each line of output is a 
+unique flow entry, which begins with some common information:
+
+.IP \fBduration\fR
+The number of seconds the entry has been in the table.
+
+.IP \fBtable_id\fR
+The table that contains the flow.  When a packet arrives, the switch 
+begins searching for an entry at the lowest numbered table.  Tables are 
+numbered as shown by the \fBdump-tables\fR command.
+
+.IP \fBpriority\fR
+The priority of the entry in relation to other entries within the same
+table.  A higher value will match before a lower one.
+
+.IP \fBn_packets\fR
+The number of packets that have matched the entry.
+
+.IP \fBn_bytes\fR
+The total number of bytes from packets that have matched the entry.
+
+.PP
+The rest of the line consists of a description of the flow entry as 
+described in \fBFlow Syntax\fR, above.
+
+
 .SH OPTIONS
 .TP
 \fB--strict\fR
@@ -581,6 +613,7 @@ Prints the flow entries in the switch.
 
 .SH "SEE ALSO"
 
+.BR vswitchd (8),
 .BR secchan (8),
 .BR controller (8),
 .BR udatapath (8),