lib/librte_gro/rte_gro.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
   5  *
   6  *   Redistribution and use in source and binary forms, with or without
   7  *   modification, are permitted provided that the following conditions
   8  *   are met:
   9  *
  10  *     * Redistributions of source code must retain the above copyright
  11  *       notice, this list of conditions and the following disclaimer.
  12  *     * Redistributions in binary form must reproduce the above copyright
  13  *       notice, this list of conditions and the following disclaimer in
  14  *       the documentation and/or other materials provided with the
  15  *       distribution.
  16  *     * Neither the name of Intel Corporation nor the names of its
  17  *       contributors may be used to endorse or promote products derived
  18  *       from this software without specific prior written permission.
  19  *
  20  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 #ifndef _RTE_GRO_H_
  34 #define _RTE_GRO_H_
  35
  36 /**
  37  * @file
  38  * Interface to GRO library
  39  */
  40
  41 #include <stdint.h>
  42 #include <rte_mbuf.h>
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 #define RTE_GRO_MAX_BURST_ITEM_NUM 128U
  49 /**< the max number of packets that rte_gro_reassemble_burst()
  50  * can process in each invocation.
  51  */
  52 #define RTE_GRO_TYPE_MAX_NUM 64
  53 /**< the max number of supported GRO types */
  54 #define RTE_GRO_TYPE_SUPPORT_NUM 1
  55 /**< the number of currently supported GRO types */
  56
  57 #define RTE_GRO_TCP_IPV4_INDEX 0
  58 #define RTE_GRO_TCP_IPV4 (1ULL << RTE_GRO_TCP_IPV4_INDEX)
  59 /**< TCP/IPv4 GRO flag */
  60
  61 /**
  62  * A structure which is used to create GRO context objects or tell
  63  * rte_gro_reassemble_burst() what reassembly rules are demanded.
  64  */
  65 struct rte_gro_param {
  66         uint64_t gro_types;
  67         /**< desired GRO types */
  68         uint16_t max_flow_num;
  69         /**< max flow number */
  70         uint16_t max_item_per_flow;
  71         /**< max packet number per flow */
  72         uint16_t socket_id;
  73         /**< socket index for allocating GRO related data structures,
  74          * like reassembly tables. When use rte_gro_reassemble_burst(),
  75          * applications don't need to set this value.
  76          */
  77 };
  78
  79 /**
  80  * @warning
  81  * @b EXPERIMENTAL: this API may change without prior notice
  82  *
  83  * This function create a GRO context object, which is used to merge
  84  * packets in rte_gro_reassemble().
  85  *
  86  * @param param
  87  *  applications use it to pass needed parameters to create a GRO
  88  *  context object.
  89  *
  90  * @return
  91  *  if create successfully, return a pointer which points to the GRO
  92  *  context object. Otherwise, return NULL.
  93  */
  94 void *rte_gro_ctx_create(const struct rte_gro_param *param);
  95
  96 /**
  97  * @warning
  98  * @b EXPERIMENTAL: this API may change without prior notice
  99  *
 100  * This function destroys a GRO context object.
 101  *
 102  * @param ctx
 103  *  pointer points to a GRO context object.
 104  */
 105 void rte_gro_ctx_destroy(void *ctx);
 106
 107 /**
 108  * This is one of the main reassembly APIs, which merges numbers of
 109  * packets at a time. It assumes that all inputted packets are with
 110  * correct checksums. That is, applications should guarantee all
 111  * inputted packets are correct. Besides, it doesn't re-calculate
 112  * checksums for merged packets. If inputted packets are IP fragmented,
 113  * this function assumes them are complete (i.e. with L4 header). After
 114  * finishing processing, it returns all GROed packets to applications
 115  * immediately.
 116  *
 117  * @param pkts
 118  *  a pointer array which points to the packets to reassemble. Besides,
 119  *  it keeps mbuf addresses for the GROed packets.
 120  * @param nb_pkts
 121  *  the number of packets to reassemble.
 122  * @param param
 123  *  applications use it to tell rte_gro_reassemble_burst() what rules
 124  *  are demanded.
 125  *
 126  * @return
 127  *  the number of packets after been GROed. If no packets are merged,
 128  *  the returned value is nb_pkts.
 129  */
 130 uint16_t rte_gro_reassemble_burst(struct rte_mbuf **pkts,
 131                 uint16_t nb_pkts,
 132                 const struct rte_gro_param *param);
 133
 134 /**
 135  * @warning
 136  * @b EXPERIMENTAL: this API may change without prior notice
 137  *
 138  * Reassembly function, which tries to merge inputted packets with
 139  * the packets in the reassembly tables of a given GRO context. This
 140  * function assumes all inputted packets are with correct checksums.
 141  * And it won't update checksums if two packets are merged. Besides,
 142  * if inputted packets are IP fragmented, this function assumes they
 143  * are complete packets (i.e. with L4 header).
 144  *
 145  * If the inputted packets don't have data or are with unsupported GRO
 146  * types etc., they won't be processed and are returned to applications.
 147  * Otherwise, the inputted packets are either merged or inserted into
 148  * the table. If applications want get packets in the table, they need
 149  * to call flush API.
 150  *
 151  * @param pkts
 152  *  packet to reassemble. Besides, after this function finishes, it
 153  *  keeps the unprocessed packets (e.g. without data or unsupported
 154  *  GRO types).
 155  * @param nb_pkts
 156  *  the number of packets to reassemble.
 157  * @param ctx
 158  *  a pointer points to a GRO context object.
 159  *
 160  * @return
 161  *  return the number of unprocessed packets (e.g. without data or
 162  *  unsupported GRO types). If all packets are processed (merged or
 163  *  inserted into the table), return 0.
 164  */
 165 uint16_t rte_gro_reassemble(struct rte_mbuf **pkts,
 166                 uint16_t nb_pkts,
 167                 void *ctx);
 168
 169 /**
 170  * @warning
 171  * @b EXPERIMENTAL: this API may change without prior notice
 172  *
 173  * This function flushes the timeout packets from reassembly tables of
 174  * desired GRO types. The max number of flushed timeout packets is the
 175  * element number of the array which is used to keep the flushed packets.
 176  *
 177  * Besides, this function won't re-calculate checksums for merged
 178  * packets in the tables. That is, the returned packets may be with
 179  * wrong checksums.
 180  *
 181  * @param ctx
 182  *  a pointer points to a GRO context object.
 183  * @param timeout_cycles
 184  *  max TTL for packets in reassembly tables, measured in nanosecond.
 185  * @param gro_types
 186  *  this function only flushes packets which belong to the GRO types
 187  *  specified by gro_types.
 188  * @param out
 189  *  a pointer array that is used to keep flushed timeout packets.
 190  * @param max_nb_out
 191  *  the element number of out. It's also the max number of timeout
 192  *  packets that can be flushed finally.
 193  *
 194  * @return
 195  *  the number of flushed packets. If no packets are flushed, return 0.
 196  */
 197 uint16_t rte_gro_timeout_flush(void *ctx,
 198                 uint64_t timeout_cycles,
 199                 uint64_t gro_types,
 200                 struct rte_mbuf **out,
 201                 uint16_t max_nb_out);
 202
 203 /**
 204  * @warning
 205  * @b EXPERIMENTAL: this API may change without prior notice
 206  *
 207  * This function returns the number of packets in all reassembly tables
 208  * of a given GRO context.
 209  *
 210  * @param ctx
 211  *  pointer points to a GRO context object.
 212  *
 213  * @return
 214  *  the number of packets in all reassembly tables.
 215  */
 216 uint64_t rte_gro_get_pkt_count(void *ctx);
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif /* _RTE_GRO_H_ */