lib/librte_metrics/rte_metrics.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /**
  35  * @file
  36  *
  37  * DPDK Metrics module
  38  *
  39  * Metrics are statistics that are not generated by PMDs, and hence
  40  * are better reported through a mechanism that is independent from
  41  * the ethdev-based extended statistics. Providers will typically
  42  * be other libraries and consumers will typically be applications.
  43  *
  44  * Metric information is populated using a push model, where producers
  45  * update the values contained within the metric library by calling
  46  * an update function on the relevant metrics. Consumers receive
  47  * metric information by querying the central metric data, which is
  48  * held in shared memory. Currently only bulk querying of metrics
  49  * by consumers is supported.
  50  */
  51
  52 #ifndef _RTE_METRICS_H_
  53 #define _RTE_METRICS_H_
  54
  55 #include <stdint.h>
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 /** Maximum length of metric name (including null-terminator) */
  62 #define RTE_METRICS_MAX_NAME_LEN 64
  63
  64 /**
  65  * Global metric special id.
  66  *
  67  * When used for the port_id parameter when calling
  68  * rte_metrics_update_metric() or rte_metrics_update_metric(),
  69  * the global metric, which are not associated with any specific
  70  * port (i.e. device), are updated.
  71  */
  72 #define RTE_METRICS_GLOBAL -1
  73
  74
  75 /**
  76  * A name-key lookup for metrics.
  77  *
  78  * An array of this structure is returned by rte_metrics_get_names().
  79  * The struct rte_metric_value references these names via their array index.
  80  */
  81 struct rte_metric_name {
  82         /** String describing metric */
  83         char name[RTE_METRICS_MAX_NAME_LEN];
  84 };
  85
  86
  87 /**
  88  * Metric value structure.
  89  *
  90  * This structure is used by rte_metrics_get_values() to return metrics,
  91  * which are statistics that are not generated by PMDs. It maps a name key,
  92  * which corresponds to an index in the array returned by
  93  * rte_metrics_get_names().
  94  */
  95 struct rte_metric_value {
  96         /** Numeric identifier of metric. */
  97         uint16_t key;
  98         /** Value for metric */
  99         uint64_t value;
 100 };
 101
 102
 103 /**
 104  * Initializes metric module. This function must be called from
 105  * a primary process before metrics are used.
 106  *
 107  * @param socket_id
 108  *   Socket to use for shared memory allocation.
 109  */
 110 void rte_metrics_init(int socket_id);
 111
 112 /**
 113  * Register a metric, making it available as a reporting parameter.
 114  *
 115  * Registering a metric is the way producers declare a parameter
 116  * that they wish to be reported. Once registered, the associated
 117  * numeric key can be obtained via rte_metrics_get_names(), which
 118  * is required for updating said metric's value.
 119  *
 120  * @param name
 121  *   Metric name. If this exceeds RTE_METRICS_MAX_NAME_LEN (including
 122  *   the NULL terminator), it is truncated.
 123  *
 124  * @return
 125  *  - Zero or positive: Success (index key of new metric)
 126  *  - -EIO: Error, unable to access metrics shared memory
 127  *    (rte_metrics_init() not called)
 128  *  - -EINVAL: Error, invalid parameters
 129  *  - -ENOMEM: Error, maximum metrics reached
 130  */
 131 int rte_metrics_reg_name(const char *name);
 132
 133 /**
 134  * Register a set of metrics.
 135  *
 136  * This is a bulk version of rte_metrics_reg_names() and aside from
 137  * handling multiple keys at once is functionally identical.
 138  *
 139  * @param names
 140  *   List of metric names
 141  *
 142  * @param cnt_names
 143  *   Number of metrics in set
 144  *
 145  * @return
 146  *  - Zero or positive: Success (index key of start of set)
 147  *  - -EIO: Error, unable to access metrics shared memory
 148  *    (rte_metrics_init() not called)
 149  *  - -EINVAL: Error, invalid parameters
 150  *  - -ENOMEM: Error, maximum metrics reached
 151  */
 152 int rte_metrics_reg_names(const char * const *names, uint16_t cnt_names);
 153
 154 /**
 155  * Get metric name-key lookup table.
 156  *
 157  * @param names
 158  *   A struct rte_metric_name array of at least *capacity* in size to
 159  *   receive key names. If this is NULL, function returns the required
 160  *   number of elements for this array.
 161  *
 162  * @param capacity
 163  *   Size (number of elements) of struct rte_metric_name array.
 164  *   Disregarded if names is NULL.
 165  *
 166  * @return
 167  *   - Positive value above capacity: error, *names* is too small.
 168  *     Return value is required size.
 169  *   - Positive value equal or less than capacity: Success. Return
 170  *     value is number of elements filled in.
 171  *   - Negative value: error.
 172  */
 173 int rte_metrics_get_names(
 174         struct rte_metric_name *names,
 175         uint16_t capacity);
 176
 177 /**
 178  * Get metric value table.
 179  *
 180  * @param port_id
 181  *   Port id to query
 182  *
 183  * @param values
 184  *   A struct rte_metric_value array of at least *capacity* in size to
 185  *   receive metric ids and values. If this is NULL, function returns
 186  *   the required number of elements for this array.
 187  *
 188  * @param capacity
 189  *   Size (number of elements) of struct rte_metric_value array.
 190  *   Disregarded if names is NULL.
 191  *
 192  * @return
 193  *   - Positive value above capacity: error, *values* is too small.
 194  *     Return value is required size.
 195  *   - Positive value equal or less than capacity: Success. Return
 196  *     value is number of elements filled in.
 197  *   - Negative value: error.
 198  */
 199 int rte_metrics_get_values(
 200         int port_id,
 201         struct rte_metric_value *values,
 202         uint16_t capacity);
 203
 204 /**
 205  * Updates a metric
 206  *
 207  * @param port_id
 208  *   Port to update metrics for
 209  * @param key
 210  *   Id of metric to update
 211  * @param value
 212  *   New value
 213  *
 214  * @return
 215  *   - -EIO if unable to access shared metrics memory
 216  *   - Zero on success
 217  */
 218 int rte_metrics_update_value(
 219         int port_id,
 220         uint16_t key,
 221         const uint64_t value);
 222
 223 /**
 224  * Updates a metric set. Note that it is an error to try to
 225  * update across a set boundary.
 226  *
 227  * @param port_id
 228  *   Port to update metrics for
 229  * @param key
 230  *   Base id of metrics set to update
 231  * @param values
 232  *   Set of new values
 233  * @param count
 234  *   Number of new values
 235  *
 236  * @return
 237  *   - -ERANGE if count exceeds metric set size
 238  *   - -EIO if unable to access shared metrics memory
 239  *   - Zero on success
 240  */
 241 int rte_metrics_update_values(
 242         int port_id,
 243         uint16_t key,
 244         const uint64_t *values,
 245         uint32_t count);
 246
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251 #endif