ovs-ofctl: Refine documentation of Geneve option mapping.

The text didn't say how to actually match on them.  I took the liberty of
massaging the text a little further, too.

Suggested-by: Alex Wang <alexw@nicira.com>
Signed-off-by: Ben Pfaff <blp@nicira.com>
Acked-by: Alex Wang <alexw@nicira.com>

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index 92a29f3..850fd76 100644 (file)
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -421,14 +421,25 @@ buckets of the group are removed.
 .
 .SS "OpenFlow Switch Geneve Option Table Commands"
 .
-In order to work with Geneve options, it is necessary to maintain a mapping
-table between an option (defined by <class, type, length>) and an NXM field
-that can be operated on for the purposes of matches, actions, etc. This
-mapping must be explicitly specified by the user through the following
-commands. The format for \fIoptions\fR is given in \fBOption Syntax\fR below.
+Open vSwitch maintains a mapping table between Geneve options (defined
+by <class, type, length>) and an NXM field \fBtun_metadata\fIn\fR,
+where \fIn\fR ranges from 0 to 63, that can be operated on for the
+purposes of matches, actions, etc. This mapping must be explicitly
+specified by the user through the following commands.
 
-Note that a given mapping should not be changed while it is in active use by
-a flow. The result of doing so is undefined.
+A Geneve option mapping is specified with the syntax
+\fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR.
+When an option mapping exists for a given \fBtun_metadata\fIn\fR,
+matching on the defined field becomes possible, e.g.:
+
+.RS
+ovs-ofctl add-geneve-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
+.PP
+ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller
+.RE
+
+A mapping should not be changed while it is in active
+use by a flow. The result of doing so is undefined.
 
 Currently, the Geneve mapping table is shared between all OpenFlow
 switches in a given instance of Open vSwitch. This restriction will
@@ -437,29 +448,19 @@ be lifted in the future to allow for easier management.
 These commands are Nicira extensions to OpenFlow and require Open vSwitch
 2.5 or later.
 
-.IP "\fBadd\-geneve\-map \fIswitch options\fR"
-Add each option entry to \fIswitch\fR's tables. Duplicate fields are
+.IP "\fBadd\-geneve\-map \fIswitch option\fR[\fB,\fIoption\fR]..."
+Add each \fIoption\fR to \fIswitch\fR's tables. Duplicate fields are
 rejected.
 .
-.IP "\fBdel\-geneve\-map \fIswitch \fR[\fIoptions\fR]"
-Delete each option entry in \fIswitch\fR's tables based on its field index.
-Fields that aren't already mapped will be ignored. If no options are
-specified then the entire table will be cleared.
+.IP "\fBdel\-geneve\-map \fIswitch \fR[\fIoption\fR[\fB,\fIoption\fR]]..."
+Delete each \fIoption\fR from \fIswitch\fR's table, or all Geneve option
+mapping if no \fIoption\fR is specified.
+Fields that aren't mapped are ignored.
 .
 .IP "\fBdump\-geneve\-map \fIswitch\fR"
 Show the currently mapped fields in the switch's option table as well
 as switch capabilities.
 .
-.IP "\fBOption Syntax\fR"
-\fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR
-
-An option can be specified in this form (repeating as necessary and
-separated by commas). For example, the follow is used to map a new option:
-
-.RS
-add-geneve-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
-.RE
-.
 .SS "OpenFlow Switch Monitoring Commands"
 .
 .IP "\fBsnoop \fIswitch\fR"