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