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