diff mbox

[RFC,PATCHv2,2/2] api: classification: add odp_cls_context routines for stateful classification

Message ID 1435716730-30445-2-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer July 1, 2015, 2:12 a.m. UTC
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 include/odp/api/classification.h | 106 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

Comments

Ivan Khoronzhuk July 1, 2015, 12:20 p.m. UTC | #1
Hi, Bill

On 01.07.15 05:12, Bill Fischofer wrote:
> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
> ---
>   include/odp/api/classification.h | 106 +++++++++++++++++++++++++++++++++++++++
>   1 file changed, 106 insertions(+)
>
> diff --git a/include/odp/api/classification.h b/include/odp/api/classification.h
> index f597b26..1829f74 100644
> --- a/include/odp/api/classification.h
> +++ b/include/odp/api/classification.h
> @@ -24,6 +24,16 @@ extern "C" {
>    *  @{
>    */
>
> +/**
> + * @typedef odp_cls_context_t
> + * Context for classification rule chains
> + */
> +
> +/**
> + * @def ODP_CLS_CONTEXT_INVALID
> + * This value is the "null context" used to represent
> + * no context.
> + */
>
>   /**
>    * @typedef odp_cos_t
> @@ -59,6 +69,48 @@ extern "C" {
>    * Invalid odp_pmr_set_t value.
>    */
>
> + /**
> + * Create a classification context
> + *
> + * @param  name Name for context lookup, or NULL for anonymous
> + *
> + * @return ctx      Classification context handle
> + * @retval          ODP_CLS_CONTEXT_INVALID on failure
> + */
> +odp_cls_context_t odp_cls_context_create(const char *name);
> +
> +/**
> + * Destroy a classification context
> + *
> + * @param ctx       Classification context handle
> + * @retval          0 on success
> + * @retval          <0 on failure
> + */
> +int odp_cls_context_destroy(odp_cls_context_t ctx);
> +
> +/**
> + * Lookup a classification context
> + *
> + * @param name  String name of the context to be retrieved
> + *
> + * @return ctx      Classification context handle
> + * @retval          ODP_CLS_CONTEXT_INVALID on lookup failure
> + */
> +odp_cls_context_t odp_cls_context_lookup(const char *name);
> +
> +/**
> + * Get printable value for an odp_cls_context_t
> + *
> + * @param ctx   Handle to be printed
> + * @return      uint64_t value that can be used to print/display
> + *              this handle
> + *
> + * @note This routine is intended to be used for diagnostic purposes
> + * to enable applications to generate a printable value that represents
> + * an odp_cls_context_t handle.
> + */
> +uint64_t odp_cls_context_to_u64(odp_cls_context_t ctx);
> +
>   /**
>    * Class-of-service packet drop policies
>    */
> @@ -263,6 +315,46 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id,
>   		      odp_pktio_t src_pktio, odp_cos_t dst_cos);
>
>   /**
> + * Apply a PMR to a classification context to assign a CoS.
> + *
> + * @param[in]   ctx             Classification context to which
> + *                              this PMR is to be applied
> + * @param[in]	pmr_id		PMR to be activated
> + * @param[in]	dst_cos		CoS to be assigned by this PMR
> + *
> + * @retval		0 on success
> + * @retval		<0 on failure
> + */
> +int odp_cls_context_pmr_cos(odp_cls_context_t ctx,
> +			    odp_pmr_t pmr_id, odp_cos_t dst_cos);
> +
> +/**
> + * Apply a classification context to a pktio to make it active
> + *
> + * @param      src_pktio   pktio to which this context is to be applies
> + * @param      new_ctx     context to be applied to this pktio
> + * @param      root        the PMR with new_ctx that represents the root
> + *                         of changes--may be used by the implementation
> + *                         to optimize handling of partial changes to
> + *                         a classification tree. Specify as NULL if
> + *                         changes have no specific starting node or if
> + *                         the context contains PMR sets.
> + * @param[out] old_ctx     prior context that was applied to this pktio
> + *
> + * @retval                 0 on success
> + * @retval                 <0 on failure
> + *
> + * @note Applying a classification context to a pktio that has no current
> + * context returns ODP_CLS_CONTEXT_INVALID as the old_ctx. Similarly, to
> + * remove a classification context from a pktio use ODP_CLS_CONTEXT_INVALID
> + * as the new_ctx.
> + */
> +int odp_pktio_cls_context_swap(odp_pktio_t src_pktio,
> +			       odp_cls_context_t new_ctx,
> +			       odp_pmr_t root,
> +			       odp_cls_context_t *old_ctx);
> +

This function "activates" only context for a pktio. As I understand
the main idea of new API is to allow some platforms to postpone
resource allocation and allow do some check/optimization. It's obvious
that new API allows postpone resource allocation for several PMRs
connected to a pktio. But not everything is clear.

- What if an implementation can do "compilation/optimization" for
several contexts that are connected to different pktios? Is here some 
hided rule, like "create all contexts first, then start connect them" or
"don't modify any of the contexts if you connect at least one of them."

- The same for several contexts connected for the same pktio? No reason
but, is it allowed?

- When the implementation can decide: Now I can do "optimization" using
several contexts. Where this point?

> +/**
>    * Cascade a PMR to refine packets from one CoS to another.
>    *
>    * @param[in]	pmr_id		PMR to be activated
> @@ -358,6 +450,20 @@ int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t src_pktio,
>   				odp_cos_t dst_cos);
>
>   /**
> + * Apply a PMR set to a classification context to assign a CoS.
> + *
> + * @param[in]   ctx             Classification context to which
> + *                              this PMR set is to be applied
> + * @param[in]	pmr_set_id	PMR set to be activated
> + * @param[in]	dst_cos		CoS to be assigned by this PMR
> + *
> + * @retval		0 on success
> + * @retval		<0 on failure
> + */
> +int odp_cls_context_pmr_set_cos(odp_cls_context_t ctx,
> +				odp_pmr_set_t pmr_set_id, odp_cos_t dst_cos);
> +
> +/**
>    * Get printable value for an odp_cos_t
>    *
>    * @param hdl  odp_cos_t handle to be printed
>
Bill Fischofer July 1, 2015, 12:51 p.m. UTC | #2
The intent is that a pktio has a single classification context at a time.
These contexts can contain any number of PMRs however the application
wishes to arrange them.  So a context is a complete description of what
should be done for packets arriving on a single pktio.

If a PMR is associated with multiple contexts (so that they can be applied
to different pktio objects) then it's up to implementation as to whether
the structures used to support these definitions are shared or duplicated
as that behavior is not specified by the API.

The original API specification was stateless in that each PMR "stood
alone".  In this RFC the context serves that role. Requiring a total
specification of all classification rules that apply to any pktio before
they are activated would seem to impose a significant burden on both
applications and implementations and was not something we discussed during
the Sprint.

On Wed, Jul 1, 2015 at 7:20 AM, Ivan Khoronzhuk <ivan.khoronzhuk@linaro.org>
wrote:

> Hi, Bill
>
>
> On 01.07.15 05:12, Bill Fischofer wrote:
>
>> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
>> ---
>>   include/odp/api/classification.h | 106
>> +++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 106 insertions(+)
>>
>> diff --git a/include/odp/api/classification.h
>> b/include/odp/api/classification.h
>> index f597b26..1829f74 100644
>> --- a/include/odp/api/classification.h
>> +++ b/include/odp/api/classification.h
>> @@ -24,6 +24,16 @@ extern "C" {
>>    *  @{
>>    */
>>
>> +/**
>> + * @typedef odp_cls_context_t
>> + * Context for classification rule chains
>> + */
>> +
>> +/**
>> + * @def ODP_CLS_CONTEXT_INVALID
>> + * This value is the "null context" used to represent
>> + * no context.
>> + */
>>
>>   /**
>>    * @typedef odp_cos_t
>> @@ -59,6 +69,48 @@ extern "C" {
>>    * Invalid odp_pmr_set_t value.
>>    */
>>
>> + /**
>> + * Create a classification context
>> + *
>> + * @param  name Name for context lookup, or NULL for anonymous
>> + *
>> + * @return ctx      Classification context handle
>> + * @retval          ODP_CLS_CONTEXT_INVALID on failure
>> + */
>> +odp_cls_context_t odp_cls_context_create(const char *name);
>> +
>> +/**
>> + * Destroy a classification context
>> + *
>> + * @param ctx       Classification context handle
>> + * @retval          0 on success
>> + * @retval          <0 on failure
>> + */
>> +int odp_cls_context_destroy(odp_cls_context_t ctx);
>> +
>> +/**
>> + * Lookup a classification context
>> + *
>> + * @param name  String name of the context to be retrieved
>> + *
>> + * @return ctx      Classification context handle
>> + * @retval          ODP_CLS_CONTEXT_INVALID on lookup failure
>> + */
>> +odp_cls_context_t odp_cls_context_lookup(const char *name);
>> +
>> +/**
>> + * Get printable value for an odp_cls_context_t
>> + *
>> + * @param ctx   Handle to be printed
>> + * @return      uint64_t value that can be used to print/display
>> + *              this handle
>> + *
>> + * @note This routine is intended to be used for diagnostic purposes
>> + * to enable applications to generate a printable value that represents
>> + * an odp_cls_context_t handle.
>> + */
>> +uint64_t odp_cls_context_to_u64(odp_cls_context_t ctx);
>> +
>>   /**
>>    * Class-of-service packet drop policies
>>    */
>> @@ -263,6 +315,46 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id,
>>                       odp_pktio_t src_pktio, odp_cos_t dst_cos);
>>
>>   /**
>> + * Apply a PMR to a classification context to assign a CoS.
>> + *
>> + * @param[in]   ctx             Classification context to which
>> + *                              this PMR is to be applied
>> + * @param[in]  pmr_id          PMR to be activated
>> + * @param[in]  dst_cos         CoS to be assigned by this PMR
>> + *
>> + * @retval             0 on success
>> + * @retval             <0 on failure
>> + */
>> +int odp_cls_context_pmr_cos(odp_cls_context_t ctx,
>> +                           odp_pmr_t pmr_id, odp_cos_t dst_cos);
>> +
>> +/**
>> + * Apply a classification context to a pktio to make it active
>> + *
>> + * @param      src_pktio   pktio to which this context is to be applies
>> + * @param      new_ctx     context to be applied to this pktio
>> + * @param      root        the PMR with new_ctx that represents the root
>> + *                         of changes--may be used by the implementation
>> + *                         to optimize handling of partial changes to
>> + *                         a classification tree. Specify as NULL if
>> + *                         changes have no specific starting node or if
>> + *                         the context contains PMR sets.
>> + * @param[out] old_ctx     prior context that was applied to this pktio
>> + *
>> + * @retval                 0 on success
>> + * @retval                 <0 on failure
>> + *
>> + * @note Applying a classification context to a pktio that has no current
>> + * context returns ODP_CLS_CONTEXT_INVALID as the old_ctx. Similarly, to
>> + * remove a classification context from a pktio use
>> ODP_CLS_CONTEXT_INVALID
>> + * as the new_ctx.
>> + */
>> +int odp_pktio_cls_context_swap(odp_pktio_t src_pktio,
>> +                              odp_cls_context_t new_ctx,
>> +                              odp_pmr_t root,
>> +                              odp_cls_context_t *old_ctx);
>> +
>>
>
> This function "activates" only context for a pktio. As I understand
> the main idea of new API is to allow some platforms to postpone
> resource allocation and allow do some check/optimization. It's obvious
> that new API allows postpone resource allocation for several PMRs
> connected to a pktio. But not everything is clear.
>
> - What if an implementation can do "compilation/optimization" for
> several contexts that are connected to different pktios? Is here some
> hided rule, like "create all contexts first, then start connect them" or
> "don't modify any of the contexts if you connect at least one of them."
>
> - The same for several contexts connected for the same pktio? No reason
> but, is it allowed?
>
> - When the implementation can decide: Now I can do "optimization" using
> several contexts. Where this point?
>
>
>  +/**
>>    * Cascade a PMR to refine packets from one CoS to another.
>>    *
>>    * @param[in] pmr_id          PMR to be activated
>> @@ -358,6 +450,20 @@ int odp_pktio_pmr_match_set_cos(odp_pmr_set_t
>> pmr_set_id, odp_pktio_t src_pktio,
>>                                 odp_cos_t dst_cos);
>>
>>   /**
>> + * Apply a PMR set to a classification context to assign a CoS.
>> + *
>> + * @param[in]   ctx             Classification context to which
>> + *                              this PMR set is to be applied
>> + * @param[in]  pmr_set_id      PMR set to be activated
>> + * @param[in]  dst_cos         CoS to be assigned by this PMR
>> + *
>> + * @retval             0 on success
>> + * @retval             <0 on failure
>> + */
>> +int odp_cls_context_pmr_set_cos(odp_cls_context_t ctx,
>> +                               odp_pmr_set_t pmr_set_id, odp_cos_t
>> dst_cos);
>> +
>> +/**
>>    * Get printable value for an odp_cos_t
>>    *
>>    * @param hdl  odp_cos_t handle to be printed
>>
>>
diff mbox

Patch

diff --git a/include/odp/api/classification.h b/include/odp/api/classification.h
index f597b26..1829f74 100644
--- a/include/odp/api/classification.h
+++ b/include/odp/api/classification.h
@@ -24,6 +24,16 @@  extern "C" {
  *  @{
  */
 
+/**
+ * @typedef odp_cls_context_t
+ * Context for classification rule chains
+ */
+
+/**
+ * @def ODP_CLS_CONTEXT_INVALID
+ * This value is the "null context" used to represent
+ * no context.
+ */
 
 /**
  * @typedef odp_cos_t
@@ -59,6 +69,48 @@  extern "C" {
  * Invalid odp_pmr_set_t value.
  */
 
+ /**
+ * Create a classification context
+ *
+ * @param  name Name for context lookup, or NULL for anonymous
+ *
+ * @return ctx      Classification context handle
+ * @retval          ODP_CLS_CONTEXT_INVALID on failure
+ */
+odp_cls_context_t odp_cls_context_create(const char *name);
+
+/**
+ * Destroy a classification context
+ *
+ * @param ctx       Classification context handle
+ * @retval          0 on success
+ * @retval          <0 on failure
+ */
+int odp_cls_context_destroy(odp_cls_context_t ctx);
+
+/**
+ * Lookup a classification context
+ *
+ * @param name  String name of the context to be retrieved
+ *
+ * @return ctx      Classification context handle
+ * @retval          ODP_CLS_CONTEXT_INVALID on lookup failure
+ */
+odp_cls_context_t odp_cls_context_lookup(const char *name);
+
+/**
+ * Get printable value for an odp_cls_context_t
+ *
+ * @param ctx   Handle to be printed
+ * @return      uint64_t value that can be used to print/display
+ *              this handle
+ *
+ * @note This routine is intended to be used for diagnostic purposes
+ * to enable applications to generate a printable value that represents
+ * an odp_cls_context_t handle.
+ */
+uint64_t odp_cls_context_to_u64(odp_cls_context_t ctx);
+
 /**
  * Class-of-service packet drop policies
  */
@@ -263,6 +315,46 @@  int odp_pktio_pmr_cos(odp_pmr_t pmr_id,
 		      odp_pktio_t src_pktio, odp_cos_t dst_cos);
 
 /**
+ * Apply a PMR to a classification context to assign a CoS.
+ *
+ * @param[in]   ctx             Classification context to which
+ *                              this PMR is to be applied
+ * @param[in]	pmr_id		PMR to be activated
+ * @param[in]	dst_cos		CoS to be assigned by this PMR
+ *
+ * @retval		0 on success
+ * @retval		<0 on failure
+ */
+int odp_cls_context_pmr_cos(odp_cls_context_t ctx,
+			    odp_pmr_t pmr_id, odp_cos_t dst_cos);
+
+/**
+ * Apply a classification context to a pktio to make it active
+ *
+ * @param      src_pktio   pktio to which this context is to be applies
+ * @param      new_ctx     context to be applied to this pktio
+ * @param      root        the PMR with new_ctx that represents the root
+ *                         of changes--may be used by the implementation
+ *                         to optimize handling of partial changes to
+ *                         a classification tree. Specify as NULL if
+ *                         changes have no specific starting node or if
+ *                         the context contains PMR sets.
+ * @param[out] old_ctx     prior context that was applied to this pktio
+ *
+ * @retval                 0 on success
+ * @retval                 <0 on failure
+ *
+ * @note Applying a classification context to a pktio that has no current
+ * context returns ODP_CLS_CONTEXT_INVALID as the old_ctx. Similarly, to
+ * remove a classification context from a pktio use ODP_CLS_CONTEXT_INVALID
+ * as the new_ctx.
+ */
+int odp_pktio_cls_context_swap(odp_pktio_t src_pktio,
+			       odp_cls_context_t new_ctx,
+			       odp_pmr_t root,
+			       odp_cls_context_t *old_ctx);
+
+/**
  * Cascade a PMR to refine packets from one CoS to another.
  *
  * @param[in]	pmr_id		PMR to be activated
@@ -358,6 +450,20 @@  int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t src_pktio,
 				odp_cos_t dst_cos);
 
 /**
+ * Apply a PMR set to a classification context to assign a CoS.
+ *
+ * @param[in]   ctx             Classification context to which
+ *                              this PMR set is to be applied
+ * @param[in]	pmr_set_id	PMR set to be activated
+ * @param[in]	dst_cos		CoS to be assigned by this PMR
+ *
+ * @retval		0 on success
+ * @retval		<0 on failure
+ */
+int odp_cls_context_pmr_set_cos(odp_cls_context_t ctx,
+				odp_pmr_set_t pmr_set_id, odp_cos_t dst_cos);
+
+/**
  * Get printable value for an odp_cos_t
  *
  * @param hdl  odp_cos_t handle to be printed