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 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #define RTE_GRO_MAX_BURST_ITEM_NUM 128U
  46 /**< the max number of packets that rte_gro_reassemble_burst()
  47  * can process in each invocation.
  48  */
  49 #define RTE_GRO_TYPE_MAX_NUM 64
  50 /**< the max number of supported GRO types */
  51 #define RTE_GRO_TYPE_SUPPORT_NUM 1
  52 /**< the number of currently supported GRO types */
  53
  54 #define RTE_GRO_TCP_IPV4_INDEX 0
  55 #define RTE_GRO_TCP_IPV4 (1ULL << RTE_GRO_TCP_IPV4_INDEX)
  56 /**< TCP/IPv4 GRO flag */
  57
  58 /**
  59  * A structure which is used to create GRO context objects or tell
  60  * rte_gro_reassemble_burst() what reassembly rules are demanded.
  61  */
  62 struct rte_gro_param {
  63         uint64_t gro_types;
  64         /**< desired GRO types */
  65         uint16_t max_flow_num;
  66         /**< max flow number */
  67         uint16_t max_item_per_flow;
  68         /**< max packet number per flow */
  69         uint16_t socket_id;
  70         /**< socket index for allocating GRO related data structures,
  71          * like reassembly tables. When use rte_gro_reassemble_burst(),
  72          * applications don't need to set this value.
  73          */
  74 };
  75
  76 /**
  77  * @warning
  78  * @b EXPERIMENTAL: this API may change without prior notice
  79  *
  80  * This function create a GRO context object, which is used to merge
  81  * packets in rte_gro_reassemble().
  82  *
  83  * @param param
  84  *  applications use it to pass needed parameters to create a GRO
  85  *  context object.
  86  *
  87  * @return
  88  *  if create successfully, return a pointer which points to the GRO
  89  *  context object. Otherwise, return NULL.
  90  */
  91 void *rte_gro_ctx_create(const struct rte_gro_param *param);
  92
  93 /**
  94  * @warning
  95  * @b EXPERIMENTAL: this API may change without prior notice
  96  *
  97  * This function destroys a GRO context object.
  98  *
  99  * @param ctx
 100  *  pointer points to a GRO context object.
 101  */
 102 void rte_gro_ctx_destroy(void *ctx);
 103
 104 /**
 105  * This is one of the main reassembly APIs, which merges numbers of
 106  * packets at a time. It assumes that all inputted packets are with
 107  * correct checksums. That is, applications should guarantee all
 108  * inputted packets are correct. Besides, it doesn't re-calculate
 109  * checksums for merged packets. If inputted packets are IP fragmented,
 110  * this function assumes them are complete (i.e. with L4 header). After
 111  * finishing processing, it returns all GROed packets to applications
 112  * immediately.
 113  *
 114  * @param pkts
 115  *  a pointer array which points to the packets to reassemble. Besides,
 116  *  it keeps mbuf addresses for the GROed packets.
 117  * @param nb_pkts
 118  *  the number of packets to reassemble.
 119  * @param param
 120  *  applications use it to tell rte_gro_reassemble_burst() what rules
 121  *  are demanded.
 122  *
 123  * @return
 124  *  the number of packets after been GROed. If no packets are merged,
 125  *  the returned value is nb_pkts.
 126  */
 127 uint16_t rte_gro_reassemble_burst(struct rte_mbuf **pkts,
 128                 uint16_t nb_pkts,
 129                 const struct rte_gro_param *param);
 130
 131 /**
 132  * @warning
 133  * @b EXPERIMENTAL: this API may change without prior notice
 134  *
 135  * Reassembly function, which tries to merge inputted packets with
 136  * the packets in the reassembly tables of a given GRO context. This
 137  * function assumes all inputted packets are with correct checksums.
 138  * And it won't update checksums if two packets are merged. Besides,
 139  * if inputted packets are IP fragmented, this function assumes they
 140  * are complete packets (i.e. with L4 header).
 141  *
 142  * If the inputted packets don't have data or are with unsupported GRO
 143  * types etc., they won't be processed and are returned to applications.
 144  * Otherwise, the inputted packets are either merged or inserted into
 145  * the table. If applications want get packets in the table, they need
 146  * to call flush API.
 147  *
 148  * @param pkts
 149  *  packet to reassemble. Besides, after this function finishes, it
 150  *  keeps the unprocessed packets (e.g. without data or unsupported
 151  *  GRO types).
 152  * @param nb_pkts
 153  *  the number of packets to reassemble.
 154  * @param ctx
 155  *  a pointer points to a GRO context object.
 156  *
 157  * @return
 158  *  return the number of unprocessed packets (e.g. without data or
 159  *  unsupported GRO types). If all packets are processed (merged or
 160  *  inserted into the table), return 0.
 161  */
 162 uint16_t rte_gro_reassemble(struct rte_mbuf **pkts,
 163                 uint16_t nb_pkts,
 164                 void *ctx);
 165
 166 /**
 167  * @warning
 168  * @b EXPERIMENTAL: this API may change without prior notice
 169  *
 170  * This function flushes the timeout packets from reassembly tables of
 171  * desired GRO types. The max number of flushed timeout packets is the
 172  * element number of the array which is used to keep the flushed packets.
 173  *
 174  * Besides, this function won't re-calculate checksums for merged
 175  * packets in the tables. That is, the returned packets may be with
 176  * wrong checksums.
 177  *
 178  * @param ctx
 179  *  a pointer points to a GRO context object.
 180  * @param timeout_cycles
 181  *  max TTL for packets in reassembly tables, measured in nanosecond.
 182  * @param gro_types
 183  *  this function only flushes packets which belong to the GRO types
 184  *  specified by gro_types.
 185  * @param out
 186  *  a pointer array that is used to keep flushed timeout packets.
 187  * @param max_nb_out
 188  *  the element number of out. It's also the max number of timeout
 189  *  packets that can be flushed finally.
 190  *
 191  * @return
 192  *  the number of flushed packets. If no packets are flushed, return 0.
 193  */
 194 uint16_t rte_gro_timeout_flush(void *ctx,
 195                 uint64_t timeout_cycles,
 196                 uint64_t gro_types,
 197                 struct rte_mbuf **out,
 198                 uint16_t max_nb_out);
 199
 200 /**
 201  * @warning
 202  * @b EXPERIMENTAL: this API may change without prior notice
 203  *
 204  * This function returns the number of packets in all reassembly tables
 205  * of a given GRO context.
 206  *
 207  * @param ctx
 208  *  pointer points to a GRO context object.
 209  *
 210  * @return
 211  *  the number of packets in all reassembly tables.
 212  */
 213 uint64_t rte_gro_get_pkt_count(void *ctx);
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif /* _RTE_GRO_H_ */