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