From: Ben Pfaff Date: Wed, 13 Nov 2013 01:10:16 +0000 (-0800) Subject: dpif: Document datapath masking. X-Git-Tag: sliver-openvswitch-2.0.90-1~5^2~35 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=ee75c5460e8a038faf8b17d81facb51cd866b83d;hp=9dd165e0508143d36c73f258d8bcfdbbb356830a;p=sliver-openvswitch.git dpif: Document datapath masking. Signed-off-by: Ben Pfaff Acked-by: Andy Zhou --- diff --git a/lib/dpif.c b/lib/dpif.c index 783a7cb77..f3845db81 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 + * or EEXIST, 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 6db6ad38b..499ee7917 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,