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 * Deinitialize metric module. This function must be called from 87 * a primary process after all the metrics usage is over, to 88 * release the shared memory. 89 * 90 * @return 91 * -EINVAL - invalid parameter. 92 * -EIO: Error, unable to access metrics shared memory 93 * (rte_metrics_init() not called) 94 * 0 - success 95 */ 96 int rte_metrics_deinit(void); 97 98 /** 99 * Register a metric, making it available as a reporting parameter. 100 * 101 * Registering a metric is the way producers declare a parameter 102 * that they wish to be reported. Once registered, the associated 103 * numeric key can be obtained via rte_metrics_get_names(), which 104 * is required for updating said metric's value. 105 * 106 * @param name 107 * Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including 108 * the NULL terminator), it is truncated. 109 * 110 * @return 111 * - Zero or positive: Success (index key of new metric) 112 * - -EIO: Error, unable to access metrics shared memory 113 * (rte_metrics_init() not called) 114 * - -EINVAL: Error, invalid parameters 115 * - -ENOMEM: Error, maximum metrics reached 116 */ 117 int rte_metrics_reg_name(const char *name); 118 119 /** 120 * Register a set of metrics. 121 * 122 * This is a bulk version of rte_metrics_reg_names() and aside from 123 * handling multiple keys at once is functionally identical. 124 * 125 * @param names 126 * List of metric names 127 * 128 * @param cnt_names 129 * Number of metrics in set 130 * 131 * @return 132 * - Zero or positive: Success (index key of start of set) 133 * - -EIO: Error, unable to access metrics shared memory 134 * (rte_metrics_init() not called) 135 * - -EINVAL: Error, invalid parameters 136 * - -ENOMEM: Error, maximum metrics reached 137 */ 138 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names); 139 140 /** 141 * Get metric name-key lookup table. 142 * 143 * @param names 144 * A struct rte_metric_name array of at least *capacity* in size to 145 * receive key names. If this is NULL, function returns the required 146 * number of elements for this array. 147 * 148 * @param capacity 149 * Size (number of elements) of struct rte_metric_name array. 150 * Disregarded if names is NULL. 151 * 152 * @return 153 * - Positive value above capacity: error, *names* is too small. 154 * Return value is required size. 155 * - Positive value equal or less than capacity: Success. Return 156 * value is number of elements filled in. 157 * - Negative value: error. 158 */ 159 int rte_metrics_get_names( 160 struct rte_metric_name *names, 161 uint16_t capacity); 162 163 /** 164 * Get metric value table. 165 * 166 * @param port_id 167 * Port id to query 168 * 169 * @param values 170 * A struct rte_metric_value array of at least *capacity* in size to 171 * receive metric ids and values. If this is NULL, function returns 172 * the required number of elements for this array. 173 * 174 * @param capacity 175 * Size (number of elements) of struct rte_metric_value array. 176 * Disregarded if names is NULL. 177 * 178 * @return 179 * - Positive value above capacity: error, *values* is too small. 180 * Return value is required size. 181 * - Positive value equal or less than capacity: Success. Return 182 * value is number of elements filled in. 183 * - Negative value: error. 184 */ 185 int rte_metrics_get_values( 186 int port_id, 187 struct rte_metric_value *values, 188 uint16_t capacity); 189 190 /** 191 * Updates a metric 192 * 193 * @param port_id 194 * Port to update metrics for 195 * @param key 196 * Id of metric to update 197 * @param value 198 * New value 199 * 200 * @return 201 * - -EIO if unable to access shared metrics memory 202 * - Zero on success 203 */ 204 int rte_metrics_update_value( 205 int port_id, 206 uint16_t key, 207 const uint64_t value); 208 209 /** 210 * Updates a metric set. Note that it is an error to try to 211 * update across a set boundary. 212 * 213 * @param port_id 214 * Port to update metrics for 215 * @param key 216 * Base id of metrics set to update 217 * @param values 218 * Set of new values 219 * @param count 220 * Number of new values 221 * 222 * @return 223 * - -ERANGE if count exceeds metric set size 224 * - -EIO if unable to access shared metrics memory 225 * - Zero on success 226 */ 227 int rte_metrics_update_values( 228 int port_id, 229 uint16_t key, 230 const uint64_t *values, 231 uint32_t count); 232 233 #ifdef __cplusplus 234 } 235 #endif 236 237 #endif 238