1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
8 #include <rte_compat.h>
10 #ifndef _RTE_TELEMETRY_H_
11 #define _RTE_TELEMETRY_H_
13 /** Maximum number of telemetry callbacks. */
14 #define TELEMETRY_MAX_CALLBACKS 64
15 /** Maximum length for string used in object. */
16 #define RTE_TEL_MAX_STRING_LEN 64
17 /** Maximum length of string. */
18 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
19 /** Maximum number of dictionary entries. */
20 #define RTE_TEL_MAX_DICT_ENTRIES 256
21 /** Maximum number of array entries. */
22 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
31 * All functions in this file may be changed or removed without prior notice.
33 * The telemetry library provides a method to retrieve statistics from
34 * DPDK by sending a request message over a socket. DPDK will send
35 * a JSON encoded response containing telemetry data.
38 /** opaque structure used internally for managing data from callbacks */
42 * The types of data that can be managed in arrays or dicts.
43 * For arrays, this must be specified at creation time, while for
44 * dicts this is specified implicitly each time an element is added
45 * via calling a type-specific function.
47 enum rte_tel_value_type {
48 RTE_TEL_STRING_VAL, /** a string value */
49 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
50 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
51 RTE_TEL_CONTAINER, /** a container struct */
55 * Start an array of the specified type for returning from a callback
58 * The data structure passed to the callback
60 * The type of the array of data
62 * 0 on success, negative errno on error
66 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
69 * Start a dictionary of values for returning from a callback
72 * The data structure passed to the callback
74 * 0 on success, negative errno on error
78 rte_tel_data_start_dict(struct rte_tel_data *d);
81 * Set a string for returning from a callback
84 * The data structure passed to the callback
86 * The string to be returned in the data structure
88 * 0 on success, negative errno on error, E2BIG on string truncation
92 rte_tel_data_string(struct rte_tel_data *d, const char *str);
95 * Add a string to an array.
96 * The array must have been started by rte_tel_data_start_array() with
97 * RTE_TEL_STRING_VAL as the type parameter.
100 * The data structure passed to the callback
102 * The string to be returned in the array
104 * 0 on success, negative errno on error, E2BIG on string truncation
108 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
111 * Add an int to an array.
112 * The array must have been started by rte_tel_data_start_array() with
113 * RTE_TEL_INT_VAL as the type parameter.
116 * The data structure passed to the callback
118 * The number to be returned in the array
120 * 0 on success, negative errno on error
124 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
127 * Add a uint64_t to an array.
128 * The array must have been started by rte_tel_data_start_array() with
129 * RTE_TEL_U64_VAL as the type parameter.
132 * The data structure passed to the callback
134 * The number to be returned in the array
136 * 0 on success, negative errno on error
140 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
143 * Add a container to an array. A container is an existing telemetry data
144 * array. The array the container is to be added to must have been started by
145 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
146 * The container type must be an array of type uint64_t/int/string.
149 * The data structure passed to the callback
151 * The pointer to the container to be stored in the array.
153 * Flag to indicate that the container memory should not be automatically
154 * freed by the telemetry library once it has finished with the data.
155 * 1 = keep, 0 = free.
157 * 0 on success, negative errno on error
161 rte_tel_data_add_array_container(struct rte_tel_data *d,
162 struct rte_tel_data *val, int keep);
165 * Add a string value to a dictionary.
166 * The dict must have been started by rte_tel_data_start_dict().
169 * The data structure passed to the callback
171 * The name the value is to be stored under in the dict
173 * The string to be stored in the dict
175 * 0 on success, negative errno on error, E2BIG on string truncation of
176 * either name or value.
180 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
184 * Add an int value to a dictionary.
185 * The dict must have been started by rte_tel_data_start_dict().
188 * The data structure passed to the callback
190 * The name the value is to be stored under in the dict
192 * The number to be stored in the dict
194 * 0 on success, negative errno on error, E2BIG on string truncation of name.
198 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
201 * Add a uint64_t value to a dictionary.
202 * The dict must have been started by rte_tel_data_start_dict().
205 * The data structure passed to the callback
207 * The name the value is to be stored under in the dict
209 * The number to be stored in the dict
211 * 0 on success, negative errno on error, E2BIG on string truncation of name.
215 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
216 const char *name, uint64_t val);
219 * Add a container to a dictionary. A container is an existing telemetry data
220 * array. The dict the container is to be added to must have been started by
221 * rte_tel_data_start_dict(). The container must be an array of type
222 * uint64_t/int/string.
225 * The data structure passed to the callback
227 * The name the value is to be stored under in the dict.
229 * The pointer to the container to be stored in the dict.
231 * Flag to indicate that the container memory should not be automatically
232 * freed by the telemetry library once it has finished with the data.
233 * 1 = keep, 0 = free.
235 * 0 on success, negative errno on error
239 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
240 struct rte_tel_data *val, int keep);
243 * This telemetry callback is used when registering a telemetry command.
244 * It handles getting and formatting information to be returned to telemetry
248 * The cmd that was requested by the client.
250 * Contains data required by the callback function.
252 * The information to be returned to the caller.
255 * Length of buffer used on success.
257 * Negative integer on error.
259 typedef int (*telemetry_cb)(const char *cmd, const char *params,
260 struct rte_tel_data *info);
263 * Used for handling data received over a telemetry socket.
266 * ID for the socket to be used by the handler.
271 typedef void * (*handler)(void *sock_id);
274 * Used when registering a command and callback function with telemetry.
277 * The command to register with telemetry.
279 * Callback function to be called when the command is requested.
281 * Help text for the command.
286 * -EINVAL for invalid parameters failure.
288 * -ENOENT if max callbacks limit has been reached.
292 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
296 * Get a pointer to a container with memory allocated. The container is to be
297 * used embedded within an existing telemetry dict/array.
300 * Pointer to a container.
303 struct rte_tel_data *
304 rte_tel_data_alloc(void);
308 * Free a container that has memory allocated.
311 * Pointer to container.
316 rte_tel_data_free(struct rte_tel_data *data);