api: cls: introduce mark support

In order to accelerate the lookup function, typical classification
HW gives a feature to embedded a custom application-defined value as
metadata when a specific flow matches the PMR rule.

Introduce a new feature called mark to enable this use-case where
the application can create a PMR with mark and configure the application
defined values as struct odp_pmr_create_opt_t::mark for the given
PMR, and then application retrieve the value through odp_packet_cls_mark()
in fast-path to achieve the first level HW accelerated lookup.

Since the existing odp_cls_pmr_create() API does not support
structure version to accept new arguments, introduced
odp_cls_pmr_create_opt() API provide additional options for
creating the PMR which include the mark support.

Signed-off-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Kiran Kumar K <kirankumark@marvell.com>
Signed-off-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Janne Peltonen <janne.peltonen@nokia.com>

2 files changed, 77 insertions, 0 deletions

diff --git a/include/odp/api/spec/classification.h b/include/odp/api/spec/classification.h
index 5fd546484..176c53ff3 100644
--- a/include/odp/api/spec/classification.h
+++ b/include/odp/api/spec/classification.h
@@ -204,6 +204,10 @@ typedef struct odp_cls_capability_t {
 
 	/** Supported threshold type for BP */
 	odp_threshold_types_t threshold_bp;
+
+	/** Maximum value of odp_pmr_create_opt_t::mark */
+	uint64_t max_mark;
+
 } odp_cls_capability_t;
 
 /**
@@ -606,6 +610,30 @@ typedef struct odp_pmr_param_t {
 } odp_pmr_param_t;
 
 /**
+ * Packet Matching Rule creation options
+ */
+typedef struct odp_pmr_create_opt_t {
+	/** PMR terms
+	 *
+	 *  Array of odp_pmr_param_t entries, one entry per term desired.
+	 *  Use odp_cls_pmr_param_init() to initialize parameters into their default values.
+	 */
+	odp_pmr_param_t *terms;
+
+	/** Number of terms in the match rule. */
+	int num_terms;
+
+	/** Classification mark value
+	 *
+	 * Value to be set in the CLS mark of a packet when the packet matches this
+	 * Packet Matching Rule. The default value is zero. The maximum value is indicated in
+	 * odp_cls_capability_t::max_mark capability.
+	 */
+	uint64_t mark;
+
+} odp_pmr_create_opt_t;
+
+/**
  * Initialize packet matching rule parameters
  *
  * Initialize an odp_pmr_param_t to its default values for all fields
@@ -615,6 +643,15 @@ typedef struct odp_pmr_param_t {
 void odp_cls_pmr_param_init(odp_pmr_param_t *param);
 
 /**
+ * Initialize packet matching rule creation option
+ *
+ * Initialize an odp_pmr_create_opt_t to its default values for all fields
+ *
+ * @param opt       Address of the odp_pmr_create_opt_t to be initialized
+ */
+void odp_cls_pmr_create_opt_init(odp_pmr_create_opt_t *opt);
+
+/**
  * Create a packet matching rule
  *
  * Create a packet match rule between source and destination class of service.
@@ -640,11 +677,37 @@ void odp_cls_pmr_param_init(odp_pmr_param_t *param);
  *
  * @return Handle to the Packet Match Rule.
  * @retval ODP_PMR_INVALID on failure
+ *
+ * @note Matching PMR rule created through this function sets the CLS mark metadata
+ * of the packet to zero.
+ *
+ * @note Rules created through this function are equivalent to rules created through
+ * odp_cls_pmr_create_opt() with the same PMR terms and with the additional option
+ * fields set to their default values.
  */
 odp_pmr_t odp_cls_pmr_create(const odp_pmr_param_t *terms, int num_terms,
 			     odp_cos_t src_cos, odp_cos_t dst_cos);
 
 /**
+ * Create a packet matching rule with options
+ *
+ * Similar to odp_cls_pmr_create() function with additional PMR creation
+ * options specified through odp_pmr_create_opt_t.
+ *
+ * Use odp_cls_pmr_create_opt_init() to initialize options into their default
+ * values.
+ *
+ * @param opt	       points to PMR create options
+ * @param src_cos      source CoS handle
+ * @param dst_cos      destination CoS handle
+ *
+ * @return Handle to the Packet Match Rule.
+ * @retval ODP_PMR_INVALID on failure
+ *
+ */
+odp_pmr_t odp_cls_pmr_create_opt(const odp_pmr_create_opt_t *opt,
+				 odp_cos_t src_cos, odp_cos_t dst_cos);
+/**
  * Function to destroy a packet match rule
  * Destroying a PMR removes the link between the source and destination
  * class of service and this PMR will no longer be applied for packets arriving
diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index 604f1cf61..b2dcf28f2 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -1990,6 +1990,20 @@ int8_t odp_packet_shaper_len_adjust(odp_packet_t pkt);
  */
 void odp_packet_shaper_len_adjust_set(odp_packet_t pkt, int8_t adj);
 
+/**
+ * Classification mark value
+ *
+ * Get the value of the CLS mark of the packet. The mark value is zero by default, but may be
+ * changed by the classification subsystem.
+ *
+ * @param pkt Packet handle
+ *
+ * @return mark value
+ *
+ * @see odp_cls_capability_t::max_mark, odp_pmr_create_opt_t::mark, odp_cls_pmr_create_opt()
+ */
+uint64_t odp_packet_cls_mark(odp_packet_t pkt);
+
 /*
  *
  * Debugging