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