]> git.proxmox.com Git - ceph.git/blame - ceph/src/spdk/dpdk/lib/librte_acl/rte_acl.h
import 15.2.0 Octopus source
[ceph.git] / ceph / src / spdk / dpdk / lib / librte_acl / rte_acl.h
CommitLineData
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
17extern "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
27union rte_acl_field_types {
28 uint8_t u8;
29 uint16_t u16;
30 uint32_t u32;
31 uint64_t u64;
32};
33
34enum {
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 */
51struct 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 */
63struct 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 */
75struct 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
87enum {
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 */
100struct 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
116RTE_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 */
128struct 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 */
147struct rte_acl_ctx *
148rte_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 */
160struct rte_acl_ctx *
161rte_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 */
169void
170rte_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 */
191int
192rte_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 */
203void
204rte_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 */
220int
221rte_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 */
231void
232rte_acl_reset(struct rte_acl_ctx *ctx);
233
234/**
235 * Available implementations of ACL classify.
236 */
237enum 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 */
276extern int
277rte_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 */
316extern int
317rte_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 */
335extern int
336rte_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 */
345void
346rte_acl_dump(const struct rte_acl_ctx *ctx);
347
348/**
349 * Dump all ACL context structures to the console.
350 */
351void
352rte_acl_list_dump(void);
353
354#ifdef __cplusplus
355}
356#endif
357
358#endif /* _RTE_ACL_H_ */