[dpdk-dev,v2,4/4] doc: update documentation for flow classify lib

  Updates the documentation for flow classification
library and sample application.

Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
---
v2:
- replace parse flow function with validate API

 doc/guides/prog_guide/flow_classify_lib.rst | 59 ++++++++++++-----------------
 doc/guides/sample_app_ug/flow_classify.rst  |  8 +---
 2 files changed, 27 insertions(+), 40 deletions(-)
  

Hi Jasvinder,

> -----Original Message-----
> From: Singh, Jasvinder
> Sent: Monday, December 11, 2017 4:27 PM
> To: dev@dpdk.org
> Cc: Iremonger, Bernard <bernard.iremonger@intel.com>; Mcnamara, John
> <john.mcnamara@intel.com>
> Subject: [PATCH v2 4/4] doc: update documentation for flow classify lib
> 
> Updates the documentation for flow classification library and sample
> application.
> 
> Signed-off-by: Jasvinder Singh <jasvinder.singh@intel.com>
> ---
> v2:
> - replace parse flow function with validate API
> 
>  doc/guides/prog_guide/flow_classify_lib.rst | 59 ++++++++++++-----------------
> doc/guides/sample_app_ug/flow_classify.rst  |  8 +---
>  2 files changed, 27 insertions(+), 40 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/flow_classify_lib.rst
> b/doc/guides/prog_guide/flow_classify_lib.rst
> index 820dc72..b0d3c1e 100644
> --- a/doc/guides/prog_guide/flow_classify_lib.rst
> +++ b/doc/guides/prog_guide/flow_classify_lib.rst
> @@ -101,30 +101,26 @@ The library has the following API's
>       *   Handle to flow classifier instance
>       * @param params
>       *   Parameters for flow_classify table creation
> -     * @param table_id
> -     *   Table ID. Valid only within the scope of table IDs of the current
> -     *   classifier. Only returned after a successful invocation.
>       * @return
>       *   0 on success, error code otherwise
>       */
>      int
>      rte_flow_classify_table_create(struct rte_flow_classifier *cls,
> -           struct rte_flow_classify_table_params *params,
> -           uint32_t *table_id);
> +           struct rte_flow_classify_table_params *params);
> 
>      /**
>       * Add a flow classify rule to the flow_classifier table.
>       *
>       * @param[in] cls
>       *   Flow classifier handle
> -     * @param[in] table_id
> -     *   id of table
>       * @param[in] attr
>       *   Flow rule attributes
>       * @param[in] pattern
>       *   Pattern specification (list terminated by the END pattern item).
>       * @param[in] actions
>       *   Associated actions (list terminated by the END pattern item).
> +     * @param[out] key_found
> +     *   returns 1 if rule present already, 0 otherwise.
>       * @param[out] error
>       *   Perform verbose error reporting if not NULL. Structure
>       *   initialised in case of error only.
> @@ -133,10 +129,10 @@ The library has the following API's
>       */
>      struct rte_flow_classify_rule *
>      rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
> -            uint32_t table_id,
>              const struct rte_flow_attr *attr,
>              const struct rte_flow_item pattern[],
>              const struct rte_flow_action actions[],
> +            int *key_found;
>              struct rte_flow_error *error);
> 
>      /**
> @@ -144,8 +140,6 @@ The library has the following API's
>       *
>       * @param[in] cls
>       *   Flow classifier handle
> -     * @param[in] table_id
> -     *   id of table
>       * @param[in] rule
>       *   Flow classify rule
>       * @return
> @@ -153,7 +147,6 @@ The library has the following API's
>       */
>      int
>      rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
> -            uint32_t table_id,
>              struct rte_flow_classify_rule *rule);
> 
>      /**
> @@ -161,8 +154,6 @@ The library has the following API's
>       *
>       * @param[in] cls
>       *   Flow classifier handle
> -     * @param[in] table_id
> -     *   id of table
>       * @param[in] pkts
>       *   Pointer to packets to process
>       * @param[in] nb_pkts
> @@ -177,7 +168,6 @@ The library has the following API's
>       */
>      int
>      rte_flow_classifier_query(struct rte_flow_classifier *cls,
> -            uint32_t table_id,
>              struct rte_mbuf **pkts,
>              const uint16_t nb_pkts,
>              struct rte_flow_classify_rule *rule, @@ -200,16 +190,13 @@ application
> before calling the API.
>          /** CPU socket ID where memory for the flow classifier and its */
>          /** elements (tables) should be allocated */
>          int socket_id;
> -
> -        /** Table type */
> -        enum rte_flow_classify_table_type type;
>      };
> 

A description of the rte_flow_validate API should be added to the list of API's.

>  The ``Classifier`` has the following internal structures:
> 
>  .. code-block:: c
> 
> -    struct rte_table {
> +    struct rte_cls_table {
>          /* Input parameters */
>          struct rte_table_ops ops;
>          uint32_t entry_size;
> @@ -225,11 +212,16 @@ The ``Classifier`` has the following internal structures:
>          /* Input parameters */
>          char name[RTE_FLOW_CLASSIFIER_MAX_NAME_SZ];
>          int socket_id;
> -        enum rte_flow_classify_table_type type;
> 
> -        /* Internal tables */
> -        struct rte_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX];
> +        /* Internal */
> +        /* ntuple_fliter */
> +        struct rte_eth_ntuple_filter ntuple_filter;
> +
> +        /* clasifier tables */
> +        struct rte_cls_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX];
> +        uint32_t table_mask;
>          uint32_t num_tables;
> +
>          uint16_t nb_pkts;
>          struct rte_flow_classify_table_entry
>              *entries[RTE_PORT_IN_BURST_SIZE_MAX];
> @@ -252,9 +244,8 @@ application before calling the API.
>          /** Opaque param to be passed to the table create operation */
>          void *arg_create;
> 
> -        /** Memory size to be reserved per classifier object entry for */
> -        /** storing meta data */
> -        uint32_t table_metadata_size;
> +        /** Classifier table type */
> +        enum rte_flow_classify_table_type type;
>       };
> 
>  To create an ACL table the ``rte_table_acl_params`` structure must be @@ -
> 314,14 +305,14 @@ and SCTP.
>          RTE_FLOW_ITEM_TYPE_END,
>      };
> 
> -The internal function ``flow_classify_parse_flow`` parses the
> +The API function ``rte_flow_classify_validate`` parses the
>  IPv4 5-tuple pattern, attributes and actions and returns the 5-tuple data in the
> ``rte_eth_ntuple_filter`` structure.
> 
>  .. code-block:: c
> 
>      static int
> -    flow_classify_parse_flow(
> +    rte_flow_classify_validate(struct rte_flow_classifier *cls,
>                     const struct rte_flow_attr *attr,
>                     const struct rte_flow_item pattern[],
>                     const struct rte_flow_action actions[], @@ -333,7 +324,7 @@
> Adding Flow Rules  The ``rte_flow_classify_table_entry_add`` API creates an
> ``rte_flow_classify`` object which contains the flow_classify id and type, the
> action, a union of add and delete keys and a union of rules.
> -It uses the ``flow_classify_parse_flow`` internal function for parsing the
> +It uses the ``rte_flow_classify_validate`` api function for parsing the
>  flow parameters.
>  The 5-tuple ACL key data is obtained from the ``rte_eth_ntuple_filter``  structure
> populated by the ``classify_parse_ntuple_filter`` function which @@ -343,7
> +334,7 @@ parses the Flow rule.
> 
>      struct acl_keys {
>          struct rte_table_acl_rule_add_params key_add; /* add key */
> -        struct rte_table_acl_rule_delete_params	key_del; /* delete key */
> +        struct rte_table_acl_rule_delete_params key_del; /* delete key
> + */
>      };
> 
>      struct classify_rules {
> @@ -355,24 +346,24 @@ parses the Flow rule.
> 
>      struct rte_flow_classify {
>          uint32_t id;  /* unique ID of classify object */
> -        struct rte_flow_action action; /* action when match found */
> -	struct classify_rules rules; /* union of rules */
> +        enum rte_flow_classify_table_type tbl_type; /* rule table */
> +        struct classify_rules rules; /* union of rules */
>          union {
>              struct acl_keys key;
>          } u;
>          int key_found; /* rule key found in table */
> -        void *entry; /* pointer to buffer to hold rule meta data */
> +        struct rte_flow_classify_table_entry entry;  /* rule meta data
> + */
>          void *entry_ptr; /* handle to the table entry for rule meta data */
>      };
> 
> -It then calls the ``table[table_id].ops.f_add`` API to add the rule to the ACL
> +It then calls the ``table.ops.f_add`` API to add the rule to the ACL
>  table.
> 
>  Deleting Flow Rules
>  ~~~~~~~~~~~~~~~~~~~
> 
>  The ``rte_flow_classify_table_entry_delete`` API calls the -
> ``table[table_id].ops.f_delete`` API to delete a rule from the ACL table.
> +``table.ops.f_delete`` API to delete a rule from the ACL table.
> 
>  Packet Matching
>  ~~~~~~~~~~~~~~~
> @@ -380,7 +371,7 @@ Packet Matching
>  The ``rte_flow_classifier_query`` API is used to find packets which match a
> given flow Flow rule in the table.
>  This API calls the flow_classify_run internal function which calls the -
> ``table[table_id].ops.f_lookup`` API to see if any packets in a burst match any
> +``table.ops.f_lookup`` API to see if any packets in a burst match any
>  of the Flow rules in the table.
>  The meta data for the highest priority rule matched for each packet is returned
> in the entries array in the ``rte_flow_classify`` object.
> diff --git a/doc/guides/sample_app_ug/flow_classify.rst
> b/doc/guides/sample_app_ug/flow_classify.rst
> index bc12b87..427fded 100644
> --- a/doc/guides/sample_app_ug/flow_classify.rst
> +++ b/doc/guides/sample_app_ug/flow_classify.rst
> @@ -228,7 +228,6 @@ table`` to the flow classifier.
> 
>      struct flow_classifier {
>          struct rte_flow_classifier *cls;
> -        uint32_t table_id[RTE_FLOW_CLASSIFY_TABLE_MAX];
>      };
> 
>      struct flow_classifier_acl {
> @@ -243,7 +242,6 @@ table`` to the flow classifier.
> 
>      cls_params.name = "flow_classifier";
>      cls_params.socket_id = socket_id;
> -    cls_params.type = RTE_FLOW_CLASSIFY_TABLE_TYPE_ACL;
> 
>      cls_app->cls = rte_flow_classifier_create(&cls_params);
>      if (cls_app->cls == NULL) {
> @@ -260,10 +258,9 @@ table`` to the flow classifier.
>      /* initialise table create params */
>      cls_table_params.ops = &rte_table_acl_ops,
>      cls_table_params.arg_create = &table_acl_params,
> -    cls_table_params.table_metadata_size = 0;
> +    cls_table_params.type = RTE_FLOW_CLASSIFY_TABLE_ACL_IP4_5TUPLE;
> 
> -    ret = rte_flow_classify_table_create(cls_app->cls, &cls_table_params,
> -                  &cls->table_id[0]);
> +    ret = rte_flow_classify_table_create(cls_app->cls,
> + &cls_table_params);
>      if (ret) {
>          rte_flow_classifier_free(cls_app->cls);
>          rte_free(cls);
> @@ -495,7 +492,6 @@ following:
>                      if (rules[i]) {
>                          ret = rte_flow_classifier_query(
>                              cls_app->cls,
> -                            cls_app->table_id[0],
>                              bufs, nb_rx, rules[i],
>                              &classify_stats);
>                          if (ret)
> --
> 2.9.3

Regards,

Bernard.