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