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