[dpdk-dev] [PATCH v3 2/4] ethdev: Add tunnel encap/decap actions

[Declan Doherty <declan.doherty@intel.com>]

Add new flow action types and associated action data structures to
support the encapsulation and decapsulation of the virtual tunnel
endpoints.

The RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP action will cause the matching
flow to be encapsulated in the virtual tunnel endpoint overlay
defined in the tunnel_encap action data.

The RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP action will cause all virtual
tunnel endpoint overlays up to and including the first instance of
the flow item type defined in the tunnel_decap action data for the
matching flows.

Signed-off-by: Declan Doherty <declan.doherty@intel.com>
---
 doc/guides/prog_guide/rte_flow.rst | 77 ++++++++++++++++++++++++++++++++--
 lib/librte_ether/rte_flow.h        | 84 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 155 insertions(+), 6 deletions(-)

diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index fd33d19..106fb93 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -997,9 +997,11 @@ Actions
 
 Each possible action is represented by a type. Some have associated
 configuration structures. Several actions combined in a list can be assigned
-to a flow rule. That list is not ordered.
+to a flow rule. That list is not ordered, with the exception of  actions which
+modify the packet itself, these packet modification actions must be specified
+in the explicit order in which they are to be executed.
 
-They fall in three categories:
+They fall in four categories:
 
 - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
   processing matched packets by subsequent flow rules, unless overridden
@@ -1008,8 +1010,11 @@ They fall in three categories:
 - Non-terminating actions (PASSTHRU, DUP) that leave matched packets up for
   additional processing by subsequent flow rules.
 
+- Non-terminating meta actions that do not affect the fate of packets but result
+  in modification of the packet itself (SECURITY, TUNNEL_ENCAP, TUNNEL_DECAP).
+
 - Other non-terminating meta actions that do not affect the fate of packets
-  (END, VOID, MARK, FLAG, COUNT, SECURITY).
+  (END, VOID, MARK, FLAG, COUNT).
 
 When several actions are combined in a flow rule, they should all have
 different types (e.g. dropping a packet twice is not possible).
@@ -1486,6 +1491,72 @@ fields in the pattern items.
    | 1     | END      |
    +-------+----------+
 
+
+Action: ``TUNNEL_ENCAP``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Performs an encapsulation action by encapsulating the flows matched by the
+pattern items according to the network overlay defined in the
+``rte_flow_action_tunnel_encap`` pattern items.
+
+This action modifies the payload of matched flows. The pattern items specified
+in the ``rte_flow_action_tunnel_encap`` action structure must defined a valid
+set of overlay headers, from the Ethernet header up to the overlay header. The
+pattern must be terminated with the RTE_FLOW_ITEM_TYPE_END item type.
+
+- Non-terminating by default.
+
+.. _table_rte_flow_action_tunnel_encap:
+
+.. table:: TUNNEL_ENCAP
+
+   +-------------+---------------------------------------------+
+   | Field       | Value                                       |
+   +=============+=============================================+
+   | ``pattern`` | Virtual tunnel end-point pattern definition |
+   +-------------+---------------------------------------------+
+
+
+.. _table_rte_flow_action_tunnel_encap_example:
+
+.. table:: IPv4 VxLAN flow pattern example.
+
+   +-------+--------------------------+------------+
+   | Index | Flow Item Type           | Flow Item  |
+   +=======+==========================+============+
+   | 0     | RTE_FLOW_ITEM_TYPE_ETH   | eth item   |
+   +-------+--------------------------+------------+
+   | 1     | RTE_FLOW_ITEM_TYPE_IPV4  | ipv4 item  |
+   +-------+--------------------------+------------+
+   | 2     | RTE_FLOW_ITEM_TYPE_UDP   | udp item   |
+   +-------+--------------------------+------------+
+   | 3     | RTE_FLOW_ITEM_TYPE_VXLAN | vxlan item |
+   +-------+--------------------------+------------+
+   | 4     | RTE_FLOW_ITEM_TYPE_END   | NULL       |
+   +-------+--------------------------+------------+
+
+
+Action: ``TUNNEL_DECAP``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Performs a decapsulation action by stripping all headers of the virtual tunnel
+end-point overlay up to the header defined by the flow item type of flows
+matched by the pattern items.
+
+This action modifies the payload of matched flows. The flow item type specified
+in the ``rte_flow_action_tunnel_decap`` action structure must defined a valid
+set of overlay header type.
+
+- Non-terminating by default.
+
+.. _table_rte_flow_action_tunnel_decap:
+
+   +---------------+----------------------------------------------+
+   | Field         | Value                                        |
+   +===============+==============================================+
+   | ``item type`` | Item type of tunnel end-point to decapsulate |
+   +---------------+----------------------------------------------+
+
 Negative types
 ~~~~~~~~~~~~~~
 
diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h
index 7d1f89d..6d94423 100644
--- a/lib/librte_ether/rte_flow.h
+++ b/lib/librte_ether/rte_flow.h
@@ -854,14 +854,17 @@ struct rte_flow_item {
 	const void *mask; /**< Bit-mask applied to spec and last. */
 };
 
+
 /**
  * Action types.
  *
  * Each possible action is represented by a type. Some have associated
  * configuration structures. Several actions combined in a list can be
- * affected to a flow rule. That list is not ordered.
+ * affected to a flow rule. That list is not ordered, with the exception of
+ * actions which modify the packet itself, these packet modification actions
+ * must be specified in the explicit order in which they are to be executed.
  *
- * They fall in three categories:
+ * They fall in four categories:
  *
  * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
  *   processing matched packets by subsequent flow rules, unless overridden
@@ -870,6 +873,10 @@ struct rte_flow_item {
  * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
  *   for additional processing by subsequent flow rules.
  *
+ * - Non terminating meta actions that do not affect the fate of
+ *   packets but result in modification of the packet itself (SECURITY,
+ *   TUNNEL_ENCAP, TUNNEL_DECAP).
+ *
  * - Other non terminating meta actions that do not affect the fate of
  *   packets (END, VOID, MARK, FLAG, COUNT).
  *
@@ -1022,7 +1029,42 @@ enum rte_flow_action_type {
 	 *
 	 * See struct rte_flow_action_group_count.
 	 */
-	RTE_FLOW_ACTION_TYPE_GROUP_COUNT
+	RTE_FLOW_ACTION_TYPE_GROUP_COUNT,
+	/**
+	 * Encapsulate flow with tunnel defined in
+	 * rte_flow_action_tunnel_encap structure.
+	 *
+	 * See struct rte_flow_action_tunnel_encap.
+	 */
+	RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP,
+
+	/**
+	 * Decapsulate all the headers of the tunnel
+	 *
+	 * See struct rte_flow_action_tunnel_decap.
+	 */
+	RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP,
+
+	/**
+	 * Redirects packets to the logical group of the current device.
+	 *
+	 * In a logical hierarchy of groups, which can be used to represent a
+	 * physical of logical chaining of flow tables, this action allows the
+	 * terminating action to be a logical group of the same device.
+	 *
+	 * See struct rte_flow_action_group.
+	 */
+	RTE_FLOW_ACTION_TYPE_GROUP,
+
+	/**
+	 * [META]
+	 *
+	 * Set specific metadata field associated with packet which is then
+	 * available to further pipeline stages.
+	 *
+	 * See struct rte_flow_action_metadata.
+	 */
+	RTE_FLOW_ACTION_TYPE_METADATA
 };
 
 /**
@@ -1173,6 +1215,42 @@ struct rte_flow_action_group_count {
 };
 
 /**
+ * RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP
+ *
+ * Virtual tunnel end-point encapsulation action data.
+ *
+ * Non-terminating action by default.
+ */
+struct rte_flow_action_tunnel_encap {
+	struct rte_flow_action_item {
+		enum rte_flow_item_type type;
+		/**< Flow item type. */
+		const void *item;
+		/**< Flow item definition which points to the data of
+		 * corresponding rte_flow_item_type.
+		 */
+	} *pattern;
+	/**<
+	 * Tunnel pattern specification (list terminated by the END pattern
+	 * item).
+	 */
+};
+
+/**
+ * RTE_FLOW_ACTION_TYP_TUNNEL_DECAP
+ *
+ * Virtual tunnel end-point decapsulation action data.
+ *
+ * Non-terminating action by default.
+ */
+struct rte_flow_action_tunnel_decap {
+	enum rte_flow_item_type type;
+	/**<
+	 * Flow item type of virtual tunnel end-point to be decapsulated
+	 */
+};
+
+/**
  * Definition of a single action.
  *
  * A list of actions is terminated by a END action.
-- 
2.7.4