1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
7 #include <rte_compat.h>
9 #ifndef _RTE_TELEMETRY_H_
10 #define _RTE_TELEMETRY_H_
12 /** Maximum number of telemetry callbacks. */
13 #define TELEMETRY_MAX_CALLBACKS 64
14 /** Maximum length for string used in object. */
15 #define RTE_TEL_MAX_STRING_LEN 64
16 /** Maximum length of string. */
17 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
18 /** Maximum number of dictionary entries. */
19 #define RTE_TEL_MAX_DICT_ENTRIES 256
20 /** Maximum number of array entries. */
21 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
30 * All functions in this file may be changed or removed without prior notice.
32 * The telemetry library provides a method to retrieve statistics from
33 * DPDK by sending a request message over a socket. DPDK will send
34 * a JSON encoded response containing telemetry data.
37 /** opaque structure used internally for managing data from callbacks */
41 * The types of data that can be managed in arrays or dicts.
42 * For arrays, this must be specified at creation time, while for
43 * dicts this is specified implicitly each time an element is added
44 * via calling a type-specific function.
46 enum rte_tel_value_type {
47 RTE_TEL_STRING_VAL, /** a string value */
48 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
49 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
50 RTE_TEL_CONTAINER, /** a container struct */
54 * Start an array of the specified type for returning from a callback
57 * The data structure passed to the callback
59 * The type of the array of data
61 * 0 on success, negative errno on error
65 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
68 * Start a dictionary of values for returning from a callback
71 * The data structure passed to the callback
73 * 0 on success, negative errno on error
77 rte_tel_data_start_dict(struct rte_tel_data *d);
80 * Set a string for returning from a callback
83 * The data structure passed to the callback
85 * The string to be returned in the data structure
87 * 0 on success, negative errno on error, E2BIG on string truncation
91 rte_tel_data_string(struct rte_tel_data *d, const char *str);
94 * Add a string to an array.
95 * The array must have been started by rte_tel_data_start_array() with
96 * RTE_TEL_STRING_VAL as the type parameter.
99 * The data structure passed to the callback
101 * The string to be returned in the array
103 * 0 on success, negative errno on error, E2BIG on string truncation
107 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
110 * Add an int to an array.
111 * The array must have been started by rte_tel_data_start_array() with
112 * RTE_TEL_INT_VAL as the type parameter.
115 * The data structure passed to the callback
117 * The number to be returned in the array
119 * 0 on success, negative errno on error
123 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
126 * Add a uint64_t to an array.
127 * The array must have been started by rte_tel_data_start_array() with
128 * RTE_TEL_U64_VAL as the type parameter.
131 * The data structure passed to the callback
133 * The number to be returned in the array
135 * 0 on success, negative errno on error
139 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
142 * Add a container to an array. A container is an existing telemetry data
143 * array. The array the container is to be added to must have been started by
144 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
145 * The container type must be an array of type uint64_t/int/string.
148 * The data structure passed to the callback
150 * The pointer to the container to be stored in the array.
152 * Flag to indicate that the container memory should not be automatically
153 * freed by the telemetry library once it has finished with the data.
154 * 1 = keep, 0 = free.
156 * 0 on success, negative errno on error
160 rte_tel_data_add_array_container(struct rte_tel_data *d,
161 struct rte_tel_data *val, int keep);
164 * Add a string value to a dictionary.
165 * The dict must have been started by rte_tel_data_start_dict().
168 * The data structure passed to the callback
170 * The name the value is to be stored under in the dict
172 * The string to be stored in the dict
174 * 0 on success, negative errno on error, E2BIG on string truncation of
175 * either name or value.
179 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
183 * Add an int value to a dictionary.
184 * The dict must have been started by rte_tel_data_start_dict().
187 * The data structure passed to the callback
189 * The name the value is to be stored under in the dict
191 * The number to be stored in the dict
193 * 0 on success, negative errno on error, E2BIG on string truncation of name.
197 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
200 * Add a uint64_t value to a dictionary.
201 * The dict must have been started by rte_tel_data_start_dict().
204 * The data structure passed to the callback
206 * The name the value is to be stored under in the dict
208 * The number to be stored in the dict
210 * 0 on success, negative errno on error, E2BIG on string truncation of name.
214 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
215 const char *name, uint64_t val);
218 * Add a container to a dictionary. A container is an existing telemetry data
219 * array. The dict the container is to be added to must have been started by
220 * rte_tel_data_start_dict(). The container must be an array of type
221 * uint64_t/int/string.
224 * The data structure passed to the callback
226 * The name the value is to be stored under in the dict.
228 * The pointer to the container to be stored in the dict.
230 * Flag to indicate that the container memory should not be automatically
231 * freed by the telemetry library once it has finished with the data.
232 * 1 = keep, 0 = free.
234 * 0 on success, negative errno on error
238 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
239 struct rte_tel_data *val, int keep);
242 * This telemetry callback is used when registering a telemetry command.
243 * It handles getting and formatting information to be returned to telemetry
247 * The cmd that was requested by the client.
249 * Contains data required by the callback function.
251 * The information to be returned to the caller.
254 * Length of buffer used on success.
256 * Negative integer on error.
258 typedef int (*telemetry_cb)(const char *cmd, const char *params,
259 struct rte_tel_data *info);
262 * Used for handling data received over a telemetry socket.
265 * ID for the socket to be used by the handler.
270 typedef void * (*handler)(void *sock_id);
273 * Used when registering a command and callback function with telemetry.
276 * The command to register with telemetry.
278 * Callback function to be called when the command is requested.
280 * Help text for the command.
285 * -EINVAL for invalid parameters failure.
287 * -ENOENT if max callbacks limit has been reached.
291 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
295 * Initialize Telemetry.
298 * The runtime directory of DPDK.
300 * The CPU set to be used for setting the thread affinity.
302 * This err_str pointer should point to NULL on entry. In the case of an error
303 * or warning, it will be non-NULL on exit.
312 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
313 const char **err_str);
316 * Get a pointer to a container with memory allocated. The container is to be
317 * used embedded within an existing telemetry dict/array.
320 * Pointer to a container.
323 struct rte_tel_data *
324 rte_tel_data_alloc(void);
328 * Free a container that has memory allocated.
331 * Pointer to container.
336 rte_tel_data_free(struct rte_tel_data *data);