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 length for string used in object. */
13 #define RTE_TEL_MAX_STRING_LEN 128
14 /** Maximum length of string. */
15 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
16 /** Maximum number of dictionary entries. */
17 #define RTE_TEL_MAX_DICT_ENTRIES 256
18 /** Maximum number of array entries. */
19 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
28 * All functions in this file may be changed or removed without prior notice.
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
63 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
66 * Start a dictionary of values for returning from a callback
69 * The data structure passed to the callback
71 * 0 on success, negative errno on error
75 rte_tel_data_start_dict(struct rte_tel_data *d);
78 * Set a string for returning from a callback
81 * The data structure passed to the callback
83 * The string to be returned in the data structure
85 * 0 on success, negative errno on error, E2BIG on string truncation
89 rte_tel_data_string(struct rte_tel_data *d, const char *str);
92 * Add a string to an array.
93 * The array must have been started by rte_tel_data_start_array() with
94 * RTE_TEL_STRING_VAL as the type parameter.
97 * The data structure passed to the callback
99 * The string to be returned in the array
101 * 0 on success, negative errno on error, E2BIG on string truncation
105 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
108 * Add an int to an array.
109 * The array must have been started by rte_tel_data_start_array() with
110 * RTE_TEL_INT_VAL as the type parameter.
113 * The data structure passed to the callback
115 * The number to be returned in the array
117 * 0 on success, negative errno on error
121 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
124 * Add a uint64_t to an array.
125 * The array must have been started by rte_tel_data_start_array() with
126 * RTE_TEL_U64_VAL as the type parameter.
129 * The data structure passed to the callback
131 * The number to be returned in the array
133 * 0 on success, negative errno on error
137 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
140 * Add a container to an array. A container is an existing telemetry data
141 * array. The array the container is to be added to must have been started by
142 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
143 * The container type must be an array of type uint64_t/int/string.
146 * The data structure passed to the callback
148 * The pointer to the container to be stored in the array.
150 * Flag to indicate that the container memory should not be automatically
151 * freed by the telemetry library once it has finished with the data.
152 * 1 = keep, 0 = free.
154 * 0 on success, negative errno on error
158 rte_tel_data_add_array_container(struct rte_tel_data *d,
159 struct rte_tel_data *val, int keep);
162 * Add a string value to a dictionary.
163 * The dict must have been started by rte_tel_data_start_dict().
166 * The data structure passed to the callback
168 * The name the value is to be stored under in the dict
170 * The string to be stored in the dict
172 * 0 on success, negative errno on error, E2BIG on string truncation of
173 * either name or value.
177 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
181 * Add an int value to a dictionary.
182 * The dict must have been started by rte_tel_data_start_dict().
185 * The data structure passed to the callback
187 * The name the value is to be stored under in the dict
189 * The number to be stored in the dict
191 * 0 on success, negative errno on error, E2BIG on string truncation of name.
195 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
198 * Add a uint64_t value to a dictionary.
199 * The dict must have been started by rte_tel_data_start_dict().
202 * The data structure passed to the callback
204 * The name the value is to be stored under in the dict
206 * The number to be stored in the dict
208 * 0 on success, negative errno on error, E2BIG on string truncation of name.
212 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
213 const char *name, uint64_t val);
216 * Add a container to a dictionary. A container is an existing telemetry data
217 * array. The dict the container is to be added to must have been started by
218 * rte_tel_data_start_dict(). The container must be an array of type
219 * uint64_t/int/string.
222 * The data structure passed to the callback
224 * The name the value is to be stored under in the dict.
226 * The pointer to the container to be stored in the dict.
228 * Flag to indicate that the container memory should not be automatically
229 * freed by the telemetry library once it has finished with the data.
230 * 1 = keep, 0 = free.
232 * 0 on success, negative errno on error
236 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
237 struct rte_tel_data *val, int keep);
240 * This telemetry callback is used when registering a telemetry command.
241 * It handles getting and formatting information to be returned to telemetry
245 * The cmd that was requested by the client.
247 * Contains data required by the callback function.
249 * The information to be returned to the caller.
252 * Length of buffer used on success.
254 * Negative integer on error.
256 typedef int (*telemetry_cb)(const char *cmd, const char *params,
257 struct rte_tel_data *info);
260 * Used for handling data received over a telemetry socket.
263 * ID for the socket to be used by the handler.
268 typedef void * (*handler)(void *sock_id);
271 * Used when registering a command and callback function with telemetry.
274 * The command to register with telemetry.
276 * Callback function to be called when the command is requested.
278 * Help text for the command.
283 * -EINVAL for invalid parameters failure.
285 * -ENOMEM for mem allocation failure.
289 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
293 * Get a pointer to a container with memory allocated. The container is to be
294 * used embedded within an existing telemetry dict/array.
297 * Pointer to a container.
300 struct rte_tel_data *
301 rte_tel_data_alloc(void);
305 * Free a container that has memory allocated.
308 * Pointer to container.
313 rte_tel_data_free(struct rte_tel_data *data);