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_compat.h>
  24 #include <rte_debug.h>
  25 #include <rte_errno.h>
  26 #include <rte_memzone.h>
  27 #include <rte_spinlock.h>
  28
  29 #define RTE_TAILQ_STACK_NAME "RTE_STACK"
  30 #define RTE_STACK_MZ_PREFIX "STK_"
  31 /** The maximum length of a stack name. */
  32 #define RTE_STACK_NAMESIZE (RTE_MEMZONE_NAMESIZE - \
  33                            sizeof(RTE_STACK_MZ_PREFIX) + 1)
  34
  35 /* Structure containing the LIFO, its current length, and a lock for mutual
  36  * exclusion.
  37  */
  38 struct rte_stack_std {
  39         rte_spinlock_t lock; /**< LIFO lock */
  40         uint32_t len; /**< LIFO len */
  41         void *objs[]; /**< LIFO pointer table */
  42 };
  43
  44 /* The RTE stack structure contains the LIFO structure itself, plus metadata
  45  * such as its name and memzone pointer.
  46  */
  47 struct rte_stack {
  48         /** Name of the stack. */
  49         char name[RTE_STACK_NAMESIZE] __rte_cache_aligned;
  50         /** Memzone containing the rte_stack structure. */
  51         const struct rte_memzone *memzone;
  52         uint32_t capacity; /**< Usable size of the stack. */
  53         uint32_t flags; /**< Flags supplied at creation. */
  54         struct rte_stack_std stack_std; /**< LIFO structure. */
  55 } __rte_cache_aligned;
  56
  57 #include "rte_stack_std.h"
  58
  59 /**
  60  * @warning
  61  * @b EXPERIMENTAL: this API may change without prior notice
  62  *
  63  * Push several objects on the stack (MT-safe).
  64  *
  65  * @param s
  66  *   A pointer to the stack structure.
  67  * @param obj_table
  68  *   A pointer to a table of void * pointers (objects).
  69  * @param n
  70  *   The number of objects to push on the stack from the obj_table.
  71  * @return
  72  *   Actual number of objects pushed (either 0 or *n*).
  73  */
  74 static __rte_always_inline unsigned int __rte_experimental
  75 rte_stack_push(struct rte_stack *s, void * const *obj_table, unsigned int n)
  76 {
  77         RTE_ASSERT(s != NULL);
  78         RTE_ASSERT(obj_table != NULL);
  79
  80         return __rte_stack_std_push(s, obj_table, n);
  81 }
  82
  83 /**
  84  * @warning
  85  * @b EXPERIMENTAL: this API may change without prior notice
  86  *
  87  * Pop several objects from the stack (MT-safe).
  88  *
  89  * @param s
  90  *   A pointer to the stack structure.
  91  * @param obj_table
  92  *   A pointer to a table of void * pointers (objects).
  93  * @param n
  94  *   The number of objects to pull from the stack.
  95  * @return
  96  *   Actual number of objects popped (either 0 or *n*).
  97  */
  98 static __rte_always_inline unsigned int __rte_experimental
  99 rte_stack_pop(struct rte_stack *s, void **obj_table, unsigned int n)
 100 {
 101         RTE_ASSERT(s != NULL);
 102         RTE_ASSERT(obj_table != NULL);
 103
 104         return __rte_stack_std_pop(s, obj_table, n);
 105 }
 106
 107 /**
 108  * @warning
 109  * @b EXPERIMENTAL: this API may change without prior notice
 110  *
 111  * Return the number of used entries in a stack.
 112  *
 113  * @param s
 114  *   A pointer to the stack structure.
 115  * @return
 116  *   The number of used entries in the stack.
 117  */
 118 static __rte_always_inline unsigned int __rte_experimental
 119 rte_stack_count(struct rte_stack *s)
 120 {
 121         RTE_ASSERT(s != NULL);
 122
 123         return __rte_stack_std_count(s);
 124 }
 125
 126 /**
 127  * @warning
 128  * @b EXPERIMENTAL: this API may change without prior notice
 129  *
 130  * Return the number of free entries in a stack.
 131  *
 132  * @param s
 133  *   A pointer to the stack structure.
 134  * @return
 135  *   The number of free entries in the stack.
 136  */
 137 static __rte_always_inline unsigned int __rte_experimental
 138 rte_stack_free_count(struct rte_stack *s)
 139 {
 140         RTE_ASSERT(s != NULL);
 141
 142         return s->capacity - rte_stack_count(s);
 143 }
 144
 145 /**
 146  * @warning
 147  * @b EXPERIMENTAL: this API may change without prior notice
 148  *
 149  * Create a new stack named *name* in memory.
 150  *
 151  * This function uses ``memzone_reserve()`` to allocate memory for a stack of
 152  * size *count*. The behavior of the stack is controlled by the *flags*.
 153  *
 154  * @param name
 155  *   The name of the stack.
 156  * @param count
 157  *   The size of the stack.
 158  * @param socket_id
 159  *   The *socket_id* argument is the socket identifier in case of
 160  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 161  *   constraint for the reserved zone.
 162  * @param flags
 163  *   Reserved for future use.
 164  * @return
 165  *   On success, the pointer to the new allocated stack. NULL on error with
 166  *    rte_errno set appropriately. Possible errno values include:
 167  *    - ENOSPC - the maximum number of memzones has already been allocated
 168  *    - EEXIST - a stack with the same name already exists
 169  *    - ENOMEM - insufficient memory to create the stack
 170  *    - ENAMETOOLONG - name size exceeds RTE_STACK_NAMESIZE
 171  */
 172 struct rte_stack *__rte_experimental
 173 rte_stack_create(const char *name, unsigned int count, int socket_id,
 174                  uint32_t flags);
 175
 176 /**
 177  * @warning
 178  * @b EXPERIMENTAL: this API may change without prior notice
 179  *
 180  * Free all memory used by the stack.
 181  *
 182  * @param s
 183  *   Stack to free
 184  */
 185 void __rte_experimental
 186 rte_stack_free(struct rte_stack *s);
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice
 191  *
 192  * Lookup a stack by its name.
 193  *
 194  * @param name
 195  *   The name of the stack.
 196  * @return
 197  *   The pointer to the stack matching the name, or NULL if not found,
 198  *   with rte_errno set appropriately. Possible rte_errno values include:
 199  *    - ENOENT - Stack with name *name* not found.
 200  *    - EINVAL - *name* pointer is NULL.
 201  */
 202 struct rte_stack * __rte_experimental
 203 rte_stack_lookup(const char *name);
 204
 205 #ifdef __cplusplus
 206 }
 207 #endif
 208
 209 #endif /* _RTE_STACK_H_ */