Re: [dpdk-dev] [RFC] ethdev: support tunnel encapsulation action

[Ori Kam <orika@mellanox.com>]

Due to the very short release cycle for this
18.08 release, and the need for good discussions,
It is more reasonable to target 18.11 for this proposal.

The intent is to have a good generic API for all tunnel encapsulation
and working well with all HW constraints.

So please let's start the multi-vendor discussion now.

For your information I have submitted a patch for MPLS only (as v2) 
to be integrated in 18.08 in the meantime. 

> -----Original Message-----
> From: Ori Kam
> Sent: Tuesday, June 5, 2018 6:48 PM
> To: ferruh.yigit@intel.com; declan.doherty@intel.com; dev@dpdk.org;
> Adrien Mazarguil <adrien.mazarguil@6wind.com>; Nélio Laranjeiro
> <nelio.laranjeiro@6wind.com>; Ori Kam <orika@mellanox.com>
> Subject: [RFC] ethdev: support tunnel encapsulation action
> 
> This RFC contain proposal to add generic support for tunnel
> encapsulation/decapsulation.
> 
> Due to the fact that there are many possible tunnel types
> and each tunnel type has number of header variations, there
> is a need for some generic command.
> 
> example for tunnel headers in case of MPLSoGRE:
> ETH / VLAN / IPV4 / GRE / MPLS / ETH / IP / L4-L7
> ETH / VLAN / IPV6 / GRE / MPLS / ETH / IP / L4-L7
> ETH / IPV4 / GRE / MPLS / ETH / IP / L4-L7
> ETH / IPV6 / GRE / MPLS / ETH / IP / L4-L7
> ETH / VLAN / IPV4 / GRE / MPLS / IP / L4-L7
> ETH / VLAN / IPV6 / GRE / MPLS / IP / L4-L7
> ETH / IPV4 / GRE / MPLS / IP / L4-L7
> ETH / IPV6 / GRE / MPLS / IP / L4-L7
> 
> As can be seen from the examples some of the encapsulation
> is done by overwriting the inner L2 packet spec.
> 
> To support all of those configuration it is much
> easer if we create 2 encap functions one that
> is used to encap L2 packet and one that is used
> to encap L3 packet by removing the L2 and applying
> the encapsulation header.
> 
> The use of void * buffer will enable the
> insertion of any valid encapsulation header.
> the use of such a buffer will also simplify the processing
> needed to validate and apply vs the use of rte_flow_items.
> The use of a buffer will also will be easer
> for some applications (for example vrouter)
> 
> For decap we will also have 2 actions
> one for decaping a packet with inner L2
> and one for decaping a packet with inner L3.
> when decaping L3 packet the user should
> supplay the L2 data which should be added to the inner packet.
> 
> Signed-off-by: Ori Kam <orika@mellanox.com>
> ---
>  doc/guides/prog_guide/rte_flow.rst |  141 ++++++++++++++-----------------
>  lib/librte_ethdev/rte_flow.h       |  165 +++++++++++++++++++++-------------
> -
>  2 files changed, 161 insertions(+), 145 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/rte_flow.rst
> b/doc/guides/prog_guide/rte_flow.rst
> index b305a72..7417833 100644
> --- a/doc/guides/prog_guide/rte_flow.rst
> +++ b/doc/guides/prog_guide/rte_flow.rst
> @@ -1969,112 +1969,95 @@ Implements ``OFPAT_PUSH_MPLS`` ("push a
> new MPLS tag") as defined by the
>     | ``ethertype`` | EtherType |
>     +---------------+-----------+
> 
> -Action: ``VXLAN_ENCAP``
> -^^^^^^^^^^^^^^^^^^^^^^^
> -
> -Performs a VXLAN encapsulation action by encapsulating the matched flow
> in the
> -VXLAN tunnel as defined in the``rte_flow_action_vxlan_encap`` flow items
> -definition.
> +Action: ``TUNNEL_ENCAP``
> +^^^^^^^^^^^^^^^^^^^^^^^^
> 
> -This action modifies the payload of matched flows. The flow definition
> specified
> -in the ``rte_flow_action_tunnel_encap`` action structure must define a valid
> -VLXAN network overlay which conforms with RFC 7348 (Virtual eXtensible
> Local
> -Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2
> Networks
> -over Layer 3 Networks). The pattern must be terminated with the
> -RTE_FLOW_ITEM_TYPE_END item type.
> +Perform a tunnel encapsulation action by encapsulating the matched flow
> with
> +the given buffer.
> 
> -.. _table_rte_flow_action_vxlan_encap:
> +This action modifies the payload of the matched flows.
> +The buffer must hold a valid tunnel encapsulation header.
> 
> -.. table:: VXLAN_ENCAP
> +.. _table_rte_flow_action_tunnel_encap:
> 
> +.. table:: TUNNEL_ENCAP
> +
>     +----------------+-------------------------------------+
>     | Field          | Value                               |
>     +================+=====================================+
> -   | ``definition`` | Tunnel end-point overlay definition |
> +   | ``type``       | Encapsulation tunnel type.          |
> +   +----------------+-------------------------------------+
> +   | ``buf``        | The encapsulation header.           |
> +   +----------------+-------------------------------------+
> +   | ``len``        | Buf len.                            |
>     +----------------+-------------------------------------+
> 
> -.. _table_rte_flow_action_vxlan_encap_example:
> -
> -.. table:: IPv4 VxLAN flow pattern example.
> -
> -   +-------+----------+
> -   | Index | Item     |
> -   +=======+==========+
> -   | 0     | Ethernet |
> -   +-------+----------+
> -   | 1     | IPv4     |
> -   +-------+----------+
> -   | 2     | UDP      |
> -   +-------+----------+
> -   | 3     | VXLAN    |
> -   +-------+----------+
> -   | 4     | END      |
> -   +-------+----------+
> -
> -Action: ``VXLAN_DECAP``
> -^^^^^^^^^^^^^^^^^^^^^^^
> +Action: ``TUNNEL_DECAP``
> +^^^^^^^^^^^^^^^^^^^^^^^^
> 
> -Performs a decapsulation action by stripping all headers of the VXLAN
> tunnel
> -network overlay from the matched flow.
> +Perform a tunnel decapsulation on L2 inner packet
> 
> -The flow items pattern defined for the flow rule with which a
> ``VXLAN_DECAP``
> -action is specified, must define a valid VXLAN tunnel as per RFC7348. If the
> -flow pattern does not specify a valid VXLAN tunnel then a
> -RTE_FLOW_ERROR_TYPE_ACTION error should be returned.
> +This action modifies the payload of the matched flows.
> +The buffer must hold a valid tunnel encapsulation header.
> 
> -This action modifies the payload of matched flows.
> +.. _table_rte_flow_action_tunnel_decap:
> 
> -Action: ``NVGRE_ENCAP``
> -^^^^^^^^^^^^^^^^^^^^^^^
> +.. table:: TUNNEL_DECAP
> +
> +   +----------------+-------------------------------------+
> +   | Field          | Value                               |
> +   +================+=====================================+
> +   | ``type``       | Encapsulation tunnel type.          |
> +   +----------------+-------------------------------------+
> 
> -Performs a NVGRE encapsulation action by encapsulating the matched flow
> in the
> -NVGRE tunnel as defined in the``rte_flow_action_tunnel_encap`` flow item
> -definition.
> +Action: ``TUNNEL_ENCAP_L3``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> -This action modifies the payload of matched flows. The flow definition
> specified
> -in the ``rte_flow_action_tunnel_encap`` action structure must defined a
> valid
> -NVGRE network overlay which conforms with RFC 7637 (NVGRE: Network
> -Virtualization Using Generic Routing Encapsulation). The pattern must be
> -terminated with the RTE_FLOW_ITEM_TYPE_END item type.
> +Perform a tunnel encapsulation action by encapsulating the matched flow
> with
> +the given buffer.
> +The given encapsulation is overwritten the original L2 part of the original
> +packet.
> 
> -.. _table_rte_flow_action_nvgre_encap:
> +This action modifies the payload of the matched flows. The buffer must
> hold
> +a valid tunnel encapsulation header.
> 
> -.. table:: NVGRE_ENCAP
> +.. _table_rte_flow_action_tunnel_encap_l3:
> 
> +.. table:: TUNNEL_ENCAP_L3
> +
>     +----------------+-------------------------------------+
>     | Field          | Value                               |
>     +================+=====================================+
> -   | ``definition`` | NVGRE end-point overlay definition  |
> +   | ``type``       | Encapsulation tunnel type.          |
> +   +----------------+-------------------------------------+
> +   | ``buf``        | The encapsulation header.           |
> +   +----------------+-------------------------------------+
> +   | ``len``        | Buf len.                            |
>     +----------------+-------------------------------------+
> 
> -.. _table_rte_flow_action_nvgre_encap_example:
> -
> -.. table:: IPv4 NVGRE flow pattern example.
> -
> -   +-------+----------+
> -   | Index | Item     |
> -   +=======+==========+
> -   | 0     | Ethernet |
> -   +-------+----------+
> -   | 1     | IPv4     |
> -   +-------+----------+
> -   | 2     | NVGRE    |
> -   +-------+----------+
> -   | 3     | END      |
> -   +-------+----------+
> +Action: ``TUNNEL_DECAP_L3``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> -Action: ``NVGRE_DECAP``
> -^^^^^^^^^^^^^^^^^^^^^^^
> +Perform a tunnel decapsulation action by removing the encapsulating
> packet header
> +and adding the L2 header which is suplied in the buf parameter.
> 
> -Performs a decapsulation action by stripping all headers of the NVGRE
> tunnel
> -network overlay from the matched flow.
> +This action modifies the payload of the matched flows.
> +The buffer must hold a valid L2 header and the flow must match patteran
> with the
> +selected tunnel type.
> 
> -The flow items pattern defined for the flow rule with which a
> ``NVGRE_DECAP``
> -action is specified, must define a valid NVGRE tunnel as per RFC7637. If the
> -flow pattern does not specify a valid NVGRE tunnel then a
> -RTE_FLOW_ERROR_TYPE_ACTION error should be returned.
> +.. _table_rte_flow_action_tunnel_decap_l3:
> 
> -This action modifies the payload of matched flows.
> +.. table:: TUNNEL_DECAP_L3
> +
> +   +----------------+-------------------------------------+
> +   | Field          | Value                               |
> +   +================+=====================================+
> +   | ``type``       | Encapsulation tunnel type.          |
> +   +----------------+-------------------------------------+
> +   | ``buf``        | The encapsulation header.           |
> +   +----------------+-------------------------------------+
> +   | ``len``        | Buf len.                            |
> +   +----------------+-------------------------------------+
> 
>  Negative types
>  ~~~~~~~~~~~~~~
> diff --git a/lib/librte_ethdev/rte_flow.h b/lib/librte_ethdev/rte_flow.h
> index f8ba71c..cc01786 100644
> --- a/lib/librte_ethdev/rte_flow.h
> +++ b/lib/librte_ethdev/rte_flow.h
> @@ -1473,40 +1473,74 @@ enum rte_flow_action_type {
>  	RTE_FLOW_ACTION_TYPE_OF_PUSH_MPLS,
> 
>  	/**
> -	 * Encapsulate flow in VXLAN tunnel as defined in
> -	 * rte_flow_action_vxlan_encap action structure.
> + 	 * Encapsulte a packet with tunnel header.
> + 	 *
> + 	 * See struct rte_flow_action_tunnel_encap.
> + 	 */
> +	RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP,
> +
> +	/**
> + 	 * Encapsulte a packet with tunnel header replacing
> + 	 * the inner L2 data.
> + 	 *
> + 	 * See struct rte_flow_action_tunnel_encap_l3.
> + 	 */
> +	RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP_L3,
> +
> +	/**
> +	 * Decapsulate outer most tunnel from matched flow.
>  	 *
> -	 * See struct rte_flow_action_vxlan_encap.
> +	 * If flow pattern does not define a valid tunnel then
> +	 * the PMD should return a RTE_FLOW_ERROR_TYPE_ACTION
> +	 * error.
>  	 */
> -	RTE_FLOW_ACTION_TYPE_VXLAN_ENCAP,
> +	RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP,
> 
>  	/**
> -	 * Decapsulate outer most VXLAN tunnel from matched flow.
> +	 * Decapsulate outer most tunnel from matched flow and replace
> +	 * the L2 header with the new header.
> +	 * Valid header must be L2 only.
>  	 *
> -	 * If flow pattern does not define a valid VXLAN tunnel (as specified
> by
> -	 * RFC7348) then the PMD should return a
> RTE_FLOW_ERROR_TYPE_ACTION
> +	 * If flow pattern does not define a valid tunnel then
> +	 * the PMD should return a RTE_FLOW_ERROR_TYPE_ACTION
>  	 * error.
> +	 *
> +	 * See struct rte_flow_action_tunnel_decap_l3
>  	 */
> -	RTE_FLOW_ACTION_TYPE_VXLAN_DECAP,
> +	RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP_L3,
> +};
> 
> +enum rte_flow_tunnel_type {
>  	/**
> -	 * Encapsulate flow in NVGRE tunnel defined in the
> -	 * rte_flow_action_nvgre_encap action structure.
> -	 *
> -	 * See struct rte_flow_action_nvgre_encap.
> +	 * VXLAN tunnel type.
>  	 */
> -	RTE_FLOW_ACTION_TYPE_NVGRE_ENCAP,
> +	RTE_FLOW_TUNNEL_TYPE_VXLAN,
> 
>  	/**
> -	 * Decapsulate outer most NVGRE tunnel from matched flow.
> -	 *
> -	 * If flow pattern does not define a valid NVGRE tunnel (as specified
> by
> -	 * RFC7637) then the PMD should return a
> RTE_FLOW_ERROR_TYPE_ACTION
> -	 * error.
> +	 * VXLAN_GPE tunnel type.
>  	 */
> -	RTE_FLOW_ACTION_TYPE_NVGRE_DECAP,
> -};
> +	RTE_FLOW_TUNNEL_TYPE_VXLAN_GPE,
> 
> +	/**
> +	 * MPLSoGRE tunnel type.
> +	 */
> +	RTE_FLOW_TUNNEL_TYPE_MPLSoGRE,
> +
> +	/**
> +	 * MPLSoUDP tunnel type.
> +	 */
> +	RTE_FLOW_TUNNEL_TYPE_MPLSoUDP,
> +
> +	/**
> +	 * NVGRE tunnel type.
> +	 */
> +	RTE_FLOW_TUNNEL_TYPE_NVGRE,
> +
> +	/**
> +	 * GRE tunnel type.
> +	 */
> +	RTE_FLOW_TUNNEL_TYPE_GRE,
> +};
>  /**
>   * RTE_FLOW_ACTION_TYPE_MARK
>   *
> @@ -1526,7 +1560,7 @@ struct rte_flow_action_mark {
>   * @b EXPERIMENTAL: this structure may change without prior notice
>   *
>   * RTE_FLOW_ACTION_TYPE_JUMP
> - *
> + o*
>   * Redirects packets to a group on the current device.
>   *
>   * In a hierarchy of groups, which can be used to represent physical or logical
> @@ -1803,69 +1837,68 @@ struct rte_flow_action_of_push_mpls {
>   * @warning
>   * @b EXPERIMENTAL: this structure may change without prior notice
>   *
> - * RTE_FLOW_ACTION_TYPE_VXLAN_ENCAP
> - *
> - * VXLAN tunnel end-point encapsulation data definition
> + * RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP
>   *
> - * The tunnel definition is provided through the flow item pattern, the
> - * provided pattern must conform to RFC7348 for the tunnel specified. The
> flow
> - * definition must be provided in order from the
> RTE_FLOW_ITEM_TYPE_ETH
> - * definition up the end item which is specified by
> RTE_FLOW_ITEM_TYPE_END.
> + * Tunnel end-point encapsulation data definition.
>   *
> - * The mask field allows user to specify which fields in the flow item
> - * definitions can be ignored and which have valid data and can be used
> - * verbatim.
> - *
> - * Note: the last field is not used in the definition of a tunnel and can be
> - * ignored.
> + * The tunnel definition is provided through the use of buffer that
> + * holds the encapsulating header.
> + * Provided header must be a valid outer tunnel header.
> + */
> +struct rte_flow_action_tunnel_encap {
> +	enum rte_flow_tunnel_type type; /**< The tunnel type. */
> +	void *buf; /**< The header to be used. */
> +	uint32_t len; /**< The buf len. */
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
>   *
> - * Valid flow definition for RTE_FLOW_ACTION_TYPE_VXLAN_ENCAP
> include:
> + * RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP
>   *
> - * - ETH / IPV4 / UDP / VXLAN / END
> - * - ETH / IPV6 / UDP / VXLAN / END
> - * - ETH / VLAN / IPV4 / UDP / VXLAN / END
> + * Tunnel end-point dencapsulation data definition.
>   *
> + * The tunnel type must match the flow rule spec.
>   */
> -struct rte_flow_action_vxlan_encap {
> -	/**
> -	 * Encapsulating vxlan tunnel definition
> -	 * (terminated by the END pattern item).
> -	 */
> -	struct rte_flow_item *definition;
> +struct rte_flow_action_tunnel_decap {
> +	enum rte_flow_tunnel_type type; /**< The tunnel type. */
>  };
> 
>  /**
>   * @warning
>   * @b EXPERIMENTAL: this structure may change without prior notice
>   *
> - * RTE_FLOW_ACTION_TYPE_NVGRE_ENCAP
> - *
> - * NVGRE tunnel end-point encapsulation data definition
> - *
> - * The tunnel definition is provided through the flow item pattern  the
> - * provided pattern must conform with RFC7637. The flow definition must
> be
> - * provided in order from the RTE_FLOW_ITEM_TYPE_ETH definition up the
> end item
> - * which is specified by RTE_FLOW_ITEM_TYPE_END.
> + * RTE_FLOW_ACTION_TYPE_TUNNEL_ENCAP_L3
>   *
> - * The mask field allows user to specify which fields in the flow item
> - * definitions can be ignored and which have valid data and can be used
> - * verbatim.
> + * Tunnel end-point encapsulation over the inner L2 data definition.
>   *
> - * Note: the last field is not used in the definition of a tunnel and can be
> - * ignored.
> + * The tunnel definition is provided through the use of buffer that
> + * holds the encapsulating header.
> + * Provided header must be a valid outer tunnel header.
> + */
> +struct rte_flow_action_tunnel_encap_l3 {
> +	enum rte_flow_tunnel_type type; /**< The tunnel type. */
> +	void *buf; /**< The header to be used. */
> +	uint32_t len; /**< The buf len. */
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
>   *
> - * Valid flow definition for RTE_FLOW_ACTION_TYPE_NVGRE_ENCAP
> include:
> + * RTE_FLOW_ACTION_TYPE_TUNNEL_DECAP_L3
>   *
> - * - ETH / IPV4 / NVGRE / END
> - * - ETH / VLAN / IPV6 / NVGRE / END
> + * Tunnel end-point dencapsulation data definition.
> + * after the decapsulation, the L2 of the resulted packet
> + * is replaced with the supplied buffer.
>   *
> + * The tunnel type must match the flow rule spec.
>   */
> -struct rte_flow_action_nvgre_encap {
> -	/**
> -	 * Encapsulating vxlan tunnel definition
> -	 * (terminated by the END pattern item).
> -	 */
> -	struct rte_flow_item *definition;
> +struct rte_flow_action_tunnel_decap_l3 {
> +	enum rte_flow_tunnel_type type; /**< The tunnel type. */
> +	void *buf; /**< The L2 header to be used.*/
> +	uint32_t len; /**< The len of the buf. */
>  };
> 
>  /*
> --
> 1.7.1