tle_tcp.h revision aa97dd1c
1/*
2 * Copyright (c) 2016  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_TCP_H_
17#define _TLE_TCP_H_
18
19#include <tle_ctx.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/**
26 * TCP stream creation parameters.
27 */
28struct tle_tcp_stream_addr {
29	struct sockaddr_storage local;  /**< stream local address. */
30	struct sockaddr_storage remote; /**< stream remote address. */
31};
32
33#define	TLE_TCP_DEFAULT_RETRIES	3
34
35struct tle_tcp_stream_cfg {
36	uint8_t nb_retries;     /**< max number of retransmission attempts. */
37
38	/* _cb and _ev are mutually exclusive */
39	struct tle_event *err_ev;      /**< error event to use.  */
40	struct tle_stream_cb err_cb;   /**< error callback to use. */
41
42	struct tle_event *recv_ev;      /**< recv event to use.  */
43	struct tle_stream_cb recv_cb;   /**< recv callback to use. */
44
45	struct tle_event *send_ev;      /**< send event to use. */
46	struct tle_stream_cb send_cb;   /**< send callback to use. */
47};
48
49struct tle_tcp_stream_param {
50	struct tle_tcp_stream_addr addr;
51	struct tle_tcp_stream_cfg cfg;
52};
53
54/**
55 * create a new stream within given TCP context.
56 * @param ctx
57 *   TCP context to create new stream within.
58 * @param prm
59 *   Parameters used to create and initialise the new stream.
60 * @return
61 *   Pointer to TCP stream structure that can be used in future TCP API calls,
62 *   or NULL on error, with error code set in rte_errno.
63 *   Possible rte_errno errors include:
64 *   - EINVAL - invalid parameter passed to function
65 *   - ENOFILE - max limit of open streams reached for that context
66 */
67struct tle_stream *
68tle_tcp_stream_open(struct tle_ctx *ctx,
69	const struct tle_tcp_stream_param *prm);
70
71/**
72 * close an open stream.
73 * if the stream is in connected state, then:
74 * - connection termination would be performed.
75 * - if stream contains unsent data, then actual close will be postponed
76 * till either remaining data will be TX-ed, or timeout will expire.
77 * All packets that belong to that stream and remain in the device
78 * TX queue will be kept for father transmission.
79 * @param s
80 *   Pointer to the stream to close.
81 * @return
82 *   zero on successful completion.
83 *   - -EINVAL - invalid parameter passed to function
84 *   - -EDEADLK - close was already invoked on that stream
85 */
86int tle_tcp_stream_close(struct tle_stream *s);
87
88/**
89 * close a group of open streams.
90 * if the stream is in connected state, then:
91 * - connection termination would be performed.
92 * - if stream contains unsent data, then actual close will be postponed
93 * till either remaining data will be TX-ed, or timeout will expire.
94 * All packets that belong to that stream and remain in the device
95 * TX queue will be kept for father transmission.
96 * @param ts
97 *   An array of pointers to streams that have to be closed.
98 * @param num
99 *   Number of elements in the *ts* array.
100 * @return
101 *   number of successfully closed streams.
102 *   In case of error, error code set in rte_errno.
103 *   Possible rte_errno errors include:
104 *   - EINVAL - invalid parameter passed to function
105 *   - EDEADLK - close was already invoked on that stream
106 */
107uint32_t
108tle_tcp_stream_close_bulk(struct tle_stream *ts[], uint32_t num);
109
110/**
111 * get open stream local and remote addresses.
112 * @param s
113 *   Pointer to the stream.
114 * @return
115 *   zero on successful completion.
116 *   - EINVAL - invalid parameter passed to function
117 */
118int
119tle_tcp_stream_get_addr(const struct tle_stream *s,
120	struct tle_tcp_stream_addr *addr);
121
122/**
123 * Client mode connect API.
124 */
125
126/**
127 * Attempt to establish connection with the destination TCP endpoint.
128 * Stream write event (or callback) will fire, if the connection will be
129 * established successfully.
130 * Note that stream in listen state or stream with already established
131 * connection, can't be subject of connect() call.
132 * In case of unsuccessful attempt, error event (or callback) will be
133 * activated.
134 * @param s
135 *   Pointer to the stream.
136 * @param addr
137 *   Address of the destination endpoint.
138 * @return
139 *   zero on successful completion.
140 *   - -EINVAL - invalid parameter passed to function
141 */
142int tle_tcp_stream_connect(struct tle_stream *s, const struct sockaddr *addr);
143
144/*
145 * Server mode connect API.
146 * Basic scheme for server mode API usage:
147 *
148 * <stream open happens here>
149 * tle_tcp_stream_listen(stream_to_listen);
150 * <wait for read event/callback on that stream>
151 * n = tle_tcp_synreqs(stream_to_listen, syn_reqs, sizeof(syn_reqs));
152 * for (i = 0, k = 0; i != n; i++) {
153 *	rc = <decide should connection from that endpoint be allowed>;
154 *	if (rc == 0) {
155 *		//proceed with connection establishment
156 *		k++;
157 *		accept_param[k].syn = syn_reqs[i];
158 *		<fill rest of accept_param fields for k-th connection>
159 *	} else {
160 *		//reject connection requests from that endpoint
161 *		rej_reqs[i - k] = syn_reqs[i];
162 *	}
163 * }
164 *
165 *	//reject n - k connection requests
166 *	tle_tcp_reject(stream_to_listen, rej_reqs, n - k);
167 *
168 *	//accept k new connections
169 *	rc = tle_tcp_accept(stream_to_listen, accept_param, new_con_streams, k);
170 *	<handle errors>
171 */
172
173struct tle_syn_req {
174	struct rte_mbuf *pkt;
175	/*< mbuf with incoming connection request. */
176	void *opaque;    /*< tldk related opaque pointer. */
177};
178
179struct tle_tcp_accept_param {
180	struct tle_syn_req syn;        /*< mbuf with incoming SYN request. */
181	struct tle_tcp_stream_cfg cfg; /*< stream configure options. */
182};
183
184
185/**
186 * Set stream into the listen state (passive opener), i.e. make stream ready
187 * to accept new connections.
188 * Stream read event (or callback) will be activated as new SYN requests
189 * will arrive.
190 * Note that stream with already established (or establishing) connection
191 * can't be subject of listen() call.
192 * @param s
193 *   Pointer to the stream.
194 * @return
195 *   zero on successful completion.
196 *   - -EINVAL - invalid parameter passed to function
197 */
198int tle_tcp_stream_listen(struct tle_stream *s);
199
200/**
201 * return up to *num* mbufs with SYN requests that were received
202 * for given TCP endpoint.
203 * Note that the stream has to be in listen state.
204 * For each returned mbuf:
205 * data_off set to the start of the packet
206 * l2_len, l3_len, l4_len are setup properly
207 * (so user can still extract L2/L3/L4 header info if needed)
208 * packet_type RTE_PTYPE_L2/L3/L4 bits are setup properly.
209 * L3/L4 checksum is verified.
210 * @param s
211 *   TCP stream to receive packets from.
212 * @param rq
213 *   An array of tle_syn_req structures that contains
214 *   at least *num* elements in it.
215 * @param num
216 *   Number of elements in the *pkt* array.
217 * @return
218 *   number of of entries filled inside *pkt* array.
219 */
220uint16_t tle_tcp_stream_synreqs(struct tle_stream *s, struct tle_syn_req rq[],
221	uint32_t num);
222
223/**
224 * Accept connection requests for the given stream.
225 * Note that the stream has to be in listen state.
226 * For each new connection a new stream will be open.
227 * @param s
228 *   TCP listen stream.
229 * @param prm
230 *   An array of *tle_tcp_accept_param* structures that
231 *   contains at least *num* elements in it.
232 * @param rs
233 *   An array of pointers to *tle_stream* structures that
234 *   must be large enough to store up to *num* pointers in it.
235 * @param num
236 *   Number of elements in the *prm* and *rs* arrays.
237 * @return
238 *   number of of entries filled inside *rs* array.
239 *   In case of error, error code set in rte_errno.
240 *   Possible rte_errno errors include:
241 *   - EINVAL - invalid parameter passed to function
242 *   - ENFILE - no more streams are avaialble to open.
243 */
244int tle_tcp_stream_accept(struct tle_stream *s,
245	const struct tle_tcp_accept_param prm[], struct tle_stream *rs[],
246	uint32_t num);
247
248/**
249 * Reject connection requests for the given stream.
250 * Note that the stream has to be in listen state.
251 * For each new connection a new stream will be open.
252 * @param s
253 *   TCP listen stream.
254 * @param rq
255 *   An array of tle_syn_req structures that contains
256 *   at least *num* elements in it.
257 * @param num
258 *   Number of elements in the *pkt* array.
259 */
260void tle_tcp_reject(struct tle_stream *s, const struct tle_syn_req rq[],
261	uint32_t num);
262
263/**
264 * return up to *num* mbufs that was received for given TCP stream.
265 * Note that the stream has to be in connected state.
266 * Data ordering is preserved.
267 * For each returned mbuf:
268 * data_off set to the start of the packet's TCP data
269 * l2_len, l3_len, l4_len are setup properly
270 * (so user can still extract L2/L3 address info if needed)
271 * packet_type RTE_PTYPE_L2/L3/L4 bits are setup properly.
272 * L3/L4 checksum is verified.
273 * @param s
274 *   TCP stream to receive packets from.
275 * @param pkt
276 *   An array of pointers to *rte_mbuf* structures that
277 *   must be large enough to store up to *num* pointers in it.
278 * @param num
279 *   Number of elements in the *pkt* array.
280 * @return
281 *   number of of entries filled inside *pkt* array.
282 */
283uint16_t tle_tcp_stream_recv(struct tle_stream *s, struct rte_mbuf *pkt[],
284	uint16_t num);
285
286/**
287 * Consume and queue up to *num* packets, that will be sent eventually
288 * by tle_tcp_tx_bulk().
289 * Note that the stream has to be in connected state.
290 * It is responsibility of that function is to determine over which TCP dev
291 * given packets have to be sent out and do necessary preparations for that.
292 * Based on the *dst_addr* it does route lookup, fills L2/L3/L4 headers,
293 * and, if necessary, fragments packets.
294 * Depending on the underlying device information, it either does
295 * IP/TCP checksum calculations in SW or sets mbuf TX checksum
296 * offload fields properly.
297 * For each input mbuf the following conditions have to be met:
298 *	- data_off point to the start of packet's TCP data.
299 *	- there is enough header space to prepend L2/L3/L4 headers.
300 * @param s
301 *   TCP stream to send packets over.
302 * @param pkt
303 *   The burst of output packets that need to be send.
304 * @param num
305 *   Number of elements in the *pkt* array.
306 * @return
307 *   number of packets successfully queued in the stream send buffer.
308 *   In case of error, error code can be set in rte_errno.
309 *   Possible rte_errno errors include:
310 *   - EAGAIN - operation can be perfomed right now
311 *              (most likely close() was perfomed on that stream allready).
312 *   - ENOTCONN - the stream is not connected.
313 */
314uint16_t tle_tcp_stream_send(struct tle_stream *s, struct rte_mbuf *pkt[],
315	uint16_t num);
316
317/**
318 * Back End (BE) API.
319 * BE API functions are not multi-thread safe.
320 * Supposed to be called by the L2/L3 processing layer.
321 */
322
323/**
324 * Take input mbufs and distribute them to open TCP streams.
325 * expects that for each input packet:
326 *	- l2_len, l3_len, l4_len are setup correctly
327 *	- (packet_type & (RTE_PTYPE_L3_IPV4 | RTE_PTYPE_L3_IPV6)) != 0,
328 *	- (packet_type & RTE_PTYPE_L4_TCP) != 0,
329 * During delivery L3/L4 checksums will be verified
330 * (either relies on HW offload or in SW).
331 * May cause some extra packets to be queued for TX.
332 * This function is not multi-thread safe.
333 * @param dev
334 *   TCP device the packets were received from.
335 * @param pkt
336 *   The burst of input packets that need to be processed.
337 * @param rp
338 *   The array that will contain pointers of unprocessed packets at return.
339 *   Should contain at least *num* elements.
340 * @param rc
341 *   The array that will contain error code for corresponding rp[] entry:
342 *   - ENOENT - no open stream matching this packet.
343 *   - ENOBUFS - receive buffer of the destination stream is full.
344 *   Should contain at least *num* elements.
345 * @param num
346 *   Number of elements in the *pkt* input array.
347 * @return
348 *   number of packets delivered to the TCP streams.
349 */
350uint16_t tle_tcp_rx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
351	struct rte_mbuf *rp[], int32_t rc[], uint16_t num);
352
353/**
354 * Fill *pkt* with pointers to the packets that have to be transmitted
355 * over given TCP device.
356 * Output packets have to be ready to be passed straight to rte_eth_tx_burst()
357 * without any extra processing.
358 * TCP/IPv4 checksum either already calculated or appropriate mbuf fields set
359 * properly for HW offload.
360 * This function is not multi-thread safe.
361 * @param dev
362 *   TCP device the output packets will be transmitted over.
363 * @param pkt
364 *   An array of pointers to *rte_mbuf* structures that
365 *   must be large enough to store up to *num* pointers in it.
366 * @param num
367 *   Number of elements in the *pkt* array.
368 * @return
369 *   number of of entries filled inside *pkt* array.
370 */
371uint16_t tle_tcp_tx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
372	uint16_t num);
373
374/**
375 * perform internal processing for given TCP context.
376 * Checks which timers are expired and performs the required actions
377 * (retransmission/connection abort, etc.)
378 * May cause some extra packets to be queued for TX.
379 * This function is not multi-thread safe.
380 * @param ctx
381 *   TCP context to process.
382 * @param num
383 *   maximum number of streams to process.
384 * @return
385 *   zero on successful completion.
386 *   - EINVAL - invalid parameter passed to function
387 * @return
388 */
389int tle_tcp_process(struct tle_ctx *ctx, uint32_t num);
390
391#ifdef __cplusplus
392}
393#endif
394
395#endif /* _TLE_TCP_H_ */
396