numam-dpdk/drivers/common/mlx5/mlx5_common_utils.h
Shiri Kuzin 25245d5dc9 common/mlx5: share hash list tool
In order to use the hash list defined in net in other drivers, the
hash list is moved to common utilities.

In addition, the log definition was moved from the common utilities to
a dedicated new log file in common in order to prevent a conflict.

Signed-off-by: Shiri Kuzin <shirik@nvidia.com>
Acked-by: Matan Azrad <matan@nvidia.com>
2021-05-04 22:49:37 +02:00

209 lines
6.2 KiB
C

/* SPDX-License-Identifier: BSD-3-Clause
* Copyright 2019 Mellanox Technologies, Ltd
*/
#ifndef RTE_PMD_MLX5_COMMON_UTILS_H_
#define RTE_PMD_MLX5_COMMON_UTILS_H_
#include "mlx5_common.h"
#define MLX5_HLIST_DIRECT_KEY 0x0001 /* Use the key directly as hash index. */
#define MLX5_HLIST_WRITE_MOST 0x0002 /* List mostly used for append new. */
/** Maximum size of string for naming the hlist table. */
#define MLX5_HLIST_NAMESIZE 32
struct mlx5_hlist;
/**
* Structure of the entry in the hash list, user should define its own struct
* that contains this in order to store the data. The 'key' is 64-bits right
* now and its user's responsibility to guarantee there is no collision.
*/
struct mlx5_hlist_entry {
LIST_ENTRY(mlx5_hlist_entry) next; /* entry pointers in the list. */
uint32_t idx; /* Bucket index the entry belongs to. */
uint32_t ref_cnt; /* Reference count. */
};
/** Structure for hash head. */
LIST_HEAD(mlx5_hlist_head, mlx5_hlist_entry);
/**
* Type of callback function for entry removal.
*
* @param list
* The hash list.
* @param entry
* The entry in the list.
*/
typedef void (*mlx5_hlist_remove_cb)(struct mlx5_hlist *list,
struct mlx5_hlist_entry *entry);
/**
* Type of function for user defined matching.
*
* @param list
* The hash list.
* @param entry
* The entry in the list.
* @param key
* The new entry key.
* @param ctx
* The pointer to new entry context.
*
* @return
* 0 if matching, non-zero number otherwise.
*/
typedef int (*mlx5_hlist_match_cb)(struct mlx5_hlist *list,
struct mlx5_hlist_entry *entry,
uint64_t key, void *ctx);
/**
* Type of function for user defined hash list entry creation.
*
* @param list
* The hash list.
* @param key
* The key of the new entry.
* @param ctx
* The pointer to new entry context.
*
* @return
* Pointer to allocated entry on success, NULL otherwise.
*/
typedef struct mlx5_hlist_entry *(*mlx5_hlist_create_cb)
(struct mlx5_hlist *list,
uint64_t key, void *ctx);
/* Hash list bucket head. */
struct mlx5_hlist_bucket {
struct mlx5_hlist_head head; /* List head. */
rte_rwlock_t lock; /* Bucket lock. */
uint32_t gen_cnt; /* List modification will update generation count. */
} __rte_cache_aligned;
/**
* Hash list table structure
*
* Entry in hash list could be reused if entry already exists, reference
* count will increase and the existing entry returns.
*
* When destroy an entry from list, decrease reference count and only
* destroy when no further reference.
*/
struct mlx5_hlist {
char name[MLX5_HLIST_NAMESIZE]; /**< Name of the hash list. */
/**< number of heads, need to be power of 2. */
uint32_t table_sz;
uint32_t entry_sz; /**< Size of entry, used to allocate entry. */
/**< mask to get the index of the list heads. */
uint32_t mask;
bool direct_key; /* Use the new entry key directly as hash index. */
bool write_most; /* List mostly used for append new or destroy. */
void *ctx;
mlx5_hlist_create_cb cb_create; /**< entry create callback. */
mlx5_hlist_match_cb cb_match; /**< entry match callback. */
mlx5_hlist_remove_cb cb_remove; /**< entry remove callback. */
struct mlx5_hlist_bucket buckets[] __rte_cache_aligned;
/**< list bucket arrays. */
};
/**
* Create a hash list table, the user can specify the list heads array size
* of the table, now the size should be a power of 2 in order to get better
* distribution for the entries. Each entry is a part of the whole data element
* and the caller should be responsible for the data element's allocation and
* cleanup / free. Key of each entry will be calculated with CRC in order to
* generate a little fairer distribution.
*
* @param name
* Name of the hash list(optional).
* @param size
* Heads array size of the hash list.
* @param entry_size
* Entry size to allocate if cb_create not specified.
* @param flags
* The hash list attribute flags.
* @param cb_create
* Callback function for entry create.
* @param cb_match
* Callback function for entry match.
* @param cb_destroy
* Callback function for entry destroy.
* @return
* Pointer of the hash list table created, NULL on failure.
*/
__rte_internal
struct mlx5_hlist *mlx5_hlist_create(const char *name, uint32_t size,
uint32_t entry_size, uint32_t flags,
mlx5_hlist_create_cb cb_create,
mlx5_hlist_match_cb cb_match,
mlx5_hlist_remove_cb cb_destroy);
/**
* Search an entry matching the key.
*
* Result returned might be destroyed by other thread, must use
* this function only in main thread.
*
* @param h
* Pointer to the hast list table.
* @param key
* Key for the searching entry.
* @param ctx
* Common context parameter used by entry callback function.
*
* @return
* Pointer of the hlist entry if found, NULL otherwise.
*/
__rte_internal
struct mlx5_hlist_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
void *ctx);
/**
* Insert an entry to the hash list table, the entry is only part of whole data
* element and a 64B key is used for matching. User should construct the key or
* give a calculated hash signature and guarantee there is no collision.
*
* @param h
* Pointer to the hast list table.
* @param entry
* Entry to be inserted into the hash list table.
* @param ctx
* Common context parameter used by callback function.
*
* @return
* registered entry on success, NULL otherwise
*/
__rte_internal
struct mlx5_hlist_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
void *ctx);
/**
* Remove an entry from the hash list table. User should guarantee the validity
* of the entry.
*
* @param h
* Pointer to the hast list table. (not used)
* @param entry
* Entry to be removed from the hash list table.
* @return
* 0 on entry removed, 1 on entry still referenced.
*/
__rte_internal
int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_hlist_entry *entry);
/**
* Destroy the hash list table, all the entries already inserted into the lists
* will be handled by the callback function provided by the user (including
* free if needed) before the table is freed.
*
* @param h
* Pointer to the hast list table.
*/
__rte_internal
void mlx5_hlist_destroy(struct mlx5_hlist *h);
#endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */