1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #include <stdint.h> 6 7 #include <rte_compat.h> 8 9 #ifndef _RTE_TELEMETRY_H_ 10 #define _RTE_TELEMETRY_H_ 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 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 32-bit int value */ 47 RTE_TEL_U64_VAL, /** an unsigned 64-bit int value */ 48 RTE_TEL_CONTAINER, /** a container struct */ 49 }; 50 51 /** 52 * Start an array of the specified type for returning from a callback 53 * 54 * @param d 55 * The data structure passed to the callback 56 * @param type 57 * The type of the array of data 58 * @return 59 * 0 on success, negative errno on error 60 */ 61 int 62 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type); 63 64 /** 65 * Start a dictionary of values for returning from a callback 66 * 67 * @param d 68 * The data structure passed to the callback 69 * @return 70 * 0 on success, negative errno on error 71 */ 72 int 73 rte_tel_data_start_dict(struct rte_tel_data *d); 74 75 /** 76 * Set a string for returning from a callback 77 * 78 * @param d 79 * The data structure passed to the callback 80 * @param str 81 * The string to be returned in the data structure 82 * @return 83 * 0 on success, negative errno on error, E2BIG on string truncation 84 */ 85 int 86 rte_tel_data_string(struct rte_tel_data *d, const char *str); 87 88 /** 89 * Add a string to an array. 90 * The array must have been started by rte_tel_data_start_array() with 91 * RTE_TEL_STRING_VAL as the type parameter. 92 * 93 * @param d 94 * The data structure passed to the callback 95 * @param str 96 * The string to be returned in the array 97 * @return 98 * 0 on success, negative errno on error, E2BIG on string truncation 99 */ 100 int 101 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str); 102 103 /** 104 * Add an int to an array. 105 * The array must have been started by rte_tel_data_start_array() with 106 * RTE_TEL_INT_VAL as the type parameter. 107 * 108 * @param d 109 * The data structure passed to the callback 110 * @param x 111 * The number to be returned in the array 112 * @return 113 * 0 on success, negative errno on error 114 */ 115 int 116 rte_tel_data_add_array_int(struct rte_tel_data *d, int x); 117 118 /** 119 * Add a uint64_t to an array. 120 * The array must have been started by rte_tel_data_start_array() with 121 * RTE_TEL_U64_VAL as the type parameter. 122 * 123 * @param d 124 * The data structure passed to the callback 125 * @param x 126 * The number to be returned in the array 127 * @return 128 * 0 on success, negative errno on error 129 */ 130 int 131 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x); 132 133 /** 134 * Add a container to an array. A container is an existing telemetry data 135 * array. The array the container is to be added to must have been started by 136 * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter. 137 * The container type must be an array of type uint64_t/int/string. 138 * 139 * @param d 140 * The data structure passed to the callback 141 * @param val 142 * The pointer to the container to be stored in the array. 143 * @param keep 144 * Flag to indicate that the container memory should not be automatically 145 * freed by the telemetry library once it has finished with the data. 146 * 1 = keep, 0 = free. 147 * @return 148 * 0 on success, negative errno on error 149 */ 150 int 151 rte_tel_data_add_array_container(struct rte_tel_data *d, 152 struct rte_tel_data *val, int keep); 153 154 /** 155 * Add a string value to a dictionary. 156 * The dict must have been started by rte_tel_data_start_dict(). 157 * 158 * @param d 159 * The data structure passed to the callback 160 * @param name 161 * The name the value is to be stored under in the dict 162 * @param val 163 * The string to be stored in the dict 164 * @return 165 * 0 on success, negative errno on error, E2BIG on string truncation of 166 * either name or value. 167 */ 168 int 169 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name, 170 const char *val); 171 172 /** 173 * Add an int value to a dictionary. 174 * The dict must have been started by rte_tel_data_start_dict(). 175 * 176 * @param d 177 * The data structure passed to the callback 178 * @param name 179 * The name the value is to be stored under in the dict 180 * @param val 181 * The number to be stored in the dict 182 * @return 183 * 0 on success, negative errno on error, E2BIG on string truncation of name. 184 */ 185 int 186 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val); 187 188 /** 189 * Add a uint64_t value to a dictionary. 190 * The dict must have been started by rte_tel_data_start_dict(). 191 * 192 * @param d 193 * The data structure passed to the callback 194 * @param name 195 * The name the value is to be stored under in the dict 196 * @param val 197 * The number to be stored in the dict 198 * @return 199 * 0 on success, negative errno on error, E2BIG on string truncation of name. 200 */ 201 int 202 rte_tel_data_add_dict_u64(struct rte_tel_data *d, 203 const char *name, uint64_t val); 204 205 /** 206 * Add a container to a dictionary. A container is an existing telemetry data 207 * array. The dict the container is to be added to must have been started by 208 * rte_tel_data_start_dict(). The container must be an array of type 209 * uint64_t/int/string. 210 * 211 * @param d 212 * The data structure passed to the callback 213 * @param name 214 * The name the value is to be stored under in the dict. 215 * @param val 216 * The pointer to the container to be stored in the dict. 217 * @param keep 218 * Flag to indicate that the container memory should not be automatically 219 * freed by the telemetry library once it has finished with the data. 220 * 1 = keep, 0 = free. 221 * @return 222 * 0 on success, negative errno on error 223 */ 224 int 225 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name, 226 struct rte_tel_data *val, int keep); 227 228 /** 229 * This telemetry callback is used when registering a telemetry command. 230 * It handles getting and formatting information to be returned to telemetry 231 * when requested. 232 * 233 * @param cmd 234 * The cmd that was requested by the client. 235 * @param params 236 * Contains data required by the callback function. 237 * @param info 238 * The information to be returned to the caller. 239 * 240 * @return 241 * Length of buffer used on success. 242 * @return 243 * Negative integer on error. 244 */ 245 typedef int (*telemetry_cb)(const char *cmd, const char *params, 246 struct rte_tel_data *info); 247 248 /** 249 * Used for handling data received over a telemetry socket. 250 * 251 * @param sock_id 252 * ID for the socket to be used by the handler. 253 * 254 * @return 255 * Void. 256 */ 257 typedef void * (*handler)(void *sock_id); 258 259 /** 260 * Used when registering a command and callback function with telemetry. 261 * 262 * @param cmd 263 * The command to register with telemetry. 264 * @param fn 265 * Callback function to be called when the command is requested. 266 * @param help 267 * Help text for the command. 268 * 269 * @return 270 * 0 on success. 271 * @return 272 * -EINVAL for invalid parameters failure. 273 * @return 274 * -ENOMEM for mem allocation failure. 275 */ 276 int 277 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help); 278 279 280 /** 281 * Get a pointer to a container with memory allocated. The container is to be 282 * used embedded within an existing telemetry dict/array. 283 * 284 * @return 285 * Pointer to a container. 286 */ 287 struct rte_tel_data * 288 rte_tel_data_alloc(void); 289 290 /** 291 * @internal 292 * Free a container that has memory allocated. 293 * 294 * @param data 295 * Pointer to container. 296 *. 297 */ 298 void 299 rte_tel_data_free(struct rte_tel_data *data); 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 #endif 306