doc/guides/prog_guide/flow_classify_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Flow Classification Library
   5 ===========================
   6
   7 DPDK provides a Flow Classification library that provides the ability
   8 to classify an input packet by matching it against a set of Flow rules.
   9
  10 The initial implementation supports counting of IPv4 5-tuple packets which match
  11 a particular Flow rule only.
  12
  13 Please refer to the
  14 :doc:`./rte_flow`
  15 for more information.
  16
  17 The Flow Classification library uses the ``librte_table`` API for managing Flow
  18 rules and matching packets against the Flow rules.
  19 The library is table agnostic and can use the following tables:
  20 ``Access Control List``, ``Hash`` and ``Longest Prefix Match(LPM)``.
  21 The ``Access Control List`` table is used in the initial implementation.
  22
  23 Please refer to the
  24 :doc:`./packet_framework`
  25 for more information.on ``librte_table``.
  26
  27 DPDK provides an Access Control List library that provides the ability to
  28 classify an input packet based on a set of classification rules.
  29
  30 Please refer to the
  31 :doc:`./packet_classif_access_ctrl`
  32 library for more information on ``librte_acl``.
  33
  34 There is also a Flow Classify sample application which demonstrates the use of
  35 the Flow Classification Library API's.
  36
  37 Please refer to the
  38 :doc:`../sample_app_ug/flow_classify`
  39 for more information on the ``flow_classify`` sample application.
  40
  41 Overview
  42 --------
  43
  44 The library has the following API's
  45
  46 .. code-block:: c
  47
  48     /**
  49      * Flow classifier create
  50      *
  51      * @param params
  52      *   Parameters for flow classifier creation
  53      * @return
  54      *   Handle to flow classifier instance on success or NULL otherwise
  55      */
  56     struct rte_flow_classifier *
  57     rte_flow_classifier_create(struct rte_flow_classifier_params *params);
  58
  59     /**
  60      * Flow classifier free
  61      *
  62      * @param cls
  63      *   Handle to flow classifier instance
  64      * @return
  65      *   0 on success, error code otherwise
  66      */
  67     int
  68     rte_flow_classifier_free(struct rte_flow_classifier *cls);
  69
  70     /**
  71      * Flow classify table create
  72      *
  73      * @param cls
  74      *   Handle to flow classifier instance
  75      * @param params
  76      *   Parameters for flow_classify table creation
  77      * @return
  78      *   0 on success, error code otherwise
  79      */
  80     int
  81     rte_flow_classify_table_create(struct rte_flow_classifier *cls,
  82            struct rte_flow_classify_table_params *params);
  83
  84     /**
  85      * Validate the flow classify rule
  86      *
  87      * @param[in] cls
  88      *   Handle to flow classifier instance
  89      * @param[in] attr
  90      *   Flow rule attributes
  91      * @param[in] pattern
  92      *   Pattern specification (list terminated by the END pattern item).
  93      * @param[in] actions
  94      *   Associated actions (list terminated by the END pattern item).
  95      * @param[out] error
  96      *   Perform verbose error reporting if not NULL. Structure
  97      *   initialised in case of error only.
  98      * @return
  99      *   0 on success, error code otherwise
 100      */
 101     int
 102     rte_flow_classify_validate(struct rte_flow_classifier *cls,
 103             const struct rte_flow_attr *attr,
 104             const struct rte_flow_item pattern[],
 105             const struct rte_flow_action actions[],
 106             struct rte_flow_error *error);
 107
 108     /**
 109      * Add a flow classify rule to the flow_classifier table.
 110      *
 111      * @param[in] cls
 112      *   Flow classifier handle
 113      * @param[in] attr
 114      *   Flow rule attributes
 115      * @param[in] pattern
 116      *   Pattern specification (list terminated by the END pattern item).
 117      * @param[in] actions
 118      *   Associated actions (list terminated by the END pattern item).
 119      * @param[out] key_found
 120      *   returns 1 if rule present already, 0 otherwise.
 121      * @param[out] error
 122      *   Perform verbose error reporting if not NULL. Structure
 123      *   initialised in case of error only.
 124      * @return
 125      *   A valid handle in case of success, NULL otherwise.
 126      */
 127     struct rte_flow_classify_rule *
 128     rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
 129             const struct rte_flow_attr *attr,
 130             const struct rte_flow_item pattern[],
 131             const struct rte_flow_action actions[],
 132             int *key_found;
 133             struct rte_flow_error *error);
 134
 135     /**
 136      * Delete a flow classify rule from the flow_classifier table.
 137      *
 138      * @param[in] cls
 139      *   Flow classifier handle
 140      * @param[in] rule
 141      *   Flow classify rule
 142      * @return
 143      *   0 on success, error code otherwise.
 144      */
 145     int
 146     rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
 147             struct rte_flow_classify_rule *rule);
 148
 149     /**
 150      * Query flow classifier for given rule.
 151      *
 152      * @param[in] cls
 153      *   Flow classifier handle
 154      * @param[in] pkts
 155      *   Pointer to packets to process
 156      * @param[in] nb_pkts
 157      *   Number of packets to process
 158      * @param[in] rule
 159      *   Flow classify rule
 160      * @param[in] stats
 161      *   Flow classify stats
 162      *
 163      * @return
 164      *   0 on success, error code otherwise.
 165      */
 166     int
 167     rte_flow_classifier_query(struct rte_flow_classifier *cls,
 168             struct rte_mbuf **pkts,
 169             const uint16_t nb_pkts,
 170             struct rte_flow_classify_rule *rule,
 171             struct rte_flow_classify_stats *stats);
 172
 173 Classifier creation
 174 ~~~~~~~~~~~~~~~~~~~
 175
 176 The application creates the ``Classifier`` using the
 177 ``rte_flow_classifier_create`` API.
 178 The ``rte_flow_classify_params`` structure must be initialised by the
 179 application before calling the API.
 180
 181 .. code-block:: c
 182
 183     struct rte_flow_classifier_params {
 184         /** flow classifier name */
 185         const char *name;
 186
 187         /** CPU socket ID where memory for the flow classifier and its */
 188         /** elements (tables) should be allocated */
 189         int socket_id;
 190     };
 191
 192 The ``Classifier`` has the following internal structures:
 193
 194 .. code-block:: c
 195
 196     struct rte_cls_table {
 197         /* Input parameters */
 198         struct rte_table_ops ops;
 199         uint32_t entry_size;
 200         enum rte_flow_classify_table_type type;
 201
 202         /* Handle to the low-level table object */
 203         void *h_table;
 204     };
 205
 206     #define RTE_FLOW_CLASSIFIER_MAX_NAME_SZ 256
 207
 208     struct rte_flow_classifier {
 209         /* Input parameters */
 210         char name[RTE_FLOW_CLASSIFIER_MAX_NAME_SZ];
 211         int socket_id;
 212
 213         /* Internal */
 214         /* ntuple_filter */
 215         struct rte_eth_ntuple_filter ntuple_filter;
 216
 217         /* classifier tables */
 218         struct rte_cls_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX];
 219         uint32_t table_mask;
 220         uint32_t num_tables;
 221
 222         uint16_t nb_pkts;
 223         struct rte_flow_classify_table_entry
 224             *entries[RTE_PORT_IN_BURST_SIZE_MAX];
 225     } __rte_cache_aligned;
 226
 227 Adding a table to the Classifier
 228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 229
 230 The application adds a table to the ``Classifier`` using the
 231 ``rte_flow_classify_table_create`` API.
 232 The ``rte_flow_classify_table_params`` structure must be initialised by the
 233 application before calling the API.
 234
 235 .. code-block:: c
 236
 237     struct rte_flow_classify_table_params {
 238         /** Table operations (specific to each table type) */
 239         struct rte_table_ops *ops;
 240
 241         /** Opaque param to be passed to the table create operation */
 242         void *arg_create;
 243
 244         /** Classifier table type */
 245         enum rte_flow_classify_table_type type;
 246      };
 247
 248 To create an ACL table the ``rte_table_acl_params`` structure must be
 249 initialised and assigned to ``arg_create`` in the
 250 ``rte_flow_classify_table_params`` structure.
 251
 252 .. code-block:: c
 253
 254     struct rte_table_acl_params {
 255         /** Name */
 256         const char *name;
 257
 258         /** Maximum number of ACL rules in the table */
 259         uint32_t n_rules;
 260
 261         /** Number of fields in the ACL rule specification */
 262         uint32_t n_rule_fields;
 263
 264         /** Format specification of the fields of the ACL rule */
 265         struct rte_acl_field_def field_format[RTE_ACL_MAX_FIELDS];
 266     };
 267
 268 The fields for the ACL rule must also be initialised by the application.
 269
 270 An ACL table can be added to the ``Classifier`` for each ACL rule, for example
 271 another table could be added for the IPv6 5-tuple rule.
 272
 273 Flow Parsing
 274 ~~~~~~~~~~~~
 275
 276 The library currently supports three IPv4 5-tuple flow patterns, for UDP, TCP
 277 and SCTP.
 278
 279 .. code-block:: c
 280
 281     /* Pattern for IPv4 5-tuple UDP filter */
 282     static enum rte_flow_item_type pattern_ntuple_1[] = {
 283         RTE_FLOW_ITEM_TYPE_ETH,
 284         RTE_FLOW_ITEM_TYPE_IPV4,
 285         RTE_FLOW_ITEM_TYPE_UDP,
 286         RTE_FLOW_ITEM_TYPE_END,
 287     };
 288
 289     /* Pattern for IPv4 5-tuple TCP filter */
 290     static enum rte_flow_item_type pattern_ntuple_2[] = {
 291         RTE_FLOW_ITEM_TYPE_ETH,
 292         RTE_FLOW_ITEM_TYPE_IPV4,
 293         RTE_FLOW_ITEM_TYPE_TCP,
 294         RTE_FLOW_ITEM_TYPE_END,
 295     };
 296
 297     /* Pattern for IPv4 5-tuple SCTP filter */
 298     static enum rte_flow_item_type pattern_ntuple_3[] = {
 299         RTE_FLOW_ITEM_TYPE_ETH,
 300         RTE_FLOW_ITEM_TYPE_IPV4,
 301         RTE_FLOW_ITEM_TYPE_SCTP,
 302         RTE_FLOW_ITEM_TYPE_END,
 303     };
 304
 305 The API function ``rte_flow_classify_validate`` parses the
 306 IPv4 5-tuple pattern, attributes and actions and returns the 5-tuple data in the
 307 ``rte_eth_ntuple_filter`` structure.
 308
 309 .. code-block:: c
 310
 311     static int
 312     rte_flow_classify_validate(struct rte_flow_classifier *cls,
 313                    const struct rte_flow_attr *attr,
 314                    const struct rte_flow_item pattern[],
 315                    const struct rte_flow_action actions[],
 316                    struct rte_flow_error *error)
 317
 318 Adding Flow Rules
 319 ~~~~~~~~~~~~~~~~~
 320
 321 The ``rte_flow_classify_table_entry_add`` API creates an
 322 ``rte_flow_classify`` object which contains the flow_classify id and type, the
 323 action, a union of add and delete keys and a union of rules.
 324 It uses the ``rte_flow_classify_validate`` API function for parsing the
 325 flow parameters.
 326 The 5-tuple ACL key data is obtained from the ``rte_eth_ntuple_filter``
 327 structure populated by the ``classify_parse_ntuple_filter`` function which
 328 parses the Flow rule.
 329
 330 .. code-block:: c
 331
 332     struct acl_keys {
 333         struct rte_table_acl_rule_add_params key_add; /* add key */
 334         struct rte_table_acl_rule_delete_params key_del; /* delete key */
 335     };
 336
 337     struct classify_rules {
 338         enum rte_flow_classify_rule_type type;
 339         union {
 340             struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;
 341         } u;
 342     };
 343
 344     struct rte_flow_classify {
 345         uint32_t id;  /* unique ID of classify object */
 346         enum rte_flow_classify_table_type tbl_type; /* rule table */
 347         struct classify_rules rules; /* union of rules */
 348         union {
 349             struct acl_keys key;
 350         } u;
 351         int key_found; /* rule key found in table */
 352         struct rte_flow_classify_table_entry entry;  /* rule meta data */
 353         void *entry_ptr; /* handle to the table entry for rule meta data */
 354     };
 355
 356 It then calls the ``table.ops.f_add`` API to add the rule to the ACL
 357 table.
 358
 359 Deleting Flow Rules
 360 ~~~~~~~~~~~~~~~~~~~
 361
 362 The ``rte_flow_classify_table_entry_delete`` API calls the
 363 ``table.ops.f_delete`` API to delete a rule from the ACL table.
 364
 365 Packet Matching
 366 ~~~~~~~~~~~~~~~
 367
 368 The ``rte_flow_classifier_query`` API is used to find packets which match a
 369 given flow rule in the table.
 370 This API calls the flow_classify_run internal function which calls the
 371 ``table.ops.f_lookup`` API to see if any packets in a burst match any
 372 of the Flow rules in the table.
 373 The meta data for the highest priority rule matched for each packet is returned
 374 in the entries array in the ``rte_flow_classify`` object.
 375 The internal function ``action_apply`` implements the ``Count`` action which is
 376 used to return data which matches a particular Flow rule.
 377
 378 The rte_flow_classifier_query API uses the following structures to return data
 379 to the application.
 380
 381 .. code-block:: c
 382
 383     /** IPv4 5-tuple data */
 384     struct rte_flow_classify_ipv4_5tuple {
 385         uint32_t dst_ip;         /**< Destination IP address in big endian. */
 386         uint32_t dst_ip_mask;    /**< Mask of destination IP address. */
 387         uint32_t src_ip;         /**< Source IP address in big endian. */
 388         uint32_t src_ip_mask;    /**< Mask of destination IP address. */
 389         uint16_t dst_port;       /**< Destination port in big endian. */
 390         uint16_t dst_port_mask;  /**< Mask of destination port. */
 391         uint16_t src_port;       /**< Source Port in big endian. */
 392         uint16_t src_port_mask;  /**< Mask of source port. */
 393         uint8_t proto;           /**< L4 protocol. */
 394         uint8_t proto_mask;      /**< Mask of L4 protocol. */
 395     };
 396
 397     /**
 398      * Flow stats
 399      *
 400      * For the count action, stats can be returned by the query API.
 401      *
 402      * Storage for stats is provided by the application.
 403      *
 404      *
 405      */
 406     struct rte_flow_classify_stats {
 407         void *stats;
 408     };
 409
 410     struct rte_flow_classify_5tuple_stats {
 411         /** count of packets that match IPv4 5tuple pattern */
 412         uint64_t counter1;
 413         /** IPv4 5tuple data */
 414         struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;
 415     };