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  * A structure which is used to create GRO context objects or tell
  35  * rte_gro_reassemble_burst() what reassembly rules are demanded.
  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 assumes that all inputted packets are with
  82  * correct checksums. That is, applications should guarantee all
  83  * inputted packets are correct. Besides, it doesn't re-calculate
  84  * checksums for merged packets. If inputted packets are IP fragmented,
  85  * this function assumes them are complete (i.e. with L4 header). After
  86  * finishing processing, it returns all GROed packets to applications
  87  * immediately.
  88  *
  89  * @param pkts
  90  *  a pointer array which points to the packets to reassemble. Besides,
  91  *  it keeps mbuf addresses for the GROed packets.
  92  * @param nb_pkts
  93  *  the number of packets to reassemble.
  94  * @param param
  95  *  applications use it to tell rte_gro_reassemble_burst() what rules
  96  *  are demanded.
  97  *
  98  * @return
  99  *  the number of packets after been GROed. If no packets are merged,
 100  *  the returned value is 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 inputted packets with
 111  * the packets in the reassembly tables of a given GRO context. This
 112  * function assumes all inputted packets are with correct checksums.
 113  * And it won't update checksums if two packets are merged. Besides,
 114  * if inputted packets are IP fragmented, this function assumes they
 115  * are complete packets (i.e. with L4 header).
 116  *
 117  * If the inputted packets don't have data or are with unsupported GRO
 118  * types etc., they won't be processed and are returned to applications.
 119  * Otherwise, the inputted packets are either merged or inserted into
 120  * the table. If applications want get packets in the table, they need
 121  * to call flush API.
 122  *
 123  * @param pkts
 124  *  packet to reassemble. Besides, after this function finishes, it
 125  *  keeps the unprocessed packets (e.g. without data or unsupported
 126  *  GRO types).
 127  * @param nb_pkts
 128  *  the number of packets to reassemble.
 129  * @param ctx
 130  *  a pointer points to a GRO context object.
 131  *
 132  * @return
 133  *  return the number of unprocessed packets (e.g. without data or
 134  *  unsupported GRO types). If all packets are processed (merged or
 135  *  inserted into the table), return 0.
 136  */
 137 uint16_t rte_gro_reassemble(struct rte_mbuf **pkts,
 138                 uint16_t nb_pkts,
 139                 void *ctx);
 140
 141 /**
 142  * @warning
 143  * @b EXPERIMENTAL: this API may change without prior notice
 144  *
 145  * This function flushes the timeout packets from reassembly tables of
 146  * desired GRO types. The max number of flushed timeout packets is the
 147  * element number of the array which is used to keep the flushed packets.
 148  *
 149  * Besides, this function won't re-calculate checksums for merged
 150  * packets in the tables. That is, the returned packets may be with
 151  * wrong checksums.
 152  *
 153  * @param ctx
 154  *  a pointer points to a GRO context object.
 155  * @param timeout_cycles
 156  *  max TTL for packets in reassembly tables, measured in nanosecond.
 157  * @param gro_types
 158  *  this function only flushes packets which belong to the GRO types
 159  *  specified by gro_types.
 160  * @param out
 161  *  a pointer array that is used to keep flushed timeout packets.
 162  * @param max_nb_out
 163  *  the element number of out. It's also the max number of timeout
 164  *  packets that can be flushed finally.
 165  *
 166  * @return
 167  *  the number of flushed packets. If no packets are flushed, return 0.
 168  */
 169 uint16_t rte_gro_timeout_flush(void *ctx,
 170                 uint64_t timeout_cycles,
 171                 uint64_t gro_types,
 172                 struct rte_mbuf **out,
 173                 uint16_t max_nb_out);
 174
 175 /**
 176  * @warning
 177  * @b EXPERIMENTAL: this API may change without prior notice
 178  *
 179  * This function returns the number of packets in all reassembly tables
 180  * of a given GRO context.
 181  *
 182  * @param ctx
 183  *  pointer points to a GRO context object.
 184  *
 185  * @return
 186  *  the number of packets in all reassembly tables.
 187  */
 188 uint64_t rte_gro_get_pkt_count(void *ctx);
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif
 193
 194 #endif /* _RTE_GRO_H_ */