DPDK  18.08.0
rte_efd.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2016-2017 Intel Corporation
3  */
4 
5 #ifndef _RTE_EFD_H_
6 #define _RTE_EFD_H_
7 
14 #include <stdint.h>
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 /*************************************************************************
21  * User selectable constants
22  *************************************************************************/
23 
24 /*
25  * If possible, best lookup performance will be achieved by ensuring that
26  * the entire table fits in the L3 cache.
27  *
28  * Some formulas for calculating various sizes are listed below:
29  *
30  * # of chunks =
31  * 2 ^ (ceiling(log2((requested # of rules) /
32  * (EFD_CHUNK_NUM_GROUPS * EFD_TARGET_GROUP_NUM_RULES))))
33  *
34  * Target # of rules = (# of chunks) * EFD_CHUNK_NUM_GROUPS *
35  * EFD_TARGET_GROUP_NUM_RULES
36  *
37  * Group Size (in bytes) = 4 (per value bit)
38  *
39  * Table size (in bytes) = RTE_EFD_VALUE_NUM_BITS * (# of chunks) *
40  * EFD_CHUNK_NUM_GROUPS * (group size)
41  */
42 
64 #ifndef RTE_EFD_VALUE_NUM_BITS
65 #define RTE_EFD_VALUE_NUM_BITS (8)
66 #endif
67 
68 /*
69  * EFD_TARGET_GROUP_NUM_RULES:
70  * Adjusts how many groups/chunks are allocated at table creation time
71  * to support the requested number of rules. Higher values pack entries
72  * more tightly in memory, resulting in a smaller memory footprint
73  * for the online table.
74  * This comes at the cost of lower insert/update performance.
75  *
76  * EFD_MAX_GROUP_NUM_RULES:
77  * This adjusts the amount of offline memory allocated to store key/value
78  * pairs for the table. The recommended numbers are upper-bounds for
79  * this parameter
80  * - any higher and it becomes very unlikely that a perfect hash function
81  * can be found for that group size. This value should be at
82  * least 40% larger than EFD_TARGET_GROUP_NUM_RULES
83  *
84  * Recommended values for various lookuptable and hashfunc sizes are:
85  *
86  * HASH_FUNC_SIZE = 16, LOOKUPTBL_SIZE = 16:
87  * EFD_TARGET_GROUP_NUM_RULES = 22
88  * EFD_MAX_GROUP_NUM_RULES = 28
89  */
90 #define EFD_TARGET_GROUP_NUM_RULES (22)
91 #define EFD_MAX_GROUP_NUM_RULES (28LU)
92 
93 #define EFD_MIN_BALANCED_NUM_RULES 5
94 
98 #ifndef RTE_EFD_BURST_MAX
99 #define RTE_EFD_BURST_MAX (32)
100 #endif
101 
103 #define RTE_EFD_NAMESIZE 32
104 
105 #if (RTE_EFD_VALUE_NUM_BITS > 0 && RTE_EFD_VALUE_NUM_BITS <= 8)
106 typedef uint8_t efd_value_t;
107 #elif (RTE_EFD_VALUE_NUM_BITS > 8 && RTE_EFD_VALUE_NUM_BITS <= 16)
108 typedef uint16_t efd_value_t;
109 #elif (RTE_EFD_VALUE_NUM_BITS > 16 && RTE_EFD_VALUE_NUM_BITS <= 32)
110 typedef uint32_t efd_value_t;
111 #else
112 #error("RTE_EFD_VALUE_NUM_BITS must be in the range [1:32]")
113 #endif
114 
115 #define EFD_LOOKUPTBL_SHIFT (32 - 4)
116 typedef uint16_t efd_lookuptbl_t;
117 typedef uint16_t efd_hashfunc_t;
118 
140 struct rte_efd_table *
141 rte_efd_create(const char *name, uint32_t max_num_rules, uint32_t key_len,
142  uint8_t online_cpu_socket_bitmask, uint8_t offline_cpu_socket);
143 
150 void
151 rte_efd_free(struct rte_efd_table *table);
152 
163 struct rte_efd_table*
164 rte_efd_find_existing(const char *name);
165 
166 #define RTE_EFD_UPDATE_WARN_GROUP_FULL (1)
167 #define RTE_EFD_UPDATE_NO_CHANGE (2)
168 #define RTE_EFD_UPDATE_FAILED (3)
169 
199 int
200 rte_efd_update(struct rte_efd_table *table, unsigned int socket_id,
201  const void *key, efd_value_t value);
202 
221 int
222 rte_efd_delete(struct rte_efd_table *table, unsigned int socket_id,
223  const void *key, efd_value_t *prev_value);
224 
245 efd_value_t
246 rte_efd_lookup(const struct rte_efd_table *table, unsigned int socket_id,
247  const void *key);
248 
270 void
271 rte_efd_lookup_bulk(const struct rte_efd_table *table, unsigned int socket_id,
272  int num_keys, const void **key_list,
273  efd_value_t *value_list);
274 
275 #ifdef __cplusplus
276 }
277 #endif
278 
279 #endif /* _RTE_EFD_H_ */