lib/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_elem_pvt.h>
  33
  34 /**
  35  * Enqueue several objects on the HTS ring (multi-producers safe).
  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 free_space
  48  *   if non-NULL, returns the amount of space in the ring after the
  49  *   enqueue operation has finished.
  50  * @return
  51  *   The number of objects enqueued, either 0 or n
  52  */
  53 __rte_experimental
  54 static __rte_always_inline unsigned int
  55 rte_ring_mp_hts_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table,
  56         unsigned int esize, unsigned int n, unsigned int *free_space)
  57 {
  58         return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
  59                         RTE_RING_QUEUE_FIXED, free_space);
  60 }
  61
  62 /**
  63  * Dequeue several objects from an HTS ring (multi-consumers safe).
  64  *
  65  * @param r
  66  *   A pointer to the ring structure.
  67  * @param obj_table
  68  *   A pointer to a table of objects that will be filled.
  69  * @param esize
  70  *   The size of ring element, in bytes. It must be a multiple of 4.
  71  *   This must be the same value used while creating the ring. Otherwise
  72  *   the results are undefined.
  73  * @param n
  74  *   The number of objects to dequeue from the ring to the obj_table.
  75  * @param available
  76  *   If non-NULL, returns the number of remaining ring entries after the
  77  *   dequeue has finished.
  78  * @return
  79  *   The number of objects dequeued, either 0 or n
  80  */
  81 __rte_experimental
  82 static __rte_always_inline unsigned int
  83 rte_ring_mc_hts_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
  84         unsigned int esize, unsigned int n, unsigned int *available)
  85 {
  86         return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
  87                 RTE_RING_QUEUE_FIXED, available);
  88 }
  89
  90 /**
  91  * Enqueue several objects on the HTS ring (multi-producers safe).
  92  *
  93  * @param r
  94  *   A pointer to the ring structure.
  95  * @param obj_table
  96  *   A pointer to a table of objects.
  97  * @param esize
  98  *   The size of ring element, in bytes. It must be a multiple of 4.
  99  *   This must be the same value used while creating the ring. Otherwise
 100  *   the results are undefined.
 101  * @param n
 102  *   The number of objects to add in the ring from the obj_table.
 103  * @param free_space
 104  *   if non-NULL, returns the amount of space in the ring after the
 105  *   enqueue operation has finished.
 106  * @return
 107  *   - n: Actual number of objects enqueued.
 108  */
 109 __rte_experimental
 110 static __rte_always_inline unsigned int
 111 rte_ring_mp_hts_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
 112         unsigned int esize, unsigned int n, unsigned int *free_space)
 113 {
 114         return __rte_ring_do_hts_enqueue_elem(r, obj_table, esize, n,
 115                         RTE_RING_QUEUE_VARIABLE, free_space);
 116 }
 117
 118 /**
 119  * Dequeue several objects from an HTS  ring (multi-consumers safe).
 120  * When the requested objects are more than the available objects,
 121  * only dequeue the actual number of objects.
 122  *
 123  * @param r
 124  *   A pointer to the ring structure.
 125  * @param obj_table
 126  *   A pointer to a table of objects that will be filled.
 127  * @param esize
 128  *   The size of ring element, in bytes. It must be a multiple of 4.
 129  *   This must be the same value used while creating the ring. Otherwise
 130  *   the results are undefined.
 131  * @param n
 132  *   The number of objects to dequeue from the ring to the obj_table.
 133  * @param available
 134  *   If non-NULL, returns the number of remaining ring entries after the
 135  *   dequeue has finished.
 136  * @return
 137  *   - n: Actual number of objects dequeued, 0 if ring is empty
 138  */
 139 __rte_experimental
 140 static __rte_always_inline unsigned int
 141 rte_ring_mc_hts_dequeue_burst_elem(struct rte_ring *r, void *obj_table,
 142         unsigned int esize, unsigned int n, unsigned int *available)
 143 {
 144         return __rte_ring_do_hts_dequeue_elem(r, obj_table, esize, n,
 145                         RTE_RING_QUEUE_VARIABLE, available);
 146 }
 147
 148 /**
 149  * Enqueue several objects on the HTS ring (multi-producers safe).
 150  *
 151  * @param r
 152  *   A pointer to the ring structure.
 153  * @param obj_table
 154  *   A pointer to a table of void * pointers (objects).
 155  * @param n
 156  *   The number of objects to add in the ring from the obj_table.
 157  * @param free_space
 158  *   if non-NULL, returns the amount of space in the ring after the
 159  *   enqueue operation has finished.
 160  * @return
 161  *   The number of objects enqueued, either 0 or n
 162  */
 163 __rte_experimental
 164 static __rte_always_inline unsigned int
 165 rte_ring_mp_hts_enqueue_bulk(struct rte_ring *r, void * const *obj_table,
 166                          unsigned int n, unsigned int *free_space)
 167 {
 168         return rte_ring_mp_hts_enqueue_bulk_elem(r, obj_table,
 169                         sizeof(uintptr_t), n, free_space);
 170 }
 171
 172 /**
 173  * Dequeue several objects from an HTS ring (multi-consumers safe).
 174  *
 175  * @param r
 176  *   A pointer to the ring structure.
 177  * @param obj_table
 178  *   A pointer to a table of void * pointers (objects) that will be filled.
 179  * @param n
 180  *   The number of objects to dequeue from the ring to the obj_table.
 181  * @param available
 182  *   If non-NULL, returns the number of remaining ring entries after the
 183  *   dequeue has finished.
 184  * @return
 185  *   The number of objects dequeued, either 0 or n
 186  */
 187 __rte_experimental
 188 static __rte_always_inline unsigned int
 189 rte_ring_mc_hts_dequeue_bulk(struct rte_ring *r, void **obj_table,
 190                 unsigned int n, unsigned int *available)
 191 {
 192         return rte_ring_mc_hts_dequeue_bulk_elem(r, obj_table,
 193                         sizeof(uintptr_t), n, available);
 194 }
 195
 196 /**
 197  * Enqueue several objects on the HTS ring (multi-producers safe).
 198  *
 199  * @param r
 200  *   A pointer to the ring structure.
 201  * @param obj_table
 202  *   A pointer to a table of void * pointers (objects).
 203  * @param n
 204  *   The number of objects to add in the ring from the obj_table.
 205  * @param free_space
 206  *   if non-NULL, returns the amount of space in the ring after the
 207  *   enqueue operation has finished.
 208  * @return
 209  *   - n: Actual number of objects enqueued.
 210  */
 211 __rte_experimental
 212 static __rte_always_inline unsigned int
 213 rte_ring_mp_hts_enqueue_burst(struct rte_ring *r, void * const *obj_table,
 214                          unsigned int n, unsigned int *free_space)
 215 {
 216         return rte_ring_mp_hts_enqueue_burst_elem(r, obj_table,
 217                         sizeof(uintptr_t), n, free_space);
 218 }
 219
 220 /**
 221  * Dequeue several objects from an HTS  ring (multi-consumers safe).
 222  * When the requested objects are more than the available objects,
 223  * only dequeue the actual number of objects.
 224  *
 225  * @param r
 226  *   A pointer to the ring structure.
 227  * @param obj_table
 228  *   A pointer to a table of void * pointers (objects) that will be filled.
 229  * @param n
 230  *   The number of objects to dequeue from the ring to the obj_table.
 231  * @param available
 232  *   If non-NULL, returns the number of remaining ring entries after the
 233  *   dequeue has finished.
 234  * @return
 235  *   - n: Actual number of objects dequeued, 0 if ring is empty
 236  */
 237 __rte_experimental
 238 static __rte_always_inline unsigned int
 239 rte_ring_mc_hts_dequeue_burst(struct rte_ring *r, void **obj_table,
 240                 unsigned int n, unsigned int *available)
 241 {
 242         return rte_ring_mc_hts_dequeue_burst_elem(r, obj_table,
 243                         sizeof(uintptr_t), n, available);
 244 }
 245
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249
 250 #endif /* _RTE_RING_HTS_H_ */