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