lib/metrics/rte_metrics.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 /**
   6  * @file
   7  *
   8  * DPDK Metrics module
   9  *
  10  * Metrics are statistics that are not generated by PMDs, and hence
  11  * are better reported through a mechanism that is independent from
  12  * the ethdev-based extended statistics. Providers will typically
  13  * be other libraries and consumers will typically be applications.
  14  *
  15  * Metric information is populated using a push model, where producers
  16  * update the values contained within the metric library by calling
  17  * an update function on the relevant metrics. Consumers receive
  18  * metric information by querying the central metric data, which is
  19  * held in shared memory. Currently only bulk querying of metrics
  20  * by consumers is supported.
  21  */
  22
  23 #ifndef _RTE_METRICS_H_
  24 #define _RTE_METRICS_H_
  25
  26 #include <stdint.h>
  27 #include <rte_compat.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 extern int metrics_initialized;
  34
  35 /** Maximum length of metric name (including null-terminator) */
  36 #define RTE_METRICS_MAX_NAME_LEN 64
  37 #define RTE_METRICS_MAX_METRICS 256
  38
  39 /**
  40  * Global metric special id.
  41  *
  42  * When used for the port_id parameter when calling
  43  * rte_metrics_update_metric() or rte_metrics_update_metric(),
  44  * the global metric, which are not associated with any specific
  45  * port (i.e. device), are updated.
  46  */
  47 #define RTE_METRICS_GLOBAL -1
  48
  49 /**
  50  * A name-key lookup for metrics.
  51  *
  52  * An array of this structure is returned by rte_metrics_get_names().
  53  * The struct rte_metric_value references these names via their array index.
  54  */
  55 struct rte_metric_name {
  56         /** String describing metric */
  57         char name[RTE_METRICS_MAX_NAME_LEN];
  58 };
  59
  60
  61 /**
  62  * Metric value structure.
  63  *
  64  * This structure is used by rte_metrics_get_values() to return metrics,
  65  * which are statistics that are not generated by PMDs. It maps a name key,
  66  * which corresponds to an index in the array returned by
  67  * rte_metrics_get_names().
  68  */
  69 struct rte_metric_value {
  70         /** Numeric identifier of metric. */
  71         uint16_t key;
  72         /** Value for metric */
  73         uint64_t value;
  74 };
  75
  76 /**
  77  * Initializes metric module. This function must be called from
  78  * a primary process before metrics are used.
  79  *
  80  * @param socket_id
  81  *   Socket to use for shared memory allocation.
  82  */
  83 void rte_metrics_init(int socket_id);
  84
  85 /**
  86  * @warning
  87  * @b EXPERIMENTAL: this API may change without prior notice
  88  *
  89  * Deinitialize metric module. This function must be called from
  90  * a primary process after all the metrics usage is over, to
  91  *  release the shared memory.
  92  *
  93  * @return
  94  *  -EINVAL - invalid parameter.
  95  *  -EIO: Error, unable to access metrics shared memory
  96  *    (rte_metrics_init() not called)
  97  *  0 - success
  98  */
  99 __rte_experimental
 100 int rte_metrics_deinit(void);
 101
 102 /**
 103  * Register a metric, making it available as a reporting parameter.
 104  *
 105  * Registering a metric is the way producers declare a parameter
 106  * that they wish to be reported. Once registered, the associated
 107  * numeric key can be obtained via rte_metrics_get_names(), which
 108  * is required for updating said metric's value.
 109  *
 110  * @param name
 111  *   Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including
 112  *   the NULL terminator), it is truncated.
 113  *
 114  * @return
 115  *  - Zero or positive: Success (index key of new metric)
 116  *  - -EIO: Error, unable to access metrics shared memory
 117  *    (rte_metrics_init() not called)
 118  *  - -EINVAL: Error, invalid parameters
 119  *  - -ENOMEM: Error, maximum metrics reached
 120  */
 121 int rte_metrics_reg_name(const char *name);
 122
 123 /**
 124  * Register a set of metrics.
 125  *
 126  * This is a bulk version of rte_metrics_reg_names() and aside from
 127  * handling multiple keys at once is functionally identical.
 128  *
 129  * @param names
 130  *   List of metric names
 131  *
 132  * @param cnt_names
 133  *   Number of metrics in set
 134  *
 135  * @return
 136  *  - Zero or positive: Success (index key of start of set)
 137  *  - -EIO: Error, unable to access metrics shared memory
 138  *    (rte_metrics_init() not called)
 139  *  - -EINVAL: Error, invalid parameters
 140  *  - -ENOMEM: Error, maximum metrics reached
 141  */
 142 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names);
 143
 144 /**
 145  * Get metric name-key lookup table.
 146  *
 147  * @param names
 148  *   A struct rte_metric_name array of at least *capacity* in size to
 149  *   receive key names. If this is NULL, function returns the required
 150  *   number of elements for this array.
 151  *
 152  * @param capacity
 153  *   Size (number of elements) of struct rte_metric_name array.
 154  *   Disregarded if names is NULL.
 155  *
 156  * @return
 157  *   - Positive value above capacity: error, *names* is too small.
 158  *     Return value is required size.
 159  *   - Positive value equal or less than capacity: Success. Return
 160  *     value is number of elements filled in.
 161  *   - Negative value: error.
 162  */
 163 int rte_metrics_get_names(
 164         struct rte_metric_name *names,
 165         uint16_t capacity);
 166
 167 /**
 168  * Get metric value table.
 169  *
 170  * @param port_id
 171  *   Port id to query
 172  *
 173  * @param values
 174  *   A struct rte_metric_value array of at least *capacity* in size to
 175  *   receive metric ids and values. If this is NULL, function returns
 176  *   the required number of elements for this array.
 177  *
 178  * @param capacity
 179  *   Size (number of elements) of struct rte_metric_value array.
 180  *   Disregarded if names is NULL.
 181  *
 182  * @return
 183  *   - Positive value above capacity: error, *values* is too small.
 184  *     Return value is required size.
 185  *   - Positive value equal or less than capacity: Success. Return
 186  *     value is number of elements filled in.
 187  *   - Negative value: error.
 188  */
 189 int rte_metrics_get_values(
 190         int port_id,
 191         struct rte_metric_value *values,
 192         uint16_t capacity);
 193
 194 /**
 195  * Updates a metric
 196  *
 197  * @param port_id
 198  *   Port to update metrics for
 199  * @param key
 200  *   Id of metric to update
 201  * @param value
 202  *   New value
 203  *
 204  * @return
 205  *   - -EIO if unable to access shared metrics memory
 206  *   - Zero on success
 207  */
 208 int rte_metrics_update_value(
 209         int port_id,
 210         uint16_t key,
 211         const uint64_t value);
 212
 213 /**
 214  * Updates a metric set. Note that it is an error to try to
 215  * update across a set boundary.
 216  *
 217  * @param port_id
 218  *   Port to update metrics for
 219  * @param key
 220  *   Base id of metrics set to update
 221  * @param values
 222  *   Set of new values
 223  * @param count
 224  *   Number of new values
 225  *
 226  * @return
 227  *   - -ERANGE if count exceeds metric set size
 228  *   - -EIO if unable to access shared metrics memory
 229  *   - Zero on success
 230  */
 231 int rte_metrics_update_values(
 232         int port_id,
 233         uint16_t key,
 234         const uint64_t *values,
 235         uint32_t count);
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif