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  * The telemetry library provides a method to retrieve statistics from
  27  * DPDK by sending a request message over a socket. DPDK will send
  28  * a JSON encoded response containing telemetry data.
  29  ***/
  30
  31 /** opaque structure used internally for managing data from callbacks */
  32 struct rte_tel_data;
  33
  34 /**
  35  * The types of data that can be managed in arrays or dicts.
  36  * For arrays, this must be specified at creation time, while for
  37  * dicts this is specified implicitly each time an element is added
  38  * via calling a type-specific function.
  39  */
  40 enum rte_tel_value_type {
  41         RTE_TEL_STRING_VAL, /** a string value */
  42         RTE_TEL_INT_VAL,    /** a signed 32-bit int value */
  43         RTE_TEL_U64_VAL,    /** an unsigned 64-bit int value */
  44         RTE_TEL_CONTAINER, /** a container struct */
  45 };
  46
  47 /**
  48  * Start an array of the specified type for returning from a callback
  49  *
  50  * @param d
  51  *   The data structure passed to the callback
  52  * @param type
  53  *   The type of the array of data
  54  * @return
  55  *   0 on success, negative errno on error
  56  */
  57 int
  58 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
  59
  60 /**
  61  * Start a dictionary of values for returning from a callback
  62  *
  63  * @param d
  64  *   The data structure passed to the callback
  65  * @return
  66  *   0 on success, negative errno on error
  67  */
  68 int
  69 rte_tel_data_start_dict(struct rte_tel_data *d);
  70
  71 /**
  72  * Set a string for returning from a callback
  73  *
  74  * @param d
  75  *   The data structure passed to the callback
  76  * @param str
  77  *   The string to be returned in the data structure
  78  * @return
  79  *   0 on success, negative errno on error, E2BIG on string truncation
  80  */
  81 int
  82 rte_tel_data_string(struct rte_tel_data *d, const char *str);
  83
  84 /**
  85  * Add a string to an array.
  86  * The array must have been started by rte_tel_data_start_array() with
  87  * RTE_TEL_STRING_VAL as the type parameter.
  88  *
  89  * @param d
  90  *   The data structure passed to the callback
  91  * @param str
  92  *   The string to be returned in the array
  93  * @return
  94  *   0 on success, negative errno on error, E2BIG on string truncation
  95  */
  96 int
  97 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
  98
  99 /**
 100  * Add an int to an array.
 101  * The array must have been started by rte_tel_data_start_array() with
 102  * RTE_TEL_INT_VAL as the type parameter.
 103  *
 104  * @param d
 105  *   The data structure passed to the callback
 106  * @param x
 107  *   The number to be returned in the array
 108  * @return
 109  *   0 on success, negative errno on error
 110  */
 111 int
 112 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
 113
 114 /**
 115  * Add a uint64_t to an array.
 116  * The array must have been started by rte_tel_data_start_array() with
 117  * RTE_TEL_U64_VAL as the type parameter.
 118  *
 119  * @param d
 120  *   The data structure passed to the callback
 121  * @param x
 122  *   The number to be returned in the array
 123  * @return
 124  *   0 on success, negative errno on error
 125  */
 126 int
 127 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
 128
 129 /**
 130  * Add a container to an array. A container is an existing telemetry data
 131  * array. The array the container is to be added to must have been started by
 132  * rte_tel_data_start_array() with RTE_TEL_CONTAINER as the type parameter.
 133  * The container type must be an array of type uint64_t/int/string.
 134  *
 135  * @param d
 136  *   The data structure passed to the callback
 137  * @param val
 138  *   The pointer to the container to be stored in the array.
 139  * @param keep
 140  *   Flag to indicate that the container memory should not be automatically
 141  *   freed by the telemetry library once it has finished with the data.
 142  *   1 = keep, 0 = free.
 143  * @return
 144  *   0 on success, negative errno on error
 145  */
 146 int
 147 rte_tel_data_add_array_container(struct rte_tel_data *d,
 148                 struct rte_tel_data *val, int keep);
 149
 150 /**
 151  * Add a string value to a dictionary.
 152  * The dict must have been started by rte_tel_data_start_dict().
 153  *
 154  * @param d
 155  *   The data structure passed to the callback
 156  * @param name
 157  *   The name the value is to be stored under in the dict
 158  * @param val
 159  *   The string to be stored in the dict
 160  * @return
 161  *   0 on success, negative errno on error, E2BIG on string truncation of
 162  *   either name or value.
 163  */
 164 int
 165 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
 166                 const char *val);
 167
 168 /**
 169  * Add an int value to a dictionary.
 170  * The dict must have been started by rte_tel_data_start_dict().
 171  *
 172  * @param d
 173  *   The data structure passed to the callback
 174  * @param name
 175  *   The name the value is to be stored under in the dict
 176  * @param val
 177  *   The number to be stored in the dict
 178  * @return
 179  *   0 on success, negative errno on error, E2BIG on string truncation of name.
 180  */
 181 int
 182 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
 183
 184 /**
 185  * Add a uint64_t 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 int
 198 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
 199                 const char *name, uint64_t val);
 200
 201 /**
 202  * Add a container to a dictionary. A container is an existing telemetry data
 203  * array. The dict the container is to be added to must have been started by
 204  * rte_tel_data_start_dict(). The container must be an array of type
 205  * uint64_t/int/string.
 206  *
 207  * @param d
 208  *   The data structure passed to the callback
 209  * @param name
 210  *   The name the value is to be stored under in the dict.
 211  * @param val
 212  *   The pointer to the container to be stored in the dict.
 213  * @param keep
 214  *   Flag to indicate that the container memory should not be automatically
 215  *   freed by the telemetry library once it has finished with the data.
 216  *   1 = keep, 0 = free.
 217  * @return
 218  *   0 on success, negative errno on error
 219  */
 220 int
 221 rte_tel_data_add_dict_container(struct rte_tel_data *d, const char *name,
 222                 struct rte_tel_data *val, int keep);
 223
 224 /**
 225  * This telemetry callback is used when registering a telemetry command.
 226  * It handles getting and formatting information to be returned to telemetry
 227  * when requested.
 228  *
 229  * @param cmd
 230  * The cmd that was requested by the client.
 231  * @param params
 232  * Contains data required by the callback function.
 233  * @param info
 234  * The information to be returned to the caller.
 235  *
 236  * @return
 237  * Length of buffer used on success.
 238  * @return
 239  * Negative integer on error.
 240  */
 241 typedef int (*telemetry_cb)(const char *cmd, const char *params,
 242                 struct rte_tel_data *info);
 243
 244 /**
 245  * Used for handling data received over a telemetry socket.
 246  *
 247  * @param sock_id
 248  * ID for the socket to be used by the handler.
 249  *
 250  * @return
 251  * Void.
 252  */
 253 typedef void * (*handler)(void *sock_id);
 254
 255 /**
 256  * Used when registering a command and callback function with telemetry.
 257  *
 258  * @param cmd
 259  * The command to register with telemetry.
 260  * @param fn
 261  * Callback function to be called when the command is requested.
 262  * @param help
 263  * Help text for the command.
 264  *
 265  * @return
 266  *  0 on success.
 267  * @return
 268  *  -EINVAL for invalid parameters failure.
 269  *  @return
 270  *  -ENOMEM for mem allocation failure.
 271  */
 272 int
 273 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
 274
 275
 276 /**
 277  * Get a pointer to a container with memory allocated. The container is to be
 278  * used embedded within an existing telemetry dict/array.
 279  *
 280  * @return
 281  *  Pointer to a container.
 282  */
 283 struct rte_tel_data *
 284 rte_tel_data_alloc(void);
 285
 286 /**
 287  * @internal
 288  * Free a container that has memory allocated.
 289  *
 290  * @param data
 291  *  Pointer to container.
 292  *.
 293  */
 294 void
 295 rte_tel_data_free(struct rte_tel_data *data);
 296
 297 #endif