1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #ifndef _RTE_TELEMETRY_H_ 6 #define _RTE_TELEMETRY_H_ 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 #include <stdint.h> 13 #include <rte_compat.h> 14 #include <rte_common.h> 15 16 /** Maximum length for string used in object. */ 17 #define RTE_TEL_MAX_STRING_LEN 128 18 /** Maximum length of string. */ 19 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192 20 /** Maximum number of dictionary entries. */ 21 #define RTE_TEL_MAX_DICT_ENTRIES 256 22 /** Maximum number of array entries. */ 23 #define RTE_TEL_MAX_ARRAY_ENTRIES 512 24 25 /** 26 * @file 27 * 28 * RTE Telemetry. 29 * 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. 33 ***/ 34 35 /** opaque structure used internally for managing data from callbacks */ 36 struct rte_tel_data; 37 38 /** 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. 43 */ 44 enum rte_tel_value_type { 45 RTE_TEL_STRING_VAL, /** a string value */ 46 RTE_TEL_INT_VAL, /** a signed 64-bit int value */ 47 RTE_TEL_UINT_VAL, /** an unsigned 64-bit int value */ 48 RTE_TEL_CONTAINER, /** a container struct */ 49 }; 50 51 #define RTE_TEL_U64_VAL RTE_TEL_UINT_VAL 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 int 64 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type); 65 66 /** 67 * Start a dictionary of values for returning from a callback 68 * 69 * Dictionaries consist of key-values pairs to be returned, where the keys, 70 * or names, are strings and the values can be any of the types supported by telemetry. 71 * Name strings may only contain alphanumeric characters as well as '_' or '/' 72 * 73 * @param d 74 * The data structure passed to the callback 75 * @return 76 * 0 on success, negative errno on error 77 */ 78 int 79 rte_tel_data_start_dict(struct rte_tel_data *d); 80 81 /** 82 * Set a string for returning from a callback 83 * 84 * @param d 85 * The data structure passed to the callback 86 * @param str 87 * The string to be returned in the data structure 88 * @return 89 * 0 on success, negative errno on error, E2BIG on string truncation 90 */ 91 int 92 rte_tel_data_string(struct rte_tel_data *d, const char *str); 93 94 /** 95 * Add a string to an array. 96 * The array must have been started by rte_tel_data_start_array() with 97 * RTE_TEL_STRING_VAL as the type parameter. 98 * 99 * @param d 100 * The data structure passed to the callback 101 * @param str 102 * The string to be returned in the array 103 * @return 104 * 0 on success, negative errno on error, E2BIG on string truncation 105 */ 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 int 122 rte_tel_data_add_array_int(struct rte_tel_data *d, int64_t x); 123 124 /** 125 * Add an unsigned value to an array. 126 * The array must have been started by rte_tel_data_start_array() with 127 * RTE_TEL_UINT_VAL as the type parameter. 128 * 129 * @param d 130 * The data structure passed to the callback 131 * @param x 132 * The number to be returned in the array 133 * @return 134 * 0 on success, negative errno on error 135 */ 136 int 137 rte_tel_data_add_array_uint(struct rte_tel_data *d, uint64_t x); 138 139 /** 140 * Add a uint64_t to an array. 141 * The array must have been started by rte_tel_data_start_array() with 142 * RTE_TEL_UINT_VAL as the type parameter. 143 * 144 * @param d 145 * The data structure passed to the callback 146 * @param x 147 * The number to be returned in the array 148 * @return 149 * 0 on success, negative errno on error 150 */ 151 int 152 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x) 153 __rte_deprecated_msg("use 'rte_tel_data_add_array_uint' instead"); 154 155 /** 156 * Add a container to an array. A container is an existing telemetry data 157 * array. The array the container is to be added to must have been started by 158 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. 159 * The container type must be an array of type uint64_t/int/string. 160 * 161 * @param d 162 * The data structure passed to the callback 163 * @param val 164 * The pointer to the container to be stored in the array. 165 * @param keep 166 * Flag to indicate that the container memory should not be automatically 167 * freed by the telemetry library once it has finished with the data. 168 * 1 = keep, 0 = free. 169 * @return 170 * 0 on success, negative errno on error 171 */ 172 int 173 rte_tel_data_add_array_container(struct rte_tel_data *d, 174 struct rte_tel_data *val, int keep); 175 176 /** 177 * Convert an unsigned integer to hexadecimal encoded strings 178 * and add this string to an array. 179 * The array must have been started by rte_tel_data_start_array() 180 * with RTE_TEL_STRING_VAL as the type parameter. 181 * 182 * @param d 183 * The data structure passed to the callback. 184 * @param val 185 * The number to be returned in the array as a hexadecimal encoded strings. 186 * @param display_bitwidth 187 * The display bit width of the 'val'. If 'display_bitwidth' is zero, the 188 * value is stored in the array as no-padding zero hexadecimal encoded string, 189 * or the value is stored as padding zero to specified hexadecimal width. 190 * @return 191 * 0 on success, negative errno on error. 192 */ 193 __rte_experimental 194 int 195 rte_tel_data_add_array_uint_hex(struct rte_tel_data *d, uint64_t val, 196 uint8_t display_bitwidth); 197 198 /** 199 * Add a string value to a dictionary. 200 * The dict must have been started by rte_tel_data_start_dict(). 201 * 202 * @param d 203 * The data structure passed to the callback 204 * @param name 205 * The name the value is to be stored under in the dict 206 * Must contain only alphanumeric characters or the symbols: '_' or '/' 207 * @param val 208 * The string to be stored in the dict 209 * @return 210 * 0 on success, negative errno on error, E2BIG on string truncation of 211 * either name or value. 212 */ 213 int 214 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name, 215 const char *val); 216 217 /** 218 * Add an int value to a dictionary. 219 * The dict must have been started by rte_tel_data_start_dict(). 220 * 221 * @param d 222 * The data structure passed to the callback 223 * @param name 224 * The name the value is to be stored under in the dict 225 * Must contain only alphanumeric characters or the symbols: '_' or '/' 226 * @param val 227 * The number to be stored in the dict 228 * @return 229 * 0 on success, negative errno on error, E2BIG on string truncation of name. 230 */ 231 int 232 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int64_t val); 233 234 /** 235 * Add an unsigned value to a dictionary. 236 * The dict must have been started by rte_tel_data_start_dict(). 237 * 238 * @param d 239 * The data structure passed to the callback 240 * @param name 241 * The name the value is to be stored under in the dict 242 * Must contain only alphanumeric characters or the symbols: '_' or '/' 243 * @param val 244 * The number to be stored in the dict 245 * @return 246 * 0 on success, negative errno on error, E2BIG on string truncation of name. 247 */ 248 int 249 rte_tel_data_add_dict_uint(struct rte_tel_data *d, 250 const char *name, uint64_t val); 251 252 /** 253 * Add a uint64_t value to a dictionary. 254 * The dict must have been started by rte_tel_data_start_dict(). 255 * 256 * @param d 257 * The data structure passed to the callback 258 * @param name 259 * The name the value is to be stored under in the dict 260 * Must contain only alphanumeric characters or the symbols: '_' or '/' 261 * @param val 262 * The number to be stored in the dict 263 * @return 264 * 0 on success, negative errno on error, E2BIG on string truncation of name. 265 */ 266 int 267 rte_tel_data_add_dict_u64(struct rte_tel_data *d, 268 const char *name, uint64_t val) 269 __rte_deprecated_msg("use 'rte_tel_data_add_dict_uint' instead"); 270 271 /** 272 * Add a container to a dictionary. A container is an existing telemetry data 273 * array. The dict the container is to be added to must have been started by 274 * rte_tel_data_start_dict(). The container must be an array of type 275 * uint64_t/int/string. 276 * 277 * @param d 278 * The data structure passed to the callback 279 * @param name 280 * The name the value is to be stored under in the dict. 281 * Must contain only alphanumeric characters or the symbols: '_' or '/' 282 * @param val 283 * The pointer to the container to be stored in the dict. 284 * @param keep 285 * Flag to indicate that the container memory should not be automatically 286 * freed by the telemetry library once it has finished with the data. 287 * 1 = keep, 0 = free. 288 * @return 289 * 0 on success, negative errno on error 290 */ 291 int 292 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name, 293 struct rte_tel_data *val, int keep); 294 295 /** 296 * Convert an unsigned integer to hexadecimal encoded strings 297 * and add this string to an dictionary. 298 * The dict must have been started by rte_tel_data_start_dict(). 299 * 300 * @param d 301 * The data structure passed to the callback. 302 * @param name 303 * The name of the value is to be stored in the dict. 304 * Must contain only alphanumeric characters or the symbols: '_' or '/'. 305 * @param val 306 * The number to be stored in the dict as a hexadecimal encoded strings. 307 * @param display_bitwidth 308 * The display bit width of the 'val'. If 'display_bitwidth' is zero, the 309 * value is stored in the array as no-padding zero hexadecimal encoded string, 310 * or the value is stored as padding zero to specified hexadecimal width. 311 * @return 312 * 0 on success, negative errno on error. 313 */ 314 __rte_experimental 315 int 316 rte_tel_data_add_dict_uint_hex(struct rte_tel_data *d, const char *name, 317 uint64_t val, uint8_t display_bitwidth); 318 319 /** 320 * This telemetry callback is used when registering a telemetry command. 321 * It handles getting and formatting information to be returned to telemetry 322 * when requested. 323 * 324 * @param cmd 325 * The cmd that was requested by the client. 326 * @param params 327 * Contains data required by the callback function. 328 * @param info 329 * The information to be returned to the caller. 330 * 331 * @return 332 * Length of buffer used on success. 333 * @return 334 * Negative integer on error. 335 */ 336 typedef int (*telemetry_cb)(const char *cmd, const char *params, 337 struct rte_tel_data *info); 338 339 /** 340 * Used for handling data received over a telemetry socket. 341 * 342 * @param sock_id 343 * ID for the socket to be used by the handler. 344 * 345 * @return 346 * Void. 347 */ 348 typedef void * (*handler)(void *sock_id); 349 350 /** 351 * Used when registering a command and callback function with telemetry. 352 * 353 * @param cmd 354 * The command to register with telemetry. 355 * @param fn 356 * Callback function to be called when the command is requested. 357 * @param help 358 * Help text for the command. 359 * 360 * @return 361 * 0 on success. 362 * @return 363 * -EINVAL for invalid parameters failure. 364 * @return 365 * -ENOMEM for mem allocation failure. 366 */ 367 int 368 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help); 369 370 371 /** 372 * Get a pointer to a container with memory allocated. The container is to be 373 * used embedded within an existing telemetry dict/array. 374 * 375 * @return 376 * Pointer to a container. 377 */ 378 struct rte_tel_data * 379 rte_tel_data_alloc(void); 380 381 /** 382 * @internal 383 * Free a container that has memory allocated. 384 * 385 * @param data 386 * Pointer to container. 387 * If data is NULL, no operation is performed. 388 */ 389 void 390 rte_tel_data_free(struct rte_tel_data *data); 391 392 #ifdef __cplusplus 393 } 394 #endif 395 396 #endif 397