summaryrefslogtreecommitdiffstats
path: root/lib/librte_gro/rte_gro.h
blob: 8d781b5f4b30f82fcc87c50874e9b5435ecd31f0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
/* SPDX-License-Identifier: BSD-3-Clause
 * Copyright(c) 2017 Intel Corporation
 */

#ifndef _RTE_GRO_H_
#define _RTE_GRO_H_

/**
 * @file
 * Interface to GRO library
 */

#include <stdint.h>
#include <rte_mbuf.h>

#ifdef __cplusplus
extern "C" {
#endif

#define RTE_GRO_MAX_BURST_ITEM_NUM 128U
/**< the max number of packets that rte_gro_reassemble_burst()
 * can process in each invocation.
 */
#define RTE_GRO_TYPE_MAX_NUM 64
/**< the max number of supported GRO types */
#define RTE_GRO_TYPE_SUPPORT_NUM 2
/**< the number of currently supported GRO types */

#define RTE_GRO_TCP_IPV4_INDEX 0
#define RTE_GRO_TCP_IPV4 (1ULL << RTE_GRO_TCP_IPV4_INDEX)
/**< TCP/IPv4 GRO flag */
#define RTE_GRO_IPV4_VXLAN_TCP_IPV4_INDEX 1
#define RTE_GRO_IPV4_VXLAN_TCP_IPV4 (1ULL << RTE_GRO_IPV4_VXLAN_TCP_IPV4_INDEX)
/**< VxLAN GRO flag. */

/**
 * Structure used to create GRO context objects or used to pass
 * application-determined parameters to rte_gro_reassemble_burst().
 */
struct rte_gro_param {
	uint64_t gro_types;
	/**< desired GRO types */
	uint16_t max_flow_num;
	/**< max flow number */
	uint16_t max_item_per_flow;
	/**< max packet number per flow */
	uint16_t socket_id;
	/**< socket index for allocating GRO related data structures,
	 * like reassembly tables. When use rte_gro_reassemble_burst(),
	 * applications don't need to set this value.
	 */
};

/**
 * @warning
 * @b EXPERIMENTAL: this API may change without prior notice
 *
 * This function create a GRO context object, which is used to merge
 * packets in rte_gro_reassemble().
 *
 * @param param
 *  applications use it to pass needed parameters to create a GRO
 *  context object.
 *
 * @return
 *  if create successfully, return a pointer which points to the GRO
 *  context object. Otherwise, return NULL.
 */
void *rte_gro_ctx_create(const struct rte_gro_param *param);

/**
 * @warning
 * @b EXPERIMENTAL: this API may change without prior notice
 *
 * This function destroys a GRO context object.
 *
 * @param ctx
 *  pointer points to a GRO context object.
 */
void rte_gro_ctx_destroy(void *ctx);

/**
 * This is one of the main reassembly APIs, which merges numbers of
 * packets at a time. It doesn't check if input packets have correct
 * checksums and doesn't re-calculate checksums for merged packets.
 * It assumes the packets are complete (i.e., MF==0 && frag_off==0),
 * when IP fragmentation is possible (i.e., DF==0). The GROed packets
 * are returned as soon as the function finishes.
 *
 * @param pkts
 *  Pointer array pointing to the packets to reassemble. Besides, it
 *  keeps MBUF addresses for the GROed packets.
 * @param nb_pkts
 *  The number of packets to reassemble
 * @param param
 *  Application-determined parameters for reassembling packets.
 *
 * @return
 *  The number of packets after been GROed. If no packets are merged,
 *  the return value is equals to nb_pkts.
 */
uint16_t rte_gro_reassemble_burst(struct rte_mbuf **pkts,
		uint16_t nb_pkts,
		const struct rte_gro_param *param);

/**
 * @warning
 * @b EXPERIMENTAL: this API may change without prior notice
 *
 * Reassembly function, which tries to merge input packets with the
 * existed packets in the reassembly tables of a given GRO context.
 * It doesn't check if input packets have correct checksums and doesn't
 * re-calculate checksums for merged packets. Additionally, it assumes
 * the packets are complete (i.e., MF==0 && frag_off==0), when IP
 * fragmentation is possible (i.e., DF==0).
 *
 * If the input packets have invalid parameters (e.g. no data payload,
 * unsupported GRO types), they are returned to applications. Otherwise,
 * they are either merged or inserted into the table. Applications need
 * to flush packets from the tables by flush API, if they want to get the
 * GROed packets.
 *
 * @param pkts
 *  Packets to reassemble. It's also used to store the unprocessed packets.
 * @param nb_pkts
 *  The number of packets to reassemble
 * @param ctx
 *  GRO context object pointer
 *
 * @return
 *  The number of unprocessed packets.
 */
uint16_t rte_gro_reassemble(struct rte_mbuf **pkts,
		uint16_t nb_pkts,
		void *ctx);

/**
 * @warning
 * @b EXPERIMENTAL: this API may change without prior notice
 *
 * This function flushes the timeout packets from the reassembly tables
 * of desired GRO types. The max number of flushed packets is the
 * element number of 'out'.
 *
 * Additionally, the flushed packets may have incorrect checksums, since
 * this function doesn't re-calculate checksums for merged packets.
 *
 * @param ctx
 *  GRO context object pointer.
 * @param timeout_cycles
 *  The max TTL for packets in reassembly tables, measured in nanosecond.
 * @param gro_types
 *  This function flushes packets whose GRO types are specified by
 *  gro_types.
 * @param out
 *  Pointer array used to keep flushed packets.
 * @param max_nb_out
 *  The element number of 'out'. It's also the max number of timeout
 *  packets that can be flushed finally.
 *
 * @return
 *  The number of flushed packets.
 */
uint16_t rte_gro_timeout_flush(void *ctx,
		uint64_t timeout_cycles,
		uint64_t gro_types,
		struct rte_mbuf **out,
		uint16_t max_nb_out);

/**
 * @warning
 * @b EXPERIMENTAL: this API may change without prior notice
 *
 * This function returns the number of packets in all reassembly tables
 * of a given GRO context.
 *
 * @param ctx
 *  GRO context object pointer.
 *
 * @return
 *  The number of packets in the tables.
 */
uint64_t rte_gro_get_pkt_count(void *ctx);

#ifdef __cplusplus
}
#endif

#endif /* _RTE_GRO_H_ */