e1000: use the right debug macro
[dpdk.git] / 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 defintion.
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 };
98
99 /**
100  * Defines the value of a field for a rule.
101  */
102 struct rte_acl_field {
103         union rte_acl_field_types value;
104         /**< a 1,2,4, or 8 byte value of the field. */
105         union rte_acl_field_types mask_range;
106         /**<
107          * depending on field type:
108          * mask -> 1.2.3.4/32 value=0x1020304, mask_range=32,
109          * range -> 0 : 65535 value=0, mask_range=65535,
110          * bitmask -> 0x06/0xff value=6, mask_range=0xff.
111          */
112 };
113
114 enum {
115         RTE_ACL_TYPE_SHIFT = 29,
116         RTE_ACL_MAX_INDEX = LEN2MASK(RTE_ACL_TYPE_SHIFT),
117         RTE_ACL_MAX_PRIORITY = RTE_ACL_MAX_INDEX,
118         RTE_ACL_MIN_PRIORITY = 0,
119 };
120
121 #define RTE_ACL_INVALID_USERDATA        0
122
123 /**
124  * Miscellaneous data for ACL rule.
125  */
126 struct rte_acl_rule_data {
127         uint32_t category_mask; /**< Mask of categories for that rule. */
128         int32_t  priority;      /**< Priority for that rule. */
129         uint32_t userdata;      /**< Associated with the rule user data. */
130 };
131
132 /**
133  * Defines single ACL rule.
134  * data - miscellaneous data for the rule.
135  * field[] - value and mask or range for each field.
136  */
137 #define RTE_ACL_RULE_DEF(name, fld_num) struct name {\
138         struct rte_acl_rule_data data;               \
139         struct rte_acl_field field[fld_num];         \
140 }
141
142 RTE_ACL_RULE_DEF(rte_acl_rule, 0);
143
144 #define RTE_ACL_RULE_SZ(fld_num)        \
145         (sizeof(struct rte_acl_rule) + sizeof(struct rte_acl_field) * (fld_num))
146
147
148 /** Max number of characters in name.*/
149 #define RTE_ACL_NAMESIZE                32
150
151 /**
152  * Parameters used when creating the ACL context.
153  */
154 struct rte_acl_param {
155         const char *name;         /**< Name of the ACL context. */
156         int         socket_id;    /**< Socket ID to allocate memory for. */
157         uint32_t    rule_size;    /**< Size of each rule. */
158         uint32_t    max_rule_num; /**< Maximum number of rules. */
159 };
160
161
162 /**
163  * Create a new ACL context.
164  *
165  * @param param
166  *   Parameters used to create and initialise the ACL context.
167  * @return
168  *   Pointer to ACL context structure that is used in future ACL
169  *   operations, or NULL on error, with error code set in rte_errno.
170  *   Possible rte_errno errors include:
171  *   - E_RTE_NO_TAILQ - no tailq list could be got for the ACL context list
172  *   - EINVAL - invalid parameter passed to function
173  */
174 struct rte_acl_ctx *
175 rte_acl_create(const struct rte_acl_param *param);
176
177 /**
178  * Find an existing ACL context object and return a pointer to it.
179  *
180  * @param name
181  *   Name of the ACL context as passed to rte_acl_create()
182  * @return
183  *   Pointer to ACL context or NULL if object not found
184  *   with rte_errno set appropriately. Possible rte_errno values include:
185  *    - ENOENT - value not available for return
186  */
187 struct rte_acl_ctx *
188 rte_acl_find_existing(const char *name);
189
190 /**
191  * De-allocate all memory used by ACL context.
192  *
193  * @param ctx
194  *   ACL context to free
195  */
196 void
197 rte_acl_free(struct rte_acl_ctx *ctx);
198
199 /**
200  * Add rules to an existing ACL context.
201  * This function is not multi-thread safe.
202  *
203  * @param ctx
204  *   ACL context to add patterns to.
205  * @param rules
206  *   Array of rules to add to the ACL context.
207  *   Note that all fields in rte_acl_rule structures are expected
208  *   to be in host byte order.
209  *   Each rule expected to be in the same format and not exceed size
210  *   specified at ACL context creation time.
211  * @param num
212  *   Number of elements in the input array of rules.
213  * @return
214  *   - -ENOMEM if there is no space in the ACL context for these rules.
215  *   - -EINVAL if the parameters are invalid.
216  *   - Zero if operation completed successfully.
217  */
218 int
219 rte_acl_add_rules(struct rte_acl_ctx *ctx, const struct rte_acl_rule *rules,
220         uint32_t num);
221
222 /**
223  * Delete all rules from the ACL context.
224  * This function is not multi-thread safe.
225  * Note that internal run-time structures are not affected.
226  *
227  * @param ctx
228  *   ACL context to delete rules from.
229  */
230 void
231 rte_acl_reset_rules(struct rte_acl_ctx *ctx);
232
233 /**
234  * Analyze set of rules and build required internal run-time structures.
235  * This function is not multi-thread safe.
236  *
237  * @param ctx
238  *   ACL context to build.
239  * @param cfg
240  *   Pointer to struct rte_acl_config - defines build parameters.
241  * @return
242  *   - -ENOMEM if couldn't allocate enough memory.
243  *   - -EINVAL if the parameters are invalid.
244  *   - Negative error code if operation failed.
245  *   - Zero if operation completed successfully.
246  */
247 int
248 rte_acl_build(struct rte_acl_ctx *ctx, const struct rte_acl_config *cfg);
249
250 /**
251  * Delete all rules from the ACL context and
252  * destroy all internal run-time structures.
253  * This function is not multi-thread safe.
254  *
255  * @param ctx
256  *   ACL context to reset.
257  */
258 void
259 rte_acl_reset(struct rte_acl_ctx *ctx);
260
261 /**
262  *  Avaialble implementations of ACL classify.
263  */
264 enum rte_acl_classify_alg {
265         RTE_ACL_CLASSIFY_DEFAULT = 0,
266         RTE_ACL_CLASSIFY_SCALAR = 1,  /**< generic implementation. */
267         RTE_ACL_CLASSIFY_SSE = 2,     /**< requries SSE4.1 support. */
268 };
269
270 /**
271  * Perform search for a matching ACL rule for each input data buffer.
272  * Each input data buffer can have up to *categories* matches.
273  * That implies that results array should be big enough to hold
274  * (categories * num) elements.
275  * Also categories parameter should be either one or multiple of
276  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
277  * If more than one rule is applicable for given input buffer and
278  * given category, then rule with highest priority will be returned as a match.
279  * Note, that it is a caller's responsibility to ensure that input parameters
280  * are valid and point to correct memory locations.
281  *
282  * @param ctx
283  *   ACL context to search with.
284  * @param data
285  *   Array of pointers to input data buffers to perform search.
286  *   Note that all fields in input data buffers supposed to be in network
287  *   byte order (MSB).
288  * @param results
289  *   Array of search results, *categories* results per each input data buffer.
290  * @param num
291  *   Number of elements in the input data buffers array.
292  * @param categories
293  *   Number of maximum possible matches for each input buffer, one possible
294  *   match per category.
295  * @return
296  *   zero on successful completion.
297  *   -EINVAL for incorrect arguments.
298  */
299 extern int
300 rte_acl_classify(const struct rte_acl_ctx *ctx,
301                  const uint8_t **data,
302                  uint32_t *results, uint32_t num,
303                  uint32_t categories);
304
305 /**
306  * Perform search using specified algorithm for a matching ACL rule for
307  * each input data buffer.
308  * Each input data buffer can have up to *categories* matches.
309  * That implies that results array should be big enough to hold
310  * (categories * num) elements.
311  * Also categories parameter should be either one or multiple of
312  * RTE_ACL_RESULTS_MULTIPLIER and can't be bigger than RTE_ACL_MAX_CATEGORIES.
313  * If more than one rule is applicable for given input buffer and
314  * given category, then rule with highest priority will be returned as a match.
315  * Note, that it is a caller's responsibility to ensure that input parameters
316  * are valid and point to correct memory locations.
317  *
318  * @param ctx
319  *   ACL context to search with.
320  * @param data
321  *   Array of pointers to input data buffers to perform search.
322  *   Note that all fields in input data buffers supposed to be in network
323  *   byte order (MSB).
324  * @param results
325  *   Array of search results, *categories* results per each input data buffer.
326  * @param num
327  *   Number of elements in the input data buffers array.
328  * @param categories
329  *   Number of maximum possible matches for each input buffer, one possible
330  *   match per category.
331  * @param alg
332  *   Algorithm to be used for the search.
333  *   It is the caller responibility to ensure that the value refers to the
334  *   existing algorithm, and that it could be run on the given CPU.
335  * @return
336  *   zero on successful completion.
337  *   -EINVAL for incorrect arguments.
338  */
339 extern int
340 rte_acl_classify_alg(const struct rte_acl_ctx *ctx,
341                  const uint8_t **data,
342                  uint32_t *results, uint32_t num,
343                  uint32_t categories,
344                  enum rte_acl_classify_alg alg);
345
346 /*
347  * Override the default classifier function for a given ACL context.
348  * @param ctx
349  *   ACL context to change classify function for.
350  * @param alg
351  *   New default classify algorithm for given ACL context.
352  *   It is the caller responibility to ensure that the value refers to the
353  *   existing algorithm, and that it could be run on the given CPU.
354  * @return
355  *   - -EINVAL if the parameters are invalid.
356  *   - Zero if operation completed successfully.
357  */
358 extern int
359 rte_acl_set_ctx_classify(struct rte_acl_ctx *ctx,
360         enum rte_acl_classify_alg alg);
361
362 /**
363  * Dump an ACL context structure to the console.
364  *
365  * @param ctx
366  *   ACL context to dump.
367  */
368 void
369 rte_acl_dump(const struct rte_acl_ctx *ctx);
370
371 /**
372  * Dump all ACL context structures to the console.
373  */
374 void
375 rte_acl_list_dump(void);
376
377 /**
378  * Legacy support for 7-tuple IPv4 and VLAN rule.
379  * This structure and corresponding API is deprecated.
380  */
381 struct rte_acl_ipv4vlan_rule {
382         struct rte_acl_rule_data data; /**< Miscellaneous data for the rule. */
383         uint8_t proto;                 /**< IPv4 protocol ID. */
384         uint8_t proto_mask;            /**< IPv4 protocol ID mask. */
385         uint16_t vlan;                 /**< VLAN ID. */
386         uint16_t vlan_mask;            /**< VLAN ID mask. */
387         uint16_t domain;               /**< VLAN domain. */
388         uint16_t domain_mask;          /**< VLAN domain mask. */
389         uint32_t src_addr;             /**< IPv4 source address. */
390         uint32_t src_mask_len;         /**< IPv4 source address mask. */
391         uint32_t dst_addr;             /**< IPv4 destination address. */
392         uint32_t dst_mask_len;         /**< IPv4 destination address mask. */
393         uint16_t src_port_low;         /**< L4 source port low. */
394         uint16_t src_port_high;        /**< L4 source port high. */
395         uint16_t dst_port_low;         /**< L4 destination port low. */
396         uint16_t dst_port_high;        /**< L4 destination port high. */
397 };
398
399 /**
400  * Specifies fields layout inside rte_acl_rule for rte_acl_ipv4vlan_rule.
401  */
402 enum {
403         RTE_ACL_IPV4VLAN_PROTO_FIELD,
404         RTE_ACL_IPV4VLAN_VLAN1_FIELD,
405         RTE_ACL_IPV4VLAN_VLAN2_FIELD,
406         RTE_ACL_IPV4VLAN_SRC_FIELD,
407         RTE_ACL_IPV4VLAN_DST_FIELD,
408         RTE_ACL_IPV4VLAN_SRCP_FIELD,
409         RTE_ACL_IPV4VLAN_DSTP_FIELD,
410         RTE_ACL_IPV4VLAN_NUM_FIELDS
411 };
412
413 /**
414  * Macro to define rule size for rte_acl_ipv4vlan_rule.
415  */
416 #define RTE_ACL_IPV4VLAN_RULE_SZ        \
417         RTE_ACL_RULE_SZ(RTE_ACL_IPV4VLAN_NUM_FIELDS)
418
419 /*
420  * That effectively defines order of IPV4VLAN classifications:
421  *  - PROTO
422  *  - VLAN (TAG and DOMAIN)
423  *  - SRC IP ADDRESS
424  *  - DST IP ADDRESS
425  *  - PORTS (SRC and DST)
426  */
427 enum {
428         RTE_ACL_IPV4VLAN_PROTO,
429         RTE_ACL_IPV4VLAN_VLAN,
430         RTE_ACL_IPV4VLAN_SRC,
431         RTE_ACL_IPV4VLAN_DST,
432         RTE_ACL_IPV4VLAN_PORTS,
433         RTE_ACL_IPV4VLAN_NUM
434 };
435
436 /**
437  * Add ipv4vlan rules to an existing ACL context.
438  * This function is not multi-thread safe.
439  *
440  * @param ctx
441  *   ACL context to add patterns to.
442  * @param rules
443  *   Array of rules to add to the ACL context.
444  *   Note that all fields in rte_acl_ipv4vlan_rule structures are expected
445  *   to be in host byte order.
446  * @param num
447  *   Number of elements in the input array of rules.
448  * @return
449  *   - -ENOMEM if there is no space in the ACL context for these rules.
450  *   - -EINVAL if the parameters are invalid.
451  *   - Zero if operation completed successfully.
452  */
453 int
454 rte_acl_ipv4vlan_add_rules(struct rte_acl_ctx *ctx,
455         const struct rte_acl_ipv4vlan_rule *rules,
456         uint32_t num);
457
458 /**
459  * Analyze set of ipv4vlan rules and build required internal
460  * run-time structures.
461  * This function is not multi-thread safe.
462  *
463  * @param ctx
464  *   ACL context to build.
465  * @param layout
466  *   Layout of input data to search through.
467  * @param num_categories
468  *   Maximum number of categories to use in that build.
469  * @return
470  *   - -ENOMEM if couldn't allocate enough memory.
471  *   - -EINVAL if the parameters are invalid.
472  *   - Negative error code if operation failed.
473  *   - Zero if operation completed successfully.
474  */
475 int
476 rte_acl_ipv4vlan_build(struct rte_acl_ctx *ctx,
477         const uint32_t layout[RTE_ACL_IPV4VLAN_NUM],
478         uint32_t num_categories);
479
480
481 #ifdef __cplusplus
482 }
483 #endif
484
485 #endif /* _RTE_ACL_H_ */