lib/libtle_l4p/tle_tcp.h

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