1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
8 #include <rte_compat.h>
11 #ifndef _RTE_TELEMETRY_H_
12 #define _RTE_TELEMETRY_H_
14 /** Maximum number of telemetry callbacks. */
15 #define TELEMETRY_MAX_CALLBACKS 64
16 /** Maximum length for string used in object. */
17 #define RTE_TEL_MAX_STRING_LEN 64
18 /** Maximum length of string. */
19 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
20 /** Maximum number of dictionary entries. */
21 #define RTE_TEL_MAX_DICT_ENTRIES 256
22 /** Maximum number of array entries. */
23 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
32 * All functions in this file may be changed or removed without prior notice.
34 * The telemetry library provides a method to retrieve statistics from
35 * DPDK by sending a request message over a socket. DPDK will send
36 * a JSON encoded response containing telemetry data.
39 /** opaque structure used internally for managing data from callbacks */
43 * The types of data that can be managed in arrays or dicts.
44 * For arrays, this must be specified at creation time, while for
45 * dicts this is specified implicitly each time an element is added
46 * via calling a type-specific function.
48 enum rte_tel_value_type {
49 RTE_TEL_STRING_VAL, /** a string value */
50 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
51 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
52 RTE_TEL_CONTAINER, /** a container struct */
56 * Start an array of the specified type for returning from a callback
59 * The data structure passed to the callback
61 * The type of the array of data
63 * 0 on success, negative errno on error
67 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
70 * Start a dictionary of values for returning from a callback
73 * The data structure passed to the callback
75 * 0 on success, negative errno on error
79 rte_tel_data_start_dict(struct rte_tel_data *d);
82 * Set a string for returning from a callback
85 * The data structure passed to the callback
87 * The string to be returned in the data structure
89 * 0 on success, negative errno on error, E2BIG on string truncation
93 rte_tel_data_string(struct rte_tel_data *d, const char *str);
96 * Add a string to an array.
97 * The array must have been started by rte_tel_data_start_array() with
98 * RTE_TEL_STRING_VAL as the type parameter.
101 * The data structure passed to the callback
103 * The string to be returned in the array
105 * 0 on success, negative errno on error, E2BIG on string truncation
109 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
112 * Add an int to an array.
113 * The array must have been started by rte_tel_data_start_array() with
114 * RTE_TEL_INT_VAL as the type parameter.
117 * The data structure passed to the callback
119 * The number to be returned in the array
121 * 0 on success, negative errno on error
125 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
128 * Add a uint64_t to an array.
129 * The array must have been started by rte_tel_data_start_array() with
130 * RTE_TEL_U64_VAL as the type parameter.
133 * The data structure passed to the callback
135 * The number to be returned in the array
137 * 0 on success, negative errno on error
141 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
144 * Add a container to an array. A container is an existing telemetry data
145 * array. The array the container is to be added to must have been started by
146 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
147 * The container type must be an array of type uint64_t/int/string.
150 * The data structure passed to the callback
152 * The pointer to the container to be stored in the array.
154 * Flag to indicate that the container memory should not be automatically
155 * freed by the telemetry library once it has finished with the data.
156 * 1 = keep, 0 = free.
158 * 0 on success, negative errno on error
162 rte_tel_data_add_array_container(struct rte_tel_data *d,
163 struct rte_tel_data *val, int keep);
166 * Add a string value to a dictionary.
167 * The dict must have been started by rte_tel_data_start_dict().
170 * The data structure passed to the callback
172 * The name the value is to be stored under in the dict
174 * The string to be stored in the dict
176 * 0 on success, negative errno on error, E2BIG on string truncation of
177 * either name or value.
181 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
185 * Add an int value to a dictionary.
186 * The dict must have been started by rte_tel_data_start_dict().
189 * The data structure passed to the callback
191 * The name the value is to be stored under in the dict
193 * The number to be stored in the dict
195 * 0 on success, negative errno on error, E2BIG on string truncation of name.
199 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
202 * Add a uint64_t value to a dictionary.
203 * The dict must have been started by rte_tel_data_start_dict().
206 * The data structure passed to the callback
208 * The name the value is to be stored under in the dict
210 * The number to be stored in the dict
212 * 0 on success, negative errno on error, E2BIG on string truncation of name.
216 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
217 const char *name, uint64_t val);
220 * Add a container to a dictionary. A container is an existing telemetry data
221 * array. The dict the container is to be added to must have been started by
222 * rte_tel_data_start_dict(). The container must be an array of type
223 * uint64_t/int/string.
226 * The data structure passed to the callback
228 * The name the value is to be stored under in the dict.
230 * The pointer to the container to be stored in the dict.
232 * Flag to indicate that the container memory should not be automatically
233 * freed by the telemetry library once it has finished with the data.
234 * 1 = keep, 0 = free.
236 * 0 on success, negative errno on error
240 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
241 struct rte_tel_data *val, int keep);
244 * This telemetry callback is used when registering a telemetry command.
245 * It handles getting and formatting information to be returned to telemetry
249 * The cmd that was requested by the client.
251 * Contains data required by the callback function.
253 * The information to be returned to the caller.
256 * Length of buffer used on success.
258 * Negative integer on error.
260 typedef int (*telemetry_cb)(const char *cmd, const char *params,
261 struct rte_tel_data *info);
264 * Used for handling data received over a telemetry socket.
267 * ID for the socket to be used by the handler.
272 typedef void * (*handler)(void *sock_id);
275 * Used when registering a command and callback function with telemetry.
278 * The command to register with telemetry.
280 * Callback function to be called when the command is requested.
282 * Help text for the command.
287 * -EINVAL for invalid parameters failure.
289 * -ENOENT if max callbacks limit has been reached.
293 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
297 * Initialize Telemetry.
300 * The runtime directory of DPDK.
302 * The CPU set to be used for setting the thread affinity.
304 * This err_str pointer should point to NULL on entry. In the case of an error
305 * or warning, it will be non-NULL on exit.
314 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
315 const char **err_str);
318 * Get a pointer to a container with memory allocated. The container is to be
319 * used embedded within an existing telemetry dict/array.
322 * Pointer to a container.
325 struct rte_tel_data *
326 rte_tel_data_alloc(void);
330 * Free a container that has memory allocated.
333 * Pointer to container.
338 rte_tel_data_free(struct rte_tel_data *data);