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 definition.
  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         size_t max_size;
  98         /**< max memory limit for internal run-time structures. */
  99 };
 100
 101 /**
 102  * Defines the value of a field for a rule.
 103  */
 104 struct rte_acl_field {
 105         union rte_acl_field_types value;
 106         /**< a 1,2,4, or 8 byte value of the field. */
 107         union rte_acl_field_types mask_range;
 108         /**<
 109          * depending on field type:
 110          * mask -> 1.2.3.4/32 value=0x1020304, mask_range=32,
 111          * range -> 0 : 65535 value=0, mask_range=65535,
 112          * bitmask -> 0x06/0xff value=6, mask_range=0xff.
 113          */
 114 };
 115
 116 enum {
 117         RTE_ACL_TYPE_SHIFT = 29,
 118         RTE_ACL_MAX_INDEX = RTE_LEN2MASK(RTE_ACL_TYPE_SHIFT, uint32_t),
 119         RTE_ACL_MAX_PRIORITY = RTE_ACL_MAX_INDEX,
 120         RTE_ACL_MIN_PRIORITY = 1,
 121 };
 122
 123 #define RTE_ACL_INVALID_USERDATA        0
 124
 125 #define RTE_ACL_MASKLEN_TO_BITMASK(v, s)        \
 126 ((v) == 0 ? (v) : (typeof(v))((uint64_t)-1 << ((s) * CHAR_BIT - (v))))
 127
 128 /**
 129  * Miscellaneous data for ACL rule.
 130  */
 131 struct rte_acl_rule_data {
 132         uint32_t category_mask; /**< Mask of categories for that rule. */
 133         int32_t  priority;      /**< Priority for that rule. */
 134         uint32_t userdata;      /**< Associated with the rule user data. */
 135 };
 136
 137 /**
 138  * Defines single ACL rule.
 139  * data - miscellaneous data for the rule.
 140  * field[] - value and mask or range for each field.
 141  */
 142 #define RTE_ACL_RULE_DEF(name, fld_num) struct name {\
 143         struct rte_acl_rule_data data;               \
 144         struct rte_acl_field field[fld_num];         \
 145 }
 146
 147 RTE_ACL_RULE_DEF(rte_acl_rule,);
 148
 149 #define RTE_ACL_RULE_SZ(fld_num)        \
 150         (sizeof(struct rte_acl_rule) + sizeof(struct rte_acl_field) * (fld_num))
 151
 152
 153 /** Max number of characters in name.*/
 154 #define RTE_ACL_NAMESIZE                32
 155
 156 /**
 157  * Parameters used when creating the ACL context.
 158  */
 159 struct rte_acl_param {
 160         const char *name;         /**< Name of the ACL context. */
 161         int         socket_id;    /**< Socket ID to allocate memory for. */
 162         uint32_t    rule_size;    /**< Size of each rule. */
 163         uint32_t    max_rule_num; /**< Maximum number of rules. */
 164 };
 165
 166
 167 /**
 168  * Create a new ACL context.
 169  *
 170  * @param param
 171  *   Parameters used to create and initialise the ACL context.
 172  * @return
 173  *   Pointer to ACL context structure that is used in future ACL
 174  *   operations, or NULL on error, with error code set in rte_errno.
 175  *   Possible rte_errno errors include:
 176  *   - EINVAL - invalid parameter passed to function
 177  */
 178 struct rte_acl_ctx *
 179 rte_acl_create(const struct rte_acl_param *param);
 180
 181 /**
 182  * Find an existing ACL context object and return a pointer to it.
 183  *
 184  * @param name
 185  *   Name of the ACL context as passed to rte_acl_create()
 186  * @return
 187  *   Pointer to ACL context or NULL if object not found
 188  *   with rte_errno set appropriately. Possible rte_errno values include:
 189  *    - ENOENT - value not available for return
 190  */
 191 struct rte_acl_ctx *
 192 rte_acl_find_existing(const char *name);
 193
 194 /**
 195  * De-allocate all memory used by ACL context.
 196  *
 197  * @param ctx
 198  *   ACL context to free
 199  */
 200 void
 201 rte_acl_free(struct rte_acl_ctx *ctx);
 202
 203 /**
 204  * Add rules to an existing ACL context.
 205  * This function is not multi-thread safe.
 206  *
 207  * @param ctx
 208  *   ACL context to add patterns to.
 209  * @param rules
 210  *   Array of rules to add to the ACL context.
 211  *   Note that all fields in rte_acl_rule structures are expected
 212  *   to be in host byte order.
 213  *   Each rule expected to be in the same format and not exceed size
 214  *   specified at ACL context creation time.
 215  * @param num
 216  *   Number of elements in the input array of rules.
 217  * @return
 218  *   - -ENOMEM if there is no space in the ACL context for these rules.
 219  *   - -EINVAL if the parameters are invalid.
 220  *   - Zero if operation completed successfully.
 221  */
 222 int
 223 rte_acl_add_rules(struct rte_acl_ctx *ctx, const struct rte_acl_rule *rules,
 224         uint32_t num);
 225
 226 /**
 227  * Delete all rules from the ACL context.
 228  * This function is not multi-thread safe.
 229  * Note that internal run-time structures are not affected.
 230  *
 231  * @param ctx
 232  *   ACL context to delete rules from.
 233  */
 234 void
 235 rte_acl_reset_rules(struct rte_acl_ctx *ctx);
 236
 237 /**
 238  * Analyze set of rules and build required internal run-time structures.
 239  * This function is not multi-thread safe.
 240  *
 241  * @param ctx
 242  *   ACL context to build.
 243  * @param cfg
 244  *   Pointer to struct rte_acl_config - defines build parameters.
 245  * @return
 246  *   - -ENOMEM if couldn't allocate enough memory.
 247  *   - -EINVAL if the parameters are invalid.
 248  *   - Negative error code if operation failed.
 249  *   - Zero if operation completed successfully.
 250  */
 251 int
 252 rte_acl_build(struct rte_acl_ctx *ctx, const struct rte_acl_config *cfg);
 253
 254 /**
 255  * Delete all rules from the ACL context and
 256  * destroy all internal run-time structures.
 257  * This function is not multi-thread safe.
 258  *
 259  * @param ctx
 260  *   ACL context to reset.
 261  */
 262 void
 263 rte_acl_reset(struct rte_acl_ctx *ctx);
 264
 265 /**
 266  *  Available implementations of ACL classify.
 267  */
 268 enum rte_acl_classify_alg {
 269         RTE_ACL_CLASSIFY_DEFAULT = 0,
 270         RTE_ACL_CLASSIFY_SCALAR = 1,  /**< generic implementation. */
 271         RTE_ACL_CLASSIFY_SSE = 2,     /**< requires SSE4.1 support. */
 272         RTE_ACL_CLASSIFY_AVX2 = 3,    /**< requires AVX2 support. */
 273         RTE_ACL_CLASSIFY_NEON = 4,    /**< requires NEON support. */
 274         RTE_ACL_CLASSIFY_ALTIVEC = 5,    /**< requires ALTIVEC support. */
 275         RTE_ACL_CLASSIFY_NUM          /* should always be the last one. */
 276 };
 277
 278 /**
 279  * Perform search for a matching ACL rule for each input data buffer.
 280  * Each input data buffer can have up to *categories* matches.
 281  * That implies that results array should be big enough to hold
 282  * (categories * num) elements.
 283  * Also categories parameter should be either one or multiple of
 284  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
 285  * If more than one rule is applicable for given input buffer and
 286  * given category, then rule with highest priority will be returned as a match.
 287  * Note, that it is a caller's responsibility to ensure that input parameters
 288  * are valid and point to correct memory locations.
 289  *
 290  * @param ctx
 291  *   ACL context to search with.
 292  * @param data
 293  *   Array of pointers to input data buffers to perform search.
 294  *   Note that all fields in input data buffers supposed to be in network
 295  *   byte order (MSB).
 296  * @param results
 297  *   Array of search results, *categories* results per each input data buffer.
 298  * @param num
 299  *   Number of elements in the input data buffers array.
 300  * @param categories
 301  *   Number of maximum possible matches for each input buffer, one possible
 302  *   match per category.
 303  * @return
 304  *   zero on successful completion.
 305  *   -EINVAL for incorrect arguments.
 306  */
 307 extern int
 308 rte_acl_classify(const struct rte_acl_ctx *ctx,
 309                  const uint8_t **data,
 310                  uint32_t *results, uint32_t num,
 311                  uint32_t categories);
 312
 313 /**
 314  * Perform search using specified algorithm for a matching ACL rule for
 315  * each input data buffer.
 316  * Each input data buffer can have up to *categories* matches.
 317  * That implies that results array should be big enough to hold
 318  * (categories * num) elements.
 319  * Also categories parameter should be either one or multiple of
 320  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
 321  * If more than one rule is applicable for given input buffer and
 322  * given category, then rule with highest priority will be returned as a match.
 323  * Note, that it is a caller's responsibility to ensure that input parameters
 324  * are valid and point to correct memory locations.
 325  *
 326  * @param ctx
 327  *   ACL context to search with.
 328  * @param data
 329  *   Array of pointers to input data buffers to perform search.
 330  *   Note that all fields in input data buffers supposed to be in network
 331  *   byte order (MSB).
 332  * @param results
 333  *   Array of search results, *categories* results per each input data buffer.
 334  * @param num
 335  *   Number of elements in the input data buffers array.
 336  * @param categories
 337  *   Number of maximum possible matches for each input buffer, one possible
 338  *   match per category.
 339  * @param alg
 340  *   Algorithm to be used for the search.
 341  *   It is the caller responsibility to ensure that the value refers to the
 342  *   existing algorithm, and that it could be run on the given CPU.
 343  * @return
 344  *   zero on successful completion.
 345  *   -EINVAL for incorrect arguments.
 346  */
 347 extern int
 348 rte_acl_classify_alg(const struct rte_acl_ctx *ctx,
 349                  const uint8_t **data,
 350                  uint32_t *results, uint32_t num,
 351                  uint32_t categories,
 352                  enum rte_acl_classify_alg alg);
 353
 354 /*
 355  * Override the default classifier function for a given ACL context.
 356  * @param ctx
 357  *   ACL context to change classify function for.
 358  * @param alg
 359  *   New default classify algorithm for given ACL context.
 360  *   It is the caller responsibility to ensure that the value refers to the
 361  *   existing algorithm, and that it could be run on the given CPU.
 362  * @return
 363  *   - -EINVAL if the parameters are invalid.
 364  *   - Zero if operation completed successfully.
 365  */
 366 extern int
 367 rte_acl_set_ctx_classify(struct rte_acl_ctx *ctx,
 368         enum rte_acl_classify_alg alg);
 369
 370 /**
 371  * Dump an ACL context structure to the console.
 372  *
 373  * @param ctx
 374  *   ACL context to dump.
 375  */
 376 void
 377 rte_acl_dump(const struct rte_acl_ctx *ctx);
 378
 379 /**
 380  * Dump all ACL context structures to the console.
 381  */
 382 void
 383 rte_acl_list_dump(void);
 384
 385 #ifdef __cplusplus
 386 }
 387 #endif
 388
 389 #endif /* _RTE_ACL_H_ */