lib/libtle_l4p/tle_udp.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_UDP_H_
  17 #define _TLE_UDP_H_
  18
  19 #include <tle_ctx.h>
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * UDP stream creation parameters.
  27  */
  28 struct tle_udp_stream_param {
  29         struct sockaddr_storage local_addr;  /**< stream local address. */
  30         struct sockaddr_storage remote_addr; /**< stream remote address. */
  31
  32         /* _cb and _ev are mutually exclusive */
  33         struct tle_event *recv_ev;          /**< recv event to use.  */
  34         struct tle_stream_cb recv_cb;   /**< recv callback to use. */
  35
  36         struct tle_event *send_ev;          /**< send event to use. */
  37         struct tle_stream_cb send_cb;   /**< send callback to use. */
  38 };
  39
  40 /**
  41  * create a new stream within given UDP context.
  42  * @param ctx
  43  *   UDP context to create new stream within.
  44  * @param prm
  45  *   Parameters used to create and initialise the new stream.
  46  * @return
  47  *   Pointer to UDP stream structure that can be used in future UDP API calls,
  48  *   or NULL on error, with error code set in rte_errno.
  49  *   Possible rte_errno errors include:
  50  *   - EINVAL - invalid parameter passed to function
  51  *   - ENOFILE - max limit of open streams reached for that context
  52  */
  53 struct tle_stream *
  54 tle_udp_stream_open(struct tle_ctx *ctx,
  55         const struct tle_udp_stream_param *prm);
  56
  57 /**
  58  * close an open stream.
  59  * All packets still remaining in stream receive buffer will be freed.
  60  * All packets still remaining in stream transmit buffer will be kept
  61  * for father transmission.
  62  * @param s
  63  *   Pointer to the stream to close.
  64  * @return
  65  *   zero on successful completion.
  66  *   - -EINVAL - invalid parameter passed to function
  67  */
  68 int tle_udp_stream_close(struct tle_stream *s);
  69
  70 /**
  71  * get open stream parameters.
  72  * @param s
  73  *   Pointer to the stream.
  74  * @return
  75  *   zero on successful completion.
  76  *   - EINVAL - invalid parameter passed to function
  77  */
  78 int
  79 tle_udp_stream_get_param(const struct tle_stream *s,
  80         struct tle_udp_stream_param *prm);
  81
  82 /**
  83  * Take input mbufs and distribute them to open UDP streams.
  84  * expects that for each input packet:
  85  *      - l2_len, l3_len, l4_len are setup correctly
  86  *      - (packet_type & (RTE_PTYPE_L3_IPV4 | RTE_PTYPE_L3_IPV6)) != 0,
  87  *      - (packet_type & RTE_PTYPE_L4_UDP) != 0,
  88  * During delivery L3/L4 checksums will be verified
  89  * (either relies on HW offload or in SW).
  90  * This function is not multi-thread safe.
  91  * @param dev
  92  *   UDP device the packets were received from.
  93  * @param pkt
  94  *   The burst of input packets that need to be processed.
  95  * @param rp
  96  *   The array that will contain pointers of unprocessed packets at return.
  97  *   Should contain at least *num* elements.
  98  * @param rc
  99  *   The array that will contain error code for corresponding rp[] entry:
 100  *   - ENOENT - no open stream matching this packet.
 101  *   - ENOBUFS - receive buffer of the destination stream is full.
 102  *   Should contain at least *num* elements.
 103  * @param num
 104  *   Number of elements in the *pkt* input array.
 105  * @return
 106  *   number of packets delivered to the UDP streams.
 107  */
 108 uint16_t tle_udp_rx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
 109         struct rte_mbuf *rp[], int32_t rc[], uint16_t num);
 110
 111 /**
 112  * Fill *pkt* with pointers to the packets that have to be transmitted
 113  * over given UDP device.
 114  * Output packets have to be ready to be passed straight to rte_eth_tx_burst()
 115  * without any extra processing.
 116  * UDP/IPv4 checksum either already calculated or appropriate mbuf fields set
 117  * properly for HW offload.
 118  * This function is not multi-thread safe.
 119  * @param dev
 120  *   UDP device the output packets will be transmitted over.
 121  * @param pkt
 122  *   An array of pointers to *rte_mbuf* structures that
 123  *   must be large enough to store up to *num* pointers in it.
 124  * @param num
 125  *   Number of elements in the *pkt* array.
 126  * @return
 127  *   number of of entries filled inside *pkt* array.
 128  */
 129 uint16_t tle_udp_tx_bulk(struct tle_dev *dev, struct rte_mbuf *pkt[],
 130         uint16_t num);
 131
 132 /*
 133  * return up to *num* mbufs that was received for given UDP stream.
 134  * For each returned mbuf:
 135  * data_off set to the start of the packet's UDP data
 136  * l2_len, l3_len, l4_len are setup properly
 137  * (so user can still extract L2/L3 address info if needed)
 138  * packet_type RTE_PTYPE_L2/L3/L4 bits are setup properly.
 139  * L3/L4 checksum is verified.
 140  * Packets with invalid L3/L4 checksum will be silently dropped.
 141  * @param s
 142  *   UDP stream to receive packets from.
 143  * @param pkt
 144  *   An array of pointers to *rte_mbuf* structures that
 145  *   must be large enough to store up to *num* pointers in it.
 146  * @param num
 147  *   Number of elements in the *pkt* array.
 148  * @return
 149  *   number of of entries filled inside *pkt* array.
 150  */
 151 uint16_t tle_udp_stream_recv(struct tle_stream *s, struct rte_mbuf *pkt[],
 152         uint16_t num);
 153
 154 /**
 155  * Consume and queue up to *num* packets, that will be sent eventually
 156  * by tle_udp_tx_bulk().
 157  * If *dst_addr* is NULL, then default remote address associated with that
 158  * stream (if any) will be used.
 159  * The main purpose of that function is to determine over which UDP dev
 160  * given packets have to be sent out and do necessary preparations for that.
 161  * Based on the *dst_addr* it does route lookup, fills L2/L3/L4 headers,
 162  * and, if necessary, fragments packets.
 163  * Depending on the underlying device information, it either does
 164  * IP/UDP checksum calculations in SW or sets mbuf TX checksum
 165  * offload fields properly.
 166  * For each input mbuf the following conditions have to be met:
 167  *      - data_off point to the start of packet's UDP data.
 168  *      - there is enough header space to prepend L2/L3/L4 headers.
 169  * @param s
 170  *   UDP stream to send packets over.
 171  * @param pkt
 172  *   The burst of output packets that need to be send.
 173  * @param num
 174  *   Number of elements in the *pkt* array.
 175  * @param dst_addr
 176  *   Destination address to send packets to.
 177  * @return
 178  *   number of packets successfully queued in the stream send buffer.
 179  */
 180 uint16_t tle_udp_stream_send(struct tle_stream *s, struct rte_mbuf *pkt[],
 181         uint16_t num, const struct sockaddr *dst_addr);
 182
 183 #ifdef __cplusplus
 184 }
 185 #endif
 186
 187 #endif /* _TLE_UDP_H_ */