tle_tcp.h revision 7e18fa1b
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_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 * Get current TCP maximum segment size
124 * @param ts
125 *   Stream to retrieve MSS information from.
126 * @return
127 *   Maximum segment size in bytes, if successful.
128 *   Negative on failure.
129 */
130int tle_tcp_stream_get_mss(const struct tle_stream *ts);
131
132/**
133 * Client mode connect API.
134 */
135
136/**
137 * Attempt to establish connection with the destination TCP endpoint.
138 * Stream write event (or callback) will fire, if the connection will be
139 * established successfully.
140 * Note that stream in listen state or stream with already established
141 * connection, can't be subject of connect() call.
142 * In case of unsuccessful attempt, error event (or callback) will be
143 * activated.
144 * @param s
145 *   Pointer to the stream.
146 * @param addr
147 *   Address of the destination endpoint.
148 * @return
149 *   zero on successful completion.
150 *   - -EINVAL - invalid parameter passed to function
151 */
152int tle_tcp_stream_connect(struct tle_stream *s, const struct sockaddr *addr);
153
154/*
155 * Server mode connect API.
156 * Basic scheme for server mode API usage:
157 *
158 * <stream open happens here>
159 * tle_tcp_stream_listen(stream_to_listen);
160 * <wait for read event/callback on that stream>
161 * n = tle_tcp_accept(stream_to_listen, accepted_streams,
162 * 	sizeof(accepted_streams));
163 * for (i = 0, i != n; i++) {
164 * 	//prepare tle_tcp_stream_cfg for newly accepted streams
165 * 	...
166 * }
167 * k = tle_tcp_stream_update_cfg(rs, prm, n);
168 * if (n != k) {
169 * 	//handle error
170 *	...
171 * }
172 */
173
174/**
175 * Set stream into the listen state (passive opener), i.e. make stream ready
176 * to accept new connections.
177 * Stream read event (or callback) will be activated as new SYN requests
178 * will arrive.
179 * Note that stream with already established (or establishing) connection
180 * can't be subject of listen() call.
181 * @param s
182 *   Pointer to the stream.
183 * @return
184 *   zero on successful completion.
185 *   - -EINVAL - invalid parameter passed to function
186 */
187int tle_tcp_stream_listen(struct tle_stream *s);
188
189/**
190 * return up to *num* streams from the queue of pending connections
191 * for given TCP endpoint.
192 * @param s
193 *   TCP stream in listen state.
194 * @param rs
195 *   An array of pointers to the newily accepted streams.
196 *   Each such new stream represents a new connection to the given TCP endpoint.
197 *   Newly accepted stream should be in connected state and ready to use
198 *   by other FE API routines (send/recv/close/etc.).
199 * @param num
200 *   Number of elements in the *rs* array.
201 * @return
202 *   number of entries filled inside *rs* array.
203 */
204uint16_t tle_tcp_stream_accept(struct tle_stream *s, struct tle_stream *rs[],
205	uint32_t num);
206
207/**
208 * updates configuration (associated events, callbacks, stream parameters)
209 * for the given streams.
210 * @param ts
211 *   An array of pointers to the streams to update.
212 * @param prm
213 *   An array of parameters to update for the given streams.
214 * @param num
215 *   Number of elements in the *ts* and *prm* arrays.
216 * @return
217 *   number of streams successfully updated.
218 *   In case of error, error code set in rte_errno.
219 *   Possible rte_errno errors include:
220 *   - EINVAL - invalid parameter passed to function
221 */
222uint32_t tle_tcp_stream_update_cfg(struct tle_stream *ts[],
223	struct tle_tcp_stream_cfg prm[], uint32_t num);
224
225/**
226 * Accept connection requests for the given stream.
227 * Note that the stream has to be in listen state.
228 * For each new connection a new stream will be open.
229 * @param s
230 *   TCP listen stream.
231 * @param prm
232 *   An array of *tle_tcp_accept_param* structures that
233 *   contains at least *num* elements in it.
234 * @param rs
235 *   An array of pointers to *tle_stream* structures that
236 *   must be large enough to store up to *num* pointers in it.
237 * @param num
238 *   Number of elements in the *prm* and *rs* arrays.
239 * @return
240 *   number of of entries filled inside *rs* array.
241 *   In case of error, error code set in rte_errno.
242 *   Possible rte_errno errors include:
243 *   - EINVAL - invalid parameter passed to function
244 *   - ENFILE - no more streams are avaialble to open.
245 */
246
247/**
248 * Return up to *num* mbufs that was received for given TCP stream.
249 * Note that the stream has to be in connected state.
250 * Data ordering is preserved.
251 * For each returned mbuf:
252 * data_off set to the start of the packet's TCP data
253 * l2_len, l3_len, l4_len are setup properly
254 * (so user can still extract L2/L3 address info if needed)
255 * packet_type RTE_PTYPE_L2/L3/L4 bits are setup properly.
256 * L3/L4 checksum is verified.
257 * @param s
258 *   TCP stream to receive packets from.
259 * @param pkt
260 *   An array of pointers to *rte_mbuf* structures that
261 *   must be large enough to store up to *num* pointers in it.
262 * @param num
263 *   Number of elements in the *pkt* array.
264 * @return
265 *   number of of entries filled inside *pkt* array.
266 */
267uint16_t tle_tcp_stream_recv(struct tle_stream *s, struct rte_mbuf *pkt[],
268	uint16_t num);
269
270/**
271 * Reads iovcnt buffers from the for given TCP stream.
272 * Note that the stream has to be in connected state.
273 * Data ordering is preserved.
274 * Buffers are processed in array order.
275 * This means that the function will comppletely fill iov[0]
276 * before proceeding to iov[1], and so on.
277 * If there is insufficient data, then not all buffers pointed to by iov
278 * may be filled.
279 * @param ts
280 *   TCP stream to receive data from.
281 * @param iov
282 *   Points to an array of iovec structures.
283 * @param iovcnt
284 *   Number of elements in the *iov* array.
285 * @return
286 *   On success, number of bytes read in the stream receive buffer.
287 *   In case of error, returns -1 and error code will be set in rte_errno.
288 */
289ssize_t tle_tcp_stream_readv(struct tle_stream *ts, const struct iovec *iov,
290	int iovcnt);
291
292/**
293 * Consume and queue up to *num* packets, that will be sent eventually
294 * by tle_tcp_tx_bulk().
295 * Note that the stream has to be in connected state.
296 * It is responsibility of that function is to determine over which TCP dev
297 * given packets have to be sent out and do necessary preparations for that.
298 * Based on the *dst_addr* it does route lookup, fills L2/L3/L4 headers,
299 * and, if necessary, fragments packets.
300 * Depending on the underlying device information, it either does
301 * IP/TCP checksum calculations in SW or sets mbuf TX checksum
302 * offload fields properly.
303 * For each input mbuf the following conditions have to be met:
304 *	- data_off point to the start of packet's TCP data.
305 *	- there is enough header space to prepend L2/L3/L4 headers.
306 * @param s
307 *   TCP stream to send packets over.
308 * @param pkt
309 *   The burst of output packets that need to be send.
310 * @param num
311 *   Number of elements in the *pkt* array.
312 * @return
313 *   number of packets successfully queued in the stream send buffer.
314 *   In case of error, error code can be set in rte_errno.
315 *   Possible rte_errno errors include:
316 *   - EAGAIN - operation can't be perfomed right now
317 *              (most likely close() was perfomed on that stream allready).
318 *   - ENOTCONN - the stream is not connected.
319 */
320uint16_t tle_tcp_stream_send(struct tle_stream *s, struct rte_mbuf *pkt[],
321	uint16_t num);
322
323/**
324 * Writes iovcnt buffers of data described by iov to the for given TCP stream.
325 * Note that the stream has to be in connected state.
326 * Data ordering is preserved.
327 * Buffers are processed in array order.
328 * This means that the function will write out the entire contents of iov[0]
329 * before proceeding to iov[1], and so on.
330 * If there is insufficient space in stream send buffer,
331 * then not all buffers pointed to by iov may be written out.
332 * @param ts
333 *   TCP stream to send data to.
334 * @param iov
335 *   Points to an array of iovec structures.
336 * @param iovcnt
337 *   Number of elements in the *iov* array.
338 * @return
339 *   On success, number of bytes written to the stream send buffer.
340 *   In case of error, returns -1 and error code will be set in rte_errno.
341 *   - EAGAIN - operation can't be perfomed right now
342 *              (most likely close() was perfomed on that stream allready).
343 *   - ENOTCONN - the stream is not connected.
344 *   - ENOMEM - not enough internal buffer (mbuf) to store user provided data.
345 */
346ssize_t tle_tcp_stream_writev(struct tle_stream *ts, struct rte_mempool *mp,
347	const struct iovec *iov, int iovcnt);
348
349/**
350 * Back End (BE) API.
351 * BE API functions are not multi-thread safe.
352 * Supposed to be called by the L2/L3 processing layer.
353 */
354
355/**
356 * Take input mbufs and distribute them to open TCP streams.
357 * expects that for each input packet:
358 *	- l2_len, l3_len, l4_len are setup correctly
359 *	- (packet_type & (RTE_PTYPE_L3_IPV4 | RTE_PTYPE_L3_IPV6)) != 0,
360 *	- (packet_type & RTE_PTYPE_L4_TCP) != 0,
361 * During delivery L3/L4 checksums will be verified
362 * (either relies on HW offload or in SW).
363 * May cause some extra packets to be queued for TX.
364 * This function is not multi-thread safe.
365 * @param dev
366 *   TCP device the packets were received from.
367 * @param pkt
368 *   The burst of input packets that need to be processed.
369 * @param rp
370 *   The array that will contain pointers of unprocessed packets at return.
371 *   Should contain at least *num* elements.
372 * @param rc
373 *   The array that will contain error code for corresponding rp[] entry:
374 *   - ENOENT - no open stream matching this packet.
375 *   - ENOBUFS - receive buffer of the destination stream is full.
376 *   Should contain at least *num* elements.
377 * @param num
378 *   Number of elements in the *pkt* input array.
379 * @return
380 *   number of packets delivered to the TCP streams.
381 */
382uint16_t tle_tcp_rx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
383	struct rte_mbuf *rp[], int32_t rc[], uint16_t num);
384
385/**
386 * Fill *pkt* with pointers to the packets that have to be transmitted
387 * over given TCP device.
388 * Output packets have to be ready to be passed straight to rte_eth_tx_burst()
389 * without any extra processing.
390 * TCP/IPv4 checksum either already calculated or appropriate mbuf fields set
391 * properly for HW offload.
392 * This function is not multi-thread safe.
393 * @param dev
394 *   TCP device the output packets will be transmitted over.
395 * @param pkt
396 *   An array of pointers to *rte_mbuf* structures that
397 *   must be large enough to store up to *num* pointers in it.
398 * @param num
399 *   Number of elements in the *pkt* array.
400 * @return
401 *   number of of entries filled inside *pkt* array.
402 */
403uint16_t tle_tcp_tx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
404	uint16_t num);
405
406/**
407 * perform internal processing for given TCP context.
408 * Checks which timers are expired and performs the required actions
409 * (retransmission/connection abort, etc.)
410 * May cause some extra packets to be queued for TX.
411 * This function is not multi-thread safe.
412 * @param ctx
413 *   TCP context to process.
414 * @param num
415 *   maximum number of streams to process.
416 * @return
417 *   zero on successful completion.
418 *   - EINVAL - invalid parameter passed to function
419 * @return
420 */
421int tle_tcp_process(struct tle_ctx *ctx, uint32_t num);
422
423#ifdef __cplusplus
424}
425#endif
426
427#endif /* _TLE_TCP_H_ */
428