ofp-actions: Support OF1.5 (draft) masked Set-Field, merge with reg_load.

[cascardo/ovs.git] / utilities / ovs-ofctl.8.in

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index ac7c9dc..bcc3f33 100644 (file)
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -1424,12 +1424,31 @@ In OpenFlow 1.0 through 1.4, \fBmove\fR uses an Open vSwitch extension
 to OpenFlow.  In OpenFlow 1.5, \fBmove\fR uses the OpenFlow 1.5
 (draft) standard \fBcopy_field\fR action.
 .
-.IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
-Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
-in field \fIdst\fR.
-.IP
-Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
-\fB110111\fR) into bits 0 through 5, inclusive, in register 2.
+.IP "\fBset_field:\fIvalue\fR[/\fImask\fR]\fB\->\fIdst"
+.IQ "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
+Loads a literal value into a field or part of a field.  With
+\fBset_field\fR, \fBvalue\fR and the optional \fBmask\fR are given in
+the customary syntax for field \fIdst\fR, which is expressed as a
+field name.  For example, \fBset_field:00:11:22:33:44:55->eth_src\fR
+sets the Ethernet source address to 00:11:22:33:44:55.  With
+\fBload\fR, \fIvalue\fR must be an integer value (in decimal or
+prefixed by \fB0x\fR for hexadecimal) and \fIdst\fR is the NXM or OXM
+name for the field.  For example,
+\fBload:0x001122334455->OXM_OF_ETH_DST[]\fR has the same effect as the
+prior \fBset_field\fR example.
+.IP
+The two forms exist for historical reasons.  Open vSwitch 1.1
+introduced \fBNXAST_REG_LOAD\fR as a Nicira extension to OpenFlow 1.0
+and used \fBload\fR to express it.  Later, OpenFlow 1.2 introduced a
+standard \fBOFPAT_SET_FIELD\fR action that was restricted to loading
+entire fields, so Open vSwitch added the form \fBset_field\fR with
+this restriction.  OpenFlow 1.5 extended \fBOFPAT_SET_FIELD\fR to the
+point that it became a superset of \fBNXAST_REG_LOAD\fR.  Open vSwitch
+translates either syntax as necessary for the OpenFlow version in use:
+in OpenFlow 1.0 and 1.1, \fBNXAST_REG_LOAD\fR; in OpenFlow 1.2, 1.3,
+and 1.4, \fBNXAST_REG_LOAD\fR for \fBload\fR or for loading a
+subfield, \fBOFPAT_SET_FIELD\fR otherwise; and OpenFlow 1.5 and later,
+\fBOFPAT_SET_FIELD\fR.
 .
 .IP "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]"
 Pushes \fIstart\fR to \fIend\fR bits inclusive, in fields
@@ -1448,14 +1467,6 @@ Example: \fBpop:NXM_NX_REG2[0..5]\fR pops the value from top of the stack.
 Set register 2 bits 0 through 5, inclusive, based on bits 0 through 5 from the
 value just popped.
 .
-.IP "\fBset_field:\fIvalue\fB\->\fIdst"
-Writes the literal \fIvalue\fR into the field \fIdst\fR, which should
-be specified as a name used for matching.  (This is similar to
-\fBload\fR but more closely matches the set-field action defined in
-OpenFlow 1.2 and above.)
-.
-.IP
-Example: \fBset_field:00:11:22:33:44:55->eth_src\fR.
 .
 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,