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