]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | /* SPDX-License-Identifier: BSD-3-Clause |
2 | * Copyright(c) 2010-2014 Intel Corporation | |
7c673cae FG |
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, | |
9f95a23c | 91 | RTE_ACL_MIN_PRIORITY = 1, |
7c673cae FG |
92 | }; |
93 | ||
7c673cae FG |
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_ */ |