lib/librte_gro/rte_gro.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_GRO_H_
   6 #define _RTE_GRO_H_
   7
   8 /**
   9  * @file
  10  * Interface to GRO library
  11  */
  12
  13 #include <stdint.h>
  14 #include <rte_mbuf.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 #define RTE_GRO_MAX_BURST_ITEM_NUM 128U
  21 /**< the max number of packets that rte_gro_reassemble_burst()
  22  * can process in each invocation.
  23  */
  24 #define RTE_GRO_TYPE_MAX_NUM 64
  25 /**< the max number of supported GRO types */
  26 #define RTE_GRO_TYPE_SUPPORT_NUM 2
  27 /**< the number of currently supported GRO types */
  28
  29 #define RTE_GRO_TCP_IPV4_INDEX 0
  30 #define RTE_GRO_TCP_IPV4 (1ULL << RTE_GRO_TCP_IPV4_INDEX)
  31 /**< TCP/IPv4 GRO flag */
  32 #define RTE_GRO_IPV4_VXLAN_TCP_IPV4_INDEX 1
  33 #define RTE_GRO_IPV4_VXLAN_TCP_IPV4 (1ULL << RTE_GRO_IPV4_VXLAN_TCP_IPV4_INDEX)
  34 /**< VxLAN TCP/IPv4 GRO flag. */
  35 #define RTE_GRO_UDP_IPV4_INDEX 2
  36 #define RTE_GRO_UDP_IPV4 (1ULL << RTE_GRO_UDP_IPV4_INDEX)
  37 /**< UDP/IPv4 GRO flag */
  38
  39 /**
  40  * Structure used to create GRO context objects or used to pass
  41  * application-determined parameters to rte_gro_reassemble_burst().
  42  */
  43 struct rte_gro_param {
  44         uint64_t gro_types;
  45         /**< desired GRO types */
  46         uint16_t max_flow_num;
  47         /**< max flow number */
  48         uint16_t max_item_per_flow;
  49         /**< max packet number per flow */
  50         uint16_t socket_id;
  51         /**< socket index for allocating GRO related data structures,
  52          * like reassembly tables. When use rte_gro_reassemble_burst(),
  53          * applications don't need to set this value.
  54          */
  55 };
  56
  57 /**
  58  * @warning
  59  * @b EXPERIMENTAL: this API may change without prior notice
  60  *
  61  * This function create a GRO context object, which is used to merge
  62  * packets in rte_gro_reassemble().
  63  *
  64  * @param param
  65  *  applications use it to pass needed parameters to create a GRO
  66  *  context object.
  67  *
  68  * @return
  69  *  if create successfully, return a pointer which points to the GRO
  70  *  context object. Otherwise, return NULL.
  71  */
  72 void *rte_gro_ctx_create(const struct rte_gro_param *param);
  73
  74 /**
  75  * @warning
  76  * @b EXPERIMENTAL: this API may change without prior notice
  77  *
  78  * This function destroys a GRO context object.
  79  *
  80  * @param ctx
  81  *  pointer points to a GRO context object.
  82  */
  83 void rte_gro_ctx_destroy(void *ctx);
  84
  85 /**
  86  * This is one of the main reassembly APIs, which merges numbers of
  87  * packets at a time. It doesn't check if input packets have correct
  88  * checksums and doesn't re-calculate checksums for merged packets.
  89  * It assumes the packets are complete (i.e., MF==0 && frag_off==0),
  90  * when IP fragmentation is possible (i.e., DF==0). The GROed packets
  91  * are returned as soon as the function finishes.
  92  *
  93  * @param pkts
  94  *  Pointer array pointing to the packets to reassemble. Besides, it
  95  *  keeps MBUF addresses for the GROed packets.
  96  * @param nb_pkts
  97  *  The number of packets to reassemble
  98  * @param param
  99  *  Application-determined parameters for reassembling packets.
 100  *
 101  * @return
 102  *  The number of packets after been GROed. If no packets are merged,
 103  *  the return value is equals to nb_pkts.
 104  */
 105 uint16_t rte_gro_reassemble_burst(struct rte_mbuf **pkts,
 106                 uint16_t nb_pkts,
 107                 const struct rte_gro_param *param);
 108
 109 /**
 110  * @warning
 111  * @b EXPERIMENTAL: this API may change without prior notice
 112  *
 113  * Reassembly function, which tries to merge input packets with the
 114  * existed packets in the reassembly tables of a given GRO context.
 115  * It doesn't check if input packets have correct checksums and doesn't
 116  * re-calculate checksums for merged packets. Additionally, it assumes
 117  * the packets are complete (i.e., MF==0 && frag_off==0), when IP
 118  * fragmentation is possible (i.e., DF==0).
 119  *
 120  * If the input packets have invalid parameters (e.g. no data payload,
 121  * unsupported GRO types), they are returned to applications. Otherwise,
 122  * they are either merged or inserted into the table. Applications need
 123  * to flush packets from the tables by flush API, if they want to get the
 124  * GROed packets.
 125  *
 126  * @param pkts
 127  *  Packets to reassemble. It's also used to store the unprocessed packets.
 128  * @param nb_pkts
 129  *  The number of packets to reassemble
 130  * @param ctx
 131  *  GRO context object pointer
 132  *
 133  * @return
 134  *  The number of unprocessed packets.
 135  */
 136 uint16_t rte_gro_reassemble(struct rte_mbuf **pkts,
 137                 uint16_t nb_pkts,
 138                 void *ctx);
 139
 140 /**
 141  * @warning
 142  * @b EXPERIMENTAL: this API may change without prior notice
 143  *
 144  * This function flushes the timeout packets from the reassembly tables
 145  * of desired GRO types. The max number of flushed packets is the
 146  * element number of 'out'.
 147  *
 148  * Additionally, the flushed packets may have incorrect checksums, since
 149  * this function doesn't re-calculate checksums for merged packets.
 150  *
 151  * @param ctx
 152  *  GRO context object pointer.
 153  * @param timeout_cycles
 154  *  The max TTL for packets in reassembly tables, measured in nanosecond.
 155  * @param gro_types
 156  *  This function flushes packets whose GRO types are specified by
 157  *  gro_types.
 158  * @param out
 159  *  Pointer array used to keep flushed packets.
 160  * @param max_nb_out
 161  *  The element number of 'out'. It's also the max number of timeout
 162  *  packets that can be flushed finally.
 163  *
 164  * @return
 165  *  The number of flushed packets.
 166  */
 167 uint16_t rte_gro_timeout_flush(void *ctx,
 168                 uint64_t timeout_cycles,
 169                 uint64_t gro_types,
 170                 struct rte_mbuf **out,
 171                 uint16_t max_nb_out);
 172
 173 /**
 174  * @warning
 175  * @b EXPERIMENTAL: this API may change without prior notice
 176  *
 177  * This function returns the number of packets in all reassembly tables
 178  * of a given GRO context.
 179  *
 180  * @param ctx
 181  *  GRO context object pointer.
 182  *
 183  * @return
 184  *  The number of packets in the tables.
 185  */
 186 uint64_t rte_gro_get_pkt_count(void *ctx);
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif /* _RTE_GRO_H_ */