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_ */ 270