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_ */ 157