1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
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.
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.
23 #ifndef _RTE_METRICS_H_
24 #define _RTE_METRICS_H_
27 #include <rte_compat.h>
33 /** Maximum length of metric name (including null-terminator) */
34 #define RTE_METRICS_MAX_NAME_LEN 64
35 #define RTE_METRICS_MAX_METRICS 256
38 * Global metric special id.
40 * When used for the port_id parameter when calling
41 * rte_metrics_update_metric() or rte_metrics_update_metric(),
42 * the global metric, which are not associated with any specific
43 * port (i.e. device), are updated.
45 #define RTE_METRICS_GLOBAL -1
48 * A name-key lookup for metrics.
50 * An array of this structure is returned by rte_metrics_get_names().
51 * The struct rte_metric_value references these names via their array index.
53 struct rte_metric_name {
54 /** String describing metric */
55 char name[RTE_METRICS_MAX_NAME_LEN];
60 * Metric value structure.
62 * This structure is used by rte_metrics_get_values() to return metrics,
63 * which are statistics that are not generated by PMDs. It maps a name key,
64 * which corresponds to an index in the array returned by
65 * rte_metrics_get_names().
67 struct rte_metric_value {
68 /** Numeric identifier of metric. */
70 /** Value for metric */
75 * Initializes metric module. This function must be called from
76 * a primary process before metrics are used.
79 * Socket to use for shared memory allocation.
81 void rte_metrics_init(int socket_id);
85 * @b EXPERIMENTAL: this API may change without prior notice
87 * Deinitialize metric module. This function must be called from
88 * a primary process after all the metrics usage is over, to
89 * release the shared memory.
92 * -EINVAL - invalid parameter.
93 * -EIO: Error, unable to access metrics shared memory
94 * (rte_metrics_init() not called)
98 int rte_metrics_deinit(void);
101 * Register a metric, making it available as a reporting parameter.
103 * Registering a metric is the way producers declare a parameter
104 * that they wish to be reported. Once registered, the associated
105 * numeric key can be obtained via rte_metrics_get_names(), which
106 * is required for updating said metric's value.
109 * Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including
110 * the NULL terminator), it is truncated.
113 * - Zero or positive: Success (index key of new metric)
114 * - -EIO: Error, unable to access metrics shared memory
115 * (rte_metrics_init() not called)
116 * - -EINVAL: Error, invalid parameters
117 * - -ENOMEM: Error, maximum metrics reached
119 int rte_metrics_reg_name(const char *name);
122 * Register a set of metrics.
124 * This is a bulk version of rte_metrics_reg_names() and aside from
125 * handling multiple keys at once is functionally identical.
128 * List of metric names
131 * Number of metrics in set
134 * - Zero or positive: Success (index key of start of set)
135 * - -EIO: Error, unable to access metrics shared memory
136 * (rte_metrics_init() not called)
137 * - -EINVAL: Error, invalid parameters
138 * - -ENOMEM: Error, maximum metrics reached
140 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names);
143 * Get metric name-key lookup table.
146 * A struct rte_metric_name array of at least *capacity* in size to
147 * receive key names. If this is NULL, function returns the required
148 * number of elements for this array.
151 * Size (number of elements) of struct rte_metric_name array.
152 * Disregarded if names is NULL.
155 * - Positive value above capacity: error, *names* is too small.
156 * Return value is required size.
157 * - Positive value equal or less than capacity: Success. Return
158 * value is number of elements filled in.
159 * - Negative value: error.
161 int rte_metrics_get_names(
162 struct rte_metric_name *names,
166 * Get metric value table.
172 * A struct rte_metric_value array of at least *capacity* in size to
173 * receive metric ids and values. If this is NULL, function returns
174 * the required number of elements for this array.
177 * Size (number of elements) of struct rte_metric_value array.
178 * Disregarded if names is NULL.
181 * - Positive value above capacity: error, *values* is too small.
182 * Return value is required size.
183 * - Positive value equal or less than capacity: Success. Return
184 * value is number of elements filled in.
185 * - Negative value: error.
187 int rte_metrics_get_values(
189 struct rte_metric_value *values,
196 * Port to update metrics for
198 * Id of metric to update
203 * - -EIO if unable to access shared metrics memory
206 int rte_metrics_update_value(
209 const uint64_t value);
212 * Updates a metric set. Note that it is an error to try to
213 * update across a set boundary.
216 * Port to update metrics for
218 * Base id of metrics set to update
222 * Number of new values
225 * - -ERANGE if count exceeds metric set size
226 * - -EIO if unable to access shared metrics memory
229 int rte_metrics_update_values(
232 const uint64_t *values,