doc/guides/prog_guide/flow_classify_lib.rst

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