[ovs-dev] [PATCH] ovs-ofctl: Refine documentation of Geneve option mapping.

[Ben Pfaff]

Thanks, applied to master.

On Mon, Aug 03, 2015 at 02:26:09PM -0700, Alex Wang wrote:
> Thx for the refinement!~
> 
> Acked-by: Alex Wang <alexw at nicira.com>
> 
> On Mon, Aug 3, 2015 at 2:13 PM, Ben Pfaff <blp at nicira.com> wrote:
> 
> > In the commit message below, "match" on them, not "map" on them, sorry.
> >
> > On Mon, Aug 03, 2015 at 02:11:12PM -0700, Ben Pfaff wrote:
> > > The text didn't say how to actually map on them.  I took the liberty of
> > > massaging the text a little further, too.
> > >
> > > Suggested-by: Alex Wang <alexw at nicira.com>
> > > Signed-off-by: Ben Pfaff <blp at nicira.com>
> > > ---
> > >  utilities/ovs-ofctl.8.in | 47
> > ++++++++++++++++++++++++-----------------------
> > >  1 file changed, 24 insertions(+), 23 deletions(-)
> > >
> > > diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
> > > index 92a29f3..850fd76 100644
> > > --- 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"
> > > --
> > > 2.1.3
> > >
> >