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