1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2019 Mellanox Technologies, Ltd
5 #ifndef RTE_PMD_MLX5_COMMON_UTILS_H_
6 #define RTE_PMD_MLX5_COMMON_UTILS_H_
8 #include <rte_rwlock.h>
10 #include "mlx5_common.h"
12 /************************ mlx5 list *****************************/
14 /** Maximum size of string for naming. */
15 #define MLX5_NAME_SIZE 32
16 /** Maximum size of list. */
17 #define MLX5_LIST_MAX (RTE_MAX_LCORE + 2)
18 /** Global list index. */
19 #define MLX5_LIST_GLOBAL ((MLX5_LIST_MAX) - 1)
20 /** None rte core list index. */
21 #define MLX5_LIST_NLCORE ((MLX5_LIST_MAX) - 2)
26 * Structure of the entry in the mlx5 list, user should define its own struct
27 * that contains this in order to store the data.
29 struct mlx5_list_entry {
30 LIST_ENTRY(mlx5_list_entry) next; /* Entry pointers in the list. */
31 uint32_t ref_cnt __rte_aligned(8); /* 0 means, entry is invalid. */
34 struct mlx5_list_entry *gentry;
39 struct mlx5_list_cache {
40 LIST_HEAD(mlx5_list_head, mlx5_list_entry) h;
41 uint32_t inv_cnt; /* Invalid entries counter. */
42 } __rte_cache_aligned;
45 * Type of callback function for entry removal.
48 * The tool instance user context.
50 * The entry in the list.
52 typedef void (*mlx5_list_remove_cb)(void *tool_ctx,
53 struct mlx5_list_entry *entry);
56 * Type of function for user defined matching.
59 * The tool instance context.
61 * The entry in the list.
63 * The pointer to new entry context.
66 * 0 if matching, non-zero number otherwise.
68 typedef int (*mlx5_list_match_cb)(void *tool_ctx,
69 struct mlx5_list_entry *entry, void *ctx);
71 typedef struct mlx5_list_entry *(*mlx5_list_clone_cb)(void *tool_ctx,
72 struct mlx5_list_entry *entry, void *ctx);
74 typedef void (*mlx5_list_clone_free_cb)(void *tool_ctx,
75 struct mlx5_list_entry *entry);
78 * Type of function for user defined mlx5 list entry creation.
81 * The mlx5 tool instance context.
83 * The pointer to new entry context.
86 * Pointer of entry on success, NULL otherwise.
88 typedef struct mlx5_list_entry *(*mlx5_list_create_cb)(void *tool_ctx,
92 * Linked mlx5 list constant object.
94 struct mlx5_list_const {
95 char name[MLX5_NAME_SIZE]; /**< Name of the mlx5 list. */
96 void *ctx; /* user objects target to callback. */
97 bool lcores_share; /* Whether to share objects between the lcores. */
98 rte_spinlock_t lcore_lock; /* Lock for non-lcore list. */
99 mlx5_list_create_cb cb_create; /**< entry create callback. */
100 mlx5_list_match_cb cb_match; /**< entry match callback. */
101 mlx5_list_remove_cb cb_remove; /**< entry remove callback. */
102 mlx5_list_clone_cb cb_clone; /**< entry clone callback. */
103 mlx5_list_clone_free_cb cb_clone_free;
104 /**< entry clone free callback. */
108 * Linked mlx5 list inconstant data.
110 struct mlx5_list_inconst {
111 rte_rwlock_t lock; /* read/write lock. */
112 volatile uint32_t gen_cnt; /* List modification may update it. */
113 volatile uint32_t count; /* number of entries in list. */
114 struct mlx5_list_cache *cache[MLX5_LIST_MAX];
115 /* Lcore cache, last index is the global cache. */
119 * Linked mlx5 list structure.
121 * Entry in mlx5 list could be reused if entry already exists,
122 * reference count will increase and the existing entry returns.
124 * When destroy an entry from list, decrease reference count and only
125 * destroy when no further reference.
127 * Linked list is designed for limited number of entries,
128 * read mostly, less modification.
130 * For huge amount of entries, please consider hash list.
134 struct mlx5_list_const l_const;
135 struct mlx5_list_inconst l_inconst;
139 * Create a mlx5 list.
141 * For actions in SW-steering is only memory and can be allowed
142 * to create duplicate objects, the lists don't need to check if
143 * there are existing same objects in other sub local lists,
144 * search the object only in local list will be more efficient.
147 * Pointer to the hast list table.
149 * Name of the mlx5 list.
151 * Pointer to the list context data.
152 * @param lcores_share
153 * Whether to share objects between the lcores.
155 * Callback function for entry create.
157 * Callback function for entry match.
159 * Callback function for entry remove.
161 * List pointer on success, otherwise NULL.
164 struct mlx5_list *mlx5_list_create(const char *name, void *ctx,
166 mlx5_list_create_cb cb_create,
167 mlx5_list_match_cb cb_match,
168 mlx5_list_remove_cb cb_remove,
169 mlx5_list_clone_cb cb_clone,
170 mlx5_list_clone_free_cb cb_clone_free);
173 * Search an entry matching the key.
175 * Result returned might be destroyed by other thread, must use
176 * this function only in main thread.
179 * Pointer to the mlx5 list.
181 * Common context parameter used by entry callback function.
184 * Pointer of the list entry if found, NULL otherwise.
187 struct mlx5_list_entry *mlx5_list_lookup(struct mlx5_list *list,
191 * Reuse or create an entry to the mlx5 list.
194 * Pointer to the hast list table.
196 * Common context parameter used by callback function.
199 * registered entry on success, NULL otherwise
202 struct mlx5_list_entry *mlx5_list_register(struct mlx5_list *list,
206 * Remove an entry from the mlx5 list.
208 * User should guarantee the validity of the entry.
211 * Pointer to the hast list.
213 * Entry to be removed from the mlx5 list table.
215 * 0 on entry removed, 1 on entry still referenced.
218 int mlx5_list_unregister(struct mlx5_list *list,
219 struct mlx5_list_entry *entry);
222 * Destroy the mlx5 list.
225 * Pointer to the mlx5 list.
228 void mlx5_list_destroy(struct mlx5_list *list);
231 * Get entry number from the mlx5 list.
234 * Pointer to the hast list.
236 * mlx5 list entry number.
240 mlx5_list_get_entry_num(struct mlx5_list *list);
242 /********************* Hash List **********************/
244 /* Hash list bucket. */
245 struct mlx5_hlist_bucket {
246 struct mlx5_list_inconst l;
247 } __rte_cache_aligned;
250 * Hash list table structure
252 * The hash list bucket using the mlx5_list object for managing.
255 uint32_t mask; /* A mask for the bucket index range. */
257 bool direct_key; /* Whether to use the key directly as hash index. */
258 struct mlx5_list_const l_const; /* List constant data. */
259 struct mlx5_hlist_bucket buckets[] __rte_cache_aligned;
263 * Create a hash list table, the user can specify the list heads array size
264 * of the table, now the size should be a power of 2 in order to get better
265 * distribution for the entries. Each entry is a part of the whole data element
266 * and the caller should be responsible for the data element's allocation and
267 * cleanup / free. Key of each entry will be calculated with CRC in order to
268 * generate a little fairer distribution.
271 * Name of the hash list(optional).
273 * Heads array size of the hash list.
275 * Entry size to allocate if cb_create not specified.
277 * Whether to use the key directly as hash index.
278 * @param lcores_share
279 * Whether to share objects between the lcores.
281 * The hlist instance context.
283 * Callback function for entry create.
285 * Callback function for entry match.
287 * Callback function for entry remove.
289 * Callback function for entry clone.
290 * @param cb_clone_free
291 * Callback function for entry clone free.
293 * Pointer of the hash list table created, NULL on failure.
296 struct mlx5_hlist *mlx5_hlist_create(const char *name, uint32_t size,
297 bool direct_key, bool lcores_share,
298 void *ctx, mlx5_list_create_cb cb_create,
299 mlx5_list_match_cb cb_match,
300 mlx5_list_remove_cb cb_remove,
301 mlx5_list_clone_cb cb_clone,
302 mlx5_list_clone_free_cb cb_clone_free);
305 * Search an entry matching the key.
307 * Result returned might be destroyed by other thread, must use
308 * this function only in main thread.
311 * Pointer to the hast list table.
313 * Key for the searching entry.
315 * Common context parameter used by entry callback function.
318 * Pointer of the hlist entry if found, NULL otherwise.
321 struct mlx5_list_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
325 * Insert an entry to the hash list table, the entry is only part of whole data
326 * element and a 64B key is used for matching. User should construct the key or
327 * give a calculated hash signature and guarantee there is no collision.
330 * Pointer to the hast list table.
332 * Entry to be inserted into the hash list table.
334 * Common context parameter used by callback function.
337 * registered entry on success, NULL otherwise
340 struct mlx5_list_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
344 * Remove an entry from the hash list table. User should guarantee the validity
348 * Pointer to the hast list table. (not used)
350 * Entry to be removed from the hash list table.
352 * 0 on entry removed, 1 on entry still referenced.
355 int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_list_entry *entry);
358 * Destroy the hash list table, all the entries already inserted into the lists
359 * will be handled by the callback function provided by the user (including
360 * free if needed) before the table is freed.
363 * Pointer to the hast list table.
366 void mlx5_hlist_destroy(struct mlx5_hlist *h);
368 #endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */