1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #include <stdint.h> 6 #include <sched.h> 7 8 #include <rte_compat.h> 9 10 #ifndef _RTE_TELEMETRY_H_ 11 #define _RTE_TELEMETRY_H_ 12 13 /** Maximum length for string used in object. */ 14 #define RTE_TEL_MAX_STRING_LEN 128 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 21 22 /** 23 * @file 24 * 25 * RTE Telemetry. 26 * 27 * @warning 28 * @b EXPERIMENTAL: 29 * All functions in this file may be changed or removed without prior notice. 30 * 31 * The telemetry library provides a method to retrieve statistics from 32 * DPDK by sending a request message over a socket. DPDK will send 33 * a JSON encoded response containing telemetry data. 34 ***/ 35 36 /** opaque structure used internally for managing data from callbacks */ 37 struct rte_tel_data; 38 39 /** 40 * The types of data that can be managed in arrays or dicts. 41 * For arrays, this must be specified at creation time, while for 42 * dicts this is specified implicitly each time an element is added 43 * via calling a type-specific function. 44 */ 45 enum rte_tel_value_type { 46 RTE_TEL_STRING_VAL, /** a string value */ 47 RTE_TEL_INT_VAL, /** a signed 32-bit int value */ 48 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */ 49 RTE_TEL_CONTAINER, /** a container struct */ 50 }; 51 52 /** 53 * Start an array of the specified type for returning from a callback 54 * 55 * @param d 56 * The data structure passed to the callback 57 * @param type 58 * The type of the array of data 59 * @return 60 * 0 on success, negative errno on error 61 */ 62 __rte_experimental 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 * @param d 70 * The data structure passed to the callback 71 * @return 72 * 0 on success, negative errno on error 73 */ 74 __rte_experimental 75 int 76 rte_tel_data_start_dict(struct rte_tel_data *d); 77 78 /** 79 * Set a string for returning from a callback 80 * 81 * @param d 82 * The data structure passed to the callback 83 * @param str 84 * The string to be returned in the data structure 85 * @return 86 * 0 on success, negative errno on error, E2BIG on string truncation 87 */ 88 __rte_experimental 89 int 90 rte_tel_data_string(struct rte_tel_data *d, const char *str); 91 92 /** 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. 96 * 97 * @param d 98 * The data structure passed to the callback 99 * @param str 100 * The string to be returned in the array 101 * @return 102 * 0 on success, negative errno on error, E2BIG on string truncation 103 */ 104 __rte_experimental 105 int 106 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str); 107 108 /** 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. 112 * 113 * @param d 114 * The data structure passed to the callback 115 * @param x 116 * The number to be returned in the array 117 * @return 118 * 0 on success, negative errno on error 119 */ 120 __rte_experimental 121 int 122 rte_tel_data_add_array_int(struct rte_tel_data *d, int x); 123 124 /** 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. 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 __rte_experimental 137 int 138 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x); 139 140 /** 141 * Add a container to an array. A container is an existing telemetry data 142 * array. The array the container is to be added to must have been started by 143 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. 144 * The container type must be an array of type uint64_t/int/string. 145 * 146 * @param d 147 * The data structure passed to the callback 148 * @param val 149 * The pointer to the container to be stored in the array. 150 * @param keep 151 * Flag to indicate that the container memory should not be automatically 152 * freed by the telemetry library once it has finished with the data. 153 * 1 = keep, 0 = free. 154 * @return 155 * 0 on success, negative errno on error 156 */ 157 __rte_experimental 158 int 159 rte_tel_data_add_array_container(struct rte_tel_data *d, 160 struct rte_tel_data *val, int keep); 161 162 /** 163 * Add a string value to a dictionary. 164 * The dict must have been started by rte_tel_data_start_dict(). 165 * 166 * @param d 167 * The data structure passed to the callback 168 * @param name 169 * The name the value is to be stored under in the dict 170 * @param val 171 * The string to be stored in the dict 172 * @return 173 * 0 on success, negative errno on error, E2BIG on string truncation of 174 * either name or value. 175 */ 176 __rte_experimental 177 int 178 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name, 179 const char *val); 180 181 /** 182 * Add an int value to a dictionary. 183 * The dict must have been started by rte_tel_data_start_dict(). 184 * 185 * @param d 186 * The data structure passed to the callback 187 * @param name 188 * The name the value is to be stored under in the dict 189 * @param val 190 * The number to be stored in the dict 191 * @return 192 * 0 on success, negative errno on error, E2BIG on string truncation of name. 193 */ 194 __rte_experimental 195 int 196 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val); 197 198 /** 199 * Add a uint64_t 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 * @param val 207 * The number to be stored in the dict 208 * @return 209 * 0 on success, negative errno on error, E2BIG on string truncation of name. 210 */ 211 __rte_experimental 212 int 213 rte_tel_data_add_dict_u64(struct rte_tel_data *d, 214 const char *name, uint64_t val); 215 216 /** 217 * Add a container to a dictionary. A container is an existing telemetry data 218 * array. The dict the container is to be added to must have been started by 219 * rte_tel_data_start_dict(). The container must be an array of type 220 * uint64_t/int/string. 221 * 222 * @param d 223 * The data structure passed to the callback 224 * @param name 225 * The name the value is to be stored under in the dict. 226 * @param val 227 * The pointer to the container to be stored in the dict. 228 * @param keep 229 * Flag to indicate that the container memory should not be automatically 230 * freed by the telemetry library once it has finished with the data. 231 * 1 = keep, 0 = free. 232 * @return 233 * 0 on success, negative errno on error 234 */ 235 __rte_experimental 236 int 237 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name, 238 struct rte_tel_data *val, int keep); 239 240 /** 241 * This telemetry callback is used when registering a telemetry command. 242 * It handles getting and formatting information to be returned to telemetry 243 * when requested. 244 * 245 * @param cmd 246 * The cmd that was requested by the client. 247 * @param params 248 * Contains data required by the callback function. 249 * @param info 250 * The information to be returned to the caller. 251 * 252 * @return 253 * Length of buffer used on success. 254 * @return 255 * Negative integer on error. 256 */ 257 typedef int (*telemetry_cb)(const char *cmd, const char *params, 258 struct rte_tel_data *info); 259 260 /** 261 * Used for handling data received over a telemetry socket. 262 * 263 * @param sock_id 264 * ID for the socket to be used by the handler. 265 * 266 * @return 267 * Void. 268 */ 269 typedef void * (*handler)(void *sock_id); 270 271 /** 272 * Used when registering a command and callback function with telemetry. 273 * 274 * @param cmd 275 * The command to register with telemetry. 276 * @param fn 277 * Callback function to be called when the command is requested. 278 * @param help 279 * Help text for the command. 280 * 281 * @return 282 * 0 on success. 283 * @return 284 * -EINVAL for invalid parameters failure. 285 * @return 286 * -ENOMEM for mem allocation failure. 287 */ 288 __rte_experimental 289 int 290 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help); 291 292 293 /** 294 * Get a pointer to a container with memory allocated. The container is to be 295 * used embedded within an existing telemetry dict/array. 296 * 297 * @return 298 * Pointer to a container. 299 */ 300 __rte_experimental 301 struct rte_tel_data * 302 rte_tel_data_alloc(void); 303 304 /** 305 * @internal 306 * Free a container that has memory allocated. 307 * 308 * @param data 309 * Pointer to container. 310 *. 311 */ 312 __rte_experimental 313 void 314 rte_tel_data_free(struct rte_tel_data *data); 315 316 #endif 317