lib/latencystats/rte_latencystats.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_LATENCYSTATS_H_
   6 #define _RTE_LATENCYSTATS_H_
   7
   8 /**
   9  * @file
  10  * RTE latency stats
  11  *
  12  * library to provide application and flow based latency stats.
  13  */
  14
  15 #include <stdint.h>
  16 #include <rte_metrics.h>
  17 #include <rte_mbuf.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /**
  24  *  Note: This function pointer is for future flow based latency stats
  25  *  implementation.
  26  *
  27  * Function type used for identifying flow types of a Rx packet.
  28  *
  29  * The callback function is called on Rx for each packet.
  30  * This function is used for flow based latency calculations.
  31  *
  32  * @param pkt
  33  *   Packet that has to be identified with its flow types.
  34  * @param user_param
  35  *   The arbitrary user parameter passed in by the application when
  36  *   the callback was originally configured.
  37  * @return
  38  *   The flow_mask, representing the multiple flow types of a packet.
  39  */
  40 typedef uint16_t (*rte_latency_stats_flow_type_fn)(struct rte_mbuf *pkt,
  41                                                         void *user_param);
  42
  43 /**
  44  *  Registers Rx/Tx callbacks for each active port, queue.
  45  *
  46  * @param samp_intvl
  47  *  Sampling time period in nano seconds, at which packet
  48  *  should be marked with time stamp.
  49  * @param user_cb
  50  *  Note: This param is for future flow based latency stats
  51  *  implementation.
  52  *  User callback to be called to get flow types of a packet.
  53  *  Used for flow based latency calculation.
  54  *  If the value is NULL, global stats will be calculated,
  55  *  else flow based latency stats will be calculated.
  56  *  For now just pass on the NULL value to this param.
  57  *  @return
  58  *   -1     : On error
  59  *   -ENOMEM: On error
  60  *    0     : On success
  61  */
  62 int rte_latencystats_init(uint64_t samp_intvl,
  63                         rte_latency_stats_flow_type_fn user_cb);
  64
  65 /**
  66  * Calculates the latency and jitter values internally, exposing the updated
  67  * values via *rte_latencystats_get* or the rte_metrics API.
  68  * @return:
  69  *  0      : on Success
  70  *  < 0    : Error in updating values.
  71  */
  72 int32_t rte_latencystats_update(void);
  73
  74 /**
  75  *  Removes registered Rx/Tx callbacks for each active port, queue.
  76  *
  77  *  @return
  78  *   -1: On error
  79  *    0: On success
  80  */
  81 int rte_latencystats_uninit(void);
  82
  83 /**
  84  * Retrieve names of latency statistics
  85  *
  86  * @param names
  87  *  Block of memory to insert names into. Must be at least size in capacity.
  88  *  If set to NULL, function returns required capacity.
  89  * @param size
  90  *  Capacity of latency stats names (number of names).
  91  * @return
  92  *   - positive value lower or equal to size: success. The return value
  93  *     is the number of entries filled in the stats table.
  94  *   - positive value higher than size: error, the given statistics table
  95  *     is too small. The return value corresponds to the size that should
  96  *     be given to succeed. The entries in the table are not valid and
  97  *     shall not be used by the caller.
  98  */
  99 int rte_latencystats_get_names(struct rte_metric_name *names,
 100                                 uint16_t size);
 101
 102 /**
 103  * Retrieve latency statistics.
 104  *
 105  * @param values
 106  *   A pointer to a table of structure of type *rte_metric_value*
 107  *   to be filled with latency statistics ids and values.
 108  *   This parameter can be set to NULL if size is 0.
 109  * @param size
 110  *   The size of the stats table, which should be large enough to store
 111  *   all the latency stats.
 112  * @return
 113  *   - positive value lower or equal to size: success. The return value
 114  *     is the number of entries filled in the stats table.
 115  *   - positive value higher than size: error, the given statistics table
 116  *     is too small. The return value corresponds to the size that should
 117  *     be given to succeed. The entries in the table are not valid and
 118  *     shall not be used by the caller.
 119  *   -ENOMEM: On failure.
 120  */
 121 int rte_latencystats_get(struct rte_metric_value *values,
 122                         uint16_t size);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif /* _RTE_LATENCYSTATS_H_ */