4 * Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
43 #include <rte_acl_osdep.h>
49 #define RTE_ACL_MAX_CATEGORIES 16
51 #define RTE_ACL_RESULTS_MULTIPLIER (XMM_SIZE / sizeof(uint32_t))
53 #define RTE_ACL_MAX_LEVELS 64
54 #define RTE_ACL_MAX_FIELDS 64
56 union rte_acl_field_types {
64 RTE_ACL_FIELD_TYPE_MASK = 0,
65 RTE_ACL_FIELD_TYPE_RANGE,
66 RTE_ACL_FIELD_TYPE_BITMASK
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
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. */
89 * ACL build configuration.
90 * Defines the fields of an ACL trie and number of categories to build with.
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. */
98 /**< max memory limit for internal run-time structures. */
102 * Defines the value of a field for a rule.
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;
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.
117 RTE_ACL_TYPE_SHIFT = 29,
118 RTE_ACL_MAX_INDEX = LEN2MASK(RTE_ACL_TYPE_SHIFT),
119 RTE_ACL_MAX_PRIORITY = RTE_ACL_MAX_INDEX,
120 RTE_ACL_MIN_PRIORITY = 0,
123 #define RTE_ACL_INVALID_USERDATA 0
126 * Miscellaneous data for ACL rule.
128 struct rte_acl_rule_data {
129 uint32_t category_mask; /**< Mask of categories for that rule. */
130 int32_t priority; /**< Priority for that rule. */
131 uint32_t userdata; /**< Associated with the rule user data. */
135 * Defines single ACL rule.
136 * data - miscellaneous data for the rule.
137 * field[] - value and mask or range for each field.
139 #define RTE_ACL_RULE_DEF(name, fld_num) struct name {\
140 struct rte_acl_rule_data data; \
141 struct rte_acl_field field[fld_num]; \
144 RTE_ACL_RULE_DEF(rte_acl_rule, 0);
146 #define RTE_ACL_RULE_SZ(fld_num) \
147 (sizeof(struct rte_acl_rule) + sizeof(struct rte_acl_field) * (fld_num))
150 /** Max number of characters in name.*/
151 #define RTE_ACL_NAMESIZE 32
154 * Parameters used when creating the ACL context.
156 struct rte_acl_param {
157 const char *name; /**< Name of the ACL context. */
158 int socket_id; /**< Socket ID to allocate memory for. */
159 uint32_t rule_size; /**< Size of each rule. */
160 uint32_t max_rule_num; /**< Maximum number of rules. */
165 * Create a new ACL context.
168 * Parameters used to create and initialise the ACL context.
170 * Pointer to ACL context structure that is used in future ACL
171 * operations, or NULL on error, with error code set in rte_errno.
172 * Possible rte_errno errors include:
173 * - EINVAL - invalid parameter passed to function
176 rte_acl_create(const struct rte_acl_param *param);
179 * Find an existing ACL context object and return a pointer to it.
182 * Name of the ACL context as passed to rte_acl_create()
184 * Pointer to ACL context or NULL if object not found
185 * with rte_errno set appropriately. Possible rte_errno values include:
186 * - ENOENT - value not available for return
189 rte_acl_find_existing(const char *name);
192 * De-allocate all memory used by ACL context.
195 * ACL context to free
198 rte_acl_free(struct rte_acl_ctx *ctx);
201 * Add rules to an existing ACL context.
202 * This function is not multi-thread safe.
205 * ACL context to add patterns to.
207 * Array of rules to add to the ACL context.
208 * Note that all fields in rte_acl_rule structures are expected
209 * to be in host byte order.
210 * Each rule expected to be in the same format and not exceed size
211 * specified at ACL context creation time.
213 * Number of elements in the input array of rules.
215 * - -ENOMEM if there is no space in the ACL context for these rules.
216 * - -EINVAL if the parameters are invalid.
217 * - Zero if operation completed successfully.
220 rte_acl_add_rules(struct rte_acl_ctx *ctx, const struct rte_acl_rule *rules,
224 * Delete all rules from the ACL context.
225 * This function is not multi-thread safe.
226 * Note that internal run-time structures are not affected.
229 * ACL context to delete rules from.
232 rte_acl_reset_rules(struct rte_acl_ctx *ctx);
235 * Analyze set of rules and build required internal run-time structures.
236 * This function is not multi-thread safe.
239 * ACL context to build.
241 * Pointer to struct rte_acl_config - defines build parameters.
243 * - -ENOMEM if couldn't allocate enough memory.
244 * - -EINVAL if the parameters are invalid.
245 * - Negative error code if operation failed.
246 * - Zero if operation completed successfully.
249 rte_acl_build(struct rte_acl_ctx *ctx, const struct rte_acl_config *cfg);
252 * Delete all rules from the ACL context and
253 * destroy all internal run-time structures.
254 * This function is not multi-thread safe.
257 * ACL context to reset.
260 rte_acl_reset(struct rte_acl_ctx *ctx);
263 * Available implementations of ACL classify.
265 enum rte_acl_classify_alg {
266 RTE_ACL_CLASSIFY_DEFAULT = 0,
267 RTE_ACL_CLASSIFY_SCALAR = 1, /**< generic implementation. */
268 RTE_ACL_CLASSIFY_SSE = 2, /**< requires SSE4.1 support. */
269 RTE_ACL_CLASSIFY_AVX2 = 3, /**< requires AVX2 support. */
270 RTE_ACL_CLASSIFY_NUM /* should always be the last one. */
274 * Perform search for a matching ACL rule for each input data buffer.
275 * Each input data buffer can have up to *categories* matches.
276 * That implies that results array should be big enough to hold
277 * (categories * num) elements.
278 * Also categories parameter should be either one or multiple of
279 * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
280 * If more than one rule is applicable for given input buffer and
281 * given category, then rule with highest priority will be returned as a match.
282 * Note, that it is a caller's responsibility to ensure that input parameters
283 * are valid and point to correct memory locations.
286 * ACL context to search with.
288 * Array of pointers to input data buffers to perform search.
289 * Note that all fields in input data buffers supposed to be in network
292 * Array of search results, *categories* results per each input data buffer.
294 * Number of elements in the input data buffers array.
296 * Number of maximum possible matches for each input buffer, one possible
297 * match per category.
299 * zero on successful completion.
300 * -EINVAL for incorrect arguments.
303 rte_acl_classify(const struct rte_acl_ctx *ctx,
304 const uint8_t **data,
305 uint32_t *results, uint32_t num,
306 uint32_t categories);
309 * Perform search using specified algorithm for a matching ACL rule for
310 * each input data buffer.
311 * Each input data buffer can have up to *categories* matches.
312 * That implies that results array should be big enough to hold
313 * (categories * num) elements.
314 * Also categories parameter should be either one or multiple of
315 * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
316 * If more than one rule is applicable for given input buffer and
317 * given category, then rule with highest priority will be returned as a match.
318 * Note, that it is a caller's responsibility to ensure that input parameters
319 * are valid and point to correct memory locations.
322 * ACL context to search with.
324 * Array of pointers to input data buffers to perform search.
325 * Note that all fields in input data buffers supposed to be in network
328 * Array of search results, *categories* results per each input data buffer.
330 * Number of elements in the input data buffers array.
332 * Number of maximum possible matches for each input buffer, one possible
333 * match per category.
335 * Algorithm to be used for the search.
336 * It is the caller responsibility to ensure that the value refers to the
337 * existing algorithm, and that it could be run on the given CPU.
339 * zero on successful completion.
340 * -EINVAL for incorrect arguments.
343 rte_acl_classify_alg(const struct rte_acl_ctx *ctx,
344 const uint8_t **data,
345 uint32_t *results, uint32_t num,
347 enum rte_acl_classify_alg alg);
350 * Override the default classifier function for a given ACL context.
352 * ACL context to change classify function for.
354 * New default classify algorithm for given ACL context.
355 * It is the caller responsibility to ensure that the value refers to the
356 * existing algorithm, and that it could be run on the given CPU.
358 * - -EINVAL if the parameters are invalid.
359 * - Zero if operation completed successfully.
362 rte_acl_set_ctx_classify(struct rte_acl_ctx *ctx,
363 enum rte_acl_classify_alg alg);
366 * Dump an ACL context structure to the console.
369 * ACL context to dump.
372 rte_acl_dump(const struct rte_acl_ctx *ctx);
375 * Dump all ACL context structures to the console.
378 rte_acl_list_dump(void);
381 * Legacy support for 7-tuple IPv4 and VLAN rule.
382 * This structure and corresponding API is deprecated.
384 struct rte_acl_ipv4vlan_rule {
385 struct rte_acl_rule_data data; /**< Miscellaneous data for the rule. */
386 uint8_t proto; /**< IPv4 protocol ID. */
387 uint8_t proto_mask; /**< IPv4 protocol ID mask. */
388 uint16_t vlan; /**< VLAN ID. */
389 uint16_t vlan_mask; /**< VLAN ID mask. */
390 uint16_t domain; /**< VLAN domain. */
391 uint16_t domain_mask; /**< VLAN domain mask. */
392 uint32_t src_addr; /**< IPv4 source address. */
393 uint32_t src_mask_len; /**< IPv4 source address mask. */
394 uint32_t dst_addr; /**< IPv4 destination address. */
395 uint32_t dst_mask_len; /**< IPv4 destination address mask. */
396 uint16_t src_port_low; /**< L4 source port low. */
397 uint16_t src_port_high; /**< L4 source port high. */
398 uint16_t dst_port_low; /**< L4 destination port low. */
399 uint16_t dst_port_high; /**< L4 destination port high. */
403 * Specifies fields layout inside rte_acl_rule for rte_acl_ipv4vlan_rule.
406 RTE_ACL_IPV4VLAN_PROTO_FIELD,
407 RTE_ACL_IPV4VLAN_VLAN1_FIELD,
408 RTE_ACL_IPV4VLAN_VLAN2_FIELD,
409 RTE_ACL_IPV4VLAN_SRC_FIELD,
410 RTE_ACL_IPV4VLAN_DST_FIELD,
411 RTE_ACL_IPV4VLAN_SRCP_FIELD,
412 RTE_ACL_IPV4VLAN_DSTP_FIELD,
413 RTE_ACL_IPV4VLAN_NUM_FIELDS
417 * Macro to define rule size for rte_acl_ipv4vlan_rule.
419 #define RTE_ACL_IPV4VLAN_RULE_SZ \
420 RTE_ACL_RULE_SZ(RTE_ACL_IPV4VLAN_NUM_FIELDS)
423 * That effectively defines order of IPV4VLAN classifications:
425 * - VLAN (TAG and DOMAIN)
428 * - PORTS (SRC and DST)
431 RTE_ACL_IPV4VLAN_PROTO,
432 RTE_ACL_IPV4VLAN_VLAN,
433 RTE_ACL_IPV4VLAN_SRC,
434 RTE_ACL_IPV4VLAN_DST,
435 RTE_ACL_IPV4VLAN_PORTS,
440 * Add ipv4vlan rules to an existing ACL context.
441 * This function is not multi-thread safe.
444 * ACL context to add patterns to.
446 * Array of rules to add to the ACL context.
447 * Note that all fields in rte_acl_ipv4vlan_rule structures are expected
448 * to be in host byte order.
450 * Number of elements in the input array of rules.
452 * - -ENOMEM if there is no space in the ACL context for these rules.
453 * - -EINVAL if the parameters are invalid.
454 * - Zero if operation completed successfully.
457 rte_acl_ipv4vlan_add_rules(struct rte_acl_ctx *ctx,
458 const struct rte_acl_ipv4vlan_rule *rules,
462 * Analyze set of ipv4vlan rules and build required internal
463 * run-time structures.
464 * This function is not multi-thread safe.
467 * ACL context to build.
469 * Layout of input data to search through.
470 * @param num_categories
471 * Maximum number of categories to use in that build.
473 * - -ENOMEM if couldn't allocate enough memory.
474 * - -EINVAL if the parameters are invalid.
475 * - Negative error code if operation failed.
476 * - Zero if operation completed successfully.
479 rte_acl_ipv4vlan_build(struct rte_acl_ctx *ctx,
480 const uint32_t layout[RTE_ACL_IPV4VLAN_NUM],
481 uint32_t num_categories);
488 #endif /* _RTE_ACL_H_ */