net/mlx5: use SPDX tags in 6WIND copyrighted files
[dpdk.git] / lib / librte_acl / rte_acl.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef _RTE_ACL_H_
6 #define _RTE_ACL_H_
7
8 /**
9  * @file
10  *
11  * RTE Classifier.
12  */
13
14 #include <rte_acl_osdep.h>
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 #define RTE_ACL_MAX_CATEGORIES  16
21
22 #define RTE_ACL_RESULTS_MULTIPLIER      (XMM_SIZE / sizeof(uint32_t))
23
24 #define RTE_ACL_MAX_LEVELS 64
25 #define RTE_ACL_MAX_FIELDS 64
26
27 union rte_acl_field_types {
28         uint8_t  u8;
29         uint16_t u16;
30         uint32_t u32;
31         uint64_t u64;
32 };
33
34 enum {
35         RTE_ACL_FIELD_TYPE_MASK = 0,
36         RTE_ACL_FIELD_TYPE_RANGE,
37         RTE_ACL_FIELD_TYPE_BITMASK
38 };
39
40 /**
41  * ACL Field definition.
42  * Each field in the ACL rule has an associate definition.
43  * It defines the type of field, its size, its offset in the input buffer,
44  * the field index, and the input index.
45  * For performance reasons, the inner loop of the search function is unrolled
46  * to process four input bytes at a time. This requires the input to be grouped
47  * into sets of 4 consecutive bytes. The loop processes the first input byte as
48  * part of the setup and then subsequent bytes must be in groups of 4
49  * consecutive bytes.
50  */
51 struct rte_acl_field_def {
52         uint8_t  type;        /**< type - RTE_ACL_FIELD_TYPE_*. */
53         uint8_t  size;        /**< size of field 1,2,4, or 8. */
54         uint8_t  field_index; /**< index of field inside the rule. */
55         uint8_t  input_index; /**< 0-N input index. */
56         uint32_t offset;      /**< offset to start of field. */
57 };
58
59 /**
60  * ACL build configuration.
61  * Defines the fields of an ACL trie and number of categories to build with.
62  */
63 struct rte_acl_config {
64         uint32_t num_categories; /**< Number of categories to build with. */
65         uint32_t num_fields;     /**< Number of field definitions. */
66         struct rte_acl_field_def defs[RTE_ACL_MAX_FIELDS];
67         /**< array of field definitions. */
68         size_t max_size;
69         /**< max memory limit for internal run-time structures. */
70 };
71
72 /**
73  * Defines the value of a field for a rule.
74  */
75 struct rte_acl_field {
76         union rte_acl_field_types value;
77         /**< a 1,2,4, or 8 byte value of the field. */
78         union rte_acl_field_types mask_range;
79         /**<
80          * depending on field type:
81          * mask -> 1.2.3.4/32 value=0x1020304, mask_range=32,
82          * range -> 0 : 65535 value=0, mask_range=65535,
83          * bitmask -> 0x06/0xff value=6, mask_range=0xff.
84          */
85 };
86
87 enum {
88         RTE_ACL_TYPE_SHIFT = 29,
89         RTE_ACL_MAX_INDEX = RTE_LEN2MASK(RTE_ACL_TYPE_SHIFT, uint32_t),
90         RTE_ACL_MAX_PRIORITY = RTE_ACL_MAX_INDEX,
91         RTE_ACL_MIN_PRIORITY = 0,
92 };
93
94 #define RTE_ACL_MASKLEN_TO_BITMASK(v, s)        \
95 ((v) == 0 ? (v) : (typeof(v))((uint64_t)-1 << ((s) * CHAR_BIT - (v))))
96
97 /**
98  * Miscellaneous data for ACL rule.
99  */
100 struct rte_acl_rule_data {
101         uint32_t category_mask; /**< Mask of categories for that rule. */
102         int32_t  priority;      /**< Priority for that rule. */
103         uint32_t userdata;      /**< Associated with the rule user data. */
104 };
105
106 /**
107  * Defines single ACL rule.
108  * data - miscellaneous data for the rule.
109  * field[] - value and mask or range for each field.
110  */
111 #define RTE_ACL_RULE_DEF(name, fld_num) struct name {\
112         struct rte_acl_rule_data data;               \
113         struct rte_acl_field field[fld_num];         \
114 }
115
116 RTE_ACL_RULE_DEF(rte_acl_rule,);
117
118 #define RTE_ACL_RULE_SZ(fld_num)        \
119         (sizeof(struct rte_acl_rule) + sizeof(struct rte_acl_field) * (fld_num))
120
121
122 /** Max number of characters in name.*/
123 #define RTE_ACL_NAMESIZE                32
124
125 /**
126  * Parameters used when creating the ACL context.
127  */
128 struct rte_acl_param {
129         const char *name;         /**< Name of the ACL context. */
130         int         socket_id;    /**< Socket ID to allocate memory for. */
131         uint32_t    rule_size;    /**< Size of each rule. */
132         uint32_t    max_rule_num; /**< Maximum number of rules. */
133 };
134
135
136 /**
137  * Create a new ACL context.
138  *
139  * @param param
140  *   Parameters used to create and initialise the ACL context.
141  * @return
142  *   Pointer to ACL context structure that is used in future ACL
143  *   operations, or NULL on error, with error code set in rte_errno.
144  *   Possible rte_errno errors include:
145  *   - EINVAL - invalid parameter passed to function
146  */
147 struct rte_acl_ctx *
148 rte_acl_create(const struct rte_acl_param *param);
149
150 /**
151  * Find an existing ACL context object and return a pointer to it.
152  *
153  * @param name
154  *   Name of the ACL context as passed to rte_acl_create()
155  * @return
156  *   Pointer to ACL context or NULL if object not found
157  *   with rte_errno set appropriately. Possible rte_errno values include:
158  *    - ENOENT - value not available for return
159  */
160 struct rte_acl_ctx *
161 rte_acl_find_existing(const char *name);
162
163 /**
164  * De-allocate all memory used by ACL context.
165  *
166  * @param ctx
167  *   ACL context to free
168  */
169 void
170 rte_acl_free(struct rte_acl_ctx *ctx);
171
172 /**
173  * Add rules to an existing ACL context.
174  * This function is not multi-thread safe.
175  *
176  * @param ctx
177  *   ACL context to add patterns to.
178  * @param rules
179  *   Array of rules to add to the ACL context.
180  *   Note that all fields in rte_acl_rule structures are expected
181  *   to be in host byte order.
182  *   Each rule expected to be in the same format and not exceed size
183  *   specified at ACL context creation time.
184  * @param num
185  *   Number of elements in the input array of rules.
186  * @return
187  *   - -ENOMEM if there is no space in the ACL context for these rules.
188  *   - -EINVAL if the parameters are invalid.
189  *   - Zero if operation completed successfully.
190  */
191 int
192 rte_acl_add_rules(struct rte_acl_ctx *ctx, const struct rte_acl_rule *rules,
193         uint32_t num);
194
195 /**
196  * Delete all rules from the ACL context.
197  * This function is not multi-thread safe.
198  * Note that internal run-time structures are not affected.
199  *
200  * @param ctx
201  *   ACL context to delete rules from.
202  */
203 void
204 rte_acl_reset_rules(struct rte_acl_ctx *ctx);
205
206 /**
207  * Analyze set of rules and build required internal run-time structures.
208  * This function is not multi-thread safe.
209  *
210  * @param ctx
211  *   ACL context to build.
212  * @param cfg
213  *   Pointer to struct rte_acl_config - defines build parameters.
214  * @return
215  *   - -ENOMEM if couldn't allocate enough memory.
216  *   - -EINVAL if the parameters are invalid.
217  *   - Negative error code if operation failed.
218  *   - Zero if operation completed successfully.
219  */
220 int
221 rte_acl_build(struct rte_acl_ctx *ctx, const struct rte_acl_config *cfg);
222
223 /**
224  * Delete all rules from the ACL context and
225  * destroy all internal run-time structures.
226  * This function is not multi-thread safe.
227  *
228  * @param ctx
229  *   ACL context to reset.
230  */
231 void
232 rte_acl_reset(struct rte_acl_ctx *ctx);
233
234 /**
235  *  Available implementations of ACL classify.
236  */
237 enum rte_acl_classify_alg {
238         RTE_ACL_CLASSIFY_DEFAULT = 0,
239         RTE_ACL_CLASSIFY_SCALAR = 1,  /**< generic implementation. */
240         RTE_ACL_CLASSIFY_SSE = 2,     /**< requires SSE4.1 support. */
241         RTE_ACL_CLASSIFY_AVX2 = 3,    /**< requires AVX2 support. */
242         RTE_ACL_CLASSIFY_NEON = 4,    /**< requires NEON support. */
243         RTE_ACL_CLASSIFY_ALTIVEC = 5,    /**< requires ALTIVEC support. */
244         RTE_ACL_CLASSIFY_NUM          /* should always be the last one. */
245 };
246
247 /**
248  * Perform search for a matching ACL rule for each input data buffer.
249  * Each input data buffer can have up to *categories* matches.
250  * That implies that results array should be big enough to hold
251  * (categories * num) elements.
252  * Also categories parameter should be either one or multiple of
253  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
254  * If more than one rule is applicable for given input buffer and
255  * given category, then rule with highest priority will be returned as a match.
256  * Note, that it is a caller's responsibility to ensure that input parameters
257  * are valid and point to correct memory locations.
258  *
259  * @param ctx
260  *   ACL context to search with.
261  * @param data
262  *   Array of pointers to input data buffers to perform search.
263  *   Note that all fields in input data buffers supposed to be in network
264  *   byte order (MSB).
265  * @param results
266  *   Array of search results, *categories* results per each input data buffer.
267  * @param num
268  *   Number of elements in the input data buffers array.
269  * @param categories
270  *   Number of maximum possible matches for each input buffer, one possible
271  *   match per category.
272  * @return
273  *   zero on successful completion.
274  *   -EINVAL for incorrect arguments.
275  */
276 extern int
277 rte_acl_classify(const struct rte_acl_ctx *ctx,
278                  const uint8_t **data,
279                  uint32_t *results, uint32_t num,
280                  uint32_t categories);
281
282 /**
283  * Perform search using specified algorithm for a matching ACL rule for
284  * each input data buffer.
285  * Each input data buffer can have up to *categories* matches.
286  * That implies that results array should be big enough to hold
287  * (categories * num) elements.
288  * Also categories parameter should be either one or multiple of
289  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
290  * If more than one rule is applicable for given input buffer and
291  * given category, then rule with highest priority will be returned as a match.
292  * Note, that it is a caller's responsibility to ensure that input parameters
293  * are valid and point to correct memory locations.
294  *
295  * @param ctx
296  *   ACL context to search with.
297  * @param data
298  *   Array of pointers to input data buffers to perform search.
299  *   Note that all fields in input data buffers supposed to be in network
300  *   byte order (MSB).
301  * @param results
302  *   Array of search results, *categories* results per each input data buffer.
303  * @param num
304  *   Number of elements in the input data buffers array.
305  * @param categories
306  *   Number of maximum possible matches for each input buffer, one possible
307  *   match per category.
308  * @param alg
309  *   Algorithm to be used for the search.
310  *   It is the caller responsibility to ensure that the value refers to the
311  *   existing algorithm, and that it could be run on the given CPU.
312  * @return
313  *   zero on successful completion.
314  *   -EINVAL for incorrect arguments.
315  */
316 extern int
317 rte_acl_classify_alg(const struct rte_acl_ctx *ctx,
318                  const uint8_t **data,
319                  uint32_t *results, uint32_t num,
320                  uint32_t categories,
321                  enum rte_acl_classify_alg alg);
322
323 /*
324  * Override the default classifier function for a given ACL context.
325  * @param ctx
326  *   ACL context to change classify function for.
327  * @param alg
328  *   New default classify algorithm for given ACL context.
329  *   It is the caller responsibility to ensure that the value refers to the
330  *   existing algorithm, and that it could be run on the given CPU.
331  * @return
332  *   - -EINVAL if the parameters are invalid.
333  *   - Zero if operation completed successfully.
334  */
335 extern int
336 rte_acl_set_ctx_classify(struct rte_acl_ctx *ctx,
337         enum rte_acl_classify_alg alg);
338
339 /**
340  * Dump an ACL context structure to the console.
341  *
342  * @param ctx
343  *   ACL context to dump.
344  */
345 void
346 rte_acl_dump(const struct rte_acl_ctx *ctx);
347
348 /**
349  * Dump all ACL context structures to the console.
350  */
351 void
352 rte_acl_list_dump(void);
353
354 #ifdef __cplusplus
355 }
356 #endif
357
358 #endif /* _RTE_ACL_H_ */