Implement OpenFlow 1.1+ "groups" protocol.

This doesn't include a dpif implementation of groups functionality.  In its
current form, it is untested.

Signed-off-by: Neil Zhu <zhuj@centecnetworks.com>
Co-authored-by: Ben Pfaff <blp@nicira.com>
Signed-off-by: Ben Pfaff <blp@nicira.com>
Co-authored-by: Simon Horman <horms@verge.net.au>
Signed-off-by: Simon Horman <horms@verge.net.au>
Co-authored-by: Jarno Rajahalme <jrajahalme@nicira.com>
Signed-off-by: Jarno Rajahalme <jrajahalme@nicira.com>

1 files changed, 116 insertions, 0 deletions

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index 85b2e44ca..18a177243 100644
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -190,6 +190,29 @@ statistics are printed for all queues on \fIport\fR; if only
 \fIport\fR is omitted, then statistics are printed for \fIqueue\fR on
 every port where it exists.
 .
+.SS "OpenFlow 1.1+ Switch Management Commands"
+.
+The following commands work only with switches that support OpenFlow
+1.1 or later.  Because support for OpenFlow 1.1 and later is still
+experimental in Open vSwitch, it is necessary to explicitly enable
+these protocol versions in \fBovs\-ofctl\fR (using \fB\-O\fR) and in
+the switch itself (with the \fBprotocols\fR column in the \fBBridge\fR
+table).  For more information, see ``Q: What versions of OpenFlow does
+Open vSwitch support?'' in the Open vSwitch FAQ.
+.
+.IP "\fBdump\-groups \fIswitch"
+Prints to the console all group entries in \fIswitch\fR's tables. Each line
+of output is a group entry as described in \fBGroup Syntax\fR below.
+.
+.IP "\fBdump\-group\-features \fIswitch"
+Prints to the console the group features of the \fIswitch\fR.
+.
+.IP "\fBdump\-group-stats \fIswitch \fR[\fIgroups\fR]"
+Prints to the console statistics for the specified \fIgroups in the
+\fIswitch\fR's tables.  If \fIgroups\fR is omitted then statistics for all
+groups are printed.  See \fBGroup Syntax\fR, below, for the syntax of
+\fIgroups\fR.
+.
 .SS "OpenFlow Switch Flow Table Commands"
 .
 These commands manage the flow table in an OpenFlow switch.  In each
@@ -258,6 +281,30 @@ keyword \fBLOCAL\fR (the preferred way to refer to the OpenFlow
 ``local'' port), or the keyword \fBNONE\fR to indicate that the packet
 was generated by the switch itself.
 .
+.SS "OpenFlow Switch Group Table Commands"
+.
+These commands manage the group table in an OpenFlow switch.  In each
+case, \fIgroup\fR specifies a group entry in the format described in
+\fBGroup Syntax\fR, below, and \fIfile\fR is a text file that contains
+zero or more groups in the same syntax, one per line.
+
+.IP "\fBadd\-group \fIswitch group\fR"
+.IQ "\fBadd\-group \fIswitch \fB\- < \fIfile\fR"
+.IQ "\fBadd\-groups \fIswitch file\fR"
+Add each group entry to \fIswitch\fR's tables.
+.
+.IP "\fBmod\-group \fIswitch group\fR"
+.IQ "\fBmod\-group \fIswitch \fB\- < \fIfile\fR"
+Modify the action buckets in entries from \fIswitch\fR's tables for
+each group entry.
+.
+.IP "\fBdel\-groups \fIswitch\fR"
+.IQ "\fBdel\-groups \fIswitch \fR[\fIgroup\fR]"
+.IQ "\fBdel\-groups \fIswitch \fB\- < \fIfile\fR"
+Deletes entries from \fIswitch\fR's group table.  With only a
+\fIswitch\fR argument, deletes all groups.  Otherwise, deletes the group
+for each group entry.
+.
 .SS "OpenFlow Switch Monitoring Commands"
 .
 .IP "\fBsnoop \fIswitch\fR"
@@ -1439,6 +1486,75 @@ of \fBduration\fR.  (This is separate from \fBduration\fR because
 The integer number of seconds that have passed without any packets
 passing through the flow.
 .
+.SS "Group Syntax"
+.PP
+Some \fBovs\-ofctl\fR commands accept an argument that describes a group or
+groups.  Such flow descriptions comprise a series
+\fIfield\fB=\fIvalue\fR assignments, separated by commas or white
+space.  (Embedding spaces into a group description normally requires
+quoting to prevent the shell from breaking the description into
+multiple arguments.). Unless noted otherwise only the last instance
+of each field is honoured.
+.PP
+.IP \fBgroup_id=\fIid\fR
+The integer group id of group.
+When this field is specified in \fBdel-groups\fR or \fBdump-groups\fR,
+the keyword "all" may be used to designate all groups.
+.
+This field is required.
+
+
+.IP \fBtype=\fItype\fR
+The type of the group.  This \fBadd-group\fR, \fBadd-groups\fR and
+\fBdel-groups\fR command require this field.  The following keywords
+designated the allowed types:
+.RS
+.IP \fBall\fR
+Execute all buckets in the group.
+.IP \fBselect\fR
+Execute one bucket in the group.
+The switch should select the bucket in such a way that should implement
+equal load sharing is achieved.  The switch may optionally select the
+bucket based on bucket weights.
+.IP \fBindirect\fR
+Executes the one bucket in the group.
+.IP \fBff\fR
+.IQ \fBfast_failover\fR
+Executes the first live bucket in the group which is associated with
+a live port or group.
+.RE
+
+.IP \fBbucket\fR=\fIbucket_parameters\fR
+The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands
+require at least one bucket field. Bucket fields must appear after
+all other fields.
+.
+Multiple bucket fields to specify multiple buckets.
+The order in which buckets are specified corresponds to their order in
+the group. If the type of the group is "indirect" then only one group may
+be specified.
+.
+\fIbucket_parameters\fR consists of a list of \fIfield\fB=\fIvalue\fR
+assignments, separated by commas or white space followed by a
+comma-separated list of actions.
+The syntax of actions are same
+to \fBactions=\fR field described in \fBFlow Syntax\fR above.
+The fields for \fIbucket_parameters\fR are:
+.
+.RS
+.IP \fBweight=\fIvalue\fR
+The relative weight of the bucket as an integer. This may be used by the switch
+during bucket select for groups whose \fBtype\fR is \fBselect\fR.
+.IP \fBwatch_port=\fIport\fR
+Port used to determine liveness of group.
+This or the \fBwatch_group\fR field is required
+for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR.
+.IP \fBwatch_group=\fIgroup_id\fR
+Group identifier of group used to determine liveness of group.
+This or the \fBwatch_port\fR field is required
+for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR.
+.RE
+.
 .SH OPTIONS
 .TP
 \fB\-\-strict\fR