[ovs-dev] [PATCH] dpif: Document datapath masking.

Ben Pfaff blp at nicira.com
Tue Nov 12 23:20:01 UTC 2013


Signed-off-by: Ben Pfaff <blp at nicira.com>
---
 lib/dpif.c |   12 ++++++++----
 lib/dpif.h |   44 +++++++++++++++++++++++++++++++++++---------
 2 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/lib/dpif.c b/lib/dpif.c
index 783a7cb..63a7ab6 100644
--- a/lib/dpif.c
+++ b/lib/dpif.c
@@ -883,15 +883,19 @@ dpif_flow_put__(struct dpif *dpif, const struct dpif_flow_put *put)
 
 /* Adds or modifies a flow in 'dpif'.  The flow is specified by the Netlink
  * attribute OVS_FLOW_ATTR_KEY with types OVS_KEY_ATTR_* in the 'key_len' bytes
- * starting at 'key', and OVS_FLOW_ATTR_MASK with types of OVS_KEY_ATTR_* in the
- * 'mask_len' bytes starting at 'mask'. The associated actions are specified by
- * the Netlink attributes with types OVS_ACTION_ATTR_* in the 'actions_len'
- * bytes starting at 'actions'.
+ * starting at 'key', and OVS_FLOW_ATTR_MASK with types of OVS_KEY_ATTR_* in
+ * the 'mask_len' bytes starting at 'mask'. The associated actions are
+ * specified by the Netlink attributes with types OVS_ACTION_ATTR_* in the
+ * 'actions_len' bytes starting at 'actions'.
  *
  * - If the flow's key does not exist in 'dpif', then the flow will be added if
  *   'flags' includes DPIF_FP_CREATE.  Otherwise the operation will fail with
  *   ENOENT.
  *
+ *   The datapath may reject attempts to insert overlapping flows with EINVAL,
+ *   but clients should not rely on this: avoiding overlapping flows is
+ *   primarily the client's responsibility.
+ *
  *   If the operation succeeds, then 'stats', if nonnull, will be zeroed.
  *
  * - If the flow's key does exist in 'dpif', then the flow's actions will be
diff --git a/lib/dpif.h b/lib/dpif.h
index 6db6ad3..499ee79 100644
--- a/lib/dpif.h
+++ b/lib/dpif.h
@@ -103,12 +103,12 @@
  * Flow Table
  * ==========
  *
- * The flow table is a hash table of "flow entries".  Each flow entry contains:
+ * The flow table is a collection of "flow entries".  Each flow entry contains:
  *
  *    - A "flow", that is, a summary of the headers in an Ethernet packet.  The
- *      flow is the hash key and thus must be unique within the flow table.
- *      Flows are fine-grained entities that include L2, L3, and L4 headers.  A
- *      single TCP connection consists of two flows, one in each direction.
+ *      flow must be unique within the flow table.  Flows are fine-grained
+ *      entities that include L2, L3, and L4 headers.  A single TCP connection
+ *      consists of two flows, one in each direction.
  *
  *      In Open vSwitch userspace, "struct flow" is the typical way to describe
  *      a flow, but the datapath interface uses a different data format to
@@ -117,11 +117,37 @@
  *      "struct ovs_key_*" in include/linux/openvswitch.h for details.
  *      lib/odp-util.h defines several functions for working with these flows.
  *
- *      (In case you are familiar with OpenFlow, datapath flows are analogous
- *      to OpenFlow flow matches.  The most important difference is that
- *      OpenFlow allows fields to be wildcarded and prioritized, whereas a
- *      datapath's flow table is a hash table so every flow must be
- *      exact-match, thus without priorities.)
+ *    - A "mask" that, for each bit in the flow, specifies whether the datapath
+ *      should consider the corresponding flow bit when deciding whether a
+ *      given packet matches the flow entry.  The original datapath design did
+ *      not support matching: every flow entry was exact match.  With the
+ *      addition of a mask, the interface supports datapaths with a spectrum of
+ *      wildcard matching capabilities, from those that only support exact
+ *      matches to those that support bitwise wildcarding on the entire flow
+ *      key, as well as datapaths with capabilities somewhere in between.
+ *
+ *      Datapaths do not provide a way to query their wildcarding capabilities,
+ *      nor is it expected that the client should attempt to probe for the
+ *      details of their support.  Instead, a client installs flows with masks
+ *      that wildcard as many bits as acceptable.  The datapath then actually
+ *      wildcards as many of those bits as it can and changes the wildcard bits
+ *      that it does not support into exact match bits.  A datapath that can
+ *      wildcard any bit, for example, would install the supplied mask, an
+ *      exact-match only datapath would install an exact-match mask regardless
+ *      of what mask the client supplied, and a datapath in the middle of the
+ *      spectrum would selectively change some wildcard bits into exact match
+ *      bits.
+ *
+ *      Regardless of the requested or installed mask, the datapath retains the
+ *      original flow supplied by the client.  (It does not, for example, "zero
+ *      out" the wildcarded bits.)  This allows the client to unambiguously
+ *      identify the flow entry in later flow table operations.
+ *
+ *      The flow table does not have priorities; that is, all flow entries have
+ *      equal priority.  Detecting overlapping flow entries is expensive in
+ *      general, so the datapath is not required to do it.  It is primarily the
+ *      client's responsibility not to install flow entries whose flow and mask
+ *      combinations overlap.
  *
  *    - A list of "actions" that tell the datapath what to do with packets
  *      within a flow.  Some examples of actions are OVS_ACTION_ATTR_OUTPUT,
-- 
1.7.10.4




More information about the dev mailing list