1 /* SPDX-License-Identifier: BSD-3-Clause
3 * Copyright (c) 2010-2020 Intel Corporation
4 * Copyright (c) 2007-2009 Kip Macy kmacy@freebsd.org
6 * Derived from FreeBSD's bufring.h
7 * Used as BSD-3 Licensed with permission from Kip Macy.
10 #ifndef _RTE_RING_CORE_H_
11 #define _RTE_RING_CORE_H_
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>
29 #include <sys/queue.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>
41 #define RTE_TAILQ_RING_NAME "RTE_RING"
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
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)
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 */
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.
71 struct rte_ring_headtail {
72 volatile uint32_t head; /**< prod/consumer head. */
73 volatile uint32_t tail; /**< prod/consumer tail. */
76 /** sync type of prod/cons */
77 enum rte_ring_sync_type sync_type;
78 /** deprecated - True if single prod/cons */
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);
87 uint32_t cnt; /**< head/tail reference counter */
88 uint32_t pos; /**< head/tail position */
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;
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);
103 uint32_t head; /**< head position */
104 uint32_t tail; /**< tail position */
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 */
114 * An RTE ring structure.
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
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
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 */
138 char pad0 __rte_cache_aligned; /**< empty cache line */
140 /** Ring producer status. */
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;
148 char pad1 __rte_cache_aligned; /**< empty cache line */
150 /** Ring consumer status. */
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;
158 char pad2 __rte_cache_aligned; /**< empty cache line */
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". */
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.
171 #define RING_F_EXACT_SZ 0x0004
172 #define RTE_RING_SZ_MASK (0x7fffffffU) /**< Ring size mask */
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". */
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". */
184 #endif /* _RTE_RING_CORE_H_ */