lib/librte_latencystats/rte_latencystats.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
   5  *
   6  *   Redistribution and use in source and binary forms, with or without
   7  *   modification, are permitted provided that the following conditions
   8  *   are met:
   9  *
  10  *     * Redistributions of source code must retain the above copyright
  11  *       notice, this list of conditions and the following disclaimer.
  12  *     * Redistributions in binary form must reproduce the above copyright
  13  *       notice, this list of conditions and the following disclaimer in
  14  *       the documentation and/or other materials provided with the
  15  *       distribution.
  16  *     * Neither the name of Intel Corporation nor the names of its
  17  *       contributors may be used to endorse or promote products derived
  18  *       from this software without specific prior written permission.
  19  *
  20  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 #ifndef _RTE_LATENCYSTATS_H_
  34 #define _RTE_LATENCYSTATS_H_
  35
  36 /**
  37  * @file
  38  * RTE latency stats
  39  *
  40  * library to provide application and flow based latency stats.
  41  */
  42
  43 #include <stdint.h>
  44 #include <rte_metrics.h>
  45 #include <rte_mbuf.h>
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /**
  52  *  Note: This function pointer is for future flow based latency stats
  53  *  implementation.
  54  *
  55  * Function type used for identifting flow types of a Rx packet.
  56  *
  57  * The callback function is called on Rx for each packet.
  58  * This function is used for flow based latency calculations.
  59  *
  60  * @param pkt
  61  *   Packet that has to be identified with its flow types.
  62  * @param user_param
  63  *   The arbitrary user parameter passed in by the application when
  64  *   the callback was originally configured.
  65  * @return
  66  *   The flow_mask, representing the multiple flow types of a packet.
  67  */
  68 typedef uint16_t (*rte_latency_stats_flow_type_fn)(struct rte_mbuf *pkt,
  69                                                         void *user_param);
  70
  71 /**
  72  *  Registers Rx/Tx callbacks for each active port, queue.
  73  *
  74  * @param samp_intvl
  75  *  Sampling time period in nano seconds, at which packet
  76  *  should be marked with time stamp.
  77  * @param user_cb
  78  *  Note: This param is for future flow based latency stats
  79  *  implementation.
  80  *  User callback to be called to get flow types of a packet.
  81  *  Used for flow based latency calculation.
  82  *  If the value is NULL, global stats will be calculated,
  83  *  else flow based latency stats will be calculated.
  84  *  For now just pass on the NULL value to this param.
  85  *  @return
  86  *   -1     : On error
  87  *   -ENOMEM: On error
  88  *    0     : On success
  89  */
  90 int rte_latencystats_init(uint64_t samp_intvl,
  91                         rte_latency_stats_flow_type_fn user_cb);
  92
  93 /**
  94  * Calculates the latency and jitter values internally, exposing the updated
  95  * values via *rte_latencystats_get* or the rte_metrics API.
  96  * @return:
  97  *  0      : on Success
  98  *  < 0    : Error in updating values.
  99  */
 100 int32_t rte_latencystats_update(void);
 101
 102 /**
 103  *  Removes registered Rx/Tx callbacks for each active port, queue.
 104  *
 105  *  @return
 106  *   -1: On error
 107  *    0: On success
 108  */
 109 int rte_latencystats_uninit(void);
 110
 111 /**
 112  * Retrieve names of latency statistics
 113  *
 114  * @param names
 115  *  Block of memory to insert names into. Must be at least size in capacity.
 116  *  If set to NULL, function returns required capacity.
 117  * @param size
 118  *  Capacity of latency stats names (number of names).
 119  * @return
 120  *   - positive value lower or equal to size: success. The return value
 121  *     is the number of entries filled in the stats table.
 122  *   - positive value higher than size: error, the given statistics table
 123  *     is too small. The return value corresponds to the size that should
 124  *     be given to succeed. The entries in the table are not valid and
 125  *     shall not be used by the caller.
 126  */
 127 int rte_latencystats_get_names(struct rte_metric_name *names,
 128                                 uint16_t size);
 129
 130 /**
 131  * Retrieve latency statistics.
 132  *
 133  * @param values
 134  *   A pointer to a table of structure of type *rte_metric_value*
 135  *   to be filled with latency statistics ids and values.
 136  *   This parameter can be set to NULL if size is 0.
 137  * @param size
 138  *   The size of the stats table, which should be large enough to store
 139  *   all the latency stats.
 140  * @return
 141  *   - positive value lower or equal to size: success. The return value
 142  *     is the number of entries filled in the stats table.
 143  *   - positive value higher than size: error, the given statistics table
 144  *     is too small. The return value corresponds to the size that should
 145  *     be given to succeed. The entries in the table are not valid and
 146  *     shall not be used by the caller.
 147  *   -ENOMEM: On failure.
 148  */
 149 int rte_latencystats_get(struct rte_metric_value *values,
 150                         uint16_t size);
 151
 152 #ifdef __cplusplus
 153 }
 154 #endif
 155
 156 #endif /* _RTE_LATENCYSTATS_H_ */