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  * This telemetry callback is used when registering a telemetry command.
  51  * It handles getting and formatting information to be returned to telemetry
  52  * when requested.
  53  *
  54  * @param cmd
  55  * The cmd that was requested by the client.
  56  * @param params
  57  * Contains data required by the callback function.
  58  * @param info
  59  * The information to be returned to the caller.
  60  *
  61  * @return
  62  * Length of buffer used on success.
  63  * @return
  64  * Negative integer on error.
  65  */
  66 typedef int (*telemetry_cb)(const char *cmd, const char *params,
  67                 struct rte_tel_data *info);
  68
  69 /**
  70  * Used for handling data received over a telemetry socket.
  71  *
  72  * @param sock_id
  73  * ID for the socket to be used by the handler.
  74  *
  75  * @return
  76  * Void.
  77  */
  78 typedef void * (*handler)(void *sock_id);
  79
  80 /**
  81  * @warning
  82  * @b EXPERIMENTAL: this API may change without prior notice
  83  *
  84  * Initialize Telemetry
  85  *
  86  * @return
  87  *  0 on successful initialisation.
  88  * @return
  89  *  -ENOMEM on memory allocation error
  90  * @return
  91  *  -EPERM on unknown error failure
  92  * @return
  93  *  -EALREADY if Telemetry is already initialised.
  94  */
  95 __rte_experimental
  96 int32_t
  97 rte_telemetry_init(void);
  98
  99 /**
 100  * @warning
 101  * @b EXPERIMENTAL: this API may change without prior notice
 102  *
 103  * Clean up and free memory.
 104  *
 105  * @return
 106  *  0 on success
 107  * @return
 108  *  -EPERM on failure
 109  */
 110 __rte_experimental
 111 int32_t
 112 rte_telemetry_cleanup(void);
 113
 114 /**
 115  * @warning
 116  * @b EXPERIMENTAL: this API may change without prior notice
 117  *
 118  * Runs various tests to ensure telemetry initialisation and register/unregister
 119  * functions are working correctly.
 120  *
 121  * @return
 122  *  0 on success when all tests have passed
 123  * @return
 124  *  -1 on failure when the test has failed
 125  */
 126 __rte_experimental
 127 int32_t
 128 rte_telemetry_selftest(void);
 129
 130 /**
 131  * Used when registering a command and callback function with telemetry.
 132  *
 133  * @param cmd
 134  * The command to register with telemetry.
 135  * @param fn
 136  * Callback function to be called when the command is requested.
 137  * @param help
 138  * Help text for the command.
 139  *
 140  * @return
 141  *  0 on success.
 142  * @return
 143  *  -EINVAL for invalid parameters failure.
 144  *  @return
 145  *  -ENOENT if max callbacks limit has been reached.
 146  */
 147 __rte_experimental
 148 int
 149 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
 150
 151 /**
 152  * Initialize new version of Telemetry.
 153  *
 154  * @return
 155  *  0 on success.
 156  * @return
 157  *  -1 on failure.
 158  */
 159 __rte_experimental
 160 int
 161 rte_telemetry_new_init(void);
 162 #endif