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  * @warning
  24  * @b EXPERIMENTAL: all functions in this file may change without prior notice
  25  *
  26  * @file
  27  * RTE Telemetry
  28  *
  29  * The telemetry library provides a method to retrieve statistics from
  30  * DPDK by sending a request message over a socket. DPDK will send
  31  * a JSON encoded response containing telemetry data.
  32  ***/
  33
  34 /** opaque structure used internally for managing data from callbacks */
  35 struct rte_tel_data;
  36
  37 /**
  38  * The types of data that can be managed in arrays or dicts.
  39  * For arrays, this must be specified at creation time, while for
  40  * dicts this is specified implicitly each time an element is added
  41  * via calling a type-specific function.
  42  */
  43 enum rte_tel_value_type {
  44         RTE_TEL_STRING_VAL, /** a string value */
  45         RTE_TEL_INT_VAL,    /** a signed 32-bit int value */
  46         RTE_TEL_U64_VAL,    /** an unsigned 64-bit int value */
  47 };
  48
  49 /**
  50  * Start an array of the specified type for returning from a callback
  51  *
  52  * @param d
  53  *   The data structure passed to the callback
  54  * @param type
  55  *   The type of the array of data
  56  * @return
  57  *   0 on success, negative errno on error
  58  */
  59 __rte_experimental
  60 int
  61 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
  62
  63 /**
  64  * Start a dictionary of values for returning from a callback
  65  *
  66  * @param d
  67  *   The data structure passed to the callback
  68  * @return
  69  *   0 on success, negative errno on error
  70  */
  71 __rte_experimental
  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 __rte_experimental
  86 int
  87 rte_tel_data_string(struct rte_tel_data *d, const char *str);
  88
  89 /**
  90  * Add a string to an array.
  91  * The array must have been started by rte_tel_data_start_array() with
  92  * RTE_TEL_STRING_VAL as the type parameter.
  93  *
  94  * @param d
  95  *   The data structure passed to the callback
  96  * @param str
  97  *   The string to be returned in the array
  98  * @return
  99  *   0 on success, negative errno on error, E2BIG on string truncation
 100  */
 101 __rte_experimental
 102 int
 103 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
 104
 105 /**
 106  * Add an int to an array.
 107  * The array must have been started by rte_tel_data_start_array() with
 108  * RTE_TEL_INT_VAL as the type parameter.
 109  *
 110  * @param d
 111  *   The data structure passed to the callback
 112  * @param x
 113  *   The number to be returned in the array
 114  * @return
 115  *   0 on success, negative errno on error
 116  */
 117 __rte_experimental
 118 int
 119 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
 120
 121 /**
 122  * Add a uint64_t to an array.
 123  * The array must have been started by rte_tel_data_start_array() with
 124  * RTE_TEL_U64_VAL as the type parameter.
 125  *
 126  * @param d
 127  *   The data structure passed to the callback
 128  * @param x
 129  *   The number to be returned in the array
 130  * @return
 131  *   0 on success, negative errno on error
 132  */
 133 __rte_experimental
 134 int
 135 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
 136
 137 /**
 138  * Add a string value to a dictionary.
 139  * The dict must have been started by rte_tel_data_start_dict().
 140  *
 141  * @param d
 142  *   The data structure passed to the callback
 143  * @param name
 144  *   The name the value is to be stored under in the dict
 145  * @param val
 146  *   The string to be stored in the dict
 147  * @return
 148  *   0 on success, negative errno on error, E2BIG on string truncation of
 149  *   either name or value.
 150  */
 151 __rte_experimental
 152 int
 153 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
 154                 const char *val);
 155
 156 /**
 157  * Add an int value to a dictionary.
 158  * The dict must have been started by rte_tel_data_start_dict().
 159  *
 160  * @param d
 161  *   The data structure passed to the callback
 162  * @param name
 163  *   The name the value is to be stored under in the dict
 164  * @param val
 165  *   The number to be stored in the dict
 166  * @return
 167  *   0 on success, negative errno on error, E2BIG on string truncation of name.
 168  */
 169 __rte_experimental
 170 int
 171 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
 172
 173 /**
 174  * Add a uint64_t value to a dictionary.
 175  * The dict must have been started by rte_tel_data_start_dict().
 176  *
 177  * @param d
 178  *   The data structure passed to the callback
 179  * @param name
 180  *   The name the value is to be stored under in the dict
 181  * @param val
 182  *   The number to be stored in the dict
 183  * @return
 184  *   0 on success, negative errno on error, E2BIG on string truncation of name.
 185  */
 186 __rte_experimental
 187 int
 188 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
 189                 const char *name, uint64_t val);
 190
 191 /**
 192  * This telemetry callback is used when registering a telemetry command.
 193  * It handles getting and formatting information to be returned to telemetry
 194  * when requested.
 195  *
 196  * @param cmd
 197  * The cmd that was requested by the client.
 198  * @param params
 199  * Contains data required by the callback function.
 200  * @param info
 201  * The information to be returned to the caller.
 202  *
 203  * @return
 204  * Length of buffer used on success.
 205  * @return
 206  * Negative integer on error.
 207  */
 208 typedef int (*telemetry_cb)(const char *cmd, const char *params,
 209                 struct rte_tel_data *info);
 210
 211 /**
 212  * Used for handling data received over a telemetry socket.
 213  *
 214  * @param sock_id
 215  * ID for the socket to be used by the handler.
 216  *
 217  * @return
 218  * Void.
 219  */
 220 typedef void * (*handler)(void *sock_id);
 221
 222 /**
 223  * Used when registering a command and callback function with telemetry.
 224  *
 225  * @param cmd
 226  * The command to register with telemetry.
 227  * @param fn
 228  * Callback function to be called when the command is requested.
 229  * @param help
 230  * Help text for the command.
 231  *
 232  * @return
 233  *  0 on success.
 234  * @return
 235  *  -EINVAL for invalid parameters failure.
 236  *  @return
 237  *  -ENOENT if max callbacks limit has been reached.
 238  */
 239 __rte_experimental
 240 int
 241 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
 242
 243 /**
 244  * Initialize Telemetry.
 245  *
 246  * @return
 247  *  0 on success.
 248  * @return
 249  *  -1 on failure.
 250  */
 251 __rte_experimental
 252 int
 253 rte_telemetry_init(void);
 254 #endif