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_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 */
85 struct rte_reorder_buffer *
86 rte_reorder_init(struct rte_reorder_buffer *b, unsigned int bufsize,
87 const char *name, unsigned int size);
88
89 /**
90 * Find an existing reorder buffer instance
91 * and return a pointer to it.
92 *
93 * @param name
94 * Name of the reorder buffer instance as passed to rte_reorder_create()
95 * @return
96 * Pointer to reorder buffer instance or NULL if object not found with rte_errno
97 * set appropriately. Possible rte_errno values include:
98 * - ENOENT - required entry not available to return.
99 * reorder instance list
100 */
101 struct rte_reorder_buffer *
102 rte_reorder_find_existing(const char *name);
103
104 /**
105 * Reset the given reorder buffer instance with initial values.
106 *
107 * @param b
108 * Reorder buffer instance which has to be reset
109 */
110 void
111 rte_reorder_reset(struct rte_reorder_buffer *b);
112
113 /**
114 * Free reorder buffer instance.
115 *
116 * @param b
117 * reorder buffer instance
118 * @return
119 * None
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 #ifdef __cplusplus
171 }
172 #endif
173
174 #endif /* _RTE_REORDER_H_ */
175