lib/eventdev/rte_event_ring.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2016-2017 Intel Corporation
   3  * Copyright(c) 2019 Arm Limited
   4  */
   5
   6 /**
   7  * @file
   8  * RTE Event Ring
   9  *
  10  * This provides a ring implementation for passing rte_event structures
  11  * from one core to another.
  12  */
  13
  14 #ifndef _RTE_EVENT_RING_
  15 #define _RTE_EVENT_RING_
  16
  17 #include <stdint.h>
  18
  19 #include <rte_common.h>
  20 #include <rte_ring.h>
  21 #include <rte_ring_elem.h>
  22 #include "rte_eventdev.h"
  23
  24 #define RTE_TAILQ_EVENT_RING_NAME "RTE_EVENT_RING"
  25
  26 /**
  27  * Generic ring structure for passing rte_event objects from core to core.
  28  *
  29  * Based on the primitives given in the rte_ring library. Designed to be
  30  * used inside software eventdev implementations and by applications
  31  * directly as needed.
  32  */
  33 struct rte_event_ring {
  34         struct rte_ring r;
  35 };
  36
  37 /**
  38  * Returns the number of events in the ring
  39  *
  40  * @param r
  41  *   pointer to the event ring
  42  * @return
  43  *   the number of events in the ring
  44  */
  45 static __rte_always_inline unsigned int
  46 rte_event_ring_count(const struct rte_event_ring *r)
  47 {
  48         return rte_ring_count(&r->r);
  49 }
  50
  51 /**
  52  * Returns the amount of free space in the ring
  53  *
  54  * @param r
  55  *   pointer to the event ring
  56  * @return
  57  *   the number of free slots in the ring, i.e. the number of events that
  58  *   can be successfully enqueued before dequeue must be called
  59  */
  60 static __rte_always_inline unsigned int
  61 rte_event_ring_free_count(const struct rte_event_ring *r)
  62 {
  63         return rte_ring_free_count(&r->r);
  64 }
  65
  66 /**
  67  * Enqueue a set of events onto a ring
  68  *
  69  * Note: this API enqueues by copying the events themselves onto the ring,
  70  * rather than just placing a pointer to each event onto the ring. This
  71  * means that statically-allocated events can safely be enqueued by this
  72  * API.
  73  *
  74  * @param r
  75  *   pointer to the event ring
  76  * @param events
  77  *   pointer to an array of struct rte_event objects
  78  * @param n
  79  *   number of events in the array to enqueue
  80  * @param free_space
  81  *   if non-null, is updated to indicate the amount of free space in the
  82  *   ring once the enqueue has completed.
  83  * @return
  84  *   the number of elements, n', enqueued to the ring, 0 <= n' <= n
  85  */
  86 static __rte_always_inline unsigned int
  87 rte_event_ring_enqueue_burst(struct rte_event_ring *r,
  88                 const struct rte_event *events,
  89                 unsigned int n, uint16_t *free_space)
  90 {
  91         unsigned int num;
  92         uint32_t space;
  93
  94         num = rte_ring_enqueue_burst_elem(&r->r, events,
  95                                 sizeof(struct rte_event), n,
  96                                 &space);
  97
  98         if (free_space != NULL)
  99                 *free_space = space;
 100
 101         return num;
 102 }
 103
 104 /**
 105  * Dequeue a set of events from a ring
 106  *
 107  * Note: this API does not work with pointers to events, rather it copies
 108  * the events themselves to the destination ``events`` buffer.
 109  *
 110  * @param r
 111  *   pointer to the event ring
 112  * @param events
 113  *   pointer to an array to hold the struct rte_event objects
 114  * @param n
 115  *   number of events that can be held in the ``events`` array
 116  * @param available
 117  *   if non-null, is updated to indicate the number of events remaining in
 118  *   the ring once the dequeue has completed
 119  * @return
 120  *   the number of elements, n', dequeued from the ring, 0 <= n' <= n
 121  */
 122 static __rte_always_inline unsigned int
 123 rte_event_ring_dequeue_burst(struct rte_event_ring *r,
 124                 struct rte_event *events,
 125                 unsigned int n, uint16_t *available)
 126 {
 127         unsigned int num;
 128         uint32_t remaining;
 129
 130         num = rte_ring_dequeue_burst_elem(&r->r, events,
 131                                 sizeof(struct rte_event), n,
 132                                 &remaining);
 133
 134         if (available != NULL)
 135                 *available = remaining;
 136
 137         return num;
 138 }
 139
 140 /*
 141  * Initializes an already-allocated ring structure
 142  *
 143  * @param r
 144  *   pointer to the ring memory to be initialized
 145  * @param name
 146  *   name to be given to the ring
 147  * @param count
 148  *   the number of elements to be stored in the ring. If the flag
 149  *   ``RING_F_EXACT_SZ`` is not set, this must be a power of 2, and the actual
 150  *   usable space in the ring will be ``count - 1`` entries. If the flag
 151  *   ``RING_F_EXACT_SZ`` is set, the this can be any value up to the ring size
 152  *   limit - 1, and the usable space will be exactly that requested.
 153  * @param flags
 154  *   An OR of the following:
 155  *    - RING_F_SP_ENQ: If this flag is set, the default behavior when
 156  *      using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
 157  *      is "single-producer". Otherwise, it is "multi-producers".
 158  *    - RING_F_SC_DEQ: If this flag is set, the default behavior when
 159  *      using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
 160  *      is "single-consumer". Otherwise, it is "multi-consumers".
 161  *    - RING_F_EXACT_SZ: If this flag is set, the ``count`` parameter is to
 162  *      be taken as the exact usable size of the ring, and as such does not
 163  *      need to be a power of 2. The underlying ring memory should be a
 164  *      power-of-2 size greater than the count value.
 165  * @return
 166  *   0 on success, or a negative value on error.
 167  */
 168 int
 169 rte_event_ring_init(struct rte_event_ring *r, const char *name,
 170         unsigned int count, unsigned int flags);
 171
 172 /*
 173  * Create an event ring structure
 174  *
 175  * This function allocates memory and initializes an event ring inside that
 176  * memory.
 177  *
 178  * @param name
 179  *   name to be given to the ring
 180  * @param count
 181  *   the number of elements to be stored in the ring. If the flag
 182  *   ``RING_F_EXACT_SZ`` is not set, this must be a power of 2, and the actual
 183  *   usable space in the ring will be ``count - 1`` entries. If the flag
 184  *   ``RING_F_EXACT_SZ`` is set, the this can be any value up to the ring size
 185  *   limit - 1, and the usable space will be exactly that requested.
 186  * @param socket_id
 187  *   The *socket_id* argument is the socket identifier in case of
 188  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
 189  *   constraint for the reserved zone.
 190  * @param flags
 191  *   An OR of the following:
 192  *    - RING_F_SP_ENQ: If this flag is set, the default behavior when
 193  *      using ``rte_ring_enqueue()`` or ``rte_ring_enqueue_bulk()``
 194  *      is "single-producer". Otherwise, it is "multi-producers".
 195  *    - RING_F_SC_DEQ: If this flag is set, the default behavior when
 196  *      using ``rte_ring_dequeue()`` or ``rte_ring_dequeue_bulk()``
 197  *      is "single-consumer". Otherwise, it is "multi-consumers".
 198  *    - RING_F_EXACT_SZ: If this flag is set, the ``count`` parameter is to
 199  *      be taken as the exact usable size of the ring, and as such does not
 200  *      need to be a power of 2. The underlying ring memory should be a
 201  *      power-of-2 size greater than the count value.
 202  * @return
 203  *   On success, the pointer to the new allocated ring. NULL on error with
 204  *    rte_errno set appropriately. Possible errno values include:
 205  *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
 206  *    - E_RTE_SECONDARY - function was called from a secondary process instance
 207  *    - EINVAL - count provided is not a power of 2
 208  *    - ENOSPC - the maximum number of memzones has already been allocated
 209  *    - EEXIST - a memzone with the same name already exists
 210  *    - ENOMEM - no appropriate memory area found in which to create memzone
 211  */
 212 struct rte_event_ring *
 213 rte_event_ring_create(const char *name, unsigned int count, int socket_id,
 214                 unsigned int flags);
 215
 216 /**
 217  * Search for an event ring based on its name
 218  *
 219  * @param name
 220  *   The name of the ring.
 221  * @return
 222  *   The pointer to the ring matching the name, or NULL if not found,
 223  *   with rte_errno set appropriately. Possible rte_errno values include:
 224  *    - ENOENT - required entry not available to return.
 225  */
 226 struct rte_event_ring *
 227 rte_event_ring_lookup(const char *name);
 228
 229 /**
 230  * De-allocate all memory used by the ring.
 231  *
 232  * @param r
 233  *   Ring to free
 234  */
 235 void
 236 rte_event_ring_free(struct rte_event_ring *r);
 237
 238 /**
 239  * Return the size of the event ring.
 240  *
 241  * @param r
 242  *   A pointer to the ring structure.
 243  * @return
 244  *   The size of the data store used by the ring.
 245  *   NOTE: this is not the same as the usable space in the ring. To query that
 246  *   use ``rte_ring_get_capacity()``.
 247  */
 248 static inline unsigned int
 249 rte_event_ring_get_size(const struct rte_event_ring *r)
 250 {
 251         return rte_ring_get_size(&r->r);
 252 }
 253
 254 /**
 255  * Return the number of elements which can be stored in the event ring.
 256  *
 257  * @param r
 258  *   A pointer to the ring structure.
 259  * @return
 260  *   The usable size of the ring.
 261  */
 262 static inline unsigned int
 263 rte_event_ring_get_capacity(const struct rte_event_ring *r)
 264 {
 265         return rte_ring_get_capacity(&r->r);
 266 }
 267 #endif