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 "mlx5_common.h"
10 /************************ mlx5 list *****************************/
12 /** Maximum size of string for naming. */
13 #define MLX5_NAME_SIZE 32
18 * Structure of the entry in the mlx5 list, user should define its own struct
19 * that contains this in order to store the data.
21 struct mlx5_list_entry {
22 LIST_ENTRY(mlx5_list_entry) next; /* Entry pointers in the list. */
23 uint32_t ref_cnt; /* 0 means, entry is invalid. */
25 struct mlx5_list_entry *gentry;
28 struct mlx5_list_cache {
29 LIST_HEAD(mlx5_list_head, mlx5_list_entry) h;
30 uint32_t inv_cnt; /* Invalid entries counter. */
31 } __rte_cache_aligned;
34 * Type of callback function for entry removal.
39 * The entry in the list.
41 typedef void (*mlx5_list_remove_cb)(struct mlx5_list *list,
42 struct mlx5_list_entry *entry);
45 * Type of function for user defined matching.
50 * The entry in the list.
52 * The pointer to new entry context.
55 * 0 if matching, non-zero number otherwise.
57 typedef int (*mlx5_list_match_cb)(struct mlx5_list *list,
58 struct mlx5_list_entry *entry, void *ctx);
60 typedef struct mlx5_list_entry *(*mlx5_list_clone_cb)
61 (struct mlx5_list *list,
62 struct mlx5_list_entry *entry, void *ctx);
64 typedef void (*mlx5_list_clone_free_cb)(struct mlx5_list *list,
65 struct mlx5_list_entry *entry);
68 * Type of function for user defined mlx5 list entry creation.
73 * The new allocated entry, NULL if list entry size unspecified,
74 * New entry has to be allocated in callback and return.
76 * The pointer to new entry context.
79 * Pointer of entry on success, NULL otherwise.
81 typedef struct mlx5_list_entry *(*mlx5_list_create_cb)
82 (struct mlx5_list *list,
83 struct mlx5_list_entry *entry,
87 * Linked mlx5 list structure.
89 * Entry in mlx5 list could be reused if entry already exists,
90 * reference count will increase and the existing entry returns.
92 * When destroy an entry from list, decrease reference count and only
93 * destroy when no further reference.
95 * Linked list is designed for limited number of entries,
96 * read mostly, less modification.
98 * For huge amount of entries, please consider hash list.
102 char name[MLX5_NAME_SIZE]; /**< Name of the mlx5 list. */
103 void *ctx; /* user objects target to callback. */
104 bool lcores_share; /* Whether to share objects between the lcores. */
105 mlx5_list_create_cb cb_create; /**< entry create callback. */
106 mlx5_list_match_cb cb_match; /**< entry match callback. */
107 mlx5_list_remove_cb cb_remove; /**< entry remove callback. */
108 mlx5_list_clone_cb cb_clone; /**< entry clone callback. */
109 mlx5_list_clone_free_cb cb_clone_free;
110 struct mlx5_list_cache cache[RTE_MAX_LCORE + 1];
111 /* Lcore cache, last index is the global cache. */
112 volatile uint32_t gen_cnt; /* List modification may update it. */
113 volatile uint32_t count; /* number of entries in list. */
114 rte_rwlock_t lock; /* read/write lock. */
118 * Create a mlx5 list.
120 * For actions in SW-steering is only memory and can be allowed
121 * to create duplicate objects, the lists don't need to check if
122 * there are existing same objects in other sub local lists,
123 * search the object only in local list will be more efficient.
126 * Pointer to the hast list table.
128 * Name of the mlx5 list.
130 * Pointer to the list context data.
131 * @param lcores_share
132 * Whether to share objects between the lcores.
134 * Callback function for entry create.
136 * Callback function for entry match.
138 * Callback function for entry remove.
140 * List pointer on success, otherwise NULL.
143 struct mlx5_list *mlx5_list_create(const char *name, void *ctx,
145 mlx5_list_create_cb cb_create,
146 mlx5_list_match_cb cb_match,
147 mlx5_list_remove_cb cb_remove,
148 mlx5_list_clone_cb cb_clone,
149 mlx5_list_clone_free_cb cb_clone_free);
152 * Search an entry matching the key.
154 * Result returned might be destroyed by other thread, must use
155 * this function only in main thread.
158 * Pointer to the mlx5 list.
160 * Common context parameter used by entry callback function.
163 * Pointer of the list entry if found, NULL otherwise.
166 struct mlx5_list_entry *mlx5_list_lookup(struct mlx5_list *list,
170 * Reuse or create an entry to the mlx5 list.
173 * Pointer to the hast list table.
175 * Common context parameter used by callback function.
178 * registered entry on success, NULL otherwise
181 struct mlx5_list_entry *mlx5_list_register(struct mlx5_list *list,
185 * Remove an entry from the mlx5 list.
187 * User should guarantee the validity of the entry.
190 * Pointer to the hast list.
192 * Entry to be removed from the mlx5 list table.
194 * 0 on entry removed, 1 on entry still referenced.
197 int mlx5_list_unregister(struct mlx5_list *list,
198 struct mlx5_list_entry *entry);
201 * Destroy the mlx5 list.
204 * Pointer to the mlx5 list.
207 void mlx5_list_destroy(struct mlx5_list *list);
210 * Get entry number from the mlx5 list.
213 * Pointer to the hast list.
215 * mlx5 list entry number.
219 mlx5_list_get_entry_num(struct mlx5_list *list);
221 /************************ Hash list *****************************/
223 #define MLX5_HLIST_DIRECT_KEY 0x0001 /* Use the key directly as hash index. */
224 #define MLX5_HLIST_WRITE_MOST 0x0002 /* List mostly used for append new. */
226 /** Maximum size of string for naming the hlist table. */
227 #define MLX5_HLIST_NAMESIZE 32
232 * Structure of the entry in the hash list, user should define its own struct
233 * that contains this in order to store the data. The 'key' is 64-bits right
234 * now and its user's responsibility to guarantee there is no collision.
236 struct mlx5_hlist_entry {
237 LIST_ENTRY(mlx5_hlist_entry) next; /* entry pointers in the list. */
238 uint32_t idx; /* Bucket index the entry belongs to. */
239 uint32_t ref_cnt; /* Reference count. */
242 /** Structure for hash head. */
243 LIST_HEAD(mlx5_hlist_head, mlx5_hlist_entry);
246 * Type of callback function for entry removal.
251 * The entry in the list.
253 typedef void (*mlx5_hlist_remove_cb)(struct mlx5_hlist *list,
254 struct mlx5_hlist_entry *entry);
257 * Type of function for user defined matching.
262 * The entry in the list.
266 * The pointer to new entry context.
269 * 0 if matching, non-zero number otherwise.
271 typedef int (*mlx5_hlist_match_cb)(struct mlx5_hlist *list,
272 struct mlx5_hlist_entry *entry,
273 uint64_t key, void *ctx);
276 * Type of function for user defined hash list entry creation.
281 * The key of the new entry.
283 * The pointer to new entry context.
286 * Pointer to allocated entry on success, NULL otherwise.
288 typedef struct mlx5_hlist_entry *(*mlx5_hlist_create_cb)
289 (struct mlx5_hlist *list,
290 uint64_t key, void *ctx);
292 /* Hash list bucket head. */
293 struct mlx5_hlist_bucket {
294 struct mlx5_hlist_head head; /* List head. */
295 rte_rwlock_t lock; /* Bucket lock. */
296 uint32_t gen_cnt; /* List modification will update generation count. */
297 } __rte_cache_aligned;
300 * Hash list table structure
302 * Entry in hash list could be reused if entry already exists, reference
303 * count will increase and the existing entry returns.
305 * When destroy an entry from list, decrease reference count and only
306 * destroy when no further reference.
309 char name[MLX5_HLIST_NAMESIZE]; /**< Name of the hash list. */
310 /**< number of heads, need to be power of 2. */
312 uint32_t entry_sz; /**< Size of entry, used to allocate entry. */
313 /**< mask to get the index of the list heads. */
315 bool direct_key; /* Use the new entry key directly as hash index. */
316 bool write_most; /* List mostly used for append new or destroy. */
318 mlx5_hlist_create_cb cb_create; /**< entry create callback. */
319 mlx5_hlist_match_cb cb_match; /**< entry match callback. */
320 mlx5_hlist_remove_cb cb_remove; /**< entry remove callback. */
321 struct mlx5_hlist_bucket buckets[] __rte_cache_aligned;
322 /**< list bucket arrays. */
326 * Create a hash list table, the user can specify the list heads array size
327 * of the table, now the size should be a power of 2 in order to get better
328 * distribution for the entries. Each entry is a part of the whole data element
329 * and the caller should be responsible for the data element's allocation and
330 * cleanup / free. Key of each entry will be calculated with CRC in order to
331 * generate a little fairer distribution.
334 * Name of the hash list(optional).
336 * Heads array size of the hash list.
338 * Entry size to allocate if cb_create not specified.
340 * The hash list attribute flags.
342 * Callback function for entry create.
344 * Callback function for entry match.
346 * Callback function for entry destroy.
348 * Pointer of the hash list table created, NULL on failure.
351 struct mlx5_hlist *mlx5_hlist_create(const char *name, uint32_t size,
352 uint32_t entry_size, uint32_t flags,
353 mlx5_hlist_create_cb cb_create,
354 mlx5_hlist_match_cb cb_match,
355 mlx5_hlist_remove_cb cb_destroy);
358 * Search an entry matching the key.
360 * Result returned might be destroyed by other thread, must use
361 * this function only in main thread.
364 * Pointer to the hast list table.
366 * Key for the searching entry.
368 * Common context parameter used by entry callback function.
371 * Pointer of the hlist entry if found, NULL otherwise.
374 struct mlx5_hlist_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
378 * Insert an entry to the hash list table, the entry is only part of whole data
379 * element and a 64B key is used for matching. User should construct the key or
380 * give a calculated hash signature and guarantee there is no collision.
383 * Pointer to the hast list table.
385 * Entry to be inserted into the hash list table.
387 * Common context parameter used by callback function.
390 * registered entry on success, NULL otherwise
393 struct mlx5_hlist_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
397 * Remove an entry from the hash list table. User should guarantee the validity
401 * Pointer to the hast list table. (not used)
403 * Entry to be removed from the hash list table.
405 * 0 on entry removed, 1 on entry still referenced.
408 int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_hlist_entry *entry);
411 * Destroy the hash list table, all the entries already inserted into the lists
412 * will be handled by the callback function provided by the user (including
413 * free if needed) before the table is freed.
416 * Pointer to the hast list table.
419 void mlx5_hlist_destroy(struct mlx5_hlist *h);
421 #endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */