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