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_
16 /** Maximum length for string used in object. */
17 #define RTE_TEL_MAX_STRING_LEN 128
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
30 * The telemetry library provides a method to retrieve statistics from
31 * DPDK by sending a request message over a socket. DPDK will send
32 * a JSON encoded response containing telemetry data.
35 /** opaque structure used internally for managing data from callbacks */
39 * The types of data that can be managed in arrays or dicts.
40 * For arrays, this must be specified at creation time, while for
41 * dicts this is specified implicitly each time an element is added
42 * via calling a type-specific function.
44 enum rte_tel_value_type {
45 RTE_TEL_STRING_VAL, /** a string value */
46 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
47 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
48 RTE_TEL_CONTAINER, /** a container struct */
52 * Start an array of the specified type for returning from a callback
55 * The data structure passed to the callback
57 * The type of the array of data
59 * 0 on success, negative errno on error
62 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
65 * Start a dictionary of values for returning from a callback
68 * The data structure passed to the callback
70 * 0 on success, negative errno on error
73 rte_tel_data_start_dict(struct rte_tel_data *d);
76 * Set a string for returning from a callback
79 * The data structure passed to the callback
81 * The string to be returned in the data structure
83 * 0 on success, negative errno on error, E2BIG on string truncation
86 rte_tel_data_string(struct rte_tel_data *d, const char *str);
89 * Add a string to an array.
90 * The array must have been started by rte_tel_data_start_array() with
91 * RTE_TEL_STRING_VAL as the type parameter.
94 * The data structure passed to the callback
96 * The string to be returned in the array
98 * 0 on success, negative errno on error, E2BIG on string truncation
101 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
104 * Add an int to an array.
105 * The array must have been started by rte_tel_data_start_array() with
106 * RTE_TEL_INT_VAL as the type parameter.
109 * The data structure passed to the callback
111 * The number to be returned in the array
113 * 0 on success, negative errno on error
116 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
119 * Add a uint64_t to an array.
120 * The array must have been started by rte_tel_data_start_array() with
121 * RTE_TEL_U64_VAL as the type parameter.
124 * The data structure passed to the callback
126 * The number to be returned in the array
128 * 0 on success, negative errno on error
131 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
134 * Add a container to an array. A container is an existing telemetry data
135 * array. The array the container is to be added to must have been started by
136 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
137 * The container type must be an array of type uint64_t/int/string.
140 * The data structure passed to the callback
142 * The pointer to the container to be stored in the array.
144 * Flag to indicate that the container memory should not be automatically
145 * freed by the telemetry library once it has finished with the data.
146 * 1 = keep, 0 = free.
148 * 0 on success, negative errno on error
151 rte_tel_data_add_array_container(struct rte_tel_data *d,
152 struct rte_tel_data *val, int keep);
155 * Add a string value to a dictionary.
156 * The dict must have been started by rte_tel_data_start_dict().
159 * The data structure passed to the callback
161 * The name the value is to be stored under in the dict
163 * The string to be stored in the dict
165 * 0 on success, negative errno on error, E2BIG on string truncation of
166 * either name or value.
169 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
173 * Add an int value to a dictionary.
174 * The dict must have been started by rte_tel_data_start_dict().
177 * The data structure passed to the callback
179 * The name the value is to be stored under in the dict
181 * The number to be stored in the dict
183 * 0 on success, negative errno on error, E2BIG on string truncation of name.
186 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
189 * Add a uint64_t value to a dictionary.
190 * The dict must have been started by rte_tel_data_start_dict().
193 * The data structure passed to the callback
195 * The name the value is to be stored under in the dict
197 * The number to be stored in the dict
199 * 0 on success, negative errno on error, E2BIG on string truncation of name.
202 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
203 const char *name, uint64_t val);
206 * Add a container to a dictionary. A container is an existing telemetry data
207 * array. The dict the container is to be added to must have been started by
208 * rte_tel_data_start_dict(). The container must be an array of type
209 * uint64_t/int/string.
212 * The data structure passed to the callback
214 * The name the value is to be stored under in the dict.
216 * The pointer to the container to be stored in the dict.
218 * Flag to indicate that the container memory should not be automatically
219 * freed by the telemetry library once it has finished with the data.
220 * 1 = keep, 0 = free.
222 * 0 on success, negative errno on error
225 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
226 struct rte_tel_data *val, int keep);
229 * This telemetry callback is used when registering a telemetry command.
230 * It handles getting and formatting information to be returned to telemetry
234 * The cmd that was requested by the client.
236 * Contains data required by the callback function.
238 * The information to be returned to the caller.
241 * Length of buffer used on success.
243 * Negative integer on error.
245 typedef int (*telemetry_cb)(const char *cmd, const char *params,
246 struct rte_tel_data *info);
249 * Used for handling data received over a telemetry socket.
252 * ID for the socket to be used by the handler.
257 typedef void * (*handler)(void *sock_id);
260 * Used when registering a command and callback function with telemetry.
263 * The command to register with telemetry.
265 * Callback function to be called when the command is requested.
267 * Help text for the command.
272 * -EINVAL for invalid parameters failure.
274 * -ENOMEM for mem allocation failure.
277 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
281 * Get a pointer to a container with memory allocated. The container is to be
282 * used embedded within an existing telemetry dict/array.
285 * Pointer to a container.
287 struct rte_tel_data *
288 rte_tel_data_alloc(void);
292 * Free a container that has memory allocated.
295 * Pointer to container.
299 rte_tel_data_free(struct rte_tel_data *data);