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