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 constant object.
  85  */
  86 struct mlx5_list_const {
  87         char name[MLX5_NAME_SIZE]; /**< Name of the mlx5 list. */
  88         void *ctx; /* user objects target to callback. */
  89         bool lcores_share; /* Whether to share objects between the lcores. */
  90         mlx5_list_create_cb cb_create; /**< entry create callback. */
  91         mlx5_list_match_cb cb_match; /**< entry match callback. */
  92         mlx5_list_remove_cb cb_remove; /**< entry remove callback. */
  93         mlx5_list_clone_cb cb_clone; /**< entry clone callback. */
  94         mlx5_list_clone_free_cb cb_clone_free;
  95         /**< entry clone free callback. */
  96 };
  97
  98 /**
  99  * Linked mlx5 list inconstant data.
 100  */
 101 struct mlx5_list_inconst {
 102         rte_rwlock_t lock; /* read/write lock. */
 103         volatile uint32_t gen_cnt; /* List modification may update it. */
 104         volatile uint32_t count; /* number of entries in list. */
 105         struct mlx5_list_cache *cache[RTE_MAX_LCORE + 1];
 106         /* Lcore cache, last index is the global cache. */
 107 };
 108
 109 /**
 110  * Linked mlx5 list structure.
 111  *
 112  * Entry in mlx5 list could be reused if entry already exists,
 113  * reference count will increase and the existing entry returns.
 114  *
 115  * When destroy an entry from list, decrease reference count and only
 116  * destroy when no further reference.
 117  *
 118  * Linked list is designed for limited number of entries,
 119  * read mostly, less modification.
 120  *
 121  * For huge amount of entries, please consider hash list.
 122  *
 123  */
 124 struct mlx5_list {
 125         struct mlx5_list_const l_const;
 126         struct mlx5_list_inconst l_inconst;
 127 };
 128
 129 /**
 130  * Create a mlx5 list.
 131  *
 132  * For actions in SW-steering is only memory and  can be allowed
 133  * to create duplicate objects, the lists don't need to check if
 134  * there are existing same objects in other sub local lists,
 135  * search the object only in local list will be more efficient.
 136  *
 137  * @param list
 138  *   Pointer to the hast list table.
 139  * @param name
 140  *   Name of the mlx5 list.
 141  * @param ctx
 142  *   Pointer to the list context data.
 143  * @param lcores_share
 144  *   Whether to share objects between the lcores.
 145  * @param cb_create
 146  *   Callback function for entry create.
 147  * @param cb_match
 148  *   Callback function for entry match.
 149  * @param cb_remove
 150  *   Callback function for entry remove.
 151  * @return
 152  *   List pointer on success, otherwise NULL.
 153  */
 154 __rte_internal
 155 struct mlx5_list *mlx5_list_create(const char *name, void *ctx,
 156                                    bool lcores_share,
 157                                    mlx5_list_create_cb cb_create,
 158                                    mlx5_list_match_cb cb_match,
 159                                    mlx5_list_remove_cb cb_remove,
 160                                    mlx5_list_clone_cb cb_clone,
 161                                    mlx5_list_clone_free_cb cb_clone_free);
 162
 163 /**
 164  * Search an entry matching the key.
 165  *
 166  * Result returned might be destroyed by other thread, must use
 167  * this function only in main thread.
 168  *
 169  * @param list
 170  *   Pointer to the mlx5 list.
 171  * @param ctx
 172  *   Common context parameter used by entry callback function.
 173  *
 174  * @return
 175  *   Pointer of the list entry if found, NULL otherwise.
 176  */
 177 __rte_internal
 178 struct mlx5_list_entry *mlx5_list_lookup(struct mlx5_list *list,
 179                                            void *ctx);
 180
 181 /**
 182  * Reuse or create an entry to the mlx5 list.
 183  *
 184  * @param list
 185  *   Pointer to the hast list table.
 186  * @param ctx
 187  *   Common context parameter used by callback function.
 188  *
 189  * @return
 190  *   registered entry on success, NULL otherwise
 191  */
 192 __rte_internal
 193 struct mlx5_list_entry *mlx5_list_register(struct mlx5_list *list,
 194                                              void *ctx);
 195
 196 /**
 197  * Remove an entry from the mlx5 list.
 198  *
 199  * User should guarantee the validity of the entry.
 200  *
 201  * @param list
 202  *   Pointer to the hast list.
 203  * @param entry
 204  *   Entry to be removed from the mlx5 list table.
 205  * @return
 206  *   0 on entry removed, 1 on entry still referenced.
 207  */
 208 __rte_internal
 209 int mlx5_list_unregister(struct mlx5_list *list,
 210                           struct mlx5_list_entry *entry);
 211
 212 /**
 213  * Destroy the mlx5 list.
 214  *
 215  * @param list
 216  *   Pointer to the mlx5 list.
 217  */
 218 __rte_internal
 219 void mlx5_list_destroy(struct mlx5_list *list);
 220
 221 /**
 222  * Get entry number from the mlx5 list.
 223  *
 224  * @param list
 225  *   Pointer to the hast list.
 226  * @return
 227  *   mlx5 list entry number.
 228  */
 229 __rte_internal
 230 uint32_t
 231 mlx5_list_get_entry_num(struct mlx5_list *list);
 232
 233 /********************* Hash List **********************/
 234
 235 /* Hash list bucket. */
 236 struct mlx5_hlist_bucket {
 237         struct mlx5_list_inconst l;
 238 } __rte_cache_aligned;
 239
 240 /**
 241  * Hash list table structure
 242  *
 243  * The hash list bucket using the mlx5_list object for managing.
 244  */
 245 struct mlx5_hlist {
 246         uint32_t mask; /* A mask for the bucket index range. */
 247         uint8_t flags;
 248         bool direct_key; /* Whether to use the key directly as hash index. */
 249         struct mlx5_list_const l_const; /* List constant data. */
 250         struct mlx5_hlist_bucket buckets[] __rte_cache_aligned;
 251 };
 252
 253 /**
 254  * Create a hash list table, the user can specify the list heads array size
 255  * of the table, now the size should be a power of 2 in order to get better
 256  * distribution for the entries. Each entry is a part of the whole data element
 257  * and the caller should be responsible for the data element's allocation and
 258  * cleanup / free. Key of each entry will be calculated with CRC in order to
 259  * generate a little fairer distribution.
 260  *
 261  * @param name
 262  *   Name of the hash list(optional).
 263  * @param size
 264  *   Heads array size of the hash list.
 265  * @param entry_size
 266  *   Entry size to allocate if cb_create not specified.
 267  * @param direct key
 268  *   Whether to use the key directly as hash index.
 269  * @param lcores_share
 270  *   Whether to share objects between the lcores.
 271  * @param ctx
 272  *   The hlist instance context.
 273  * @param cb_create
 274  *   Callback function for entry create.
 275  * @param cb_match
 276  *   Callback function for entry match.
 277  * @param cb_remove
 278  *   Callback function for entry remove.
 279  * @param cb_clone
 280  *   Callback function for entry clone.
 281  * @param cb_clone_free
 282  *   Callback function for entry clone free.
 283  * @return
 284  *   Pointer of the hash list table created, NULL on failure.
 285  */
 286 __rte_internal
 287 struct mlx5_hlist *mlx5_hlist_create(const char *name, uint32_t size,
 288                                      bool direct_key, bool lcores_share,
 289                                      void *ctx, mlx5_list_create_cb cb_create,
 290                                      mlx5_list_match_cb cb_match,
 291                                      mlx5_list_remove_cb cb_remove,
 292                                      mlx5_list_clone_cb cb_clone,
 293                                      mlx5_list_clone_free_cb cb_clone_free);
 294
 295 /**
 296  * Search an entry matching the key.
 297  *
 298  * Result returned might be destroyed by other thread, must use
 299  * this function only in main thread.
 300  *
 301  * @param h
 302  *   Pointer to the hast list table.
 303  * @param key
 304  *   Key for the searching entry.
 305  * @param ctx
 306  *   Common context parameter used by entry callback function.
 307  *
 308  * @return
 309  *   Pointer of the hlist entry if found, NULL otherwise.
 310  */
 311 __rte_internal
 312 struct mlx5_list_entry *mlx5_hlist_lookup(struct mlx5_hlist *h, uint64_t key,
 313                                            void *ctx);
 314
 315 /**
 316  * Insert an entry to the hash list table, the entry is only part of whole data
 317  * element and a 64B key is used for matching. User should construct the key or
 318  * give a calculated hash signature and guarantee there is no collision.
 319  *
 320  * @param h
 321  *   Pointer to the hast list table.
 322  * @param entry
 323  *   Entry to be inserted into the hash list table.
 324  * @param ctx
 325  *   Common context parameter used by callback function.
 326  *
 327  * @return
 328  *   registered entry on success, NULL otherwise
 329  */
 330 __rte_internal
 331 struct mlx5_list_entry *mlx5_hlist_register(struct mlx5_hlist *h, uint64_t key,
 332                                              void *ctx);
 333
 334 /**
 335  * Remove an entry from the hash list table. User should guarantee the validity
 336  * of the entry.
 337  *
 338  * @param h
 339  *   Pointer to the hast list table. (not used)
 340  * @param entry
 341  *   Entry to be removed from the hash list table.
 342  * @return
 343  *   0 on entry removed, 1 on entry still referenced.
 344  */
 345 __rte_internal
 346 int mlx5_hlist_unregister(struct mlx5_hlist *h, struct mlx5_list_entry *entry);
 347
 348 /**
 349  * Destroy the hash list table, all the entries already inserted into the lists
 350  * will be handled by the callback function provided by the user (including
 351  * free if needed) before the table is freed.
 352  *
 353  * @param h
 354  *   Pointer to the hast list table.
 355  */
 356 __rte_internal
 357 void mlx5_hlist_destroy(struct mlx5_hlist *h);
 358
 359 #endif /* RTE_PMD_MLX5_COMMON_UTILS_H_ */