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; /* 0 means, entry is invalid. */
  24         uint32_t lcore_idx;
  25         struct mlx5_list_entry *gentry;
  26 };
  27
  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;
  32
  33 /**
  34  * Type of callback function for entry removal.
  35  *
  36  * @param list
  37  *   The mlx5 list.
  38  * @param entry
  39  *   The entry in the list.
  40  */
  41 typedef void (*mlx5_list_remove_cb)(struct mlx5_list *list,
  42                                      struct mlx5_list_entry *entry);
  43
  44 /**
  45  * Type of function for user defined matching.
  46  *
  47  * @param list
  48  *   The mlx5 list.
  49  * @param entry
  50  *   The entry in the list.
  51  * @param ctx
  52  *   The pointer to new entry context.
  53  *
  54  * @return
  55  *   0 if matching, non-zero number otherwise.
  56  */
  57 typedef int (*mlx5_list_match_cb)(struct mlx5_list *list,
  58                                    struct mlx5_list_entry *entry, void *ctx);
  59
  60 typedef struct mlx5_list_entry *(*mlx5_list_clone_cb)
  61                                  (struct mlx5_list *list,
  62                                   struct mlx5_list_entry *entry, void *ctx);
  63
  64 typedef void (*mlx5_list_clone_free_cb)(struct mlx5_list *list,
  65                                          struct mlx5_list_entry *entry);
  66
  67 /**
  68  * Type of function for user defined mlx5 list entry creation.
  69  *
  70  * @param list
  71  *   The mlx5 list.
  72  * @param entry
  73  *   The new allocated entry, NULL if list entry size unspecified,
  74  *   New entry has to be allocated in callback and return.
  75  * @param ctx
  76  *   The pointer to new entry context.
  77  *
  78  * @return
  79  *   Pointer of entry on success, NULL otherwise.
  80  */
  81 typedef struct mlx5_list_entry *(*mlx5_list_create_cb)
  82                                  (struct mlx5_list *list,
  83                                   struct mlx5_list_entry *entry,
  84                                   void *ctx);
  85
  86 /**
  87  * Linked mlx5 list structure.
  88  *
  89  * Entry in mlx5 list could be reused if entry already exists,
  90  * reference count will increase and the existing entry returns.
  91  *
  92  * When destroy an entry from list, decrease reference count and only
  93  * destroy when no further reference.
  94  *
  95  * Linked list is designed for limited number of entries,
  96  * read mostly, less modification.
  97  *
  98  * For huge amount of entries, please consider hash list.
  99  *
 100  */
 101 struct mlx5_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. */
 115 };
 116
 117 /**
 118  * Create a mlx5 list.
 119  *
 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.
 124  *
 125  * @param list
 126  *   Pointer to the hast list table.
 127  * @param name
 128  *   Name of the mlx5 list.
 129  * @param ctx
 130  *   Pointer to the list context data.
 131  * @param lcores_share
 132  *   Whether to share objects between the lcores.
 133  * @param cb_create
 134  *   Callback function for entry create.
 135  * @param cb_match
 136  *   Callback function for entry match.
 137  * @param cb_remove
 138  *   Callback function for entry remove.
 139  * @return
 140  *   List pointer on success, otherwise NULL.
 141  */
 142 __rte_internal
 143 struct mlx5_list *mlx5_list_create(const char *name, void *ctx,
 144                                    bool lcores_share,
 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);
 150
 151 /**
 152  * Search an entry matching the key.
 153  *
 154  * Result returned might be destroyed by other thread, must use
 155  * this function only in main thread.
 156  *
 157  * @param list
 158  *   Pointer to the mlx5 list.
 159  * @param ctx
 160  *   Common context parameter used by entry callback function.
 161  *
 162  * @return
 163  *   Pointer of the list entry if found, NULL otherwise.
 164  */
 165 __rte_internal
 166 struct mlx5_list_entry *mlx5_list_lookup(struct mlx5_list *list,
 167                                            void *ctx);
 168
 169 /**
 170  * Reuse or create an entry to the mlx5 list.
 171  *
 172  * @param list
 173  *   Pointer to the hast list table.
 174  * @param ctx
 175  *   Common context parameter used by callback function.
 176  *
 177  * @return
 178  *   registered entry on success, NULL otherwise
 179  */
 180 __rte_internal
 181 struct mlx5_list_entry *mlx5_list_register(struct mlx5_list *list,
 182                                              void *ctx);
 183
 184 /**
 185  * Remove an entry from the mlx5 list.
 186  *
 187  * User should guarantee the validity of the entry.
 188  *
 189  * @param list
 190  *   Pointer to the hast list.
 191  * @param entry
 192  *   Entry to be removed from the mlx5 list table.
 193  * @return
 194  *   0 on entry removed, 1 on entry still referenced.
 195  */
 196 __rte_internal
 197 int mlx5_list_unregister(struct mlx5_list *list,
 198                           struct mlx5_list_entry *entry);
 199
 200 /**
 201  * Destroy the mlx5 list.
 202  *
 203  * @param list
 204  *   Pointer to the mlx5 list.
 205  */
 206 __rte_internal
 207 void mlx5_list_destroy(struct mlx5_list *list);
 208
 209 /**
 210  * Get entry number from the mlx5 list.
 211  *
 212  * @param list
 213  *   Pointer to the hast list.
 214  * @return
 215  *   mlx5 list entry number.
 216  */
 217 __rte_internal
 218 uint32_t
 219 mlx5_list_get_entry_num(struct mlx5_list *list);
 220
 221 /************************ Hash list *****************************/
 222
 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. */
 225
 226 /** Maximum size of string for naming the hlist table. */
 227 #define MLX5_HLIST_NAMESIZE                     32
 228
 229 struct mlx5_hlist;
 230
 231 /**
 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.
 235  */
 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. */
 240 };
 241
 242 /** Structure for hash head. */
 243 LIST_HEAD(mlx5_hlist_head, mlx5_hlist_entry);
 244
 245 /**
 246  * Type of callback function for entry removal.
 247  *
 248  * @param list
 249  *   The hash list.
 250  * @param entry
 251  *   The entry in the list.
 252  */
 253 typedef void (*mlx5_hlist_remove_cb)(struct mlx5_hlist *list,
 254                                      struct mlx5_hlist_entry *entry);
 255
 256 /**
 257  * Type of function for user defined matching.
 258  *
 259  * @param list
 260  *   The hash list.
 261  * @param entry
 262  *   The entry in the list.
 263  * @param key
 264  *   The new entry key.
 265  * @param ctx
 266  *   The pointer to new entry context.
 267  *
 268  * @return
 269  *   0 if matching, non-zero number otherwise.
 270  */
 271 typedef int (*mlx5_hlist_match_cb)(struct mlx5_hlist *list,
 272                                    struct mlx5_hlist_entry *entry,
 273                                    uint64_t key, void *ctx);
 274
 275 /**
 276  * Type of function for user defined hash list entry creation.
 277  *
 278  * @param list
 279  *   The hash list.
 280  * @param key
 281  *   The key of the new entry.
 282  * @param ctx
 283  *   The pointer to new entry context.
 284  *
 285  * @return
 286  *   Pointer to allocated entry on success, NULL otherwise.
 287  */
 288 typedef struct mlx5_hlist_entry *(*mlx5_hlist_create_cb)
 289                                   (struct mlx5_hlist *list,
 290                                    uint64_t key, void *ctx);
 291
 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;
 298
 299 /**
 300  * Hash list table structure
 301  *
 302  * Entry in hash list could be reused if entry already exists, reference
 303  * count will increase and the existing entry returns.
 304  *
 305  * When destroy an entry from list, decrease reference count and only
 306  * destroy when no further reference.
 307  */
 308 struct mlx5_hlist {
 309         char name[MLX5_HLIST_NAMESIZE]; /**< Name of the hash list. */
 310         /**< number of heads, need to be power of 2. */
 311         uint32_t table_sz;
 312         uint32_t entry_sz; /**< Size of entry, used to allocate entry. */
 313         /**< mask to get the index of the list heads. */
 314         uint32_t mask;
 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. */
 317         void *ctx;
 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. */
 323 };
 324
 325 /**
 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.
 332  *
 333  * @param name
 334  *   Name of the hash list(optional).
 335  * @param size
 336  *   Heads array size of the hash list.
 337  * @param entry_size
 338  *   Entry size to allocate if cb_create not specified.
 339  * @param flags
 340  *   The hash list attribute flags.
 341  * @param cb_create
 342  *   Callback function for entry create.
 343  * @param cb_match
 344  *   Callback function for entry match.
 345  * @param cb_destroy
 346  *   Callback function for entry destroy.
 347  * @return
 348  *   Pointer of the hash list table created, NULL on failure.
 349  */
 350 __rte_internal
 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);
 356
 357 /**
 358  * Search an entry matching the key.
 359  *
 360  * Result returned might be destroyed by other thread, must use
 361  * this function only in main thread.
 362  *
 363  * @param h
 364  *   Pointer to the hast list table.
 365  * @param key
 366  *   Key for the searching entry.
 367  * @param ctx
 368  *   Common context parameter used by entry callback function.
 369  *
 370  * @return
 371  *   Pointer of the hlist entry if found, NULL otherwise.
 372  */
 373 __rte_internal
 374 struct mlx5_hlist_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
 375                                            void *ctx);
 376
 377 /**
 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.
 381  *
 382  * @param h
 383  *   Pointer to the hast list table.
 384  * @param entry
 385  *   Entry to be inserted into the hash list table.
 386  * @param ctx
 387  *   Common context parameter used by callback function.
 388  *
 389  * @return
 390  *   registered entry on success, NULL otherwise
 391  */
 392 __rte_internal
 393 struct mlx5_hlist_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
 394                                              void *ctx);
 395
 396 /**
 397  * Remove an entry from the hash list table. User should guarantee the validity
 398  * of the entry.
 399  *
 400  * @param h
 401  *   Pointer to the hast list table. (not used)
 402  * @param entry
 403  *   Entry to be removed from the hash list table.
 404  * @return
 405  *   0 on entry removed, 1 on entry still referenced.
 406  */
 407 __rte_internal
 408 int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_hlist_entry *entry);
 409
 410 /**
 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.
 414  *
 415  * @param h
 416  *   Pointer to the hast list table.
 417  */
 418 __rte_internal
 419 void mlx5_hlist_destroy(struct mlx5_hlist *h);
 420
 421 #endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */