lib/librte_ring/rte_ring_hts.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_HTS_H_
  11 #define _RTE_RING_HTS_H_
  12
  13 /**
  14  * @file rte_ring_hts.h
  15  * @b EXPERIMENTAL: this API may change without prior notice
  16  * It is not recommended to include this file directly.
  17  * Please include <rte_ring.h> instead.
  18  *
  19  * Contains functions for serialized, aka Head-Tail Sync (HTS) ring mode.
  20  * In that mode enqueue/dequeue operation is fully serialized:
  21  * at any given moment only one enqueue/dequeue operation can proceed.
  22  * This is achieved by allowing a thread to proceed with changing head.value
  23  * only when head.value == tail.value.
  24  * Both head and tail values are updated atomically (as one 64-bit value).
  25  * To achieve that 64-bit CAS is used by head update routine.
  26  */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #include <rte_ring_hts_c11_mem.h>
  33
  34 /**
  35  * @internal Enqueue several objects on the HTS ring.
  36  *
  37  * @param r
  38  *   A pointer to the ring structure.
  39  * @param obj_table
  40  *   A pointer to a table of objects.
  41  * @param esize
  42  *   The size of ring element, in bytes. It must be a multiple of 4.
  43  *   This must be the same value used while creating the ring. Otherwise
  44  *   the results are undefined.
  45  * @param n
  46  *   The number of objects to add in the ring from the obj_table.
  47  * @param behavior
  48  *   RTE_RING_QUEUE_FIXED:    Enqueue a fixed number of items from a ring
  49  *   RTE_RING_QUEUE_VARIABLE: Enqueue as many items as possible from ring
  50  * @param free_space
  51  *   returns the amount of space after the enqueue operation has finished
  52  * @return
  53  *   Actual number of objects enqueued.
  54  *   If behavior == RTE_RING_QUEUE_FIXED, this will be 0 or n only.
  55  */
  56 static __rte_always_inline unsigned int
  57 __rte_ring_do_hts_enqueue_elem(struct rte_ring *r, const void *obj_table,
  58         uint32_t esize, uint32_t n, enum rte_ring_queue_behavior behavior,
  59         uint32_t *free_space)
  60 {
  61         uint32_t free, head;
  62
  63         n =  __rte_ring_hts_move_prod_head(r, n, behavior, &head, &free);
  64
  65         if (n != 0) {
  66                 __rte_ring_enqueue_elems(r, head, obj_table, esize, n);
  67                 __rte_ring_hts_update_tail(&r->hts_prod, head, n, 1);
  68         }
  69
  70         if (free_space != NULL)
  71                 *free_space = free - n;
  72         return n;
  73 }
  74
  75 /**
  76  * @internal Dequeue several objects from the HTS ring.
  77  *
  78  * @param r
  79  *   A pointer to the ring structure.
  80  * @param obj_table
  81  *   A pointer to a table of objects.
  82  * @param esize
  83  *   The size of ring element, in bytes. It must be a multiple of 4.
  84  *   This must be the same value used while creating the ring. Otherwise
  85  *   the results are undefined.
  86  * @param n
  87  *   The number of objects to pull from the ring.
  88  * @param behavior
  89  *   RTE_RING_QUEUE_FIXED:    Dequeue a fixed number of items from a ring
  90  *   RTE_RING_QUEUE_VARIABLE: Dequeue as many items as possible from ring
  91  * @param available
  92  *   returns the number of remaining ring entries after the dequeue has finished
  93  * @return
  94  *   - Actual number of objects dequeued.
  95  *     If behavior == RTE_RING_QUEUE_FIXED, this will be 0 or n only.
  96  */
  97 static __rte_always_inline unsigned int
  98 __rte_ring_do_hts_dequeue_elem(struct rte_ring *r, void *obj_table,
  99         uint32_t esize, uint32_t n, enum rte_ring_queue_behavior behavior,
 100         uint32_t *available)
 101 {
 102         uint32_t entries, head;
 103
 104         n = __rte_ring_hts_move_cons_head(r, n, behavior, &head, &entries);
 105
 106         if (n != 0) {
 107                 __rte_ring_dequeue_elems(r, head, obj_table, esize, n);
 108                 __rte_ring_hts_update_tail(&r->hts_cons, head, n, 0);
 109         }
 110
 111         if (available != NULL)
 112                 *available = entries - n;
 113         return n;
 114 }
 115
 116 /**
 117  * Enqueue several objects on the HTS ring (multi-producers safe).
 118  *
 119  * @param r
 120  *   A pointer to the ring structure.
 121  * @param obj_table
 122  *   A pointer to a table of objects.
 123  * @param esize
 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.
 127  * @param n
 128  *   The number of objects to add in the ring from the obj_table.
 129  * @param free_space
 130  *   if non-NULL, returns the amount of space in the ring after the
 131  *   enqueue operation has finished.
 132  * @return
 133  *   The number of objects enqueued, either 0 or n
 134  */
 135 __rte_experimental
 136 static __rte_always_inline unsigned int
 137 rte_ring_mp_hts_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table,
 138         unsigned int esize, unsigned int n, unsigned int *free_space)
 139 {
 140         return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
 141                         RTE_RING_QUEUE_FIXED, free_space);
 142 }
 143
 144 /**
 145  * Dequeue several objects from an HTS ring (multi-consumers safe).
 146  *
 147  * @param r
 148  *   A pointer to the ring structure.
 149  * @param obj_table
 150  *   A pointer to a table of objects that will be filled.
 151  * @param esize
 152  *   The size of ring element, in bytes. It must be a multiple of 4.
 153  *   This must be the same value used while creating the ring. Otherwise
 154  *   the results are undefined.
 155  * @param n
 156  *   The number of objects to dequeue from the ring to the obj_table.
 157  * @param available
 158  *   If non-NULL, returns the number of remaining ring entries after the
 159  *   dequeue has finished.
 160  * @return
 161  *   The number of objects dequeued, either 0 or n
 162  */
 163 __rte_experimental
 164 static __rte_always_inline unsigned int
 165 rte_ring_mc_hts_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
 166         unsigned int esize, unsigned int n, unsigned int *available)
 167 {
 168         return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
 169                 RTE_RING_QUEUE_FIXED, available);
 170 }
 171
 172 /**
 173  * Enqueue several objects on the HTS ring (multi-producers safe).
 174  *
 175  * @param r
 176  *   A pointer to the ring structure.
 177  * @param obj_table
 178  *   A pointer to a table of objects.
 179  * @param esize
 180  *   The size of ring element, in bytes. It must be a multiple of 4.
 181  *   This must be the same value used while creating the ring. Otherwise
 182  *   the results are undefined.
 183  * @param n
 184  *   The number of objects to add in the ring from the obj_table.
 185  * @param free_space
 186  *   if non-NULL, returns the amount of space in the ring after the
 187  *   enqueue operation has finished.
 188  * @return
 189  *   - n: Actual number of objects enqueued.
 190  */
 191 __rte_experimental
 192 static __rte_always_inline unsigned int
 193 rte_ring_mp_hts_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
 194         unsigned int esize, unsigned int n, unsigned int *free_space)
 195 {
 196         return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
 197                         RTE_RING_QUEUE_VARIABLE, free_space);
 198 }
 199
 200 /**
 201  * Dequeue several objects from an HTS  ring (multi-consumers safe).
 202  * When the requested objects are more than the available objects,
 203  * only dequeue the actual number of objects.
 204  *
 205  * @param r
 206  *   A pointer to the ring structure.
 207  * @param obj_table
 208  *   A pointer to a table of objects that will be filled.
 209  * @param esize
 210  *   The size of ring element, in bytes. It must be a multiple of 4.
 211  *   This must be the same value used while creating the ring. Otherwise
 212  *   the results are undefined.
 213  * @param n
 214  *   The number of objects to dequeue from the ring to the obj_table.
 215  * @param available
 216  *   If non-NULL, returns the number of remaining ring entries after the
 217  *   dequeue has finished.
 218  * @return
 219  *   - n: Actual number of objects dequeued, 0 if ring is empty
 220  */
 221 __rte_experimental
 222 static __rte_always_inline unsigned int
 223 rte_ring_mc_hts_dequeue_burst_elem(struct rte_ring *r, void *obj_table,
 224         unsigned int esize, unsigned int n, unsigned int *available)
 225 {
 226         return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
 227                         RTE_RING_QUEUE_VARIABLE, available);
 228 }
 229
 230 /**
 231  * Enqueue several objects on the HTS ring (multi-producers safe).
 232  *
 233  * @param r
 234  *   A pointer to the ring structure.
 235  * @param obj_table
 236  *   A pointer to a table of void * pointers (objects).
 237  * @param n
 238  *   The number of objects to add in the ring from the obj_table.
 239  * @param free_space
 240  *   if non-NULL, returns the amount of space in the ring after the
 241  *   enqueue operation has finished.
 242  * @return
 243  *   The number of objects enqueued, either 0 or n
 244  */
 245 __rte_experimental
 246 static __rte_always_inline unsigned int
 247 rte_ring_mp_hts_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
 248                          unsigned int n, unsigned int *free_space)
 249 {
 250         return rte_ring_mp_hts_enqueue_bulk_elem(r, obj_table,
 251                         sizeof(uintptr_t), n, free_space);
 252 }
 253
 254 /**
 255  * Dequeue several objects from an HTS ring (multi-consumers safe).
 256  *
 257  * @param r
 258  *   A pointer to the ring structure.
 259  * @param obj_table
 260  *   A pointer to a table of void * pointers (objects) that will be filled.
 261  * @param n
 262  *   The number of objects to dequeue from the ring to the obj_table.
 263  * @param available
 264  *   If non-NULL, returns the number of remaining ring entries after the
 265  *   dequeue has finished.
 266  * @return
 267  *   The number of objects dequeued, either 0 or n
 268  */
 269 __rte_experimental
 270 static __rte_always_inline unsigned int
 271 rte_ring_mc_hts_dequeue_bulk(struct rte_ring *r, void **obj_table,
 272                 unsigned int n, unsigned int *available)
 273 {
 274         return rte_ring_mc_hts_dequeue_bulk_elem(r, obj_table,
 275                         sizeof(uintptr_t), n, available);
 276 }
 277
 278 /**
 279  * Enqueue several objects on the HTS ring (multi-producers safe).
 280  *
 281  * @param r
 282  *   A pointer to the ring structure.
 283  * @param obj_table
 284  *   A pointer to a table of void * pointers (objects).
 285  * @param n
 286  *   The number of objects to add in the ring from the obj_table.
 287  * @param free_space
 288  *   if non-NULL, returns the amount of space in the ring after the
 289  *   enqueue operation has finished.
 290  * @return
 291  *   - n: Actual number of objects enqueued.
 292  */
 293 __rte_experimental
 294 static __rte_always_inline unsigned int
 295 rte_ring_mp_hts_enqueue_burst(struct rte_ring *r, void * const *obj_table,
 296                          unsigned int n, unsigned int *free_space)
 297 {
 298         return rte_ring_mp_hts_enqueue_burst_elem(r, obj_table,
 299                         sizeof(uintptr_t), n, free_space);
 300 }
 301
 302 /**
 303  * Dequeue several objects from an HTS  ring (multi-consumers safe).
 304  * When the requested objects are more than the available objects,
 305  * only dequeue the actual number of objects.
 306  *
 307  * @param r
 308  *   A pointer to the ring structure.
 309  * @param obj_table
 310  *   A pointer to a table of void * pointers (objects) that will be filled.
 311  * @param n
 312  *   The number of objects to dequeue from the ring to the obj_table.
 313  * @param available
 314  *   If non-NULL, returns the number of remaining ring entries after the
 315  *   dequeue has finished.
 316  * @return
 317  *   - n: Actual number of objects dequeued, 0 if ring is empty
 318  */
 319 __rte_experimental
 320 static __rte_always_inline unsigned int
 321 rte_ring_mc_hts_dequeue_burst(struct rte_ring *r, void **obj_table,
 322                 unsigned int n, unsigned int *available)
 323 {
 324         return rte_ring_mc_hts_dequeue_burst_elem(r, obj_table,
 325                         sizeof(uintptr_t), n, available);
 326 }
 327
 328 #ifdef __cplusplus
 329 }
 330 #endif
 331
 332 #endif /* _RTE_RING_HTS_H_ */