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