lib/librte_stack/rte_stack.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2019 Intel Corporation
   3  */
   4
   5 /**
   6  * @file rte_stack.h
   7  * @b EXPERIMENTAL: this API may change without prior notice
   8  *
   9  * RTE Stack
  10  *
  11  * librte_stack provides an API for configuration and use of a bounded stack of
  12  * pointers. Push and pop operations are MT-safe, allowing concurrent access,
  13  * and the interface supports pushing and popping multiple pointers at a time.
  14  */
  15
  16 #ifndef _RTE_STACK_H_
  17 #define _RTE_STACK_H_
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #include <rte_atomic.h>
  24 #include <rte_compat.h>
  25 #include <rte_debug.h>
  26 #include <rte_errno.h>
  27 #include <rte_memzone.h>
  28 #include <rte_spinlock.h>
  29
  30 #define RTE_TAILQ_STACK_NAME "RTE_STACK"
  31 #define RTE_STACK_MZ_PREFIX "STK_"
  32 /** The maximum length of a stack name. */
  33 #define RTE_STACK_NAMESIZE (RTE_MEMZONE_NAMESIZE - \
  34                            sizeof(RTE_STACK_MZ_PREFIX) + 1)
  35
  36 struct rte_stack_lf_elem {
  37         void *data;                     /**< Data pointer */
  38         struct rte_stack_lf_elem *next; /**< Next pointer */
  39 };
  40
  41 struct rte_stack_lf_head {
  42         struct rte_stack_lf_elem *top; /**< Stack top */
  43         uint64_t cnt; /**< Modification counter for avoiding ABA problem */
  44 };
  45
  46 struct rte_stack_lf_list {
  47         /** List head */
  48         struct rte_stack_lf_head head __rte_aligned(16);
  49         /** List len */
  50         uint64_t len;
  51 };
  52
  53 /* Structure containing two lock-free LIFO lists: the stack itself and a list
  54  * of free linked-list elements.
  55  */
  56 struct rte_stack_lf {
  57         /** LIFO list of elements */
  58         struct rte_stack_lf_list used __rte_cache_aligned;
  59         /** LIFO list of free elements */
  60         struct rte_stack_lf_list free __rte_cache_aligned;
  61         /** LIFO elements */
  62         struct rte_stack_lf_elem elems[] __rte_cache_aligned;
  63 };
  64
  65 /* Structure containing the LIFO, its current length, and a lock for mutual
  66  * exclusion.
  67  */
  68 struct rte_stack_std {
  69         rte_spinlock_t lock; /**< LIFO lock */
  70         uint32_t len; /**< LIFO len */
  71         void *objs[]; /**< LIFO pointer table */
  72 };
  73
  74 /* The RTE stack structure contains the LIFO structure itself, plus metadata
  75  * such as its name and memzone pointer.
  76  */
  77 struct rte_stack {
  78         /** Name of the stack. */
  79         char name[RTE_STACK_NAMESIZE] __rte_cache_aligned;
  80         /** Memzone containing the rte_stack structure. */
  81         const struct rte_memzone *memzone;
  82         uint32_t capacity; /**< Usable size of the stack. */
  83         uint32_t flags; /**< Flags supplied at creation. */
  84         RTE_STD_C11
  85         union {
  86                 struct rte_stack_lf stack_lf; /**< Lock-free LIFO structure. */
  87                 struct rte_stack_std stack_std; /**< LIFO structure. */
  88         };
  89 } __rte_cache_aligned;
  90
  91 /**
  92  * The stack uses lock-free push and pop functions. This flag is only
  93  * supported on x86_64 platforms, currently.
  94  */
  95 #define RTE_STACK_F_LF 0x0001
  96
  97 #include "rte_stack_std.h"
  98 #include "rte_stack_lf.h"
  99
 100 /**
 101  * @warning
 102  * @b EXPERIMENTAL: this API may change without prior notice
 103  *
 104  * Push several objects on the stack (MT-safe).
 105  *
 106  * @param s
 107  *   A pointer to the stack structure.
 108  * @param obj_table
 109  *   A pointer to a table of void * pointers (objects).
 110  * @param n
 111  *   The number of objects to push on the stack from the obj_table.
 112  * @return
 113  *   Actual number of objects pushed (either 0 or *n*).
 114  */
 115 __rte_experimental
 116 static __rte_always_inline unsigned int
 117 rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
 118 {
 119         RTE_ASSERT(s != NULL);
 120         RTE_ASSERT(obj_table != NULL);
 121
 122         if (s->flags & RTE_STACK_F_LF)
 123                 return __rte_stack_lf_push(s, obj_table, n);
 124         else
 125                 return __rte_stack_std_push(s, obj_table, n);
 126 }
 127
 128 /**
 129  * @warning
 130  * @b EXPERIMENTAL: this API may change without prior notice
 131  *
 132  * Pop several objects from the stack (MT-safe).
 133  *
 134  * @param s
 135  *   A pointer to the stack structure.
 136  * @param obj_table
 137  *   A pointer to a table of void * pointers (objects).
 138  * @param n
 139  *   The number of objects to pull from the stack.
 140  * @return
 141  *   Actual number of objects popped (either 0 or *n*).
 142  */
 143 __rte_experimental
 144 static __rte_always_inline unsigned int
 145 rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 146 {
 147         RTE_ASSERT(s != NULL);
 148         RTE_ASSERT(obj_table != NULL);
 149
 150         if (s->flags & RTE_STACK_F_LF)
 151                 return __rte_stack_lf_pop(s, obj_table, n);
 152         else
 153                 return __rte_stack_std_pop(s, obj_table, n);
 154 }
 155
 156 /**
 157  * @warning
 158  * @b EXPERIMENTAL: this API may change without prior notice
 159  *
 160  * Return the number of used entries in a stack.
 161  *
 162  * @param s
 163  *   A pointer to the stack structure.
 164  * @return
 165  *   The number of used entries in the stack.
 166  */
 167 __rte_experimental
 168 static __rte_always_inline unsigned int
 169 rte_stack_count(struct rte_stack *s)
 170 {
 171         RTE_ASSERT(s != NULL);
 172
 173         if (s->flags & RTE_STACK_F_LF)
 174                 return __rte_stack_lf_count(s);
 175         else
 176                 return __rte_stack_std_count(s);
 177 }
 178
 179 /**
 180  * @warning
 181  * @b EXPERIMENTAL: this API may change without prior notice
 182  *
 183  * Return the number of free entries in a stack.
 184  *
 185  * @param s
 186  *   A pointer to the stack structure.
 187  * @return
 188  *   The number of free entries in the stack.
 189  */
 190 __rte_experimental
 191 static __rte_always_inline unsigned int
 192 rte_stack_free_count(struct rte_stack *s)
 193 {
 194         RTE_ASSERT(s != NULL);
 195
 196         return s->capacity - rte_stack_count(s);
 197 }
 198
 199 /**
 200  * @warning
 201  * @b EXPERIMENTAL: this API may change without prior notice
 202  *
 203  * Create a new stack named *name* in memory.
 204  *
 205  * This function uses ``memzone_reserve()`` to allocate memory for a stack of
 206  * size *count*. The behavior of the stack is controlled by the *flags*.
 207  *
 208  * @param name
 209  *   The name of the stack.
 210  * @param count
 211  *   The size of the stack.
 212  * @param socket_id
 213  *   The *socket_id* argument is the socket identifier in case of
 214  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 215  *   constraint for the reserved zone.
 216  * @param flags
 217  *   An OR of the following:
 218  *    - RTE_STACK_F_LF: If this flag is set, the stack uses lock-free
 219  *      variants of the push and pop functions. Otherwise, it achieves
 220  *      thread-safety using a lock.
 221  * @return
 222  *   On success, the pointer to the new allocated stack. NULL on error with
 223  *    rte_errno set appropriately. Possible errno values include:
 224  *    - ENOSPC - the maximum number of memzones has already been allocated
 225  *    - EEXIST - a stack with the same name already exists
 226  *    - ENOMEM - insufficient memory to create the stack
 227  *    - ENAMETOOLONG - name size exceeds RTE_STACK_NAMESIZE
 228  */
 229 __rte_experimental
 230 struct rte_stack *
 231 rte_stack_create(const char *name, unsigned int count, int socket_id,
 232                  uint32_t flags);
 233
 234 /**
 235  * @warning
 236  * @b EXPERIMENTAL: this API may change without prior notice
 237  *
 238  * Free all memory used by the stack.
 239  *
 240  * @param s
 241  *   Stack to free
 242  */
 243 __rte_experimental
 244 void
 245 rte_stack_free(struct rte_stack *s);
 246
 247 /**
 248  * @warning
 249  * @b EXPERIMENTAL: this API may change without prior notice
 250  *
 251  * Lookup a stack by its name.
 252  *
 253  * @param name
 254  *   The name of the stack.
 255  * @return
 256  *   The pointer to the stack matching the name, or NULL if not found,
 257  *   with rte_errno set appropriately. Possible rte_errno values include:
 258  *    - ENOENT - Stack with name *name* not found.
 259  *    - EINVAL - *name* pointer is NULL.
 260  */
 261 __rte_experimental
 262 struct rte_stack *
 263 rte_stack_lookup(const char *name);
 264
 265 #ifdef __cplusplus
 266 }
 267 #endif
 268
 269 #endif /* _RTE_STACK_H_ */