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 * 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