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