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