1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #include <stdint.h> 6 #include <sched.h> 7 #include <rte_compat.h> 8 9 #ifndef _RTE_TELEMETRY_H_ 10 #define _RTE_TELEMETRY_H_ 11 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 22 23 /** 24 * @file 25 * 26 * RTE Telemetry. 27 * 28 * @warning 29 * @b EXPERIMENTAL: 30 * All functions in this file may be changed or removed without prior notice. 31 * 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. 35 ***/ 36 37 /** opaque structure used internally for managing data from callbacks */ 38 struct rte_tel_data; 39 40 /** 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. 45 */ 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 */ 50 RTE_TEL_CONTAINER, /** a container struct */ 51 }; 52 53 /** 54 * Start an array of the specified type for returning from a callback 55 * 56 * @param d 57 * The data structure passed to the callback 58 * @param type 59 * The type of the array of data 60 * @return 61 * 0 on success, negative errno on error 62 */ 63 __rte_experimental 64 int 65 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type); 66 67 /** 68 * Start a dictionary of values for returning from a callback 69 * 70 * @param d 71 * The data structure passed to the callback 72 * @return 73 * 0 on success, negative errno on error 74 */ 75 __rte_experimental 76 int 77 rte_tel_data_start_dict(struct rte_tel_data *d); 78 79 /** 80 * Set a string for returning from a callback 81 * 82 * @param d 83 * The data structure passed to the callback 84 * @param str 85 * The string to be returned in the data structure 86 * @return 87 * 0 on success, negative errno on error, E2BIG on string truncation 88 */ 89 __rte_experimental 90 int 91 rte_tel_data_string(struct rte_tel_data *d, const char *str); 92 93 /** 94 * Add a string to an array. 95 * The array must have been started by rte_tel_data_start_array() with 96 * RTE_TEL_STRING_VAL as the type parameter. 97 * 98 * @param d 99 * The data structure passed to the callback 100 * @param str 101 * The string to be returned in the array 102 * @return 103 * 0 on success, negative errno on error, E2BIG on string truncation 104 */ 105 __rte_experimental 106 int 107 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str); 108 109 /** 110 * Add an int to an array. 111 * The array must have been started by rte_tel_data_start_array() with 112 * RTE_TEL_INT_VAL as the type parameter. 113 * 114 * @param d 115 * The data structure passed to the callback 116 * @param x 117 * The number to be returned in the array 118 * @return 119 * 0 on success, negative errno on error 120 */ 121 __rte_experimental 122 int 123 rte_tel_data_add_array_int(struct rte_tel_data *d, int x); 124 125 /** 126 * Add a uint64_t to an array. 127 * The array must have been started by rte_tel_data_start_array() with 128 * RTE_TEL_U64_VAL as the type parameter. 129 * 130 * @param d 131 * The data structure passed to the callback 132 * @param x 133 * The number to be returned in the array 134 * @return 135 * 0 on success, negative errno on error 136 */ 137 __rte_experimental 138 int 139 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x); 140 141 /** 142 * Add a container to an array. A container is an existing telemetry data 143 * array. The array the container is to be added to must have been started by 144 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. 145 * The container type must be an array of type uint64_t/int/string. 146 * 147 * @param d 148 * The data structure passed to the callback 149 * @param val 150 * The pointer to the container to be stored in the array. 151 * @param keep 152 * Flag to indicate that the container memory should not be automatically 153 * freed by the telemetry library once it has finished with the data. 154 * 1 = keep, 0 = free. 155 * @return 156 * 0 on success, negative errno on error 157 */ 158 __rte_experimental 159 int 160 rte_tel_data_add_array_container(struct rte_tel_data *d, 161 struct rte_tel_data *val, int keep); 162 163 /** 164 * Add a string value to a dictionary. 165 * The dict must have been started by rte_tel_data_start_dict(). 166 * 167 * @param d 168 * The data structure passed to the callback 169 * @param name 170 * The name the value is to be stored under in the dict 171 * @param val 172 * The string to be stored in the dict 173 * @return 174 * 0 on success, negative errno on error, E2BIG on string truncation of 175 * either name or value. 176 */ 177 __rte_experimental 178 int 179 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name, 180 const char *val); 181 182 /** 183 * Add an int value to a dictionary. 184 * The dict must have been started by rte_tel_data_start_dict(). 185 * 186 * @param d 187 * The data structure passed to the callback 188 * @param name 189 * The name the value is to be stored under in the dict 190 * @param val 191 * The number to be stored in the dict 192 * @return 193 * 0 on success, negative errno on error, E2BIG on string truncation of name. 194 */ 195 __rte_experimental 196 int 197 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val); 198 199 /** 200 * Add a uint64_t value to a dictionary. 201 * The dict must have been started by rte_tel_data_start_dict(). 202 * 203 * @param d 204 * The data structure passed to the callback 205 * @param name 206 * The name the value is to be stored under in the dict 207 * @param val 208 * The number to be stored in the dict 209 * @return 210 * 0 on success, negative errno on error, E2BIG on string truncation of name. 211 */ 212 __rte_experimental 213 int 214 rte_tel_data_add_dict_u64(struct rte_tel_data *d, 215 const char *name, uint64_t val); 216 217 /** 218 * Add a container to a dictionary. A container is an existing telemetry data 219 * array. The dict the container is to be added to must have been started by 220 * rte_tel_data_start_dict(). The container must be an array of type 221 * uint64_t/int/string. 222 * 223 * @param d 224 * The data structure passed to the callback 225 * @param name 226 * The name the value is to be stored under in the dict. 227 * @param val 228 * The pointer to the container to be stored in the dict. 229 * @param keep 230 * Flag to indicate that the container memory should not be automatically 231 * freed by the telemetry library once it has finished with the data. 232 * 1 = keep, 0 = free. 233 * @return 234 * 0 on success, negative errno on error 235 */ 236 __rte_experimental 237 int 238 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name, 239 struct rte_tel_data *val, int keep); 240 241 /** 242 * This telemetry callback is used when registering a telemetry command. 243 * It handles getting and formatting information to be returned to telemetry 244 * when requested. 245 * 246 * @param cmd 247 * The cmd that was requested by the client. 248 * @param params 249 * Contains data required by the callback function. 250 * @param info 251 * The information to be returned to the caller. 252 * 253 * @return 254 * Length of buffer used on success. 255 * @return 256 * Negative integer on error. 257 */ 258 typedef int (*telemetry_cb)(const char *cmd, const char *params, 259 struct rte_tel_data *info); 260 261 /** 262 * Used for handling data received over a telemetry socket. 263 * 264 * @param sock_id 265 * ID for the socket to be used by the handler. 266 * 267 * @return 268 * Void. 269 */ 270 typedef void * (*handler)(void *sock_id); 271 272 /** 273 * Used when registering a command and callback function with telemetry. 274 * 275 * @param cmd 276 * The command to register with telemetry. 277 * @param fn 278 * Callback function to be called when the command is requested. 279 * @param help 280 * Help text for the command. 281 * 282 * @return 283 * 0 on success. 284 * @return 285 * -EINVAL for invalid parameters failure. 286 * @return 287 * -ENOENT if max callbacks limit has been reached. 288 */ 289 __rte_experimental 290 int 291 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help); 292 293 /** 294 * @internal 295 * Initialize Telemetry. 296 * 297 * @param runtime_dir 298 * The runtime directory of DPDK. 299 * @param cpuset 300 * The CPU set to be used for setting the thread affinity. 301 * @param err_str 302 * This err_str pointer should point to NULL on entry. In the case of an error 303 * or warning, it will be non-NULL on exit. 304 * 305 * @return 306 * 0 on success. 307 * @return 308 * -1 on failure. 309 */ 310 __rte_experimental 311 int 312 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset, 313 const char **err_str); 314 315 /** 316 * Get a pointer to a container with memory allocated. The container is to be 317 * used embedded within an existing telemetry dict/array. 318 * 319 * @return 320 * Pointer to a container. 321 */ 322 __rte_experimental 323 struct rte_tel_data * 324 rte_tel_data_alloc(void); 325 326 /** 327 * @internal 328 * Free a container that has memory allocated. 329 * 330 * @param data 331 * Pointer to container. 332 *. 333 */ 334 __rte_experimental 335 void 336 rte_tel_data_free(struct rte_tel_data *data); 337 338 #endif 339