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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
/* SPDX-License-Identifier: BSD-3-Clause
* Copyright(c) 2018 Intel Corporation
*/
#include <stdint.h>
#include <rte_compat.h>
#ifndef _RTE_TELEMETRY_H_
#define _RTE_TELEMETRY_H_
/** Maximum number of telemetry callbacks. */
#define TELEMETRY_MAX_CALLBACKS 64
/** Maximum length for string used in object. */
#define RTE_TEL_MAX_STRING_LEN 64
/** Maximum length of string. */
#define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
/** Maximum number of dictionary entries. */
#define RTE_TEL_MAX_DICT_ENTRIES 256
/** Maximum number of array entries. */
#define RTE_TEL_MAX_ARRAY_ENTRIES 512
/**
* @warning
* @b EXPERIMENTAL: all functions in this file may change without prior notice
*
* @file
* RTE Telemetry
*
* The telemetry library provides a method to retrieve statistics from
* DPDK by sending a request message over a socket. DPDK will send
* a JSON encoded response containing telemetry data.
***/
/** opaque structure used internally for managing data from callbacks */
struct rte_tel_data;
/**
* The types of data that can be managed in arrays or dicts.
* For arrays, this must be specified at creation time, while for
* dicts this is specified implicitly each time an element is added
* via calling a type-specific function.
*/
enum rte_tel_value_type {
RTE_TEL_STRING_VAL, /** a string value */
RTE_TEL_INT_VAL, /** a signed 32-bit int value */
RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
};
/**
* Start an array of the specified type for returning from a callback
*
* @param d
* The data structure passed to the callback
* @param type
* The type of the array of data
* @return
* 0 on success, negative errno on error
*/
__rte_experimental
int
rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
/**
* Start a dictionary of values for returning from a callback
*
* @param d
* The data structure passed to the callback
* @return
* 0 on success, negative errno on error
*/
__rte_experimental
int
rte_tel_data_start_dict(struct rte_tel_data *d);
/**
* Set a string for returning from a callback
*
* @param d
* The data structure passed to the callback
* @param str
* The string to be returned in the data structure
* @return
* 0 on success, negative errno on error, E2BIG on string truncation
*/
__rte_experimental
int
rte_tel_data_string(struct rte_tel_data *d, const char *str);
/**
* Add a string to an array.
* The array must have been started by rte_tel_data_start_array() with
* RTE_TEL_STRING_VAL as the type parameter.
*
* @param d
* The data structure passed to the callback
* @param str
* The string to be returned in the array
* @return
* 0 on success, negative errno on error, E2BIG on string truncation
*/
__rte_experimental
int
rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
/**
* Add an int to an array.
* The array must have been started by rte_tel_data_start_array() with
* RTE_TEL_INT_VAL as the type parameter.
*
* @param d
* The data structure passed to the callback
* @param x
* The number to be returned in the array
* @return
* 0 on success, negative errno on error
*/
__rte_experimental
int
rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
/**
* Add a uint64_t to an array.
* The array must have been started by rte_tel_data_start_array() with
* RTE_TEL_U64_VAL as the type parameter.
*
* @param d
* The data structure passed to the callback
* @param x
* The number to be returned in the array
* @return
* 0 on success, negative errno on error
*/
__rte_experimental
int
rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
/**
* Add a string value to a dictionary.
* The dict must have been started by rte_tel_data_start_dict().
*
* @param d
* The data structure passed to the callback
* @param name
* The name the value is to be stored under in the dict
* @param val
* The string to be stored in the dict
* @return
* 0 on success, negative errno on error, E2BIG on string truncation of
* either name or value.
*/
__rte_experimental
int
rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
const char *val);
/**
* Add an int value to a dictionary.
* The dict must have been started by rte_tel_data_start_dict().
*
* @param d
* The data structure passed to the callback
* @param name
* The name the value is to be stored under in the dict
* @param val
* The number to be stored in the dict
* @return
* 0 on success, negative errno on error, E2BIG on string truncation of name.
*/
__rte_experimental
int
rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
/**
* Add a uint64_t value to a dictionary.
* The dict must have been started by rte_tel_data_start_dict().
*
* @param d
* The data structure passed to the callback
* @param name
* The name the value is to be stored under in the dict
* @param val
* The number to be stored in the dict
* @return
* 0 on success, negative errno on error, E2BIG on string truncation of name.
*/
__rte_experimental
int
rte_tel_data_add_dict_u64(struct rte_tel_data *d,
const char *name, uint64_t val);
/**
* This telemetry callback is used when registering a telemetry command.
* It handles getting and formatting information to be returned to telemetry
* when requested.
*
* @param cmd
* The cmd that was requested by the client.
* @param params
* Contains data required by the callback function.
* @param info
* The information to be returned to the caller.
*
* @return
* Length of buffer used on success.
* @return
* Negative integer on error.
*/
typedef int (*telemetry_cb)(const char *cmd, const char *params,
struct rte_tel_data *info);
/**
* Used for handling data received over a telemetry socket.
*
* @param sock_id
* ID for the socket to be used by the handler.
*
* @return
* Void.
*/
typedef void * (*handler)(void *sock_id);
/**
* Used when registering a command and callback function with telemetry.
*
* @param cmd
* The command to register with telemetry.
* @param fn
* Callback function to be called when the command is requested.
* @param help
* Help text for the command.
*
* @return
* 0 on success.
* @return
* -EINVAL for invalid parameters failure.
* @return
* -ENOENT if max callbacks limit has been reached.
*/
__rte_experimental
int
rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
/**
* @internal
* Initialize Telemetry.
*
* @param runtime_dir
* The runtime directory of DPDK.
* @param cpuset
* The CPU set to be used for setting the thread affinity.
* @param err_str
* This err_str pointer should point to NULL on entry. In the case of an error
* or warning, it will be non-NULL on exit.
*
* @return
* 0 on success.
* @return
* -1 on failure.
*/
__rte_experimental
int
rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
const char **err_str);
#endif
|
