1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2015 Intel Corporation
21 /** Maximum size of hash table that can be created. */
22 #define RTE_HASH_ENTRIES_MAX (1 << 30)
24 /** Maximum number of characters in hash name.*/
25 #define RTE_HASH_NAMESIZE 32
27 /** Maximum number of keys that can be searched for using rte_hash_lookup_bulk. */
28 #define RTE_HASH_LOOKUP_BULK_MAX 64
29 #define RTE_HASH_LOOKUP_MULTI_MAX RTE_HASH_LOOKUP_BULK_MAX
31 /** Enable Hardware transactional memory support. */
32 #define RTE_HASH_EXTRA_FLAGS_TRANS_MEM_SUPPORT 0x01
34 /** Default behavior of insertion, single writer/multi writer */
35 #define RTE_HASH_EXTRA_FLAGS_MULTI_WRITER_ADD 0x02
37 /** Signature of key that is stored internally. */
38 typedef uint32_t hash_sig_t;
40 /** Type of function that can be used for calculating the hash value. */
41 typedef uint32_t (*rte_hash_function)(const void *key, uint32_t key_len,
44 /** Type of function used to compare the hash key. */
45 typedef int (*rte_hash_cmp_eq_t)(const void *key1, const void *key2, size_t key_len);
48 * Parameters used when creating the hash table.
50 struct rte_hash_parameters {
51 const char *name; /**< Name of the hash. */
52 uint32_t entries; /**< Total hash table entries. */
53 uint32_t reserved; /**< Unused field. Should be set to 0 */
54 uint32_t key_len; /**< Length of hash key. */
55 rte_hash_function hash_func; /**< Primary Hash function used to calculate hash. */
56 uint32_t hash_func_init_val; /**< Init value used by hash_func. */
57 int socket_id; /**< NUMA Socket ID for memory. */
58 uint8_t extra_flag; /**< Indicate if additional parameters are present. */
61 /** @internal A hash table structure. */
65 * Create a new hash table.
68 * Parameters used to create and initialise the hash table.
70 * Pointer to hash table structure that is used in future hash table
71 * operations, or NULL on error, with error code set in rte_errno.
72 * Possible rte_errno errors include:
73 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
74 * - E_RTE_SECONDARY - function was called from a secondary process instance
75 * - ENOENT - missing entry
76 * - EINVAL - invalid parameter passed to function
77 * - ENOSPC - the maximum number of memzones has already been allocated
78 * - EEXIST - a memzone with the same name already exists
79 * - ENOMEM - no appropriate memory area found in which to create memzone
82 rte_hash_create(const struct rte_hash_parameters *params);
85 * Set a new hash compare function other than the default one.
87 * @note Function pointer does not work with multi-process, so do not use it
88 * in multi-process mode.
91 * Hash table for which the function is to be changed
93 * New compare function
95 void rte_hash_set_cmp_func(struct rte_hash *h, rte_hash_cmp_eq_t func);
98 * Find an existing hash table object and return a pointer to it.
101 * Name of the hash table as passed to rte_hash_create()
103 * Pointer to hash table or NULL if object not found
104 * with rte_errno set appropriately. Possible rte_errno values include:
105 * - ENOENT - value not available for return
108 rte_hash_find_existing(const char *name);
111 * De-allocate all memory used by hash table.
116 rte_hash_free(struct rte_hash *h);
119 * Reset all hash structure, by zeroing all entries
121 * Hash table to reset
124 rte_hash_reset(struct rte_hash *h);
127 * Add a key-value pair to an existing hash table.
128 * This operation is not multi-thread safe
129 * and should only be called from one thread.
132 * Hash table to add the key to.
134 * Key to add to the hash table.
136 * Data to add to the hash table.
138 * - 0 if added successfully
139 * - -EINVAL if the parameters are invalid.
140 * - -ENOSPC if there is no space in the hash for this key.
143 rte_hash_add_key_data(const struct rte_hash *h, const void *key, void *data);
146 * Add a key-value pair with a pre-computed hash value
147 * to an existing hash table.
148 * This operation is not multi-thread safe
149 * and should only be called from one thread.
152 * Hash table to add the key to.
154 * Key to add to the hash table.
156 * Precomputed hash value for 'key'
158 * Data to add to the hash table.
160 * - 0 if added successfully
161 * - -EINVAL if the parameters are invalid.
162 * - -ENOSPC if there is no space in the hash for this key.
165 rte_hash_add_key_with_hash_data(const struct rte_hash *h, const void *key,
166 hash_sig_t sig, void *data);
169 * Add a key to an existing hash table. This operation is not multi-thread safe
170 * and should only be called from one thread.
173 * Hash table to add the key to.
175 * Key to add to the hash table.
177 * - -EINVAL if the parameters are invalid.
178 * - -ENOSPC if there is no space in the hash for this key.
179 * - A positive value that can be used by the caller as an offset into an
180 * array of user data. This value is unique for this key.
183 rte_hash_add_key(const struct rte_hash *h, const void *key);
186 * Add a key to an existing hash table.
187 * This operation is not multi-thread safe
188 * and should only be called from one thread.
191 * Hash table to add the key to.
193 * Key to add to the hash table.
195 * Precomputed hash value for 'key'.
197 * - -EINVAL if the parameters are invalid.
198 * - -ENOSPC if there is no space in the hash for this key.
199 * - A positive value that can be used by the caller as an offset into an
200 * array of user data. This value is unique for this key.
203 rte_hash_add_key_with_hash(const struct rte_hash *h, const void *key, hash_sig_t sig);
206 * Remove a key from an existing hash table.
207 * This operation is not multi-thread safe
208 * and should only be called from one thread.
211 * Hash table to remove the key from.
213 * Key to remove from the hash table.
215 * - -EINVAL if the parameters are invalid.
216 * - -ENOENT if the key is not found.
217 * - A positive value that can be used by the caller as an offset into an
218 * array of user data. This value is unique for this key, and is the same
219 * value that was returned when the key was added.
222 rte_hash_del_key(const struct rte_hash *h, const void *key);
225 * Remove a key from an existing hash table.
226 * This operation is not multi-thread safe
227 * and should only be called from one thread.
230 * Hash table to remove the key from.
232 * Key to remove from the hash table.
234 * Precomputed hash value for 'key'.
236 * - -EINVAL if the parameters are invalid.
237 * - -ENOENT if the key is not found.
238 * - A positive value that can be used by the caller as an offset into an
239 * array of user data. This value is unique for this key, and is the same
240 * value that was returned when the key was added.
243 rte_hash_del_key_with_hash(const struct rte_hash *h, const void *key, hash_sig_t sig);
246 * Find a key in the hash table given the position.
247 * This operation is multi-thread safe.
250 * Hash table to get the key from.
252 * Position returned when the key was inserted.
254 * Output containing a pointer to the key
256 * - 0 if retrieved successfully
257 * - EINVAL if the parameters are invalid.
258 * - ENOENT if no valid key is found in the given position.
261 rte_hash_get_key_with_position(const struct rte_hash *h, const int32_t position,
265 * Find a key-value pair in the hash table.
266 * This operation is multi-thread safe.
269 * Hash table to look in.
273 * Output with pointer to data returned from the hash table.
275 * 0 if successful lookup
276 * - EINVAL if the parameters are invalid.
277 * - ENOENT if the key is not found.
280 rte_hash_lookup_data(const struct rte_hash *h, const void *key, void **data);
283 * Find a key-value pair with a pre-computed hash value
284 * to an existing hash table.
285 * This operation is multi-thread safe.
288 * Hash table to look in.
292 * Precomputed hash value for 'key'
294 * Output with pointer to data returned from the hash table.
296 * 0 if successful lookup
297 * - EINVAL if the parameters are invalid.
298 * - ENOENT if the key is not found.
301 rte_hash_lookup_with_hash_data(const struct rte_hash *h, const void *key,
302 hash_sig_t sig, void **data);
305 * Find a key in the hash table.
306 * This operation is multi-thread safe.
309 * Hash table to look in.
313 * - -EINVAL if the parameters are invalid.
314 * - -ENOENT if the key is not found.
315 * - A positive value that can be used by the caller as an offset into an
316 * array of user data. This value is unique for this key, and is the same
317 * value that was returned when the key was added.
320 rte_hash_lookup(const struct rte_hash *h, const void *key);
323 * Find a key in the hash table.
324 * This operation is multi-thread safe.
327 * Hash table to look in.
331 * Hash value to remove from the hash table.
333 * - -EINVAL if the parameters are invalid.
334 * - -ENOENT if the key is not found.
335 * - A positive value that can be used by the caller as an offset into an
336 * array of user data. This value is unique for this key, and is the same
337 * value that was returned when the key was added.
340 rte_hash_lookup_with_hash(const struct rte_hash *h,
341 const void *key, hash_sig_t sig);
344 * Calc a hash value by key.
345 * This operation is not multi-thread safe.
348 * Hash table to look in.
355 rte_hash_hash(const struct rte_hash *h, const void *key);
358 * Find multiple keys in the hash table.
359 * This operation is multi-thread safe.
362 * Hash table to look in.
364 * A pointer to a list of keys to look for.
366 * How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
368 * Output containing a bitmask with all successful lookups.
370 * Output containing array of data returned from all the successful lookups.
372 * -EINVAL if there's an error, otherwise number of successful lookups.
375 rte_hash_lookup_bulk_data(const struct rte_hash *h, const void **keys,
376 uint32_t num_keys, uint64_t *hit_mask, void *data[]);
379 * Find multiple keys in the hash table.
380 * This operation is multi-thread safe.
383 * Hash table to look in.
385 * A pointer to a list of keys to look for.
387 * How many keys are in the keys list (less than RTE_HASH_LOOKUP_BULK_MAX).
389 * Output containing a list of values, corresponding to the list of keys that
390 * can be used by the caller as an offset into an array of user data. These
391 * values are unique for each key, and are the same values that were returned
392 * when each key was added. If a key in the list was not found, then -ENOENT
395 * -EINVAL if there's an error, otherwise 0.
398 rte_hash_lookup_bulk(const struct rte_hash *h, const void **keys,
399 uint32_t num_keys, int32_t *positions);
402 * Iterate through the hash table, returning key-value pairs.
405 * Hash table to iterate
407 * Output containing the key where current iterator
410 * Output containing the data associated with key.
411 * Returns NULL if data was not stored.
413 * Pointer to iterator. Should be 0 to start iterating the hash table.
414 * Iterator is incremented after each call of this function.
416 * Position where key was stored, if successful.
417 * - -EINVAL if the parameters are invalid.
418 * - -ENOENT if end of the hash table.
421 rte_hash_iterate(const struct rte_hash *h, const void **key, void **data, uint32_t *next);
426 #endif /* _RTE_HASH_H_ */