drivers/common/mlx5/mlx5_common_utils.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2019 Mellanox Technologies, Ltd
   3  */
   4
   5 #ifndef RTE_PMD_MLX5_COMMON_UTILS_H_
   6 #define RTE_PMD_MLX5_COMMON_UTILS_H_
   7
   8 #include "mlx5_common.h"
   9
  10 /************************ mlx5 list *****************************/
  11
  12 /** Maximum size of string for naming. */
  13 #define MLX5_NAME_SIZE                  32
  14
  15 struct mlx5_list;
  16
  17 /**
  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.
  20  */
  21 struct mlx5_list_entry {
  22         LIST_ENTRY(mlx5_list_entry) next; /* Entry pointers in the list. */
  23         uint32_t ref_cnt __rte_aligned(8); /* 0 means, entry is invalid. */
  24         uint32_t lcore_idx;
  25         union {
  26                 struct mlx5_list_entry *gentry;
  27                 uint32_t bucket_idx;
  28         };
  29 } __rte_packed;
  30
  31 struct mlx5_list_cache {
  32         LIST_HEAD(mlx5_list_head, mlx5_list_entry) h;
  33         uint32_t inv_cnt; /* Invalid entries counter. */
  34 } __rte_cache_aligned;
  35
  36 /**
  37  * Type of callback function for entry removal.
  38  *
  39  * @param tool_ctx
  40  *   The tool instance user context.
  41  * @param entry
  42  *   The entry in the list.
  43  */
  44 typedef void (*mlx5_list_remove_cb)(void *tool_ctx,
  45                                     struct mlx5_list_entry *entry);
  46
  47 /**
  48  * Type of function for user defined matching.
  49  *
  50  * @param tool_ctx
  51  *   The tool instance context.
  52  * @param entry
  53  *   The entry in the list.
  54  * @param ctx
  55  *   The pointer to new entry context.
  56  *
  57  * @return
  58  *   0 if matching, non-zero number otherwise.
  59  */
  60 typedef int (*mlx5_list_match_cb)(void *tool_ctx,
  61                                    struct mlx5_list_entry *entry, void *ctx);
  62
  63 typedef struct mlx5_list_entry *(*mlx5_list_clone_cb)(void *tool_ctx,
  64                                       struct mlx5_list_entry *entry, void *ctx);
  65
  66 typedef void (*mlx5_list_clone_free_cb)(void *tool_ctx,
  67                                         struct mlx5_list_entry *entry);
  68
  69 /**
  70  * Type of function for user defined mlx5 list entry creation.
  71  *
  72  * @param tool_ctx
  73  *   The mlx5 tool instance context.
  74  * @param ctx
  75  *   The pointer to new entry context.
  76  *
  77  * @return
  78  *   Pointer of entry on success, NULL otherwise.
  79  */
  80 typedef struct mlx5_list_entry *(*mlx5_list_create_cb)(void *tool_ctx,
  81                                                        void *ctx);
  82
  83 /**
  84  * Linked mlx5 list structure.
  85  *
  86  * Entry in mlx5 list could be reused if entry already exists,
  87  * reference count will increase and the existing entry returns.
  88  *
  89  * When destroy an entry from list, decrease reference count and only
  90  * destroy when no further reference.
  91  *
  92  * Linked list is designed for limited number of entries,
  93  * read mostly, less modification.
  94  *
  95  * For huge amount of entries, please consider hash list.
  96  *
  97  */
  98 struct mlx5_list {
  99         char name[MLX5_NAME_SIZE]; /**< Name of the mlx5 list. */
 100         void *ctx; /* user objects target to callback. */
 101         bool lcores_share; /* Whether to share objects between the lcores. */
 102         mlx5_list_create_cb cb_create; /**< entry create callback. */
 103         mlx5_list_match_cb cb_match; /**< entry match callback. */
 104         mlx5_list_remove_cb cb_remove; /**< entry remove callback. */
 105         mlx5_list_clone_cb cb_clone; /**< entry clone callback. */
 106         mlx5_list_clone_free_cb cb_clone_free;
 107         struct mlx5_list_cache *cache[RTE_MAX_LCORE + 1];
 108         /* Lcore cache, last index is the global cache. */
 109         volatile uint32_t gen_cnt; /* List modification may update it. */
 110         volatile uint32_t count; /* number of entries in list. */
 111         rte_rwlock_t lock; /* read/write lock. */
 112 };
 113
 114 /**
 115  * Create a mlx5 list.
 116  *
 117  * For actions in SW-steering is only memory and  can be allowed
 118  * to create duplicate objects, the lists don't need to check if
 119  * there are existing same objects in other sub local lists,
 120  * search the object only in local list will be more efficient.
 121  *
 122  * @param list
 123  *   Pointer to the hast list table.
 124  * @param name
 125  *   Name of the mlx5 list.
 126  * @param ctx
 127  *   Pointer to the list context data.
 128  * @param lcores_share
 129  *   Whether to share objects between the lcores.
 130  * @param cb_create
 131  *   Callback function for entry create.
 132  * @param cb_match
 133  *   Callback function for entry match.
 134  * @param cb_remove
 135  *   Callback function for entry remove.
 136  * @return
 137  *   List pointer on success, otherwise NULL.
 138  */
 139 __rte_internal
 140 struct mlx5_list *mlx5_list_create(const char *name, void *ctx,
 141                                    bool lcores_share,
 142                                    mlx5_list_create_cb cb_create,
 143                                    mlx5_list_match_cb cb_match,
 144                                    mlx5_list_remove_cb cb_remove,
 145                                    mlx5_list_clone_cb cb_clone,
 146                                    mlx5_list_clone_free_cb cb_clone_free);
 147
 148 /**
 149  * Search an entry matching the key.
 150  *
 151  * Result returned might be destroyed by other thread, must use
 152  * this function only in main thread.
 153  *
 154  * @param list
 155  *   Pointer to the mlx5 list.
 156  * @param ctx
 157  *   Common context parameter used by entry callback function.
 158  *
 159  * @return
 160  *   Pointer of the list entry if found, NULL otherwise.
 161  */
 162 __rte_internal
 163 struct mlx5_list_entry *mlx5_list_lookup(struct mlx5_list *list,
 164                                            void *ctx);
 165
 166 /**
 167  * Reuse or create an entry to the mlx5 list.
 168  *
 169  * @param list
 170  *   Pointer to the hast list table.
 171  * @param ctx
 172  *   Common context parameter used by callback function.
 173  *
 174  * @return
 175  *   registered entry on success, NULL otherwise
 176  */
 177 __rte_internal
 178 struct mlx5_list_entry *mlx5_list_register(struct mlx5_list *list,
 179                                              void *ctx);
 180
 181 /**
 182  * Remove an entry from the mlx5 list.
 183  *
 184  * User should guarantee the validity of the entry.
 185  *
 186  * @param list
 187  *   Pointer to the hast list.
 188  * @param entry
 189  *   Entry to be removed from the mlx5 list table.
 190  * @return
 191  *   0 on entry removed, 1 on entry still referenced.
 192  */
 193 __rte_internal
 194 int mlx5_list_unregister(struct mlx5_list *list,
 195                           struct mlx5_list_entry *entry);
 196
 197 /**
 198  * Destroy the mlx5 list.
 199  *
 200  * @param list
 201  *   Pointer to the mlx5 list.
 202  */
 203 __rte_internal
 204 void mlx5_list_destroy(struct mlx5_list *list);
 205
 206 /**
 207  * Get entry number from the mlx5 list.
 208  *
 209  * @param list
 210  *   Pointer to the hast list.
 211  * @return
 212  *   mlx5 list entry number.
 213  */
 214 __rte_internal
 215 uint32_t
 216 mlx5_list_get_entry_num(struct mlx5_list *list);
 217
 218 /********************* Hash List **********************/
 219
 220 /* Hash list bucket. */
 221 struct mlx5_hlist_bucket {
 222         struct mlx5_list l;
 223 } __rte_cache_aligned;
 224
 225 /**
 226  * Hash list table structure
 227  *
 228  * The hash list bucket using the mlx5_list object for managing.
 229  */
 230 struct mlx5_hlist {
 231         uint32_t mask; /* A mask for the bucket index range. */
 232         uint8_t flags;
 233         bool direct_key; /* Whether to use the key directly as hash index. */
 234         bool lcores_share; /* Whether to share objects between the lcores. */
 235         struct mlx5_hlist_bucket buckets[] __rte_cache_aligned;
 236 };
 237
 238 /**
 239  * Create a hash list table, the user can specify the list heads array size
 240  * of the table, now the size should be a power of 2 in order to get better
 241  * distribution for the entries. Each entry is a part of the whole data element
 242  * and the caller should be responsible for the data element's allocation and
 243  * cleanup / free. Key of each entry will be calculated with CRC in order to
 244  * generate a little fairer distribution.
 245  *
 246  * @param name
 247  *   Name of the hash list(optional).
 248  * @param size
 249  *   Heads array size of the hash list.
 250  * @param entry_size
 251  *   Entry size to allocate if cb_create not specified.
 252  * @param direct key
 253  *   Whether to use the key directly as hash index.
 254  * @param lcores_share
 255  *   Whether to share objects between the lcores.
 256  * @param ctx
 257  *   The hlist instance context.
 258  * @param cb_create
 259  *   Callback function for entry create.
 260  * @param cb_match
 261  *   Callback function for entry match.
 262  * @param cb_remove
 263  *   Callback function for entry remove.
 264  * @param cb_clone
 265  *   Callback function for entry clone.
 266  * @param cb_clone_free
 267  *   Callback function for entry clone free.
 268  * @return
 269  *   Pointer of the hash list table created, NULL on failure.
 270  */
 271 __rte_internal
 272 struct mlx5_hlist *mlx5_hlist_create(const char *name, uint32_t size,
 273                                      bool direct_key, bool lcores_share,
 274                                      void *ctx, mlx5_list_create_cb cb_create,
 275                                      mlx5_list_match_cb cb_match,
 276                                      mlx5_list_remove_cb cb_remove,
 277                                      mlx5_list_clone_cb cb_clone,
 278                                      mlx5_list_clone_free_cb cb_clone_free);
 279
 280 /**
 281  * Search an entry matching the key.
 282  *
 283  * Result returned might be destroyed by other thread, must use
 284  * this function only in main thread.
 285  *
 286  * @param h
 287  *   Pointer to the hast list table.
 288  * @param key
 289  *   Key for the searching entry.
 290  * @param ctx
 291  *   Common context parameter used by entry callback function.
 292  *
 293  * @return
 294  *   Pointer of the hlist entry if found, NULL otherwise.
 295  */
 296 __rte_internal
 297 struct mlx5_list_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
 298                                            void *ctx);
 299
 300 /**
 301  * Insert an entry to the hash list table, the entry is only part of whole data
 302  * element and a 64B key is used for matching. User should construct the key or
 303  * give a calculated hash signature and guarantee there is no collision.
 304  *
 305  * @param h
 306  *   Pointer to the hast list table.
 307  * @param entry
 308  *   Entry to be inserted into the hash list table.
 309  * @param ctx
 310  *   Common context parameter used by callback function.
 311  *
 312  * @return
 313  *   registered entry on success, NULL otherwise
 314  */
 315 __rte_internal
 316 struct mlx5_list_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
 317                                              void *ctx);
 318
 319 /**
 320  * Remove an entry from the hash list table. User should guarantee the validity
 321  * of the entry.
 322  *
 323  * @param h
 324  *   Pointer to the hast list table. (not used)
 325  * @param entry
 326  *   Entry to be removed from the hash list table.
 327  * @return
 328  *   0 on entry removed, 1 on entry still referenced.
 329  */
 330 __rte_internal
 331 int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_list_entry *entry);
 332
 333 /**
 334  * Destroy the hash list table, all the entries already inserted into the lists
 335  * will be handled by the callback function provided by the user (including
 336  * free if needed) before the table is freed.
 337  *
 338  * @param h
 339  *   Pointer to the hast list table.
 340  */
 341 __rte_internal
 342 void mlx5_hlist_destroy(struct mlx5_hlist *h);
 343
 344 #endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */