1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2014 Intel Corporation 3 */ 4 5 #ifndef _RTE_REORDER_H_ 6 #define _RTE_REORDER_H_ 7 8 /** 9 * @file 10 * RTE reorder 11 * 12 * Reorder library is a component which is designed to 13 * provide ordering of out of ordered packets based on 14 * sequence number present in mbuf. 15 * 16 */ 17 18 #include <rte_compat.h> 19 #include <rte_mbuf.h> 20 #include <rte_mbuf_dyn.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 struct rte_reorder_buffer; 27 28 typedef uint32_t rte_reorder_seqn_t; 29 extern int rte_reorder_seqn_dynfield_offset; 30 31 /** 32 * @warning 33 * @b EXPERIMENTAL: this API may change without prior notice 34 * 35 * Read reorder sequence number from mbuf. 36 * 37 * @param mbuf Structure to read from. 38 * @return pointer to reorder sequence number. 39 */ 40 __rte_experimental 41 static inline rte_reorder_seqn_t * 42 rte_reorder_seqn(struct rte_mbuf *mbuf) 43 { 44 return RTE_MBUF_DYNFIELD(mbuf, rte_reorder_seqn_dynfield_offset, 45 rte_reorder_seqn_t *); 46 } 47 48 /** 49 * Create a new reorder buffer instance 50 * 51 * Allocate memory and initialize a new reorder buffer in that 52 * memory, returning the reorder buffer pointer to the user 53 * 54 * @param name 55 * The name to be given to the reorder buffer instance. 56 * @param socket_id 57 * The NUMA node on which the memory for the reorder buffer 58 * instance is to be reserved. 59 * @param size 60 * Max number of elements that can be stored in the reorder buffer 61 * @return 62 * The initialized reorder buffer instance, or NULL on error 63 * On error case, rte_errno will be set appropriately: 64 * - ENOMEM - no appropriate memory area found in which to create memzone 65 * - EINVAL - invalid parameters 66 */ 67 struct rte_reorder_buffer * 68 rte_reorder_create(const char *name, unsigned socket_id, unsigned int size); 69 70 /** 71 * Initializes given reorder buffer instance 72 * 73 * @param b 74 * Reorder buffer instance to initialize 75 * @param bufsize 76 * Size of the reorder buffer 77 * @param name 78 * The name to be given to the reorder buffer 79 * @param size 80 * Number of elements that can be stored in reorder buffer 81 * @return 82 * The initialized reorder buffer instance, or NULL on error 83 * On error case, rte_errno will be set appropriately: 84 * - EINVAL - invalid parameters 85 */ 86 struct rte_reorder_buffer * 87 rte_reorder_init(struct rte_reorder_buffer *b, unsigned int bufsize, 88 const char *name, unsigned int size); 89 90 /** 91 * Find an existing reorder buffer instance 92 * and return a pointer to it. 93 * 94 * @param name 95 * Name of the reorder buffer instance as passed to rte_reorder_create() 96 * @return 97 * Pointer to reorder buffer instance or NULL if object not found with rte_errno 98 * set appropriately. Possible rte_errno values include: 99 * - ENOENT - required entry not available to return. 100 * reorder instance list 101 */ 102 struct rte_reorder_buffer * 103 rte_reorder_find_existing(const char *name); 104 105 /** 106 * Reset the given reorder buffer instance with initial values. 107 * 108 * @param b 109 * Reorder buffer instance which has to be reset 110 */ 111 void 112 rte_reorder_reset(struct rte_reorder_buffer *b); 113 114 /** 115 * Free reorder buffer instance. 116 * 117 * @param b 118 * Pointer to reorder buffer instance. 119 * If b is NULL, no operation is performed. 120 */ 121 void 122 rte_reorder_free(struct rte_reorder_buffer *b); 123 124 /** 125 * Insert given mbuf in reorder buffer in its correct position 126 * 127 * The given mbuf is to be reordered relative to other mbufs in the system. 128 * The mbuf must contain a sequence number which is then used to place 129 * the buffer in the correct position in the reorder buffer. Reordered 130 * packets can later be taken from the buffer using the rte_reorder_drain() 131 * API. 132 * 133 * @param b 134 * Reorder buffer where the mbuf has to be inserted. 135 * @param mbuf 136 * mbuf of packet that needs to be inserted in reorder buffer. 137 * @return 138 * 0 on success 139 * -1 on error 140 * On error case, rte_errno will be set appropriately: 141 * - ENOSPC - Cannot move existing mbufs from reorder buffer to accommodate 142 * early mbuf, but it can be accommodated by performing drain and then insert. 143 * - ERANGE - Too early or late mbuf which is vastly out of range of expected 144 * window should be ignored without any handling. 145 */ 146 int 147 rte_reorder_insert(struct rte_reorder_buffer *b, struct rte_mbuf *mbuf); 148 149 /** 150 * Fetch reordered buffers 151 * 152 * Returns a set of in-order buffers from the reorder buffer structure. Gaps 153 * may be present in the sequence numbers of the mbuf if packets have been 154 * delayed too long before reaching the reorder window, or have been previously 155 * dropped by the system. 156 * 157 * @param b 158 * Reorder buffer instance from which packets are to be drained 159 * @param mbufs 160 * array of mbufs where reordered packets will be inserted from reorder buffer 161 * @param max_mbufs 162 * the number of elements in the mbufs array. 163 * @return 164 * number of mbuf pointers written to mbufs. 0 <= N < max_mbufs. 165 */ 166 unsigned int 167 rte_reorder_drain(struct rte_reorder_buffer *b, struct rte_mbuf **mbufs, 168 unsigned max_mbufs); 169 170 /** 171 * @warning 172 * @b EXPERIMENTAL: this API may change without prior notice 173 * 174 * Fetch set of reordered packets up to specified sequence number (exclusive). 175 * 176 * Returns a set of in-order packets from the reorder buffer structure. 177 * Gaps may be present since reorder buffer will try to fetch 178 * all possible packets up to given sequence number. 179 * 180 * @param b 181 * Reorder buffer instance from which packets are to be drained. 182 * @param mbufs 183 * Array of mbufs where reordered packets will be inserted from reorder buffer. 184 * @param max_mbufs 185 * The number of elements in the mbuf array. 186 * @param seqn 187 * Sequence number up to which buffer will be drained. 188 * @return 189 * Number of mbuf pointers written to mbufs. 0 <= N < max_mbufs. 190 */ 191 __rte_experimental 192 unsigned int 193 rte_reorder_drain_up_to_seqn(struct rte_reorder_buffer *b, struct rte_mbuf **mbufs, 194 unsigned int max_mbufs, rte_reorder_seqn_t seqn); 195 196 /** 197 * @warning 198 * @b EXPERIMENTAL: this API may change without prior notice 199 * 200 * Set minimum sequence number of packet allowed to be buffered. 201 * To successfully set new value, 202 * reorder buffer has to be empty (after create, reset or drain_all). 203 * 204 * @param b 205 * Empty reorder buffer instance to modify. 206 * @param min_seqn 207 * New sequence number to set. 208 * @return 209 * 0 on success, a negative value otherwise. 210 */ 211 __rte_experimental 212 unsigned int 213 rte_reorder_min_seqn_set(struct rte_reorder_buffer *b, rte_reorder_seqn_t min_seqn); 214 215 #ifdef __cplusplus 216 } 217 #endif 218 219 #endif /* _RTE_REORDER_H_ */ 220