| Message ID | 1435716730-30445-2-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
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 >
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 --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
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- include/odp/api/classification.h | 106 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+)