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 number of telemetry callbacks. */
13 #define TELEMETRY_MAX_CALLBACKS 64
14 /** Maximum length for string used in object. */
15 #define RTE_TEL_MAX_STRING_LEN 64
16 /** Maximum length of string. */
17 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
18 /** Maximum number of dictionary entries. */
19 #define RTE_TEL_MAX_DICT_ENTRIES 256
20 /** Maximum number of array entries. */
21 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
30 * All functions in this file may be changed or removed without prior notice.
32 * The telemetry library provides a method to retrieve statistics from
33 * DPDK by sending a request message over a socket. DPDK will send
34 * a JSON encoded response containing telemetry data.
37 /** opaque structure used internally for managing data from callbacks */
41 * The types of data that can be managed in arrays or dicts.
42 * For arrays, this must be specified at creation time, while for
43 * dicts this is specified implicitly each time an element is added
44 * via calling a type-specific function.
46 enum rte_tel_value_type {
47 RTE_TEL_STRING_VAL, /** a string value */
48 RTE_TEL_INT_VAL, /** a signed 32-bit int value */
49 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */
53 * Start an array of the specified type for returning from a callback
56 * The data structure passed to the callback
58 * The type of the array of data
60 * 0 on success, negative errno on error
64 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
67 * Start a dictionary of values for returning from a callback
70 * The data structure passed to the callback
72 * 0 on success, negative errno on error
76 rte_tel_data_start_dict(struct rte_tel_data *d);
79 * Set a string for returning from a callback
82 * The data structure passed to the callback
84 * The string to be returned in the data structure
86 * 0 on success, negative errno on error, E2BIG on string truncation
90 rte_tel_data_string(struct rte_tel_data *d, const char *str);
93 * Add a string to an array.
94 * The array must have been started by rte_tel_data_start_array() with
95 * RTE_TEL_STRING_VAL as the type parameter.
98 * The data structure passed to the callback
100 * The string to be returned in the array
102 * 0 on success, negative errno on error, E2BIG on string truncation
106 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
109 * Add an int to an array.
110 * The array must have been started by rte_tel_data_start_array() with
111 * RTE_TEL_INT_VAL as the type parameter.
114 * The data structure passed to the callback
116 * The number to be returned in the array
118 * 0 on success, negative errno on error
122 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
125 * Add a uint64_t to an array.
126 * The array must have been started by rte_tel_data_start_array() with
127 * RTE_TEL_U64_VAL as the type parameter.
130 * The data structure passed to the callback
132 * The number to be returned in the array
134 * 0 on success, negative errno on error
138 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
141 * Add a string value to a dictionary.
142 * The dict must have been started by rte_tel_data_start_dict().
145 * The data structure passed to the callback
147 * The name the value is to be stored under in the dict
149 * The string to be stored in the dict
151 * 0 on success, negative errno on error, E2BIG on string truncation of
152 * either name or value.
156 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
160 * Add an int value to a dictionary.
161 * The dict must have been started by rte_tel_data_start_dict().
164 * The data structure passed to the callback
166 * The name the value is to be stored under in the dict
168 * The number to be stored in the dict
170 * 0 on success, negative errno on error, E2BIG on string truncation of name.
174 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
177 * Add a uint64_t value to a dictionary.
178 * The dict must have been started by rte_tel_data_start_dict().
181 * The data structure passed to the callback
183 * The name the value is to be stored under in the dict
185 * The number to be stored in the dict
187 * 0 on success, negative errno on error, E2BIG on string truncation of name.
191 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
192 const char *name, uint64_t val);
195 * This telemetry callback is used when registering a telemetry command.
196 * It handles getting and formatting information to be returned to telemetry
200 * The cmd that was requested by the client.
202 * Contains data required by the callback function.
204 * The information to be returned to the caller.
207 * Length of buffer used on success.
209 * Negative integer on error.
211 typedef int (*telemetry_cb)(const char *cmd, const char *params,
212 struct rte_tel_data *info);
215 * Used for handling data received over a telemetry socket.
218 * ID for the socket to be used by the handler.
223 typedef void * (*handler)(void *sock_id);
226 * Used when registering a command and callback function with telemetry.
229 * The command to register with telemetry.
231 * Callback function to be called when the command is requested.
233 * Help text for the command.
238 * -EINVAL for invalid parameters failure.
240 * -ENOENT if max callbacks limit has been reached.
244 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
248 * Initialize Telemetry.
251 * The runtime directory of DPDK.
253 * The CPU set to be used for setting the thread affinity.
255 * This err_str pointer should point to NULL on entry. In the case of an error
256 * or warning, it will be non-NULL on exit.
265 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
266 const char **err_str);