4 * Copyright(c) 2017 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of Intel Corporation nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 * Metrics are statistics that are not generated by PMDs, and hence
40 * are better reported through a mechanism that is independent from
41 * the ethdev-based extended statistics. Providers will typically
42 * be other libraries and consumers will typically be applications.
44 * Metric information is populated using a push model, where producers
45 * update the values contained within the metric library by calling
46 * an update function on the relevant metrics. Consumers receive
47 * metric information by querying the central metric data, which is
48 * held in shared memory. Currently only bulk querying of metrics
49 * by consumers is supported.
52 #ifndef _RTE_METRICS_H_
53 #define _RTE_METRICS_H_
61 /** Maximum length of metric name (including null-terminator) */
62 #define RTE_METRICS_MAX_NAME_LEN 64
65 * Global metric special id.
67 * When used for the port_id parameter when calling
68 * rte_metrics_update_metric() or rte_metrics_update_metric(),
69 * the global metric, which are not associated with any specific
70 * port (i.e. device), are updated.
72 #define RTE_METRICS_GLOBAL -1
76 * A name-key lookup for metrics.
78 * An array of this structure is returned by rte_metrics_get_names().
79 * The struct rte_metric_value references these names via their array index.
81 struct rte_metric_name {
82 /** String describing metric */
83 char name[RTE_METRICS_MAX_NAME_LEN];
88 * Metric value structure.
90 * This structure is used by rte_metrics_get_values() to return metrics,
91 * which are statistics that are not generated by PMDs. It maps a name key,
92 * which corresponds to an index in the array returned by
93 * rte_metrics_get_names().
95 struct rte_metric_value {
96 /** Numeric identifier of metric. */
98 /** Value for metric */
104 * Initializes metric module. This function must be called from
105 * a primary process before metrics are used.
108 * Socket to use for shared memory allocation.
110 void rte_metrics_init(int socket_id);
113 * Register a metric, making it available as a reporting parameter.
115 * Registering a metric is the way producers declare a parameter
116 * that they wish to be reported. Once registered, the associated
117 * numeric key can be obtained via rte_metrics_get_names(), which
118 * is required for updating said metric's value.
121 * Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including
122 * the NULL terminator), it is truncated.
125 * - Zero or positive: Success (index key of new metric)
126 * - -EIO: Error, unable to access metrics shared memory
127 * (rte_metrics_init() not called)
128 * - -EINVAL: Error, invalid parameters
129 * - -ENOMEM: Error, maximum metrics reached
131 int rte_metrics_reg_name(const char *name);
134 * Register a set of metrics.
136 * This is a bulk version of rte_metrics_reg_names() and aside from
137 * handling multiple keys at once is functionally identical.
140 * List of metric names
143 * Number of metrics in set
146 * - Zero or positive: Success (index key of start of set)
147 * - -EIO: Error, unable to access metrics shared memory
148 * (rte_metrics_init() not called)
149 * - -EINVAL: Error, invalid parameters
150 * - -ENOMEM: Error, maximum metrics reached
152 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names);
155 * Get metric name-key lookup table.
158 * A struct rte_metric_name array of at least *capacity* in size to
159 * receive key names. If this is NULL, function returns the required
160 * number of elements for this array.
163 * Size (number of elements) of struct rte_metric_name array.
164 * Disregarded if names is NULL.
167 * - Positive value above capacity: error, *names* is too small.
168 * Return value is required size.
169 * - Positive value equal or less than capacity: Success. Return
170 * value is number of elements filled in.
171 * - Negative value: error.
173 int rte_metrics_get_names(
174 struct rte_metric_name *names,
178 * Get metric value table.
184 * A struct rte_metric_value array of at least *capacity* in size to
185 * receive metric ids and values. If this is NULL, function returns
186 * the required number of elements for this array.
189 * Size (number of elements) of struct rte_metric_value array.
190 * Disregarded if names is NULL.
193 * - Positive value above capacity: error, *values* is too small.
194 * Return value is required size.
195 * - Positive value equal or less than capacity: Success. Return
196 * value is number of elements filled in.
197 * - Negative value: error.
199 int rte_metrics_get_values(
201 struct rte_metric_value *values,
208 * Port to update metrics for
210 * Id of metric to update
215 * - -EIO if unable to access shared metrics memory
218 int rte_metrics_update_value(
221 const uint64_t value);
224 * Updates a metric set. Note that it is an error to try to
225 * update across a set boundary.
228 * Port to update metrics for
230 * Base id of metrics set to update
234 * Number of new values
237 * - -ERANGE if count exceeds metric set size
238 * - -EIO if unable to access shared metrics memory
241 int rte_metrics_update_values(
244 const uint64_t *values,