1 /* SPDX-License-Identifier: BSD-3-Clause 2 * 3 * Copyright (c) 2010-2020 Intel Corporation 4 * Copyright (c) 2007-2009 Kip Macy [email protected] 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_ */ 185