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
26 * The telemetry library provides a method to retrieve statistics from
27 * DPDK by sending a request message over a socket. DPDK will send
28 * a JSON encoded response containing telemetry data.
31 /** opaque structure used internally for managing data from callbacks */
35 * The types of data that can be managed in arrays or dicts.
36 * For arrays, this must be specified at creation time, while for
37 * dicts this is specified implicitly each time an element is added
38 * via calling a type-specific function.
40 enum rte_tel_value_type {
41 RTE_TEL_STRING_VAL, /** a string value */
42 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
43 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
44 RTE_TEL_CONTAINER, /** a container struct */
48 * Start an array of the specified type for returning from a callback
51 * The data structure passed to the callback
53 * The type of the array of data
55 * 0 on success, negative errno on error
58 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
61 * Start a dictionary of values for returning from a callback
64 * The data structure passed to the callback
66 * 0 on success, negative errno on error
69 rte_tel_data_start_dict(struct rte_tel_data *d);
72 * Set a string for returning from a callback
75 * The data structure passed to the callback
77 * The string to be returned in the data structure
79 * 0 on success, negative errno on error, E2BIG on string truncation
82 rte_tel_data_string(struct rte_tel_data *d, const char *str);
85 * Add a string to an array.
86 * The array must have been started by rte_tel_data_start_array() with
87 * RTE_TEL_STRING_VAL as the type parameter.
90 * The data structure passed to the callback
92 * The string to be returned in the array
94 * 0 on success, negative errno on error, E2BIG on string truncation
97 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
100 * Add an int to an array.
101 * The array must have been started by rte_tel_data_start_array() with
102 * RTE_TEL_INT_VAL as the type parameter.
105 * The data structure passed to the callback
107 * The number to be returned in the array
109 * 0 on success, negative errno on error
112 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
115 * Add a uint64_t to an array.
116 * The array must have been started by rte_tel_data_start_array() with
117 * RTE_TEL_U64_VAL as the type parameter.
120 * The data structure passed to the callback
122 * The number to be returned in the array
124 * 0 on success, negative errno on error
127 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
130 * Add a container to an array. A container is an existing telemetry data
131 * array. The array the container is to be added to must have been started by
132 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
133 * The container type must be an array of type uint64_t/int/string.
136 * The data structure passed to the callback
138 * The pointer to the container to be stored in the array.
140 * Flag to indicate that the container memory should not be automatically
141 * freed by the telemetry library once it has finished with the data.
142 * 1 = keep, 0 = free.
144 * 0 on success, negative errno on error
147 rte_tel_data_add_array_container(struct rte_tel_data *d,
148 struct rte_tel_data *val, int keep);
151 * Add a string value to a dictionary.
152 * The dict must have been started by rte_tel_data_start_dict().
155 * The data structure passed to the callback
157 * The name the value is to be stored under in the dict
159 * The string to be stored in the dict
161 * 0 on success, negative errno on error, E2BIG on string truncation of
162 * either name or value.
165 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
169 * Add an int value to a dictionary.
170 * The dict must have been started by rte_tel_data_start_dict().
173 * The data structure passed to the callback
175 * The name the value is to be stored under in the dict
177 * The number to be stored in the dict
179 * 0 on success, negative errno on error, E2BIG on string truncation of name.
182 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
185 * Add a uint64_t 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.
198 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
199 const char *name, uint64_t val);
202 * Add a container to a dictionary. A container is an existing telemetry data
203 * array. The dict the container is to be added to must have been started by
204 * rte_tel_data_start_dict(). The container must be an array of type
205 * uint64_t/int/string.
208 * The data structure passed to the callback
210 * The name the value is to be stored under in the dict.
212 * The pointer to the container to be stored in the dict.
214 * Flag to indicate that the container memory should not be automatically
215 * freed by the telemetry library once it has finished with the data.
216 * 1 = keep, 0 = free.
218 * 0 on success, negative errno on error
221 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
222 struct rte_tel_data *val, int keep);
225 * This telemetry callback is used when registering a telemetry command.
226 * It handles getting and formatting information to be returned to telemetry
230 * The cmd that was requested by the client.
232 * Contains data required by the callback function.
234 * The information to be returned to the caller.
237 * Length of buffer used on success.
239 * Negative integer on error.
241 typedef int (*telemetry_cb)(const char *cmd, const char *params,
242 struct rte_tel_data *info);
245 * Used for handling data received over a telemetry socket.
248 * ID for the socket to be used by the handler.
253 typedef void * (*handler)(void *sock_id);
256 * Used when registering a command and callback function with telemetry.
259 * The command to register with telemetry.
261 * Callback function to be called when the command is requested.
263 * Help text for the command.
268 * -EINVAL for invalid parameters failure.
270 * -ENOMEM for mem allocation failure.
273 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
277 * Get a pointer to a container with memory allocated. The container is to be
278 * used embedded within an existing telemetry dict/array.
281 * Pointer to a container.
283 struct rte_tel_data *
284 rte_tel_data_alloc(void);
288 * Free a container that has memory allocated.
291 * Pointer to container.
295 rte_tel_data_free(struct rte_tel_data *data);