lib/librte_distributor/rte_distributor.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_DISTRIBUTOR_H_
   6 #define _RTE_DISTRIBUTOR_H_
   7
   8 /**
   9  * @file
  10  * RTE distributor
  11  *
  12  * The distributor is a component which is designed to pass packets
  13  * one-at-a-time to workers, with dynamic load balancing.
  14  */
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /* Type of distribution (burst/single) */
  21 enum rte_distributor_alg_type {
  22         RTE_DIST_ALG_BURST = 0,
  23         RTE_DIST_ALG_SINGLE,
  24         RTE_DIST_NUM_ALG_TYPES
  25 };
  26
  27 struct rte_distributor;
  28 struct rte_mbuf;
  29
  30 /**
  31  * Function to create a new distributor instance
  32  *
  33  * Reserves the memory needed for the distributor operation and
  34  * initializes the distributor to work with the configured number of workers.
  35  *
  36  * @param name
  37  *   The name to be given to the distributor instance.
  38  * @param socket_id
  39  *   The NUMA node on which the memory is to be allocated
  40  * @param num_workers
  41  *   The maximum number of workers that will request packets from this
  42  *   distributor
  43  * @param alg_type
  44  *   Call the legacy API, or use the new burst API. legacy uses 32-bit
  45  *   flow ID, and works on a single packet at a time. Latest uses 15-
  46  *   bit flow ID and works on up to 8 packets at a time to workers.
  47  * @return
  48  *   The newly created distributor instance
  49  */
  50 struct rte_distributor *
  51 rte_distributor_create(const char *name, unsigned int socket_id,
  52                 unsigned int num_workers,
  53                 unsigned int alg_type);
  54
  55 /*  *** APIS to be called on the distributor lcore ***  */
  56 /*
  57  * The following APIs are the public APIs which are designed for use on a
  58  * single lcore which acts as the distributor lcore for a given distributor
  59  * instance. These functions cannot be called on multiple cores simultaneously
  60  * without using locking to protect access to the internals of the distributor.
  61  *
  62  * NOTE: a given lcore cannot act as both a distributor lcore and a worker lcore
  63  * for the same distributor instance, otherwise deadlock will result.
  64  */
  65
  66 /**
  67  * Process a set of packets by distributing them among workers that request
  68  * packets. The distributor will ensure that no two packets that have the
  69  * same flow id, or tag, in the mbuf will be processed on different cores at
  70  * the same time.
  71  *
  72  * The user is advocated to set tag for each mbuf before calling this function.
  73  * If user doesn't set the tag, the tag value can be various values depending on
  74  * driver implementation and configuration.
  75  *
  76  * This is not multi-thread safe and should only be called on a single lcore.
  77  *
  78  * @param d
  79  *   The distributor instance to be used
  80  * @param mbufs
  81  *   The mbufs to be distributed
  82  * @param num_mbufs
  83  *   The number of mbufs in the mbufs array
  84  * @return
  85  *   The number of mbufs processed.
  86  */
  87 int
  88 rte_distributor_process(struct rte_distributor *d,
  89                 struct rte_mbuf **mbufs, unsigned int num_mbufs);
  90
  91 /**
  92  * Get a set of mbufs that have been returned to the distributor by workers
  93  *
  94  * This should only be called on the same lcore as rte_distributor_process()
  95  *
  96  * @param d
  97  *   The distributor instance to be used
  98  * @param mbufs
  99  *   The mbufs pointer array to be filled in
 100  * @param max_mbufs
 101  *   The size of the mbufs array
 102  * @return
 103  *   The number of mbufs returned in the mbufs array.
 104  */
 105 int
 106 rte_distributor_returned_pkts(struct rte_distributor *d,
 107                 struct rte_mbuf **mbufs, unsigned int max_mbufs);
 108
 109 /**
 110  * Flush the distributor component, so that there are no in-flight or
 111  * backlogged packets awaiting processing
 112  *
 113  * This should only be called on the same lcore as rte_distributor_process()
 114  *
 115  * @param d
 116  *   The distributor instance to be used
 117  * @return
 118  *   The number of queued/in-flight packets that were completed by this call.
 119  */
 120 int
 121 rte_distributor_flush(struct rte_distributor *d);
 122
 123 /**
 124  * Clears the array of returned packets used as the source for the
 125  * rte_distributor_returned_pkts() API call.
 126  *
 127  * This should only be called on the same lcore as rte_distributor_process()
 128  *
 129  * @param d
 130  *   The distributor instance to be used
 131  */
 132 void
 133 rte_distributor_clear_returns(struct rte_distributor *d);
 134
 135 /*  *** APIS to be called on the worker lcores ***  */
 136 /*
 137  * The following APIs are the public APIs which are designed for use on
 138  * multiple lcores which act as workers for a distributor. Each lcore should use
 139  * a unique worker id when requesting packets.
 140  *
 141  * NOTE: a given lcore cannot act as both a distributor lcore and a worker lcore
 142  * for the same distributor instance, otherwise deadlock will result.
 143  */
 144
 145 /**
 146  * API called by a worker to get new packets to process. Any previous packets
 147  * given to the worker is assumed to have completed processing, and may be
 148  * optionally returned to the distributor via the oldpkt parameter.
 149  *
 150  * @param d
 151  *   The distributor instance to be used
 152  * @param worker_id
 153  *   The worker instance number to use - must be less that num_workers passed
 154  *   at distributor creation time.
 155  * @param pkts
 156  *   The mbufs pointer array to be filled in (up to 8 packets)
 157  * @param oldpkt
 158  *   The previous packet, if any, being processed by the worker
 159  * @param retcount
 160  *   The number of packets being returned
 161  *
 162  * @return
 163  *   The number of packets in the pkts array
 164  */
 165 int
 166 rte_distributor_get_pkt(struct rte_distributor *d,
 167         unsigned int worker_id, struct rte_mbuf **pkts,
 168         struct rte_mbuf **oldpkt, unsigned int retcount);
 169
 170 /**
 171  * API called by a worker to return a completed packet without requesting a
 172  * new packet, for example, because a worker thread is shutting down
 173  *
 174  * @param d
 175  *   The distributor instance to be used
 176  * @param worker_id
 177  *   The worker instance number to use - must be less that num_workers passed
 178  *   at distributor creation time.
 179  * @param oldpkt
 180  *   The previous packets being processed by the worker
 181  * @param num
 182  *   The number of packets in the oldpkt array
 183  */
 184 int
 185 rte_distributor_return_pkt(struct rte_distributor *d,
 186         unsigned int worker_id, struct rte_mbuf **oldpkt, int num);
 187
 188 /**
 189  * API called by a worker to request a new packet to process.
 190  * Any previous packet given to the worker is assumed to have completed
 191  * processing, and may be optionally returned to the distributor via
 192  * the oldpkt parameter.
 193  * Unlike rte_distributor_get_pkt_burst(), this function does not wait for a
 194  * new packet to be provided by the distributor.
 195  *
 196  * NOTE: after calling this function, rte_distributor_poll_pkt_burst() should
 197  * be used to poll for the packet requested. The rte_distributor_get_pkt_burst()
 198  * API should *not* be used to try and retrieve the new packet.
 199  *
 200  * @param d
 201  *   The distributor instance to be used
 202  * @param worker_id
 203  *   The worker instance number to use - must be less that num_workers passed
 204  *   at distributor creation time.
 205  * @param oldpkt
 206  *   The returning packets, if any, processed by the worker
 207  * @param count
 208  *   The number of returning packets
 209  */
 210 void
 211 rte_distributor_request_pkt(struct rte_distributor *d,
 212                 unsigned int worker_id, struct rte_mbuf **oldpkt,
 213                 unsigned int count);
 214
 215 /**
 216  * API called by a worker to check for a new packet that was previously
 217  * requested by a call to rte_distributor_request_pkt(). It does not wait
 218  * for the new packet to be available, but returns NULL if the request has
 219  * not yet been fulfilled by the distributor.
 220  *
 221  * @param d
 222  *   The distributor instance to be used
 223  * @param worker_id
 224  *   The worker instance number to use - must be less that num_workers passed
 225  *   at distributor creation time.
 226  * @param mbufs
 227  *   The array of mbufs being given to the worker
 228  *
 229  * @return
 230  *   The number of packets being given to the worker thread, zero if no
 231  *   packet is yet available.
 232  */
 233 int
 234 rte_distributor_poll_pkt(struct rte_distributor *d,
 235                 unsigned int worker_id, struct rte_mbuf **mbufs);
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif