net/virtio: fix incorrect cast of void *
[dpdk.git] / ring / rte_ring.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  *
3  * Copyright (c) 2010-2020 Intel Corporation
4  * Copyright (c) 2007-2009 Kip Macy kmacy@freebsd.org
5  * All rights reserved.
6  * Derived from FreeBSD's bufring.h
7  * Used as BSD-3 Licensed with permission from Kip Macy.
8  */
9
10 #ifndef _RTE_RING_H_
11 #define _RTE_RING_H_
12
13 /**
14  * @file
15  * RTE Ring
16  *
17  * The Ring Manager is a fixed-size queue, implemented as a table of
18  * pointers. Head and tail pointers are modified atomically, allowing
19  * concurrent access to it. It has the following features:
20  *
21  * - FIFO (First In First Out)
22  * - Maximum size is fixed; the pointers are stored in a table.
23  * - Lockless implementation.
24  * - Multi- or single-consumer dequeue.
25  * - Multi- or single-producer enqueue.
26  * - Bulk dequeue.
27  * - Bulk enqueue.
28  * - Ability to select different sync modes for producer/consumer.
29  * - Dequeue start/finish (depending on consumer sync modes).
30  * - Enqueue start/finish (depending on producer sync mode).
31  *
32  * Note: the ring implementation is not preemptible. Refer to Programmer's
33  * guide/Environment Abstraction Layer/Multiple pthread/Known Issues/rte_ring
34  * for more information.
35  *
36  */
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 #include <rte_ring_core.h>
43 #include <rte_ring_elem.h>
44
45 /**
46  * Calculate the memory size needed for a ring
47  *
48  * This function returns the number of bytes needed for a ring, given
49  * the number of elements in it. This value is the sum of the size of
50  * the structure rte_ring and the size of the memory needed by the
51  * objects pointers. The value is aligned to a cache line size.
52  *
53  * @param count
54  *   The number of elements in the ring (must be a power of 2).
55  * @return
56  *   - The memory size needed for the ring on success.
57  *   - -EINVAL if count is not a power of 2.
58  */
59 ssize_t rte_ring_get_memsize(unsigned int count);
60
61 /**
62  * Initialize a ring structure.
63  *
64  * Initialize a ring structure in memory pointed by "r". The size of the
65  * memory area must be large enough to store the ring structure and the
66  * object table. It is advised to use rte_ring_get_memsize() to get the
67  * appropriate size.
68  *
69  * The ring size is set to *count*, which must be a power of two. Water
70  * marking is disabled by default. The real usable ring size is
71  * *count-1* instead of *count* to differentiate a free ring from an
72  * empty ring.
73  *
74  * The ring is not added in RTE_TAILQ_RING global list. Indeed, the
75  * memory given by the caller may not be shareable among dpdk
76  * processes.
77  *
78  * @param r
79  *   The pointer to the ring structure followed by the objects table.
80  * @param name
81  *   The name of the ring.
82  * @param count
83  *   The number of elements in the ring (must be a power of 2).
84  * @param flags
85  *   An OR of the following:
86  *   - One of mutually exclusive flags that define producer behavior:
87  *      - RING_F_SP_ENQ: If this flag is set, the default behavior when
88  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
89  *        is "single-producer".
90  *      - RING_F_MP_RTS_ENQ: If this flag is set, the default behavior when
91  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
92  *        is "multi-producer RTS mode".
93  *      - RING_F_MP_HTS_ENQ: If this flag is set, the default behavior when
94  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
95  *        is "multi-producer HTS mode".
96  *     If none of these flags is set, then default "multi-producer"
97  *     behavior is selected.
98  *   - One of mutually exclusive flags that define consumer behavior:
99  *      - RING_F_SC_DEQ: If this flag is set, the default behavior when
100  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
101  *        is "single-consumer". Otherwise, it is "multi-consumers".
102  *      - RING_F_MC_RTS_DEQ: If this flag is set, the default behavior when
103  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
104  *        is "multi-consumer RTS mode".
105  *      - RING_F_MC_HTS_DEQ: If this flag is set, the default behavior when
106  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
107  *        is "multi-consumer HTS mode".
108  *     If none of these flags is set, then default "multi-consumer"
109  *     behavior is selected.
110  * @return
111  *   0 on success, or a negative value on error.
112  */
113 int rte_ring_init(struct rte_ring *r, const char *name, unsigned int count,
114         unsigned int flags);
115
116 /**
117  * Create a new ring named *name* in memory.
118  *
119  * This function uses ``memzone_reserve()`` to allocate memory. Then it
120  * calls rte_ring_init() to initialize an empty ring.
121  *
122  * The new ring size is set to *count*, which must be a power of
123  * two. Water marking is disabled by default. The real usable ring size
124  * is *count-1* instead of *count* to differentiate a free ring from an
125  * empty ring.
126  *
127  * The ring is added in RTE_TAILQ_RING list.
128  *
129  * @param name
130  *   The name of the ring.
131  * @param count
132  *   The size of the ring (must be a power of 2).
133  * @param socket_id
134  *   The *socket_id* argument is the socket identifier in case of
135  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
136  *   constraint for the reserved zone.
137  * @param flags
138  *   An OR of the following:
139  *   - One of mutually exclusive flags that define producer behavior:
140  *      - RING_F_SP_ENQ: If this flag is set, the default behavior when
141  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
142  *        is "single-producer".
143  *      - RING_F_MP_RTS_ENQ: If this flag is set, the default behavior when
144  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
145  *        is "multi-producer RTS mode".
146  *      - RING_F_MP_HTS_ENQ: If this flag is set, the default behavior when
147  *        using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
148  *        is "multi-producer HTS mode".
149  *     If none of these flags is set, then default "multi-producer"
150  *     behavior is selected.
151  *   - One of mutually exclusive flags that define consumer behavior:
152  *      - RING_F_SC_DEQ: If this flag is set, the default behavior when
153  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
154  *        is "single-consumer". Otherwise, it is "multi-consumers".
155  *      - RING_F_MC_RTS_DEQ: If this flag is set, the default behavior when
156  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
157  *        is "multi-consumer RTS mode".
158  *      - RING_F_MC_HTS_DEQ: If this flag is set, the default behavior when
159  *        using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
160  *        is "multi-consumer HTS mode".
161  *     If none of these flags is set, then default "multi-consumer"
162  *     behavior is selected.
163  * @return
164  *   On success, the pointer to the new allocated ring. NULL on error with
165  *    rte_errno set appropriately. Possible errno values include:
166  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
167  *    - E_RTE_SECONDARY - function was called from a secondary process instance
168  *    - EINVAL - count provided is not a power of 2
169  *    - ENOSPC - the maximum number of memzones has already been allocated
170  *    - EEXIST - a memzone with the same name already exists
171  *    - ENOMEM - no appropriate memory area found in which to create memzone
172  */
173 struct rte_ring *rte_ring_create(const char *name, unsigned int count,
174                                  int socket_id, unsigned int flags);
175
176 /**
177  * De-allocate all memory used by the ring.
178  *
179  * @param r
180  *   Ring to free
181  */
182 void rte_ring_free(struct rte_ring *r);
183
184 /**
185  * Dump the status of the ring to a file.
186  *
187  * @param f
188  *   A pointer to a file for output
189  * @param r
190  *   A pointer to the ring structure.
191  */
192 void rte_ring_dump(FILE *f, const struct rte_ring *r);
193
194 /**
195  * Enqueue several objects on the ring (multi-producers safe).
196  *
197  * This function uses a "compare and set" instruction to move the
198  * producer index atomically.
199  *
200  * @param r
201  *   A pointer to the ring structure.
202  * @param obj_table
203  *   A pointer to a table of void * pointers (objects).
204  * @param n
205  *   The number of objects to add in the ring from the obj_table.
206  * @param free_space
207  *   if non-NULL, returns the amount of space in the ring after the
208  *   enqueue operation has finished.
209  * @return
210  *   The number of objects enqueued, either 0 or n
211  */
212 static __rte_always_inline unsigned int
213 rte_ring_mp_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
214                          unsigned int n, unsigned int *free_space)
215 {
216         return rte_ring_mp_enqueue_bulk_elem(r, obj_table, sizeof(void *),
217                         n, free_space);
218 }
219
220 /**
221  * Enqueue several objects on a ring (NOT multi-producers safe).
222  *
223  * @param r
224  *   A pointer to the ring structure.
225  * @param obj_table
226  *   A pointer to a table of void * pointers (objects).
227  * @param n
228  *   The number of objects to add in the ring from the obj_table.
229  * @param free_space
230  *   if non-NULL, returns the amount of space in the ring after the
231  *   enqueue operation has finished.
232  * @return
233  *   The number of objects enqueued, either 0 or n
234  */
235 static __rte_always_inline unsigned int
236 rte_ring_sp_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
237                          unsigned int n, unsigned int *free_space)
238 {
239         return rte_ring_sp_enqueue_bulk_elem(r, obj_table, sizeof(void *),
240                         n, free_space);
241 }
242
243 /**
244  * Enqueue several objects on a ring.
245  *
246  * This function calls the multi-producer or the single-producer
247  * version depending on the default behavior that was specified at
248  * ring creation time (see flags).
249  *
250  * @param r
251  *   A pointer to the ring structure.
252  * @param obj_table
253  *   A pointer to a table of void * pointers (objects).
254  * @param n
255  *   The number of objects to add in the ring from the obj_table.
256  * @param free_space
257  *   if non-NULL, returns the amount of space in the ring after the
258  *   enqueue operation has finished.
259  * @return
260  *   The number of objects enqueued, either 0 or n
261  */
262 static __rte_always_inline unsigned int
263 rte_ring_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
264                       unsigned int n, unsigned int *free_space)
265 {
266         return rte_ring_enqueue_bulk_elem(r, obj_table, sizeof(void *),
267                         n, free_space);
268 }
269
270 /**
271  * Enqueue one object on a ring (multi-producers safe).
272  *
273  * This function uses a "compare and set" instruction to move the
274  * producer index atomically.
275  *
276  * @param r
277  *   A pointer to the ring structure.
278  * @param obj
279  *   A pointer to the object to be added.
280  * @return
281  *   - 0: Success; objects enqueued.
282  *   - -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.
283  */
284 static __rte_always_inline int
285 rte_ring_mp_enqueue(struct rte_ring *r, void *obj)
286 {
287         return rte_ring_mp_enqueue_elem(r, &obj, sizeof(void *));
288 }
289
290 /**
291  * Enqueue one object on a ring (NOT multi-producers safe).
292  *
293  * @param r
294  *   A pointer to the ring structure.
295  * @param obj
296  *   A pointer to the object to be added.
297  * @return
298  *   - 0: Success; objects enqueued.
299  *   - -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.
300  */
301 static __rte_always_inline int
302 rte_ring_sp_enqueue(struct rte_ring *r, void *obj)
303 {
304         return rte_ring_sp_enqueue_elem(r, &obj, sizeof(void *));
305 }
306
307 /**
308  * Enqueue one object on a ring.
309  *
310  * This function calls the multi-producer or the single-producer
311  * version, depending on the default behaviour that was specified at
312  * ring creation time (see flags).
313  *
314  * @param r
315  *   A pointer to the ring structure.
316  * @param obj
317  *   A pointer to the object to be added.
318  * @return
319  *   - 0: Success; objects enqueued.
320  *   - -ENOBUFS: Not enough room in the ring to enqueue; no object is enqueued.
321  */
322 static __rte_always_inline int
323 rte_ring_enqueue(struct rte_ring *r, void *obj)
324 {
325         return rte_ring_enqueue_elem(r, &obj, sizeof(void *));
326 }
327
328 /**
329  * Dequeue several objects from a ring (multi-consumers safe).
330  *
331  * This function uses a "compare and set" instruction to move the
332  * consumer index atomically.
333  *
334  * @param r
335  *   A pointer to the ring structure.
336  * @param obj_table
337  *   A pointer to a table of void * pointers (objects) that will be filled.
338  * @param n
339  *   The number of objects to dequeue from the ring to the obj_table.
340  * @param available
341  *   If non-NULL, returns the number of remaining ring entries after the
342  *   dequeue has finished.
343  * @return
344  *   The number of objects dequeued, either 0 or n
345  */
346 static __rte_always_inline unsigned int
347 rte_ring_mc_dequeue_bulk(struct rte_ring *r, void **obj_table,
348                 unsigned int n, unsigned int *available)
349 {
350         return rte_ring_mc_dequeue_bulk_elem(r, obj_table, sizeof(void *),
351                         n, available);
352 }
353
354 /**
355  * Dequeue several objects from a ring (NOT multi-consumers safe).
356  *
357  * @param r
358  *   A pointer to the ring structure.
359  * @param obj_table
360  *   A pointer to a table of void * pointers (objects) that will be filled.
361  * @param n
362  *   The number of objects to dequeue from the ring to the obj_table,
363  *   must be strictly positive.
364  * @param available
365  *   If non-NULL, returns the number of remaining ring entries after the
366  *   dequeue has finished.
367  * @return
368  *   The number of objects dequeued, either 0 or n
369  */
370 static __rte_always_inline unsigned int
371 rte_ring_sc_dequeue_bulk(struct rte_ring *r, void **obj_table,
372                 unsigned int n, unsigned int *available)
373 {
374         return rte_ring_sc_dequeue_bulk_elem(r, obj_table, sizeof(void *),
375                         n, available);
376 }
377
378 /**
379  * Dequeue several objects from a ring.
380  *
381  * This function calls the multi-consumers or the single-consumer
382  * version, depending on the default behaviour that was specified at
383  * ring creation time (see flags).
384  *
385  * @param r
386  *   A pointer to the ring structure.
387  * @param obj_table
388  *   A pointer to a table of void * pointers (objects) that will be filled.
389  * @param n
390  *   The number of objects to dequeue from the ring to the obj_table.
391  * @param available
392  *   If non-NULL, returns the number of remaining ring entries after the
393  *   dequeue has finished.
394  * @return
395  *   The number of objects dequeued, either 0 or n
396  */
397 static __rte_always_inline unsigned int
398 rte_ring_dequeue_bulk(struct rte_ring *r, void **obj_table, unsigned int n,
399                 unsigned int *available)
400 {
401         return rte_ring_dequeue_bulk_elem(r, obj_table, sizeof(void *),
402                         n, available);
403 }
404
405 /**
406  * Dequeue one object from a ring (multi-consumers safe).
407  *
408  * This function uses a "compare and set" instruction to move the
409  * consumer index atomically.
410  *
411  * @param r
412  *   A pointer to the ring structure.
413  * @param obj_p
414  *   A pointer to a void * pointer (object) that will be filled.
415  * @return
416  *   - 0: Success; objects dequeued.
417  *   - -ENOENT: Not enough entries in the ring to dequeue; no object is
418  *     dequeued.
419  */
420 static __rte_always_inline int
421 rte_ring_mc_dequeue(struct rte_ring *r, void **obj_p)
422 {
423         return rte_ring_mc_dequeue_elem(r, obj_p, sizeof(void *));
424 }
425
426 /**
427  * Dequeue one object from a ring (NOT multi-consumers safe).
428  *
429  * @param r
430  *   A pointer to the ring structure.
431  * @param obj_p
432  *   A pointer to a void * pointer (object) that will be filled.
433  * @return
434  *   - 0: Success; objects dequeued.
435  *   - -ENOENT: Not enough entries in the ring to dequeue, no object is
436  *     dequeued.
437  */
438 static __rte_always_inline int
439 rte_ring_sc_dequeue(struct rte_ring *r, void **obj_p)
440 {
441         return rte_ring_sc_dequeue_elem(r, obj_p, sizeof(void *));
442 }
443
444 /**
445  * Dequeue one object from a ring.
446  *
447  * This function calls the multi-consumers or the single-consumer
448  * version depending on the default behaviour that was specified at
449  * ring creation time (see flags).
450  *
451  * @param r
452  *   A pointer to the ring structure.
453  * @param obj_p
454  *   A pointer to a void * pointer (object) that will be filled.
455  * @return
456  *   - 0: Success, objects dequeued.
457  *   - -ENOENT: Not enough entries in the ring to dequeue, no object is
458  *     dequeued.
459  */
460 static __rte_always_inline int
461 rte_ring_dequeue(struct rte_ring *r, void **obj_p)
462 {
463         return rte_ring_dequeue_elem(r, obj_p, sizeof(void *));
464 }
465
466 /**
467  * Flush a ring.
468  *
469  * This function flush all the elements in a ring
470  *
471  * @warning
472  * Make sure the ring is not in use while calling this function.
473  *
474  * @param r
475  *   A pointer to the ring structure.
476  */
477 void
478 rte_ring_reset(struct rte_ring *r);
479
480 /**
481  * Return the number of entries in a ring.
482  *
483  * @param r
484  *   A pointer to the ring structure.
485  * @return
486  *   The number of entries in the ring.
487  */
488 static inline unsigned int
489 rte_ring_count(const struct rte_ring *r)
490 {
491         uint32_t prod_tail = r->prod.tail;
492         uint32_t cons_tail = r->cons.tail;
493         uint32_t count = (prod_tail - cons_tail) & r->mask;
494         return (count > r->capacity) ? r->capacity : count;
495 }
496
497 /**
498  * Return the number of free entries in a ring.
499  *
500  * @param r
501  *   A pointer to the ring structure.
502  * @return
503  *   The number of free entries in the ring.
504  */
505 static inline unsigned int
506 rte_ring_free_count(const struct rte_ring *r)
507 {
508         return r->capacity - rte_ring_count(r);
509 }
510
511 /**
512  * Test if a ring is full.
513  *
514  * @param r
515  *   A pointer to the ring structure.
516  * @return
517  *   - 1: The ring is full.
518  *   - 0: The ring is not full.
519  */
520 static inline int
521 rte_ring_full(const struct rte_ring *r)
522 {
523         return rte_ring_free_count(r) == 0;
524 }
525
526 /**
527  * Test if a ring is empty.
528  *
529  * @param r
530  *   A pointer to the ring structure.
531  * @return
532  *   - 1: The ring is empty.
533  *   - 0: The ring is not empty.
534  */
535 static inline int
536 rte_ring_empty(const struct rte_ring *r)
537 {
538         uint32_t prod_tail = r->prod.tail;
539         uint32_t cons_tail = r->cons.tail;
540         return cons_tail == prod_tail;
541 }
542
543 /**
544  * Return the size of the ring.
545  *
546  * @param r
547  *   A pointer to the ring structure.
548  * @return
549  *   The size of the data store used by the ring.
550  *   NOTE: this is not the same as the usable space in the ring. To query that
551  *   use ``rte_ring_get_capacity()``.
552  */
553 static inline unsigned int
554 rte_ring_get_size(const struct rte_ring *r)
555 {
556         return r->size;
557 }
558
559 /**
560  * Return the number of elements which can be stored in the ring.
561  *
562  * @param r
563  *   A pointer to the ring structure.
564  * @return
565  *   The usable size of the ring.
566  */
567 static inline unsigned int
568 rte_ring_get_capacity(const struct rte_ring *r)
569 {
570         return r->capacity;
571 }
572
573 /**
574  * Return sync type used by producer in the ring.
575  *
576  * @param r
577  *   A pointer to the ring structure.
578  * @return
579  *   Producer sync type value.
580  */
581 static inline enum rte_ring_sync_type
582 rte_ring_get_prod_sync_type(const struct rte_ring *r)
583 {
584         return r->prod.sync_type;
585 }
586
587 /**
588  * Check is the ring for single producer.
589  *
590  * @param r
591  *   A pointer to the ring structure.
592  * @return
593  *   true if ring is SP, zero otherwise.
594  */
595 static inline int
596 rte_ring_is_prod_single(const struct rte_ring *r)
597 {
598         return (rte_ring_get_prod_sync_type(r) == RTE_RING_SYNC_ST);
599 }
600
601 /**
602  * Return sync type used by consumer in the ring.
603  *
604  * @param r
605  *   A pointer to the ring structure.
606  * @return
607  *   Consumer sync type value.
608  */
609 static inline enum rte_ring_sync_type
610 rte_ring_get_cons_sync_type(const struct rte_ring *r)
611 {
612         return r->cons.sync_type;
613 }
614
615 /**
616  * Check is the ring for single consumer.
617  *
618  * @param r
619  *   A pointer to the ring structure.
620  * @return
621  *   true if ring is SC, zero otherwise.
622  */
623 static inline int
624 rte_ring_is_cons_single(const struct rte_ring *r)
625 {
626         return (rte_ring_get_cons_sync_type(r) == RTE_RING_SYNC_ST);
627 }
628
629 /**
630  * Dump the status of all rings on the console
631  *
632  * @param f
633  *   A pointer to a file for output
634  */
635 void rte_ring_list_dump(FILE *f);
636
637 /**
638  * Search a ring from its name
639  *
640  * @param name
641  *   The name of the ring.
642  * @return
643  *   The pointer to the ring matching the name, or NULL if not found,
644  *   with rte_errno set appropriately. Possible rte_errno values include:
645  *    - ENOENT - required entry not available to return.
646  */
647 struct rte_ring *rte_ring_lookup(const char *name);
648
649 /**
650  * Enqueue several objects on the ring (multi-producers safe).
651  *
652  * This function uses a "compare and set" instruction to move the
653  * producer index atomically.
654  *
655  * @param r
656  *   A pointer to the ring structure.
657  * @param obj_table
658  *   A pointer to a table of void * pointers (objects).
659  * @param n
660  *   The number of objects to add in the ring from the obj_table.
661  * @param free_space
662  *   if non-NULL, returns the amount of space in the ring after the
663  *   enqueue operation has finished.
664  * @return
665  *   - n: Actual number of objects enqueued.
666  */
667 static __rte_always_inline unsigned int
668 rte_ring_mp_enqueue_burst(struct rte_ring *r, void * const *obj_table,
669                          unsigned int n, unsigned int *free_space)
670 {
671         return rte_ring_mp_enqueue_burst_elem(r, obj_table, sizeof(void *),
672                         n, free_space);
673 }
674
675 /**
676  * Enqueue several objects on a ring (NOT multi-producers safe).
677  *
678  * @param r
679  *   A pointer to the ring structure.
680  * @param obj_table
681  *   A pointer to a table of void * pointers (objects).
682  * @param n
683  *   The number of objects to add in the ring from the obj_table.
684  * @param free_space
685  *   if non-NULL, returns the amount of space in the ring after the
686  *   enqueue operation has finished.
687  * @return
688  *   - n: Actual number of objects enqueued.
689  */
690 static __rte_always_inline unsigned int
691 rte_ring_sp_enqueue_burst(struct rte_ring *r, void * const *obj_table,
692                          unsigned int n, unsigned int *free_space)
693 {
694         return rte_ring_sp_enqueue_burst_elem(r, obj_table, sizeof(void *),
695                         n, free_space);
696 }
697
698 /**
699  * Enqueue several objects on a ring.
700  *
701  * This function calls the multi-producer or the single-producer
702  * version depending on the default behavior that was specified at
703  * ring creation time (see flags).
704  *
705  * @param r
706  *   A pointer to the ring structure.
707  * @param obj_table
708  *   A pointer to a table of void * pointers (objects).
709  * @param n
710  *   The number of objects to add in the ring from the obj_table.
711  * @param free_space
712  *   if non-NULL, returns the amount of space in the ring after the
713  *   enqueue operation has finished.
714  * @return
715  *   - n: Actual number of objects enqueued.
716  */
717 static __rte_always_inline unsigned int
718 rte_ring_enqueue_burst(struct rte_ring *r, void * const *obj_table,
719                       unsigned int n, unsigned int *free_space)
720 {
721         return rte_ring_enqueue_burst_elem(r, obj_table, sizeof(void *),
722                         n, free_space);
723 }
724
725 /**
726  * Dequeue several objects from a ring (multi-consumers safe). When the request
727  * objects are more than the available objects, only dequeue the actual number
728  * of objects
729  *
730  * This function uses a "compare and set" instruction to move the
731  * consumer index atomically.
732  *
733  * @param r
734  *   A pointer to the ring structure.
735  * @param obj_table
736  *   A pointer to a table of void * pointers (objects) that will be filled.
737  * @param n
738  *   The number of objects to dequeue from the ring to the obj_table.
739  * @param available
740  *   If non-NULL, returns the number of remaining ring entries after the
741  *   dequeue has finished.
742  * @return
743  *   - n: Actual number of objects dequeued, 0 if ring is empty
744  */
745 static __rte_always_inline unsigned int
746 rte_ring_mc_dequeue_burst(struct rte_ring *r, void **obj_table,
747                 unsigned int n, unsigned int *available)
748 {
749         return rte_ring_mc_dequeue_burst_elem(r, obj_table, sizeof(void *),
750                         n, available);
751 }
752
753 /**
754  * Dequeue several objects from a ring (NOT multi-consumers safe).When the
755  * request objects are more than the available objects, only dequeue the
756  * actual number of objects
757  *
758  * @param r
759  *   A pointer to the ring structure.
760  * @param obj_table
761  *   A pointer to a table of void * pointers (objects) that will be filled.
762  * @param n
763  *   The number of objects to dequeue from the ring to the obj_table.
764  * @param available
765  *   If non-NULL, returns the number of remaining ring entries after the
766  *   dequeue has finished.
767  * @return
768  *   - n: Actual number of objects dequeued, 0 if ring is empty
769  */
770 static __rte_always_inline unsigned int
771 rte_ring_sc_dequeue_burst(struct rte_ring *r, void **obj_table,
772                 unsigned int n, unsigned int *available)
773 {
774         return rte_ring_sc_dequeue_burst_elem(r, obj_table, sizeof(void *),
775                         n, available);
776 }
777
778 /**
779  * Dequeue multiple objects from a ring up to a maximum number.
780  *
781  * This function calls the multi-consumers or the single-consumer
782  * version, depending on the default behaviour that was specified at
783  * ring creation time (see flags).
784  *
785  * @param r
786  *   A pointer to the ring structure.
787  * @param obj_table
788  *   A pointer to a table of void * pointers (objects) that will be filled.
789  * @param n
790  *   The number of objects to dequeue from the ring to the obj_table.
791  * @param available
792  *   If non-NULL, returns the number of remaining ring entries after the
793  *   dequeue has finished.
794  * @return
795  *   - Number of objects dequeued
796  */
797 static __rte_always_inline unsigned int
798 rte_ring_dequeue_burst(struct rte_ring *r, void **obj_table,
799                 unsigned int n, unsigned int *available)
800 {
801         return rte_ring_dequeue_burst_elem(r, obj_table, sizeof(void *),
802                         n, available);
803 }
804
805 #ifdef __cplusplus
806 }
807 #endif
808
809 #endif /* _RTE_RING_H_ */