1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
6 #include <rte_compat.h>
8 #ifndef _RTE_TELEMETRY_H_
9 #define _RTE_TELEMETRY_H_
11 /** Maximum number of telemetry callbacks. */
12 #define TELEMETRY_MAX_CALLBACKS 64
13 /** Maximum length for string used in object. */
14 #define RTE_TEL_MAX_STRING_LEN 64
15 /** Maximum length of string. */
16 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
17 /** Maximum number of dictionary entries. */
18 #define RTE_TEL_MAX_DICT_ENTRIES 256
19 /** Maximum number of array entries. */
20 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
24 * @b EXPERIMENTAL: all functions in this file may change without prior notice
29 * The telemetry library provides a method to retrieve statistics from
30 * DPDK by sending a request message over a socket. DPDK will send
31 * a JSON encoded response containing telemetry data.
34 /** opaque structure used internally for managing data from callbacks */
38 * The types of data that can be managed in arrays or dicts.
39 * For arrays, this must be specified at creation time, while for
40 * dicts this is specified implicitly each time an element is added
41 * via calling a type-specific function.
43 enum rte_tel_value_type {
44 RTE_TEL_STRING_VAL, /** a string value */
45 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
46 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
50 * Start an array of the specified type for returning from a callback
53 * The data structure passed to the callback
55 * The type of the array of data
57 * 0 on success, negative errno on error
61 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
64 * Start a dictionary of values for returning from a callback
67 * The data structure passed to the callback
69 * 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
87 rte_tel_data_string(struct rte_tel_data *d, const char *str);
90 * Add a string to an array.
91 * The array must have been started by rte_tel_data_start_array() with
92 * RTE_TEL_STRING_VAL as the type parameter.
95 * The data structure passed to the callback
97 * The string to be returned in the array
99 * 0 on success, negative errno on error, E2BIG on string truncation
103 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
106 * Add an int to an array.
107 * The array must have been started by rte_tel_data_start_array() with
108 * RTE_TEL_INT_VAL as the type parameter.
111 * The data structure passed to the callback
113 * The number to be returned in the array
115 * 0 on success, negative errno on error
119 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
122 * Add a uint64_t to an array.
123 * The array must have been started by rte_tel_data_start_array() with
124 * RTE_TEL_U64_VAL as the type parameter.
127 * The data structure passed to the callback
129 * The number to be returned in the array
131 * 0 on success, negative errno on error
135 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
138 * Add a string value to a dictionary.
139 * The dict must have been started by rte_tel_data_start_dict().
142 * The data structure passed to the callback
144 * The name the value is to be stored under in the dict
146 * The string to be stored in the dict
148 * 0 on success, negative errno on error, E2BIG on string truncation of
149 * either name or value.
153 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
157 * Add an int value to a dictionary.
158 * The dict must have been started by rte_tel_data_start_dict().
161 * The data structure passed to the callback
163 * The name the value is to be stored under in the dict
165 * The number to be stored in the dict
167 * 0 on success, negative errno on error, E2BIG on string truncation of name.
171 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
174 * Add a uint64_t value to a dictionary.
175 * The dict must have been started by rte_tel_data_start_dict().
178 * The data structure passed to the callback
180 * The name the value is to be stored under in the dict
182 * The number to be stored in the dict
184 * 0 on success, negative errno on error, E2BIG on string truncation of name.
188 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
189 const char *name, uint64_t val);
192 * This telemetry callback is used when registering a telemetry command.
193 * It handles getting and formatting information to be returned to telemetry
197 * The cmd that was requested by the client.
199 * Contains data required by the callback function.
201 * The information to be returned to the caller.
204 * Length of buffer used on success.
206 * Negative integer on error.
208 typedef int (*telemetry_cb)(const char *cmd, const char *params,
209 struct rte_tel_data *info);
212 * Used for handling data received over a telemetry socket.
215 * ID for the socket to be used by the handler.
220 typedef void * (*handler)(void *sock_id);
224 * @b EXPERIMENTAL: this API may change without prior notice
226 * Initialize Telemetry
229 * 0 on successful initialisation.
231 * -ENOMEM on memory allocation error
233 * -EPERM on unknown error failure
235 * -EALREADY if Telemetry is already initialised.
239 rte_telemetry_init(void);
243 * @b EXPERIMENTAL: this API may change without prior notice
245 * Clean up and free memory.
254 rte_telemetry_cleanup(void);
258 * @b EXPERIMENTAL: this API may change without prior notice
260 * Runs various tests to ensure telemetry initialisation and register/unregister
261 * functions are working correctly.
264 * 0 on success when all tests have passed
266 * -1 on failure when the test has failed
270 rte_telemetry_selftest(void);
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);
294 * Initialize new version of Telemetry.
303 rte_telemetry_new_init(void);