lib/librte_acl/rte_acl.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef _RTE_ACL_H_
  35 #define _RTE_ACL_H_
  36
  37 /**
  38  * @file
  39  *
  40  * RTE Classifier.
  41  */
  42
  43 #include <rte_acl_osdep.h>
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 #define RTE_ACL_MAX_CATEGORIES  16
  50
  51 #define RTE_ACL_RESULTS_MULTIPLIER      (XMM_SIZE / sizeof(uint32_t))
  52
  53 #define RTE_ACL_MAX_LEVELS 64
  54 #define RTE_ACL_MAX_FIELDS 64
  55
  56 union rte_acl_field_types {
  57         uint8_t  u8;
  58         uint16_t u16;
  59         uint32_t u32;
  60         uint64_t u64;
  61 };
  62
  63 enum {
  64         RTE_ACL_FIELD_TYPE_MASK = 0,
  65         RTE_ACL_FIELD_TYPE_RANGE,
  66         RTE_ACL_FIELD_TYPE_BITMASK
  67 };
  68
  69 /**
  70  * ACL Field defintion.
  71  * Each field in the ACL rule has an associate definition.
  72  * It defines the type of field, its size, its offset in the input buffer,
  73  * the field index, and the input index.
  74  * For performance reasons, the inner loop of the search function is unrolled
  75  * to process four input bytes at a time. This requires the input to be grouped
  76  * into sets of 4 consecutive bytes. The loop processes the first input byte as
  77  * part of the setup and then subsequent bytes must be in groups of 4
  78  * consecutive bytes.
  79  */
  80 struct rte_acl_field_def {
  81         uint8_t  type;        /**< type - RTE_ACL_FIELD_TYPE_*. */
  82         uint8_t  size;        /**< size of field 1,2,4, or 8. */
  83         uint8_t  field_index; /**< index of field inside the rule. */
  84         uint8_t  input_index; /**< 0-N input index. */
  85         uint32_t offset;      /**< offset to start of field. */
  86 };
  87
  88 /**
  89  * ACL build configuration.
  90  * Defines the fields of an ACL trie and number of categories to build with.
  91  */
  92 struct rte_acl_config {
  93         uint32_t num_categories; /**< Number of categories to build with. */
  94         uint32_t num_fields;     /**< Number of field definitions. */
  95         struct rte_acl_field_def defs[RTE_ACL_MAX_FIELDS];
  96         /**< array of field definitions. */
  97 };
  98
  99 /**
 100  * Defines the value of a field for a rule.
 101  */
 102 struct rte_acl_field {
 103         union rte_acl_field_types value;
 104         /**< a 1,2,4, or 8 byte value of the field. */
 105         union rte_acl_field_types mask_range;
 106         /**<
 107          * depending on field type:
 108          * mask -> 1.2.3.4/32 value=0x1020304, mask_range=32,
 109          * range -> 0 : 65535 value=0, mask_range=65535,
 110          * bitmask -> 0x06/0xff value=6, mask_range=0xff.
 111          */
 112 };
 113
 114 enum {
 115         RTE_ACL_TYPE_SHIFT = 29,
 116         RTE_ACL_MAX_INDEX = LEN2MASK(RTE_ACL_TYPE_SHIFT),
 117         RTE_ACL_MAX_PRIORITY = RTE_ACL_MAX_INDEX,
 118         RTE_ACL_MIN_PRIORITY = 0,
 119 };
 120
 121 #define RTE_ACL_INVALID_USERDATA        0
 122
 123 /**
 124  * Miscellaneous data for ACL rule.
 125  */
 126 struct rte_acl_rule_data {
 127         uint32_t category_mask; /**< Mask of categories for that rule. */
 128         int32_t  priority;      /**< Priority for that rule. */
 129         uint32_t userdata;      /**< Associated with the rule user data. */
 130 };
 131
 132 /**
 133  * Defines single ACL rule.
 134  * data - miscellaneous data for the rule.
 135  * field[] - value and mask or range for each field.
 136  */
 137 #define RTE_ACL_RULE_DEF(name, fld_num) struct name {\
 138         struct rte_acl_rule_data data;               \
 139         struct rte_acl_field field[fld_num];         \
 140 }
 141
 142 RTE_ACL_RULE_DEF(rte_acl_rule, 0);
 143
 144 #define RTE_ACL_RULE_SZ(fld_num)        \
 145         (sizeof(struct rte_acl_rule) + sizeof(struct rte_acl_field) * (fld_num))
 146
 147
 148 /** Max number of characters in name.*/
 149 #define RTE_ACL_NAMESIZE                32
 150
 151 /**
 152  * Parameters used when creating the ACL context.
 153  */
 154 struct rte_acl_param {
 155         const char *name;         /**< Name of the ACL context. */
 156         int         socket_id;    /**< Socket ID to allocate memory for. */
 157         uint32_t    rule_size;    /**< Size of each rule. */
 158         uint32_t    max_rule_num; /**< Maximum number of rules. */
 159 };
 160
 161
 162 /**
 163  * Create a new ACL context.
 164  *
 165  * @param param
 166  *   Parameters used to create and initialise the ACL context.
 167  * @return
 168  *   Pointer to ACL context structure that is used in future ACL
 169  *   operations, or NULL on error, with error code set in rte_errno.
 170  *   Possible rte_errno errors include:
 171  *   - E_RTE_NO_TAILQ - no tailq list could be got for the ACL context list
 172  *   - EINVAL - invalid parameter passed to function
 173  */
 174 struct rte_acl_ctx *
 175 rte_acl_create(const struct rte_acl_param *param);
 176
 177 /**
 178  * Find an existing ACL context object and return a pointer to it.
 179  *
 180  * @param name
 181  *   Name of the ACL context as passed to rte_acl_create()
 182  * @return
 183  *   Pointer to ACL context or NULL if object not found
 184  *   with rte_errno set appropriately. Possible rte_errno values include:
 185  *    - ENOENT - value not available for return
 186  */
 187 struct rte_acl_ctx *
 188 rte_acl_find_existing(const char *name);
 189
 190 /**
 191  * De-allocate all memory used by ACL context.
 192  *
 193  * @param ctx
 194  *   ACL context to free
 195  */
 196 void
 197 rte_acl_free(struct rte_acl_ctx *ctx);
 198
 199 /**
 200  * Add rules to an existing ACL context.
 201  * This function is not multi-thread safe.
 202  *
 203  * @param ctx
 204  *   ACL context to add patterns to.
 205  * @param rules
 206  *   Array of rules to add to the ACL context.
 207  *   Note that all fields in rte_acl_rule structures are expected
 208  *   to be in host byte order.
 209  *   Each rule expected to be in the same format and not exceed size
 210  *   specified at ACL context creation time.
 211  * @param num
 212  *   Number of elements in the input array of rules.
 213  * @return
 214  *   - -ENOMEM if there is no space in the ACL context for these rules.
 215  *   - -EINVAL if the parameters are invalid.
 216  *   - Zero if operation completed successfully.
 217  */
 218 int
 219 rte_acl_add_rules(struct rte_acl_ctx *ctx, const struct rte_acl_rule *rules,
 220         uint32_t num);
 221
 222 /**
 223  * Delete all rules from the ACL context.
 224  * This function is not multi-thread safe.
 225  * Note that internal run-time structures are not affected.
 226  *
 227  * @param ctx
 228  *   ACL context to delete rules from.
 229  */
 230 void
 231 rte_acl_reset_rules(struct rte_acl_ctx *ctx);
 232
 233 /**
 234  * Analyze set of rules and build required internal run-time structures.
 235  * This function is not multi-thread safe.
 236  *
 237  * @param ctx
 238  *   ACL context to build.
 239  * @param cfg
 240  *   Pointer to struct rte_acl_config - defines build parameters.
 241  * @return
 242  *   - -ENOMEM if couldn't allocate enough memory.
 243  *   - -EINVAL if the parameters are invalid.
 244  *   - Negative error code if operation failed.
 245  *   - Zero if operation completed successfully.
 246  */
 247 int
 248 rte_acl_build(struct rte_acl_ctx *ctx, const struct rte_acl_config *cfg);
 249
 250 /**
 251  * Delete all rules from the ACL context and
 252  * destroy all internal run-time structures.
 253  * This function is not multi-thread safe.
 254  *
 255  * @param ctx
 256  *   ACL context to reset.
 257  */
 258 void
 259 rte_acl_reset(struct rte_acl_ctx *ctx);
 260
 261 /**
 262  * Search for a matching ACL rule for each input data buffer.
 263  * Each input data buffer can have up to *categories* matches.
 264  * That implies that results array should be big enough to hold
 265  * (categories * num) elements.
 266  * Also categories parameter should be either one or multiple of
 267  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
 268  * If more than one rule is applicable for given input buffer and
 269  * given category, then rule with highest priority will be returned as a match.
 270  * Note, that it is a caller responsibility to ensure that input parameters
 271  * are valid and point to correct memory locations.
 272  *
 273  * @param ctx
 274  *   ACL context to search with.
 275  * @param data
 276  *   Array of pointers to input data buffers to perform search.
 277  *   Note that all fields in input data buffers supposed to be in network
 278  *   byte order (MSB).
 279  * @param results
 280  *   Array of search results, *categories* results per each input data buffer.
 281  * @param num
 282  *   Number of elements in the input data buffers array.
 283  * @param categories
 284  *   Number of maximum possible matches for each input buffer, one possible
 285  *   match per category.
 286  * @return
 287  *   zero on successful completion.
 288  *   -EINVAL for incorrect arguments.
 289  */
 290 int
 291 rte_acl_classify(const struct rte_acl_ctx *ctx, const uint8_t **data,
 292         uint32_t *results, uint32_t num, uint32_t categories);
 293
 294 /**
 295  * Perform scalar search for a matching ACL rule for each input data buffer.
 296  * Note, that while the search itself will avoid explicit use of SSE/AVX
 297  * intrinsics, code for comparing matching results/priorities sill might use
 298  * vector intrinsics (for  categories > 1).
 299  * Each input data buffer can have up to *categories* matches.
 300  * That implies that results array should be big enough to hold
 301  * (categories * num) elements.
 302  * Also categories parameter should be either one or multiple of
 303  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
 304  * If more than one rule is applicable for given input buffer and
 305  * given category, then rule with highest priority will be returned as a match.
 306  * Note, that it is a caller's responsibility to ensure that input parameters
 307  * are valid and point to correct memory locations.
 308  *
 309  * @param ctx
 310  *   ACL context to search with.
 311  * @param data
 312  *   Array of pointers to input data buffers to perform search.
 313  *   Note that all fields in input data buffers supposed to be in network
 314  *   byte order (MSB).
 315  * @param results
 316  *   Array of search results, *categories* results per each input data buffer.
 317  * @param num
 318  *   Number of elements in the input data buffers array.
 319  * @param categories
 320  *   Number of maximum possible matches for each input buffer, one possible
 321  *   match per category.
 322  * @return
 323  *   zero on successful completion.
 324  *   -EINVAL for incorrect arguments.
 325  */
 326 int
 327 rte_acl_classify_scalar(const struct rte_acl_ctx *ctx, const uint8_t **data,
 328         uint32_t *results, uint32_t num, uint32_t categories);
 329
 330 /**
 331  * Dump an ACL context structure to the console.
 332  *
 333  * @param ctx
 334  *   ACL context to dump.
 335  */
 336 void
 337 rte_acl_dump(const struct rte_acl_ctx *ctx);
 338
 339 /**
 340  * Dump all ACL context structures to the console.
 341  */
 342 void
 343 rte_acl_list_dump(void);
 344
 345 /**
 346  * Legacy support for 7-tuple IPv4 and VLAN rule.
 347  * This structure and corresponding API is deprecated.
 348  */
 349 struct rte_acl_ipv4vlan_rule {
 350         struct rte_acl_rule_data data; /**< Miscellaneous data for the rule. */
 351         uint8_t proto;                 /**< IPv4 protocol ID. */
 352         uint8_t proto_mask;            /**< IPv4 protocol ID mask. */
 353         uint16_t vlan;                 /**< VLAN ID. */
 354         uint16_t vlan_mask;            /**< VLAN ID mask. */
 355         uint16_t domain;               /**< VLAN domain. */
 356         uint16_t domain_mask;          /**< VLAN domain mask. */
 357         uint32_t src_addr;             /**< IPv4 source address. */
 358         uint32_t src_mask_len;         /**< IPv4 source address mask. */
 359         uint32_t dst_addr;             /**< IPv4 destination address. */
 360         uint32_t dst_mask_len;         /**< IPv4 destination address mask. */
 361         uint16_t src_port_low;         /**< L4 source port low. */
 362         uint16_t src_port_high;        /**< L4 source port high. */
 363         uint16_t dst_port_low;         /**< L4 destination port low. */
 364         uint16_t dst_port_high;        /**< L4 destination port high. */
 365 };
 366
 367 /**
 368  * Specifies fields layout inside rte_acl_rule for rte_acl_ipv4vlan_rule.
 369  */
 370 enum {
 371         RTE_ACL_IPV4VLAN_PROTO_FIELD,
 372         RTE_ACL_IPV4VLAN_VLAN1_FIELD,
 373         RTE_ACL_IPV4VLAN_VLAN2_FIELD,
 374         RTE_ACL_IPV4VLAN_SRC_FIELD,
 375         RTE_ACL_IPV4VLAN_DST_FIELD,
 376         RTE_ACL_IPV4VLAN_SRCP_FIELD,
 377         RTE_ACL_IPV4VLAN_DSTP_FIELD,
 378         RTE_ACL_IPV4VLAN_NUM_FIELDS
 379 };
 380
 381 /**
 382  * Macro to define rule size for rte_acl_ipv4vlan_rule.
 383  */
 384 #define RTE_ACL_IPV4VLAN_RULE_SZ        \
 385         RTE_ACL_RULE_SZ(RTE_ACL_IPV4VLAN_NUM_FIELDS)
 386
 387 /*
 388  * That effectively defines order of IPV4VLAN classifications:
 389  *  - PROTO
 390  *  - VLAN (TAG and DOMAIN)
 391  *  - SRC IP ADDRESS
 392  *  - DST IP ADDRESS
 393  *  - PORTS (SRC and DST)
 394  */
 395 enum {
 396         RTE_ACL_IPV4VLAN_PROTO,
 397         RTE_ACL_IPV4VLAN_VLAN,
 398         RTE_ACL_IPV4VLAN_SRC,
 399         RTE_ACL_IPV4VLAN_DST,
 400         RTE_ACL_IPV4VLAN_PORTS,
 401         RTE_ACL_IPV4VLAN_NUM
 402 };
 403
 404 /**
 405  * Add ipv4vlan rules to an existing ACL context.
 406  * This function is not multi-thread safe.
 407  *
 408  * @param ctx
 409  *   ACL context to add patterns to.
 410  * @param rules
 411  *   Array of rules to add to the ACL context.
 412  *   Note that all fields in rte_acl_ipv4vlan_rule structures are expected
 413  *   to be in host byte order.
 414  * @param num
 415  *   Number of elements in the input array of rules.
 416  * @return
 417  *   - -ENOMEM if there is no space in the ACL context for these rules.
 418  *   - -EINVAL if the parameters are invalid.
 419  *   - Zero if operation completed successfully.
 420  */
 421 int
 422 rte_acl_ipv4vlan_add_rules(struct rte_acl_ctx *ctx,
 423         const struct rte_acl_ipv4vlan_rule *rules,
 424         uint32_t num);
 425
 426 /**
 427  * Analyze set of ipv4vlan rules and build required internal
 428  * run-time structures.
 429  * This function is not multi-thread safe.
 430  *
 431  * @param ctx
 432  *   ACL context to build.
 433  * @param layout
 434  *   Layout of input data to search through.
 435  * @param num_categories
 436  *   Maximum number of categories to use in that build.
 437  * @return
 438  *   - -ENOMEM if couldn't allocate enough memory.
 439  *   - -EINVAL if the parameters are invalid.
 440  *   - Negative error code if operation failed.
 441  *   - Zero if operation completed successfully.
 442  */
 443 int
 444 rte_acl_ipv4vlan_build(struct rte_acl_ctx *ctx,
 445         const uint32_t layout[RTE_ACL_IPV4VLAN_NUM],
 446         uint32_t num_categories);
 447
 448
 449 #ifdef __cplusplus
 450 }
 451 #endif
 452
 453 #endif /* _RTE_ACL_H_ */