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 };
  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 string value to a dictionary.
 142  * The dict must have been started by rte_tel_data_start_dict().
 143  *
 144  * @param d
 145  *   The data structure passed to the callback
 146  * @param name
 147  *   The name the value is to be stored under in the dict
 148  * @param val
 149  *   The string to be stored in the dict
 150  * @return
 151  *   0 on success, negative errno on error, E2BIG on string truncation of
 152  *   either name or value.
 153  */
 154 __rte_experimental
 155 int
 156 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
 157                 const char *val);
 158
 159 /**
 160  * Add an int value to a dictionary.
 161  * The dict must have been started by rte_tel_data_start_dict().
 162  *
 163  * @param d
 164  *   The data structure passed to the callback
 165  * @param name
 166  *   The name the value is to be stored under in the dict
 167  * @param val
 168  *   The number to be stored in the dict
 169  * @return
 170  *   0 on success, negative errno on error, E2BIG on string truncation of name.
 171  */
 172 __rte_experimental
 173 int
 174 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
 175
 176 /**
 177  * Add a uint64_t value to a dictionary.
 178  * The dict must have been started by rte_tel_data_start_dict().
 179  *
 180  * @param d
 181  *   The data structure passed to the callback
 182  * @param name
 183  *   The name the value is to be stored under in the dict
 184  * @param val
 185  *   The number to be stored in the dict
 186  * @return
 187  *   0 on success, negative errno on error, E2BIG on string truncation of name.
 188  */
 189 __rte_experimental
 190 int
 191 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
 192                 const char *name, uint64_t val);
 193
 194 /**
 195  * This telemetry callback is used when registering a telemetry command.
 196  * It handles getting and formatting information to be returned to telemetry
 197  * when requested.
 198  *
 199  * @param cmd
 200  * The cmd that was requested by the client.
 201  * @param params
 202  * Contains data required by the callback function.
 203  * @param info
 204  * The information to be returned to the caller.
 205  *
 206  * @return
 207  * Length of buffer used on success.
 208  * @return
 209  * Negative integer on error.
 210  */
 211 typedef int (*telemetry_cb)(const char *cmd, const char *params,
 212                 struct rte_tel_data *info);
 213
 214 /**
 215  * Used for handling data received over a telemetry socket.
 216  *
 217  * @param sock_id
 218  * ID for the socket to be used by the handler.
 219  *
 220  * @return
 221  * Void.
 222  */
 223 typedef void * (*handler)(void *sock_id);
 224
 225 /**
 226  * Used when registering a command and callback function with telemetry.
 227  *
 228  * @param cmd
 229  * The command to register with telemetry.
 230  * @param fn
 231  * Callback function to be called when the command is requested.
 232  * @param help
 233  * Help text for the command.
 234  *
 235  * @return
 236  *  0 on success.
 237  * @return
 238  *  -EINVAL for invalid parameters failure.
 239  *  @return
 240  *  -ENOENT if max callbacks limit has been reached.
 241  */
 242 __rte_experimental
 243 int
 244 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
 245
 246 /**
 247  * @internal
 248  * Initialize Telemetry.
 249  *
 250  * @param runtime_dir
 251  * The runtime directory of DPDK.
 252  * @param cpuset
 253  * The CPU set to be used for setting the thread affinity.
 254  * @param err_str
 255  * This err_str pointer should point to NULL on entry. In the case of an error
 256  * or warning, it will be non-NULL on exit.
 257  *
 258  * @return
 259  *  0 on success.
 260  * @return
 261  *  -1 on failure.
 262  */
 263 __rte_experimental
 264 int
 265 rte_telemetry_init(const char *runtime_dir, rte_cpuset_t *cpuset,
 266                 const char **err_str);
 267
 268 #endif