1/*
2 * Copyright (c) 2016-2017  Intel Corporation.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef _TLE_CTX_H_
17#define _TLE_CTX_H_
18
19#include <stdint.h>
20#include <sys/socket.h>
21#include <netinet/in.h>
22#include <rte_common.h>
23#include <rte_mbuf.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 * <tle_ctx>  - each such ctx represents an 'independent copy of the stack'.
31 * It owns set of <stream>s and <dev>s entities and provides
32 * (de)multiplexing input/output packets from/into devices into/from streams.
33 * <dev> is an abstraction for the underlying device, that is able
34 * to RX/TX packets and may provide some HW offload capabilities.
35 * It is a user responsibility to add to the <ctx> all <dev>s,
36 * that context has to manage, before starting to do stream operations
37 * (open/send/recv,close) over that context.
38 * Right now adding/deleting <dev>s to the context with open
39 * streams is not supported.
40 * <stream> represents an L4(UDP/TCP, etc.) endpoint <addr, port> and
41 * is an analogy to socket entity.
42 * As with a socket, there are ability to do recv/send over it.
43 * <stream> belongs to particular <ctx> but is visible globally across
44 * the process, i.e. any thread within the process can do recv/send over it
45 * without any further synchronisation.
46 * While 'upper' layer API is thread safe, lower layer API (rx_bulk/tx_bulk)
47 * is not thread safe and is not supposed to be run on multiple threads
48 * in parallel.
49 * So single thread can drive multiple <ctx>s and do IO for them,
50 * but multiple threads can't drive same <ctx> without some
51 * explicit synchronization.
52 */
53
54struct tle_ctx;
55struct tle_dev;
56
57/**
58 * Blocked L4 ports info.
59 */
60struct tle_bl_port {
61	uint32_t nb_port;     /**< number of blocked ports. */
62	const uint16_t *port; /**< list of blocked ports. */
63};
64
65
66/**
67 * device parameters.
68 */
69struct tle_dev_param {
70	uint64_t rx_offload; /**< DEV_RX_OFFLOAD_* supported. */
71	uint64_t tx_offload; /**< DEV_TX_OFFLOAD_* supported. */
72	struct in_addr local_addr4;  /**< local IPv4 address assigned. */
73	struct in6_addr local_addr6; /**< local IPv6 address assigned. */
74	struct tle_bl_port bl4; /**< blocked ports for IPv4 address. */
75	struct tle_bl_port bl6; /**< blocked ports for IPv4 address. */
76};
77
78#define TLE_DST_MAX_HDR	0x60
79
80struct tle_dest {
81	struct rte_mempool *head_mp;
82	/**< MP for fragment headers and control packets. */
83	struct tle_dev *dev;    /**< device to send packets through. */
84	uint64_t ol_flags;      /**< tx ofload flags. */
85	uint16_t mtu;           /**< MTU for given destination. */
86	uint8_t l2_len;  /**< L2 header length. */
87	uint8_t l3_len;  /**< L3 header length. */
88	uint8_t hdr[TLE_DST_MAX_HDR]; /**< L2/L3 headers. */
89};
90
91/**
92 * context creation parameters.
93 */
94
95enum {
96	TLE_PROTO_UDP,
97	TLE_PROTO_TCP,
98	TLE_PROTO_NUM
99};
100
101enum {
102	TLE_JHASH,
103	TLE_SIPHASH,
104	TLE_HASH_NUM
105};
106
107enum {
108	TLE_CTX_FLAG_ST = 1,  /**< ctx will be used by single thread */
109};
110
111struct tle_ctx_param {
112	int32_t socket_id;         /**< socket ID to allocate memory for. */
113	uint32_t proto;            /**< L4 proto to handle. */
114	uint32_t max_streams;      /**< max number of streams in context. */
115	struct {
116		uint32_t min;
117		/**< min number of free streams (grow threshold). */
118		uint32_t max;
119		/**< max number of free streams (shrink threshold). */
120	} free_streams;
121	uint32_t max_stream_rbufs; /**< max recv mbufs per stream. */
122	uint32_t max_stream_sbufs; /**< max send mbufs per stream. */
123	uint32_t send_bulk_size;   /**< expected # of packets per send call. */
124	uint32_t flags;            /**< specific flags */
125
126	int (*lookup4)(void *opaque, const struct in_addr *addr,
127		struct tle_dest *res);
128	/**< will be called by send() to get IPv4 packet destination info. */
129	void *lookup4_data;
130	/**< opaque data pointer for lookup4() callback. */
131
132	int (*lookup6)(void *opaque, const struct in6_addr *addr,
133		struct tle_dest *res);
134	/**< will be called by send() to get IPv6 packet destination info. */
135	void *lookup6_data;
136	/**< opaque data pointer for lookup6() callback. */
137
138	uint32_t hash_alg;
139	/**< hash algorithm to be used to generate sequence number. */
140	rte_xmm_t secret_key;
141	/**< secret key to be used to calculate the hash. */
142
143	uint32_t icw; /**< initial congestion window, default is 2*MSS if 0. */
144	uint32_t timewait;
145	/**< TCP TIME_WAIT state timeout duration in milliseconds,
146	 * default 2MSL, if UINT32_MAX */
147};
148
149/**
150 * use default TIMEWAIT timeout value.
151 */
152#define	TLE_TCP_TIMEWAIT_DEFAULT	UINT32_MAX
153
154/**
155 * create L4 processing context.
156 * @param ctx_prm
157 *   Parameters used to create and initialise the L4 context.
158 * @return
159 *   Pointer to context structure that can be used in future operations,
160 *   or NULL on error, with error code set in rte_errno.
161 *
162 *   Possible rte_errno errors include:
163 *   - EINVAL - invalid parameter passed to function
164 *   - ENOMEM - out of memory
165 */
166struct tle_ctx *
167tle_ctx_create(const struct tle_ctx_param *ctx_prm);
168
169/**
170 * Destroy given context.
171 *
172 * @param ctx
173 *   context to destroy
174 */
175void tle_ctx_destroy(struct tle_ctx *ctx);
176
177/**
178 * Add new device into the given context.
179 * This function is not multi-thread safe.
180 *
181 * @param ctx
182 *   context to add new device into.
183 * @param dev_prm
184 *   Parameters used to create and initialise new device inside the context.
185 * @return
186 *   Pointer to device structure that can be used in future operations,
187 *   or NULL on error, with error code set in rte_errno.
188 *   Possible rte_errno errors include:
189 *   - EINVAL - invalid parameter passed to function
190 *   - ENODEV - max possible value of open devices is reached
191 *   - ENOMEM - out of memory
192 */
193struct tle_dev *
194tle_add_dev(struct tle_ctx *ctx, const struct tle_dev_param *dev_prm);
195
196/**
197 * Remove and destroy previously added device from the given context.
198 * This function is not multi-thread safe.
199 *
200 * @param dev
201 *   device to remove and destroy.
202 * @return
203 *   zero on successful completion.
204 *   - -EINVAL - invalid parameter passed to function
205 */
206int tle_del_dev(struct tle_dev *dev);
207
208/**
209 * Flags to the context that destinations info might be changed,
210 * so if it has any destinations data cached, then
211 * it has to be invalidated.
212 * @param ctx
213 *   context to invalidate.
214 */
215void tle_ctx_invalidate(struct tle_ctx *ctx);
216
217/**
218 * Stream asynchronous notification mechanisms:
219 * a) recv/send callback.
220 * Stream recv/send notification callbacks behaviour is edge-triggered (ET).
221 * recv callback will be invoked if stream receive buffer was empty and
222 * new packet(s) have arrived.
223 * send callback will be invoked when stream send buffer was full,
224 * and some packets belonging to that stream were sent
225 * (part of send buffer became free again).
226 * Note that both recv and send callbacks are called with sort of read lock
227 * held on that stream. So it is not permitted to call stream_close()
228 * within the callback function. Doing that would cause a deadlock.
229 * While it is allowed to call stream send/recv functions within the
230 * callback, it is not recommended: callback function will be invoked
231 * within tle_udp_rx_bulk/tle_udp_tx_bulk context and some heavy processing
232 * within the callback functions might cause performance degradation
233 * or even loss of packets for further streams.
234 * b) recv/send event.
235 * Stream recv/send events behaviour is level-triggered (LT).
236 * receive event will be raised by either
237 * tle_udp_rx_burst() or tle_udp_stream_recv() as long as there are any
238 * remaining packets inside stream receive buffer.
239 * send event will be raised by either
240 * tle_udp_tx_burst() or tle_udp_stream_send() as long as there are any
241 * free space inside stream send buffer.
242 * Note that callback and event are mutually exclusive on <stream, op> basis.
243 * It is not possible to  open a stream with both recv event and callback
244 * specified.
245 * Though it is possible to open a stream with recv callback and send event,
246 * or visa-versa.
247 * If the user doesn't need any notification mechanism for that stream,
248 * both event and callback could be set to zero.
249 */
250
251struct tle_event;
252struct tle_stream;
253
254/**
255 * Stream recv/send callback function and data.
256 */
257struct tle_stream_cb {
258	void (*func)(void *, struct tle_stream *);
259	void *data;
260};
261
262#ifdef __cplusplus
263}
264#endif
265
266#endif /* _TLE_CTX_H_ */
267