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