lib/librte_ring/rte_ring_core.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_CORE_H_
  11 #define _RTE_RING_CORE_H_
  12
  13 /**
  14  * @file
  15  * This file contains definion of RTE ring structure itself,
  16  * init flags and some related macros.
  17  * For majority of DPDK entities, it is not recommended to include
  18  * this file directly, use include <rte_ring.h> or <rte_ring_elem.h>
  19  * instead.
  20  */
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #include <stdio.h>
  27 #include <stdint.h>
  28 #include <string.h>
  29 #include <sys/queue.h>
  30 #include <errno.h>
  31 #include <rte_common.h>
  32 #include <rte_config.h>
  33 #include <rte_memory.h>
  34 #include <rte_lcore.h>
  35 #include <rte_atomic.h>
  36 #include <rte_branch_prediction.h>
  37 #include <rte_memzone.h>
  38 #include <rte_pause.h>
  39 #include <rte_debug.h>
  40
  41 #define RTE_TAILQ_RING_NAME "RTE_RING"
  42
  43 /** enqueue/dequeue behavior types */
  44 enum rte_ring_queue_behavior {
  45         /** Enq/Deq a fixed number of items from a ring */
  46         RTE_RING_QUEUE_FIXED = 0,
  47         /** Enq/Deq as many items as possible from ring */
  48         RTE_RING_QUEUE_VARIABLE
  49 };
  50
  51 #define RTE_RING_MZ_PREFIX "RG_"
  52 /** The maximum length of a ring name. */
  53 #define RTE_RING_NAMESIZE (RTE_MEMZONE_NAMESIZE - \
  54                            sizeof(RTE_RING_MZ_PREFIX) + 1)
  55
  56 /** prod/cons sync types */
  57 enum rte_ring_sync_type {
  58         RTE_RING_SYNC_MT,     /**< multi-thread safe (default mode) */
  59         RTE_RING_SYNC_ST,     /**< single thread only */
  60 #ifdef ALLOW_EXPERIMENTAL_API
  61         RTE_RING_SYNC_MT_RTS, /**< multi-thread relaxed tail sync */
  62         RTE_RING_SYNC_MT_HTS, /**< multi-thread head/tail sync */
  63 #endif
  64 };
  65
  66 /**
  67  * structures to hold a pair of head/tail values and other metadata.
  68  * Depending on sync_type format of that structure might be different,
  69  * but offset for *sync_type* and *tail* values should remain the same.
  70  */
  71 struct rte_ring_headtail {
  72         volatile uint32_t head;      /**< prod/consumer head. */
  73         volatile uint32_t tail;      /**< prod/consumer tail. */
  74         RTE_STD_C11
  75         union {
  76                 /** sync type of prod/cons */
  77                 enum rte_ring_sync_type sync_type;
  78                 /** deprecated -  True if single prod/cons */
  79                 uint32_t single;
  80         };
  81 };
  82
  83 union __rte_ring_rts_poscnt {
  84         /** raw 8B value to read/write *cnt* and *pos* as one atomic op */
  85         uint64_t raw __rte_aligned(8);
  86         struct {
  87                 uint32_t cnt; /**< head/tail reference counter */
  88                 uint32_t pos; /**< head/tail position */
  89         } val;
  90 };
  91
  92 struct rte_ring_rts_headtail {
  93         volatile union __rte_ring_rts_poscnt tail;
  94         enum rte_ring_sync_type sync_type;  /**< sync type of prod/cons */
  95         uint32_t htd_max;   /**< max allowed distance between head/tail */
  96         volatile union __rte_ring_rts_poscnt head;
  97 };
  98
  99 union __rte_ring_hts_pos {
 100         /** raw 8B value to read/write *head* and *tail* as one atomic op */
 101         uint64_t raw __rte_aligned(8);
 102         struct {
 103                 uint32_t head; /**< head position */
 104                 uint32_t tail; /**< tail position */
 105         } pos;
 106 };
 107
 108 struct rte_ring_hts_headtail {
 109         volatile union __rte_ring_hts_pos ht;
 110         enum rte_ring_sync_type sync_type;  /**< sync type of prod/cons */
 111 };
 112
 113 /**
 114  * An RTE ring structure.
 115  *
 116  * The producer and the consumer have a head and a tail index. The particularity
 117  * of these index is that they are not between 0 and size(ring). These indexes
 118  * are between 0 and 2^32, and we mask their value when we access the ring[]
 119  * field. Thanks to this assumption, we can do subtractions between 2 index
 120  * values in a modulo-32bit base: that's why the overflow of the indexes is not
 121  * a problem.
 122  */
 123 struct rte_ring {
 124         /*
 125          * Note: this field kept the RTE_MEMZONE_NAMESIZE size due to ABI
 126          * compatibility requirements, it could be changed to RTE_RING_NAMESIZE
 127          * next time the ABI changes
 128          */
 129         char name[RTE_MEMZONE_NAMESIZE] __rte_cache_aligned;
 130         /**< Name of the ring. */
 131         int flags;               /**< Flags supplied at creation. */
 132         const struct rte_memzone *memzone;
 133                         /**< Memzone, if any, containing the rte_ring */
 134         uint32_t size;           /**< Size of ring. */
 135         uint32_t mask;           /**< Mask (size-1) of ring. */
 136         uint32_t capacity;       /**< Usable size of ring */
 137
 138         char pad0 __rte_cache_aligned; /**< empty cache line */
 139
 140         /** Ring producer status. */
 141         RTE_STD_C11
 142         union {
 143                 struct rte_ring_headtail prod;
 144                 struct rte_ring_hts_headtail hts_prod;
 145                 struct rte_ring_rts_headtail rts_prod;
 146         }  __rte_cache_aligned;
 147
 148         char pad1 __rte_cache_aligned; /**< empty cache line */
 149
 150         /** Ring consumer status. */
 151         RTE_STD_C11
 152         union {
 153                 struct rte_ring_headtail cons;
 154                 struct rte_ring_hts_headtail hts_cons;
 155                 struct rte_ring_rts_headtail rts_cons;
 156         }  __rte_cache_aligned;
 157
 158         char pad2 __rte_cache_aligned; /**< empty cache line */
 159 };
 160
 161 #define RING_F_SP_ENQ 0x0001 /**< The default enqueue is "single-producer". */
 162 #define RING_F_SC_DEQ 0x0002 /**< The default dequeue is "single-consumer". */
 163 /**
 164  * Ring is to hold exactly requested number of entries.
 165  * Without this flag set, the ring size requested must be a power of 2, and the
 166  * usable space will be that size - 1. With the flag, the requested size will
 167  * be rounded up to the next power of two, but the usable space will be exactly
 168  * that requested. Worst case, if a power-of-2 size is requested, half the
 169  * ring space will be wasted.
 170  */
 171 #define RING_F_EXACT_SZ 0x0004
 172 #define RTE_RING_SZ_MASK  (0x7fffffffU) /**< Ring size mask */
 173
 174 #define RING_F_MP_RTS_ENQ 0x0008 /**< The default enqueue is "MP RTS". */
 175 #define RING_F_MC_RTS_DEQ 0x0010 /**< The default dequeue is "MC RTS". */
 176
 177 #define RING_F_MP_HTS_ENQ 0x0020 /**< The default enqueue is "MP HTS". */
 178 #define RING_F_MC_HTS_DEQ 0x0040 /**< The default dequeue is "MC HTS". */
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 #endif /* _RTE_RING_CORE_H_ */