1 /* SPDX-License-Identifier: BSD-3-Clause
3 * Copyright (c) 2010-2020 Intel Corporation
4 * Copyright (c) 2007-2009 Kip Macy kmacy@freebsd.org
6 * Derived from FreeBSD's bufring.h
7 * Used as BSD-3 Licensed with permission from Kip Macy.
10 #ifndef _RTE_RING_HTS_H_
11 #define _RTE_RING_HTS_H_
14 * @file rte_ring_hts.h
15 * It is not recommended to include this file directly.
16 * Please include <rte_ring.h> instead.
18 * Contains functions for serialized, aka Head-Tail Sync (HTS) ring mode.
19 * In that mode enqueue/dequeue operation is fully serialized:
20 * at any given moment only one enqueue/dequeue operation can proceed.
21 * This is achieved by allowing a thread to proceed with changing head.value
22 * only when head.value == tail.value.
23 * Both head and tail values are updated atomically (as one 64-bit value).
24 * To achieve that 64-bit CAS is used by head update routine.
31 #include <rte_ring_hts_elem_pvt.h>
34 * Enqueue several objects on the HTS ring (multi-producers safe).
37 * A pointer to the ring structure.
39 * A pointer to a table of objects.
41 * The size of ring element, in bytes. It must be a multiple of 4.
42 * This must be the same value used while creating the ring. Otherwise
43 * the results are undefined.
45 * The number of objects to add in the ring from the obj_table.
47 * if non-NULL, returns the amount of space in the ring after the
48 * enqueue operation has finished.
50 * The number of objects enqueued, either 0 or n
52 static __rte_always_inline unsigned int
53 rte_ring_mp_hts_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table,
54 unsigned int esize, unsigned int n, unsigned int *free_space)
56 return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
57 RTE_RING_QUEUE_FIXED, free_space);
61 * Dequeue several objects from an HTS ring (multi-consumers safe).
64 * A pointer to the ring structure.
66 * A pointer to a table of objects that will be filled.
68 * The size of ring element, in bytes. It must be a multiple of 4.
69 * This must be the same value used while creating the ring. Otherwise
70 * the results are undefined.
72 * The number of objects to dequeue from the ring to the obj_table.
74 * If non-NULL, returns the number of remaining ring entries after the
75 * dequeue has finished.
77 * The number of objects dequeued, either 0 or n
79 static __rte_always_inline unsigned int
80 rte_ring_mc_hts_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
81 unsigned int esize, unsigned int n, unsigned int *available)
83 return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
84 RTE_RING_QUEUE_FIXED, available);
88 * Enqueue several objects on the HTS ring (multi-producers safe).
91 * A pointer to the ring structure.
93 * A pointer to a table of objects.
95 * The size of ring element, in bytes. It must be a multiple of 4.
96 * This must be the same value used while creating the ring. Otherwise
97 * the results are undefined.
99 * The number of objects to add in the ring from the obj_table.
101 * if non-NULL, returns the amount of space in the ring after the
102 * enqueue operation has finished.
104 * - n: Actual number of objects enqueued.
106 static __rte_always_inline unsigned int
107 rte_ring_mp_hts_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
108 unsigned int esize, unsigned int n, unsigned int *free_space)
110 return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
111 RTE_RING_QUEUE_VARIABLE, free_space);
115 * Dequeue several objects from an HTS ring (multi-consumers safe).
116 * When the requested objects are more than the available objects,
117 * only dequeue the actual number of objects.
120 * A pointer to the ring structure.
122 * A pointer to a table of objects that will be filled.
124 * The size of ring element, in bytes. It must be a multiple of 4.
125 * This must be the same value used while creating the ring. Otherwise
126 * the results are undefined.
128 * The number of objects to dequeue from the ring to the obj_table.
130 * If non-NULL, returns the number of remaining ring entries after the
131 * dequeue has finished.
133 * - n: Actual number of objects dequeued, 0 if ring is empty
135 static __rte_always_inline unsigned int
136 rte_ring_mc_hts_dequeue_burst_elem(struct rte_ring *r, void *obj_table,
137 unsigned int esize, unsigned int n, unsigned int *available)
139 return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
140 RTE_RING_QUEUE_VARIABLE, available);
144 * Enqueue several objects on the HTS ring (multi-producers safe).
147 * A pointer to the ring structure.
149 * A pointer to a table of void * pointers (objects).
151 * The number of objects to add in the ring from the obj_table.
153 * if non-NULL, returns the amount of space in the ring after the
154 * enqueue operation has finished.
156 * The number of objects enqueued, either 0 or n
158 static __rte_always_inline unsigned int
159 rte_ring_mp_hts_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
160 unsigned int n, unsigned int *free_space)
162 return rte_ring_mp_hts_enqueue_bulk_elem(r, obj_table,
163 sizeof(uintptr_t), n, free_space);
167 * Dequeue several objects from an HTS ring (multi-consumers safe).
170 * A pointer to the ring structure.
172 * A pointer to a table of void * pointers (objects) that will be filled.
174 * The number of objects to dequeue from the ring to the obj_table.
176 * If non-NULL, returns the number of remaining ring entries after the
177 * dequeue has finished.
179 * The number of objects dequeued, either 0 or n
181 static __rte_always_inline unsigned int
182 rte_ring_mc_hts_dequeue_bulk(struct rte_ring *r, void **obj_table,
183 unsigned int n, unsigned int *available)
185 return rte_ring_mc_hts_dequeue_bulk_elem(r, obj_table,
186 sizeof(uintptr_t), n, available);
190 * Enqueue several objects on the HTS ring (multi-producers safe).
193 * A pointer to the ring structure.
195 * A pointer to a table of void * pointers (objects).
197 * The number of objects to add in the ring from the obj_table.
199 * if non-NULL, returns the amount of space in the ring after the
200 * enqueue operation has finished.
202 * - n: Actual number of objects enqueued.
204 static __rte_always_inline unsigned int
205 rte_ring_mp_hts_enqueue_burst(struct rte_ring *r, void * const *obj_table,
206 unsigned int n, unsigned int *free_space)
208 return rte_ring_mp_hts_enqueue_burst_elem(r, obj_table,
209 sizeof(uintptr_t), n, free_space);
213 * Dequeue several objects from an HTS ring (multi-consumers safe).
214 * When the requested objects are more than the available objects,
215 * only dequeue the actual number of objects.
218 * A pointer to the ring structure.
220 * A pointer to a table of void * pointers (objects) that will be filled.
222 * The number of objects to dequeue from the ring to the obj_table.
224 * If non-NULL, returns the number of remaining ring entries after the
225 * dequeue has finished.
227 * - n: Actual number of objects dequeued, 0 if ring is empty
229 static __rte_always_inline unsigned int
230 rte_ring_mc_hts_dequeue_burst(struct rte_ring *r, void **obj_table,
231 unsigned int n, unsigned int *available)
233 return rte_ring_mc_hts_dequeue_burst_elem(r, obj_table,
234 sizeof(uintptr_t), n, available);
241 #endif /* _RTE_RING_HTS_H_ */