1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2017 Intel Corporation 3 */ 4 5 /** 6 * @file 7 * 8 * DPDK Metrics module 9 * 10 * Metrics are statistics that are not generated by PMDs, and hence 11 * are better reported through a mechanism that is independent from 12 * the ethdev-based extended statistics. Providers will typically 13 * be other libraries and consumers will typically be applications. 14 * 15 * Metric information is populated using a push model, where producers 16 * update the values contained within the metric library by calling 17 * an update function on the relevant metrics. Consumers receive 18 * metric information by querying the central metric data, which is 19 * held in shared memory. Currently only bulk querying of metrics 20 * by consumers is supported. 21 */ 22 23 #ifndef _RTE_METRICS_H_ 24 #define _RTE_METRICS_H_ 25 26 #include <stdint.h> 27 #include <rte_compat.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 extern int metrics_initialized; 34 35 /** Maximum length of metric name (including null-terminator) */ 36 #define RTE_METRICS_MAX_NAME_LEN 64 37 #define RTE_METRICS_MAX_METRICS 256 38 39 /** 40 * Global metric special id. 41 * 42 * When used for the port_id parameter when calling 43 * rte_metrics_update_metric() or rte_metrics_update_metric(), 44 * the global metric, which are not associated with any specific 45 * port (i.e. device), are updated. 46 */ 47 #define RTE_METRICS_GLOBAL -1 48 49 /** 50 * A name-key lookup for metrics. 51 * 52 * An array of this structure is returned by rte_metrics_get_names(). 53 * The struct rte_metric_value references these names via their array index. 54 */ 55 struct rte_metric_name { 56 /** String describing metric */ 57 char name[RTE_METRICS_MAX_NAME_LEN]; 58 }; 59 60 61 /** 62 * Metric value structure. 63 * 64 * This structure is used by rte_metrics_get_values() to return metrics, 65 * which are statistics that are not generated by PMDs. It maps a name key, 66 * which corresponds to an index in the array returned by 67 * rte_metrics_get_names(). 68 */ 69 struct rte_metric_value { 70 /** Numeric identifier of metric. */ 71 uint16_t key; 72 /** Value for metric */ 73 uint64_t value; 74 }; 75 76 /** 77 * Initializes metric module. This function must be called from 78 * a primary process before metrics are used. 79 * 80 * @param socket_id 81 * Socket to use for shared memory allocation. 82 */ 83 void rte_metrics_init(int socket_id); 84 85 /** 86 * @warning 87 * @b EXPERIMENTAL: this API may change without prior notice 88 * 89 * Deinitialize metric module. This function must be called from 90 * a primary process after all the metrics usage is over, to 91 * release the shared memory. 92 * 93 * @return 94 * -EINVAL - invalid parameter. 95 * -EIO: Error, unable to access metrics shared memory 96 * (rte_metrics_init() not called) 97 * 0 - success 98 */ 99 __rte_experimental 100 int rte_metrics_deinit(void); 101 102 /** 103 * Register a metric, making it available as a reporting parameter. 104 * 105 * Registering a metric is the way producers declare a parameter 106 * that they wish to be reported. Once registered, the associated 107 * numeric key can be obtained via rte_metrics_get_names(), which 108 * is required for updating said metric's value. 109 * 110 * @param name 111 * Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including 112 * the NULL terminator), it is truncated. 113 * 114 * @return 115 * - Zero or positive: Success (index key of new metric) 116 * - -EIO: Error, unable to access metrics shared memory 117 * (rte_metrics_init() not called) 118 * - -EINVAL: Error, invalid parameters 119 * - -ENOMEM: Error, maximum metrics reached 120 */ 121 int rte_metrics_reg_name(const char *name); 122 123 /** 124 * Register a set of metrics. 125 * 126 * This is a bulk version of rte_metrics_reg_names() and aside from 127 * handling multiple keys at once is functionally identical. 128 * 129 * @param names 130 * List of metric names 131 * 132 * @param cnt_names 133 * Number of metrics in set 134 * 135 * @return 136 * - Zero or positive: Success (index key of start of set) 137 * - -EIO: Error, unable to access metrics shared memory 138 * (rte_metrics_init() not called) 139 * - -EINVAL: Error, invalid parameters 140 * - -ENOMEM: Error, maximum metrics reached 141 */ 142 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names); 143 144 /** 145 * Get metric name-key lookup table. 146 * 147 * @param names 148 * A struct rte_metric_name array of at least *capacity* in size to 149 * receive key names. If this is NULL, function returns the required 150 * number of elements for this array. 151 * 152 * @param capacity 153 * Size (number of elements) of struct rte_metric_name array. 154 * Disregarded if names is NULL. 155 * 156 * @return 157 * - Positive value above capacity: error, *names* is too small. 158 * Return value is required size. 159 * - Positive value equal or less than capacity: Success. Return 160 * value is number of elements filled in. 161 * - Negative value: error. 162 */ 163 int rte_metrics_get_names( 164 struct rte_metric_name *names, 165 uint16_t capacity); 166 167 /** 168 * Get metric value table. 169 * 170 * @param port_id 171 * Port id to query 172 * 173 * @param values 174 * A struct rte_metric_value array of at least *capacity* in size to 175 * receive metric ids and values. If this is NULL, function returns 176 * the required number of elements for this array. 177 * 178 * @param capacity 179 * Size (number of elements) of struct rte_metric_value array. 180 * Disregarded if names is NULL. 181 * 182 * @return 183 * - Positive value above capacity: error, *values* is too small. 184 * Return value is required size. 185 * - Positive value equal or less than capacity: Success. Return 186 * value is number of elements filled in. 187 * - Negative value: error. 188 */ 189 int rte_metrics_get_values( 190 int port_id, 191 struct rte_metric_value *values, 192 uint16_t capacity); 193 194 /** 195 * Updates a metric 196 * 197 * @param port_id 198 * Port to update metrics for 199 * @param key 200 * Id of metric to update 201 * @param value 202 * New value 203 * 204 * @return 205 * - -EIO if unable to access shared metrics memory 206 * - Zero on success 207 */ 208 int rte_metrics_update_value( 209 int port_id, 210 uint16_t key, 211 const uint64_t value); 212 213 /** 214 * Updates a metric set. Note that it is an error to try to 215 * update across a set boundary. 216 * 217 * @param port_id 218 * Port to update metrics for 219 * @param key 220 * Base id of metrics set to update 221 * @param values 222 * Set of new values 223 * @param count 224 * Number of new values 225 * 226 * @return 227 * - -ERANGE if count exceeds metric set size 228 * - -EIO if unable to access shared metrics memory 229 * - Zero on success 230 */ 231 int rte_metrics_update_values( 232 int port_id, 233 uint16_t key, 234 const uint64_t *values, 235 uint32_t count); 236 237 #ifdef __cplusplus 238 } 239 #endif 240 241 #endif 242