[dpdk-dev] [v22.07] [PATCH v2] ethdev: mtr: support input color selection

[<jerinj@marvell.com>]

From: Jerin Jacob <jerinj@marvell.com>

Currently, meter object supports only DSCP based on input color table,
The patch enhance that to support VLAN based input color table,
color table based on inner field for the tunnel use case, and support
for fallback color per meter if packet based on a different field.

All of the above features are exposed through capability and added
additional capability to specify the implementation supports
more than one input color table per ethdev port

Suggested-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
Signed-off-by: Jerin Jacob <jerinj@marvell.com>
---
v2..v1:

- Fix seperate typo

v1..RFC:

Address the review comments by Cristian at
https://patches.dpdk.org/project/dpdk/patch/20210820082401.3778736-1-jerinj@marvell.com/

- Moved to v22.07 release
- Updated rte_mtr_input_color_method to support all VLAN, DSCP, Inner cases
- Added input_color_method
- Removed union between vlan_table and dscp_table
- Kept VLAN instead of PCP as HW coloring based on DEI(1bit), PCP(3 bits)

What is missing:
- 22.07 release notes update
- Testpmd and driver updates(Waiting for the review comments v1 API spec)
 .../traffic_metering_and_policing.rst         |  27 +++
 lib/ethdev/rte_mtr.h                          | 162 +++++++++++++++++-
 lib/ethdev/version.map                        |   3 +
 3 files changed, 190 insertions(+), 2 deletions(-)

diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/traffic_metering_and_policing.rst
index ceb5a96488..db8113f635 100644
--- a/doc/guides/prog_guide/traffic_metering_and_policing.rst
+++ b/doc/guides/prog_guide/traffic_metering_and_policing.rst
@@ -21,6 +21,7 @@ The main features are:
 * Policer actions (per meter output color): recolor, drop
 * Statistics (per policer output color)
 * Chaining multiple meter objects
+* Packet content based input color selection
 
 Configuration steps
 -------------------
@@ -105,3 +106,29 @@ traffic meter and policing library.
    * Adding one (or multiple) actions of the type ``RTE_FLOW_ACTION_TYPE_METER``
      to the list of meter actions (``struct rte_mtr_meter_policy_params::actions``)
      specified per color as show in :numref:`figure_rte_mtr_chaining`.
+
+Packet content based input color selection
+------------------------------------------
+
+The API supports selecting the input color based on the packet content.
+Following is the API usage model for the same.
+
+#. Probe the input color selection device capabilities using following
+   parameter using ``rte_mtr_capabilities_get()`` API
+   ``struct rte_mtr_capabilities::rte_mtr_input_color_method`` and
+   ``struct rte_mtr_capabilitie::separate_input_color_table_per_port``
+#. When creating the meter object using ``rte_mtr_create()``, configure
+   relevant input color selection parameters such as
+
+   * Select the input color method ``struct rte_mtr_params::input_color_method``
+
+   * Fill the tables ``struct rte_mtr_params::dscp_table``,
+     ``struct rte_mtr_params::dscp_table`` based on input color selected
+
+   * Update the ``struct rte_mtr_params::default_input_color`` to determine
+     the default input color in case the input packet does not match
+     the input color method
+
+   * If needed, update the input color table at runtime using
+     ``rte_mtr_meter_vlan_table_update()`` and ``rte_mtr_meter_dscp_table_update()``
+     APIs.
diff --git a/lib/ethdev/rte_mtr.h b/lib/ethdev/rte_mtr.h
index 40df0888c8..ced8bfb491 100644
--- a/lib/ethdev/rte_mtr.h
+++ b/lib/ethdev/rte_mtr.h
@@ -213,6 +213,80 @@ struct rte_mtr_meter_policy_params {
 	const struct rte_flow_action *actions[RTE_COLORS];
 };
 
+/**
+ * Input color method
+ */
+enum rte_mtr_input_color_method {
+	/**
+	 * The input color is always green.
+	 * The default_input_color is ignored for this method.
+	 * @see struct rte_mtr_params::default_input_color
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_COLOR_BLIND,
+	/**
+	 * If the input packet has at least one VLAN label, its input color is
+	 * detected by the outermost VLAN DEI(1bit), PCP(3 bits)
+	 * indexing into the struct rte_mtr_params::vlan_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::vlan_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_VLAN,
+	/**
+	 * If the input packet is IPv4 or IPv6, its input color is detected by
+	 * the outermost DSCP field indexing into the
+	 * struct rte_mtr_params::dscp_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::dscp_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_DSCP,
+	/**
+	 * If the input packet has at least one VLAN label, its input color is
+	 * detected by the outermost VLAN DEI(1bit), PCP(3 bits)
+	 * indexing into the struct rte_mtr_params::vlan_table.
+	 * If the input packet is IPv4 or IPv6, its input color is detected by
+	 * the outermost DSCP field indexing into the
+	 * struct rte_mtr_params::dscp_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::vlan_table
+	 * @see struct rte_mtr_params::dscp_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_VLAN_DSCP,
+	/**
+	 * If the input packet has at least one VLAN label, its input color is
+	 * detected by the innermost VLAN DEI(1bit), PCP(3 bits)
+	 * indexing into the struct rte_mtr_params::vlan_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::vlan_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN,
+	/**
+	 * If the input packet is IPv4 or IPv6, its input color is detected by
+	 * the innermost DSCP field indexing into the
+	 * struct rte_mtr_params::dscp_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::dscp_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_INNER_DSCP,
+	/**
+	 * If the input packet has at least one VLAN label, its input color is
+	 * detected by the innermost VLAN DEI(1bit), PCP(3 bits)
+	 * indexing into the struct rte_mtr_params::vlan_table.
+	 * If the input packet is IPv4 or IPv6, its input color is detected by
+	 * the innermost DSCP field indexing into the
+	 * struct rte_mtr_params::dscp_table.
+	 * Otherwise, the default_input_color is applied.
+	 * @see struct rte_mtr_params::default_input_color
+	 * @see struct rte_mtr_params::vlan_table
+	 * @see struct rte_mtr_params::dscp_table
+	 */
+	RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN_DSCP,
+};
+
 /**
  * Parameters for each traffic metering & policing object
  *
@@ -233,7 +307,15 @@ struct rte_mtr_params {
 	 */
 	int use_prev_mtr_color;
 
-	/** Meter input color. When non-NULL: it points to a pre-allocated and
+	/** Meter input color based on IP DSCP field.
+	 *
+	 * Valid when input_color_method set to any of the following
+	 * RTE_MTR_INPUT_COLOR_METHOD_DSCP,
+	 * RTE_MTR_INPUT_COLOR_METHOD_VLAN_DSCP,
+	 * RTE_MTR_INPUT_COLOR_METHOD_INNER_DSCP,
+	 * RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN_DSCP
+	 *
+	 * When non-NULL: it points to a pre-allocated and
 	 * pre-populated table with exactly 64 elements providing the input
 	 * color for each value of the IPv4/IPv6 Differentiated Services Code
 	 * Point (DSCP) input packet field. When NULL: it is equivalent to
@@ -244,9 +326,39 @@ struct rte_mtr_params {
 	 * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
 	 * at least one yellow or red color element, then the color aware mode
 	 * is configured.
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_DSCP
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_VLAN_DSCP
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_INNER_DSCP
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN_DSCP
+	 * @see struct rte_mtr_params::input_color_method
 	 */
 	enum rte_color *dscp_table;
-
+	/** Meter input color based on VLAN DEI(1bit), PCP(3 bits) fields.
+	 *
+	 * Valid when input_color_method set to any of the following
+	 * RTE_MTR_INPUT_COLOR_METHOD_VLAN,
+	 * RTE_MTR_INPUT_COLOR_METHOD_VLAN_DSCP,
+	 * RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN,
+	 * RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN_DSCP
+	 *
+	 * When non-NULL: it points to a pre-allocated and pre-populated
+	 * table with exactly 16 elements providing the input color for
+	 * each value of the DEI(1bit), PCP(3 bits) input packet field.
+	 * When NULL: it is equivalent to setting this parameter to an
+	 * all-green populated table (i.e. table with
+	 * all the 16 elements set to green color). The color blind mode
+	 * is configured by setting *use_prev_mtr_color* to 0 and
+	 * *vlan_table* to either NULL or to an all-green
+	 * populated table. When *use_prev_mtr_color* is non-zero value
+	 * or when *vlan_table* contains at least one yellow or
+	 * red color element, then the color aware mode is configured.
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_VLAN
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_VLAN_DSCP
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN
+	 * @see enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_INNER_VLAN_DSCP
+	 * @see struct rte_mtr_params::input_color_method
+	 */
+	enum rte_color *vlan_table;
 	/** Non-zero to enable the meter, zero to disable the meter at the time
 	 * of MTR object creation. Ignored when the meter profile indicated by
 	 * *meter_profile_id* is set to NONE.
@@ -261,6 +373,20 @@ struct rte_mtr_params {
 
 	/** Meter policy ID. @see rte_mtr_meter_policy_add() */
 	uint32_t meter_policy_id;
+
+	/** Input color method to select.
+	 * @see struct rte_mtr_params::dscp_table
+	 * @see struct rte_mtr_params::vlan_table
+	 */
+	enum rte_mtr_input_color_method input_color_method;
+
+	/** Input color to be set for the input packet when none of the
+	 * enabled input color methods is applicable to the input packet.
+	 * Ignored when this method is set to the
+	 * enum rte_mtr_input_color_method::RTE_MTR_INPUT_COLOR_METHOD_COLOR_BLIND
+	 * method.
+	 */
+	enum rte_color default_input_color;
 };
 
 /**
@@ -417,6 +543,14 @@ struct rte_mtr_capabilities {
 	 * @see enum rte_mtr_stats_type
 	 */
 	uint64_t stats_mask;
+
+	/** Input color methods supported. */
+	enum rte_mtr_input_color_method methods_supported;
+
+	/** When non-zero, it indicates that driver supports separate
+	 * input color table for given ethdev port.
+	 */
+	int separate_input_color_table_per_port;
 };
 
 /**
@@ -832,6 +966,30 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
 	enum rte_color *dscp_table,
 	struct rte_mtr_error *error);
 
+/**
+ * MTR object VLAN table update
+ *
+ * @param[in] port_id
+ *   The port identifier of the Ethernet device.
+ * @param[in] mtr_id
+ *   MTR object ID. Needs to be valid.
+ * @param[in] vlan_table
+ *   When non-NULL: it points to a pre-allocated and pre-populated table with
+ *   exactly 16 elements providing the input color for each value of the
+ *   each value of the DEI(1bit), PCP(3 bits) input packet field.
+ *   When NULL: it is equivalent to setting this parameter to an "all-green"
+ *   populated table (i.e. table with all the 16 elements set to green color).
+ * @param[out] error
+ *   Error details. Filled in only on error, when not NULL.
+ * @return
+ *   0 on success, non-zero error code otherwise.
+ */
+__rte_experimental
+int
+rte_mtr_meter_vlan_table_update(uint16_t port_id,
+	uint32_t mtr_id,
+	enum rte_color *vlan_table,
+	struct rte_mtr_error *error);
 /**
  * MTR object enabled statistics counters update
  *
diff --git a/lib/ethdev/version.map b/lib/ethdev/version.map
index d5cc56a560..430c620490 100644
--- a/lib/ethdev/version.map
+++ b/lib/ethdev/version.map
@@ -264,6 +264,9 @@ EXPERIMENTAL {
 	rte_eth_ip_reassembly_capability_get;
 	rte_eth_ip_reassembly_conf_get;
 	rte_eth_ip_reassembly_conf_set;
+
+	# added in 22.07
+	rte_mtr_meter_vlan_table_update;
 };
 
 INTERNAL {
-- 
2.35.1