lib/librte_telemetry/rte_telemetry.h

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