1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2016-2017 Intel Corporation
3 * Copyright(c) 2019 Arm Limited
10 * This provides a ring implementation for passing rte_event structures
11 * from one core to another.
14 #ifndef _RTE_EVENT_RING_
15 #define _RTE_EVENT_RING_
23 #include <rte_common.h>
25 #include <rte_ring_elem.h>
26 #include "rte_eventdev.h"
28 #define RTE_TAILQ_EVENT_RING_NAME "RTE_EVENT_RING"
31 * Generic ring structure for passing rte_event objects from core to core.
33 * Based on the primitives given in the rte_ring library. Designed to be
34 * used inside software eventdev implementations and by applications
37 struct rte_event_ring {
42 * Returns the number of events in the ring
45 * pointer to the event ring
47 * the number of events in the ring
49 static __rte_always_inline unsigned int
50 rte_event_ring_count(const struct rte_event_ring *r)
52 return rte_ring_count(&r->r);
56 * Returns the amount of free space in the ring
59 * pointer to the event ring
61 * the number of free slots in the ring, i.e. the number of events that
62 * can be successfully enqueued before dequeue must be called
64 static __rte_always_inline unsigned int
65 rte_event_ring_free_count(const struct rte_event_ring *r)
67 return rte_ring_free_count(&r->r);
71 * Enqueue a set of events onto a ring
73 * Note: this API enqueues by copying the events themselves onto the ring,
74 * rather than just placing a pointer to each event onto the ring. This
75 * means that statically-allocated events can safely be enqueued by this
79 * pointer to the event ring
81 * pointer to an array of struct rte_event objects
83 * number of events in the array to enqueue
85 * if non-null, is updated to indicate the amount of free space in the
86 * ring once the enqueue has completed.
88 * the number of elements, n', enqueued to the ring, 0 <= n' <= n
90 static __rte_always_inline unsigned int
91 rte_event_ring_enqueue_burst(struct rte_event_ring *r,
92 const struct rte_event *events,
93 unsigned int n, uint16_t *free_space)
98 num = rte_ring_enqueue_burst_elem(&r->r, events,
99 sizeof(struct rte_event), n,
102 if (free_space != NULL)
109 * Dequeue a set of events from a ring
111 * Note: this API does not work with pointers to events, rather it copies
112 * the events themselves to the destination ``events`` buffer.
115 * pointer to the event ring
117 * pointer to an array to hold the struct rte_event objects
119 * number of events that can be held in the ``events`` array
121 * if non-null, is updated to indicate the number of events remaining in
122 * the ring once the dequeue has completed
124 * the number of elements, n', dequeued from the ring, 0 <= n' <= n
126 static __rte_always_inline unsigned int
127 rte_event_ring_dequeue_burst(struct rte_event_ring *r,
128 struct rte_event *events,
129 unsigned int n, uint16_t *available)
134 num = rte_ring_dequeue_burst_elem(&r->r, events,
135 sizeof(struct rte_event), n,
138 if (available != NULL)
139 *available = remaining;
145 * Initializes an already-allocated ring structure
148 * pointer to the ring memory to be initialized
150 * name to be given to the ring
152 * the number of elements to be stored in the ring. If the flag
153 * ``RING_F_EXACT_SZ`` is not set, this must be a power of 2, and the actual
154 * usable space in the ring will be ``count - 1`` entries. If the flag
155 * ``RING_F_EXACT_SZ`` is set, the this can be any value up to the ring size
156 * limit - 1, and the usable space will be exactly that requested.
158 * An OR of the following:
159 * - RING_F_SP_ENQ: If this flag is set, the default behavior when
160 * using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
161 * is "single-producer". Otherwise, it is "multi-producers".
162 * - RING_F_SC_DEQ: If this flag is set, the default behavior when
163 * using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
164 * is "single-consumer". Otherwise, it is "multi-consumers".
165 * - RING_F_EXACT_SZ: If this flag is set, the ``count`` parameter is to
166 * be taken as the exact usable size of the ring, and as such does not
167 * need to be a power of 2. The underlying ring memory should be a
168 * power-of-2 size greater than the count value.
170 * 0 on success, or a negative value on error.
173 rte_event_ring_init(struct rte_event_ring *r, const char *name,
174 unsigned int count, unsigned int flags);
177 * Create an event ring structure
179 * This function allocates memory and initializes an event ring inside that
183 * name to be given to the ring
185 * the number of elements to be stored in the ring. If the flag
186 * ``RING_F_EXACT_SZ`` is not set, this must be a power of 2, and the actual
187 * usable space in the ring will be ``count - 1`` entries. If the flag
188 * ``RING_F_EXACT_SZ`` is set, the this can be any value up to the ring size
189 * limit - 1, and the usable space will be exactly that requested.
191 * The *socket_id* argument is the socket identifier in case of
192 * NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
193 * constraint for the reserved zone.
195 * An OR of the following:
196 * - RING_F_SP_ENQ: If this flag is set, the default behavior when
197 * using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
198 * is "single-producer". Otherwise, it is "multi-producers".
199 * - RING_F_SC_DEQ: If this flag is set, the default behavior when
200 * using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
201 * is "single-consumer". Otherwise, it is "multi-consumers".
202 * - RING_F_EXACT_SZ: If this flag is set, the ``count`` parameter is to
203 * be taken as the exact usable size of the ring, and as such does not
204 * need to be a power of 2. The underlying ring memory should be a
205 * power-of-2 size greater than the count value.
207 * On success, the pointer to the new allocated ring. NULL on error with
208 * rte_errno set appropriately. Possible errno values include:
209 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
210 * - E_RTE_SECONDARY - function was called from a secondary process instance
211 * - EINVAL - count provided is not a power of 2
212 * - ENOSPC - the maximum number of memzones has already been allocated
213 * - EEXIST - a memzone with the same name already exists
214 * - ENOMEM - no appropriate memory area found in which to create memzone
216 struct rte_event_ring *
217 rte_event_ring_create(const char *name, unsigned int count, int socket_id,
221 * Search for an event ring based on its name
224 * The name of the ring.
226 * The pointer to the ring matching the name, or NULL if not found,
227 * with rte_errno set appropriately. Possible rte_errno values include:
228 * - ENOENT - required entry not available to return.
230 struct rte_event_ring *
231 rte_event_ring_lookup(const char *name);
234 * De-allocate all memory used by the ring.
240 rte_event_ring_free(struct rte_event_ring *r);
243 * Return the size of the event ring.
246 * A pointer to the ring structure.
248 * The size of the data store used by the ring.
249 * NOTE: this is not the same as the usable space in the ring. To query that
250 * use ``rte_ring_get_capacity()``.
252 static inline unsigned int
253 rte_event_ring_get_size(const struct rte_event_ring *r)
255 return rte_ring_get_size(&r->r);
259 * Return the number of elements which can be stored in the event ring.
262 * A pointer to the ring structure.
264 * The usable size of the ring.
266 static inline unsigned int
267 rte_event_ring_get_capacity(const struct rte_event_ring *r)
269 return rte_ring_get_capacity(&r->r);