lib/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
  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 64
  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