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