lib/librte_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
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /** Maximum length of metric name (including null-terminator) */
  33 #define RTE_METRICS_MAX_NAME_LEN 64
  34
  35 /**
  36  * Global metric special id.
  37  *
  38  * When used for the port_id parameter when calling
  39  * rte_metrics_update_metric() or rte_metrics_update_metric(),
  40  * the global metric, which are not associated with any specific
  41  * port (i.e. device), are updated.
  42  */
  43 #define RTE_METRICS_GLOBAL -1
  44
  45
  46 /**
  47  * A name-key lookup for metrics.
  48  *
  49  * An array of this structure is returned by rte_metrics_get_names().
  50  * The struct rte_metric_value references these names via their array index.
  51  */
  52 struct rte_metric_name {
  53         /** String describing metric */
  54         char name[RTE_METRICS_MAX_NAME_LEN];
  55 };
  56
  57
  58 /**
  59  * Metric value structure.
  60  *
  61  * This structure is used by rte_metrics_get_values() to return metrics,
  62  * which are statistics that are not generated by PMDs. It maps a name key,
  63  * which corresponds to an index in the array returned by
  64  * rte_metrics_get_names().
  65  */
  66 struct rte_metric_value {
  67         /** Numeric identifier of metric. */
  68         uint16_t key;
  69         /** Value for metric */
  70         uint64_t value;
  71 };
  72
  73
  74 /**
  75  * Initializes metric module. This function must be called from
  76  * a primary process before metrics are used.
  77  *
  78  * @param socket_id
  79  *   Socket to use for shared memory allocation.
  80  */
  81 void rte_metrics_init(int socket_id);
  82
  83 /**
  84  * Register a metric, making it available as a reporting parameter.
  85  *
  86  * Registering a metric is the way producers declare a parameter
  87  * that they wish to be reported. Once registered, the associated
  88  * numeric key can be obtained via rte_metrics_get_names(), which
  89  * is required for updating said metric's value.
  90  *
  91  * @param name
  92  *   Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including
  93  *   the NULL terminator), it is truncated.
  94  *
  95  * @return
  96  *  - Zero or positive: Success (index key of new metric)
  97  *  - -EIO: Error, unable to access metrics shared memory
  98  *    (rte_metrics_init() not called)
  99  *  - -EINVAL: Error, invalid parameters
 100  *  - -ENOMEM: Error, maximum metrics reached
 101  */
 102 int rte_metrics_reg_name(const char *name);
 103
 104 /**
 105  * Register a set of metrics.
 106  *
 107  * This is a bulk version of rte_metrics_reg_names() and aside from
 108  * handling multiple keys at once is functionally identical.
 109  *
 110  * @param names
 111  *   List of metric names
 112  *
 113  * @param cnt_names
 114  *   Number of metrics in set
 115  *
 116  * @return
 117  *  - Zero or positive: Success (index key of start of set)
 118  *  - -EIO: Error, unable to access metrics shared memory
 119  *    (rte_metrics_init() not called)
 120  *  - -EINVAL: Error, invalid parameters
 121  *  - -ENOMEM: Error, maximum metrics reached
 122  */
 123 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names);
 124
 125 /**
 126  * Get metric name-key lookup table.
 127  *
 128  * @param names
 129  *   A struct rte_metric_name array of at least *capacity* in size to
 130  *   receive key names. If this is NULL, function returns the required
 131  *   number of elements for this array.
 132  *
 133  * @param capacity
 134  *   Size (number of elements) of struct rte_metric_name array.
 135  *   Disregarded if names is NULL.
 136  *
 137  * @return
 138  *   - Positive value above capacity: error, *names* is too small.
 139  *     Return value is required size.
 140  *   - Positive value equal or less than capacity: Success. Return
 141  *     value is number of elements filled in.
 142  *   - Negative value: error.
 143  */
 144 int rte_metrics_get_names(
 145         struct rte_metric_name *names,
 146         uint16_t capacity);
 147
 148 /**
 149  * Get metric value table.
 150  *
 151  * @param port_id
 152  *   Port id to query
 153  *
 154  * @param values
 155  *   A struct rte_metric_value array of at least *capacity* in size to
 156  *   receive metric ids and values. If this is NULL, function returns
 157  *   the required number of elements for this array.
 158  *
 159  * @param capacity
 160  *   Size (number of elements) of struct rte_metric_value array.
 161  *   Disregarded if names is NULL.
 162  *
 163  * @return
 164  *   - Positive value above capacity: error, *values* is too small.
 165  *     Return value is required size.
 166  *   - Positive value equal or less than capacity: Success. Return
 167  *     value is number of elements filled in.
 168  *   - Negative value: error.
 169  */
 170 int rte_metrics_get_values(
 171         int port_id,
 172         struct rte_metric_value *values,
 173         uint16_t capacity);
 174
 175 /**
 176  * Updates a metric
 177  *
 178  * @param port_id
 179  *   Port to update metrics for
 180  * @param key
 181  *   Id of metric to update
 182  * @param value
 183  *   New value
 184  *
 185  * @return
 186  *   - -EIO if unable to access shared metrics memory
 187  *   - Zero on success
 188  */
 189 int rte_metrics_update_value(
 190         int port_id,
 191         uint16_t key,
 192         const uint64_t value);
 193
 194 /**
 195  * Updates a metric set. Note that it is an error to try to
 196  * update across a set boundary.
 197  *
 198  * @param port_id
 199  *   Port to update metrics for
 200  * @param key
 201  *   Base id of metrics set to update
 202  * @param values
 203  *   Set of new values
 204  * @param count
 205  *   Number of new values
 206  *
 207  * @return
 208  *   - -ERANGE if count exceeds metric set size
 209  *   - -EIO if unable to access shared metrics memory
 210  *   - Zero on success
 211  */
 212 int rte_metrics_update_values(
 213         int port_id,
 214         uint16_t key,
 215         const uint64_t *values,
 216         uint32_t count);
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif