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 #include <rte_compat.h>
18 #include <rte_mbuf.h>
19 #include <rte_mbuf_dyn.h>
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 struct rte_reorder_buffer;
26
27 typedef uint32_t rte_reorder_seqn_t;
28 extern int rte_reorder_seqn_dynfield_offset;
29
30 /**
31 * @warning
32 * @b EXPERIMENTAL: this API may change without prior notice
33 *
34 * Read reorder sequence number from mbuf.
35 *
36 * @param mbuf Structure to read from.
37 * @return pointer to reorder sequence number.
38 */
39 __rte_experimental
40 static inline rte_reorder_seqn_t *
rte_reorder_seqn(struct rte_mbuf * mbuf)41 rte_reorder_seqn(struct rte_mbuf *mbuf)
42 {
43 return RTE_MBUF_DYNFIELD(mbuf, rte_reorder_seqn_dynfield_offset,
44 rte_reorder_seqn_t *);
45 }
46
47 /**
48 * Create a new reorder buffer instance
49 *
50 * Allocate memory and initialize a new reorder buffer in that
51 * memory, returning the reorder buffer pointer to the user
52 *
53 * @param name
54 * The name to be given to the reorder buffer instance.
55 * @param socket_id
56 * The NUMA node on which the memory for the reorder buffer
57 * instance is to be reserved.
58 * @param size
59 * Max number of elements that can be stored in the reorder buffer
60 * @return
61 * The initialized reorder buffer instance, or NULL on error
62 * On error case, rte_errno will be set appropriately:
63 * - ENOMEM - no appropriate memory area found in which to create memzone
64 * - EINVAL - invalid parameters
65 */
66 struct rte_reorder_buffer *
67 rte_reorder_create(const char *name, unsigned socket_id, unsigned int size);
68
69 /**
70 * Initializes given reorder buffer instance
71 *
72 * @param b
73 * Reorder buffer instance to initialize
74 * @param bufsize
75 * Size of the reorder buffer
76 * @param name
77 * The name to be given to the reorder buffer
78 * @param size
79 * Number of elements that can be stored in reorder buffer
80 * @return
81 * The initialized reorder buffer instance, or NULL on error
82 * On error case, rte_errno will be set appropriately:
83 * - EINVAL - invalid parameters
84 * - ENOMEM - not enough memory to register dynamic field
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 /**
216 * @warning
217 * @b EXPERIMENTAL: this API may change without prior notice
218 *
219 * Determine the amount of memory needed by the reorder buffer
220 * to accommodate a given number of elements.
221 * @see rte_reorder_init()
222 *
223 * @param size
224 * Number of elements that can be stored in reorder buffer.
225 * @return
226 * Reorder buffer footprint measured in bytes.
227 */
228 __rte_experimental
229 unsigned int
230 rte_reorder_memory_footprint_get(unsigned int size);
231
232 #ifdef __cplusplus
233 }
234 #endif
235
236 #endif /* _RTE_REORDER_H_ */
237