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