DESIGN: Update flow_mod section to describe OpenFlow 1.1+ behavior.

Signed-off-by: Ben Pfaff <blp@nicira.com>

1 files changed, 118 insertions, 4 deletions

diff --git a/DESIGN b/DESIGN
index 0037eea10..d36b02507 100644
--- a/DESIGN
+++ b/DESIGN
@@ -84,8 +84,8 @@ OFPP_LOCAL as a physical port and support OFPAT_ENQUEUE on it as well.
 OFPT_FLOW_MOD
 =============
 
-The OpenFlow 1.0 specification for the behavior of OFPT_FLOW_MOD is
-confusing.  The following table summarizes the Open vSwitch
+The OpenFlow specification for the behavior of OFPT_FLOW_MOD is
+confusing.  The following tables summarize the Open vSwitch
 implementation of its behavior in the following categories:
 
     - "match on priority": Whether the flow_mod acts only on flows
@@ -93,7 +93,12 @@ implementation of its behavior in the following categories:
 
     - "match on out_port": Whether the flow_mod acts only on flows
       that output to the out_port included in the flow_mod message (if
-      out_port is not OFPP_NONE).
+      out_port is not OFPP_NONE).  OpenFlow 1.1 and later have a
+      similar feature (not listed separately here) for out_group.
+
+    - "match on flow_cookie": Whether the flow_mod acts only on flows
+      whose flow_cookie matches an optional controller-specified value
+      and mask.
 
     - "updates flow_cookie": Whether the flow_mod changes the
       flow_cookie of the flow or flows that it matches to the
@@ -120,6 +125,11 @@ implementation of its behavior in the following categories:
     - "zeros counters": Whether the flow_mod resets per-flow packet
       and byte counters to zero.
 
+    - "may add a new flow": Whether the flow_mod may add a new flow to
+      the flow table.  (Obviously this is always true for "add"
+      commands but in some OpenFlow versions "modify" and
+      "modify-strict" can also add new flows.)
+
     - "sends flow_removed message": Whether the flow_mod generates a
       flow_removed message for the flow or flows that it affects.
 
@@ -128,11 +138,17 @@ indicated behavior, "---" means that it does not, an empty cell means
 that the property is not applicable, and other values are explained
 below the table.
 
+OpenFlow 1.0
+------------
+
                                           MODIFY          DELETE
                              ADD  MODIFY  STRICT  DELETE  STRICT
                              ===  ======  ======  ======  ======
-match on priority            ---    ---     yes     ---     yes
+match on priority            yes    ---     yes     ---     yes
 match on out_port            ---    ---     ---     yes     yes
+match on flow_cookie         ---    ---     ---     ---     ---
+match on table_id            ---    ---     ---     ---     ---
+controller chooses table_id  ---    ---     ---
 updates flow_cookie          yes    yes     yes
 updates OFPFF_SEND_FLOW_REM  yes     +       +
 honors OFPFF_CHECK_OVERLAP   yes     +       +
@@ -141,6 +157,48 @@ updates hard_timeout         yes     +       +
 resets idle timer            yes     +       +
 resets hard timer            yes    yes     yes
 zeros counters               yes     +       +
+may add a new flow           yes    yes     yes
+sends flow_removed message   ---    ---     ---      %       %
+
+(+) "modify" and "modify-strict" only take these actions when they
+    create a new flow, not when they update an existing flow.
+
+(%) "delete" and "delete_strict" generates a flow_removed message if
+    the deleted flow or flows have the OFPFF_SEND_FLOW_REM flag set.
+    (Each controller can separately control whether it wants to
+    receive the generated messages.)
+
+OpenFlow 1.1
+------------
+
+OpenFlow 1.1 makes these changes:
+
+    - The controller now must specify the table_id of the flow match
+      searched and into which a flow may be inserted.  Behavior for a
+      table_id of 255 is undefined.
+
+    - A flow_mod, except an "add", can now match on the flow_cookie.
+
+    - When a flow_mod matches on the flow_cookie, "modify" and
+      "modify-strict" never insert a new flow.
+
+                                          MODIFY          DELETE
+                             ADD  MODIFY  STRICT  DELETE  STRICT
+                             ===  ======  ======  ======  ======
+match on priority            yes    ---     yes     ---     yes
+match on out_port            ---    ---     ---     yes     yes
+match on flow_cookie         ---    yes     yes     yes     yes
+match on table_id            yes    yes     yes     yes     yes
+controller chooses table_id  yes    yes     yes
+updates flow_cookie          yes    ---     ---
+updates OFPFF_SEND_FLOW_REM  yes     +       +
+honors OFPFF_CHECK_OVERLAP   yes     +       +
+updates idle_timeout         yes     +       +
+updates hard_timeout         yes     +       +
+resets idle timer            yes     +       +
+resets hard timer            yes    yes     yes
+zeros counters               yes     +       +
+may add a new flow           yes     #       #
 sends flow_removed message   ---    ---     ---      %       %
 
 (+) "modify" and "modify-strict" only take these actions when they
@@ -151,6 +209,62 @@ sends flow_removed message   ---    ---     ---      %       %
     (Each controller can separately control whether it wants to
     receive the generated messages.)
 
+(#) "modify" and "modify-strict" only add a new flow if the flow_mod
+    does not match on any bits of the flow cookie
+
+OpenFlow 1.2
+------------
+
+OpenFlow 1.2 makes these changes:
+
+    - Only "add" commands ever add flows, "modify" and "modify-strict"
+      never do.
+
+    - A new flag OFPFF_RESET_COUNTS now controls whether "modify" and
+      "modify-strict" reset counters, whereas previously they never
+      reset counters (except when they inserted a new flow).
+
+                                          MODIFY          DELETE
+                             ADD  MODIFY  STRICT  DELETE  STRICT
+                             ===  ======  ======  ======  ======
+match on priority            yes    ---     yes     ---     yes
+match on out_port            ---    ---     ---     yes     yes
+match on flow_cookie         ---    yes     yes     yes     yes
+match on table_id            yes    yes     yes     yes     yes
+controller chooses table_id  yes    yes     yes
+updates flow_cookie          yes    ---     ---
+updates OFPFF_SEND_FLOW_REM  yes    ---     ---
+honors OFPFF_CHECK_OVERLAP   yes    ---     ---
+updates idle_timeout         yes    ---     ---
+updates hard_timeout         yes    ---     ---
+resets idle timer            yes    ---     ---
+resets hard timer            yes    yes     yes
+zeros counters               yes     &       &
+may add a new flow           yes    ---     ---
+sends flow_removed message   ---    ---     ---      %       %
+
+(%) "delete" and "delete_strict" generates a flow_removed message if
+    the deleted flow or flows have the OFPFF_SEND_FLOW_REM flag set.
+    (Each controller can separately control whether it wants to
+    receive the generated messages.)
+
+(&) "modify" and "modify-strict" reset counters if the
+    OFPFF_RESET_COUNTS flag is specified.
+
+OpenFlow 1.3
+------------
+
+OpenFlow 1.3 makes these changes:
+
+    - Behavior for a table_id of 255 is now defined, for "delete" and
+      "delete-strict" commands, as meaning to delete from all tables.
+      A table_id of 255 is now explicitly invalid for other commands.
+
+    - New flags OFPFF_NO_PKT_COUNTS and OFPFF_NO_BYT_COUNTS for "add"
+      operations.
+
+The table for 1.3 is the same as the one shown above for 1.2.
+
 
 VLAN Matching
 =============