lib/libtle_l4p/tle_tcp.h

   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
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * TCP stream creation parameters.
  27  */
  28 struct 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
  35 struct 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
  49 struct 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  */
  67 struct tle_stream *
  68 tle_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  */
  86 int 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  */
 107 uint32_t
 108 tle_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  */
 118 int
 119 tle_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  */
 130 int 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  */
 152 int 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  */
 187 int 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  */
 204 uint16_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  */
 222 uint32_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  */
 267 uint16_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  */
 289 ssize_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  */
 320 uint16_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  */
 346 ssize_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  */
 382 uint16_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  */
 403 uint16_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  */
 421 int tle_tcp_process(struct tle_ctx *ctx, uint32_t num);
 422
 423 #ifdef __cplusplus
 424 }
 425 #endif
 426
 427 #endif /* _TLE_TCP_H_ */