lib/librte_ethdev/rte_mtr.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright 2017 Intel Corporation
   5  *   Copyright 2017 NXP
   6  *   Copyright 2017 Cavium
   7  *
   8  *   Redistribution and use in source and binary forms, with or without
   9  *   modification, are permitted provided that the following conditions
  10  *   are met:
  11  *
  12  *     * Redistributions of source code must retain the above copyright
  13  *       notice, this list of conditions and the following disclaimer.
  14  *     * Redistributions in binary form must reproduce the above copyright
  15  *       notice, this list of conditions and the following disclaimer in
  16  *       the documentation and/or other materials provided with the
  17  *       distribution.
  18  *     * Neither the name of Intel Corporation nor the names of its
  19  *       contributors may be used to endorse or promote products derived
  20  *       from this software without specific prior written permission.
  21  *
  22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef __INCLUDE_RTE_MTR_H__
  36 #define __INCLUDE_RTE_MTR_H__
  37
  38 /**
  39  * @file
  40  * RTE Generic Traffic Metering and Policing API
  41  *
  42  * This interface provides the ability to configure the traffic metering and
  43  * policing (MTR) in a generic way.
  44  *
  45  * The processing done for each input packet hitting a MTR object is:
  46  *    A) Traffic metering: The packet is assigned a color (the meter output
  47  *       color), based on the previous history of the flow reflected in the
  48  *       current state of the MTR object, according to the specific traffic
  49  *       metering algorithm. The traffic metering algorithm can typically work
  50  *       in color aware mode, in which case the input packet already has an
  51  *       initial color (the input color), or in color blind mode, which is
  52  *       equivalent to considering all input packets initially colored as green.
  53  *    B) Policing: There is a separate policer action configured for each meter
  54  *       output color, which can:
  55  *          a) Drop the packet.
  56  *          b) Keep the same packet color: the policer output color matches the
  57  *             meter output color (essentially a no-op action).
  58  *          c) Recolor the packet: the policer output color is different than
  59  *             the meter output color.
  60  *       The policer output color is the output color of the packet, which is
  61  *       set in the packet meta-data (i.e. struct rte_mbuf::sched::color).
  62  *    C) Statistics: The set of counters maintained for each MTR object is
  63  *       configurable and subject to the implementation support. This set
  64  *       includes the number of packets and bytes dropped or passed for each
  65  *       output color.
  66  *
  67  * Once successfully created, an MTR object is linked to one or several flows
  68  * through the meter action of the flow API.
  69  *    A) Whether an MTR object is private to a flow or potentially shared by
  70  *       several flows has to be specified at creation time.
  71  *    B) Several meter actions can be potentially registered for the same flow.
  72  *
  73  * @warning
  74  * @b EXPERIMENTAL: this API may change without prior notice
  75  */
  76 #include <stdint.h>
  77 #include <rte_compat.h>
  78 #include <rte_common.h>
  79 #include <rte_meter.h>
  80
  81 #ifdef __cplusplus
  82 extern "C" {
  83 #endif
  84
  85 /* New rte_color is defined and used to deprecate rte_mtr_color soon. */
  86 #define rte_mtr_color rte_color
  87 #define RTE_MTR_GREEN RTE_COLOR_GREEN
  88 #define RTE_MTR_YELLOW RTE_COLOR_YELLOW
  89 #define RTE_MTR_RED RTE_COLOR_RED
  90 #define RTE_MTR_COLORS RTE_COLORS
  91
  92 /**
  93  * Statistics counter type
  94  */
  95 enum rte_mtr_stats_type {
  96         /** Number of packets passed as green by the policer. */
  97         RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
  98
  99         /** Number of packets passed as yellow by the policer. */
 100         RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
 101
 102         /** Number of packets passed as red by the policer. */
 103         RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
 104
 105         /** Number of packets dropped by the policer. */
 106         RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
 107
 108         /** Number of bytes passed as green by the policer. */
 109         RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
 110
 111         /** Number of bytes passed as yellow by the policer. */
 112         RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
 113
 114         /** Number of bytes passed as red by the policer. */
 115         RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
 116
 117         /** Number of bytes dropped by the policer. */
 118         RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
 119 };
 120
 121 /**
 122  * Statistics counters
 123  */
 124 struct rte_mtr_stats {
 125         /** Number of packets passed by the policer (per color). */
 126         uint64_t n_pkts[RTE_MTR_COLORS];
 127
 128         /** Number of bytes passed by the policer (per color). */
 129         uint64_t n_bytes[RTE_MTR_COLORS];
 130
 131         /** Number of packets dropped by the policer. */
 132         uint64_t n_pkts_dropped;
 133
 134         /** Number of bytes passed by the policer. */
 135         uint64_t n_bytes_dropped;
 136 };
 137
 138 /**
 139  * Traffic metering algorithms
 140  */
 141 enum rte_mtr_algorithm {
 142         /** No traffic metering performed, the output color is the same as the
 143          * input color for every input packet. The meter of the MTR object is
 144          * working in pass-through mode, having same effect as meter disable.
 145          * @see rte_mtr_meter_disable()
 146          */
 147         RTE_MTR_NONE = 0,
 148
 149         /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
 150         RTE_MTR_SRTCM_RFC2697,
 151
 152         /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
 153         RTE_MTR_TRTCM_RFC2698,
 154
 155         /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
 156         RTE_MTR_TRTCM_RFC4115,
 157 };
 158
 159 /**
 160  * Meter profile
 161  */
 162 struct rte_mtr_meter_profile {
 163         /** Traffic metering algorithm. */
 164         enum rte_mtr_algorithm alg;
 165
 166         RTE_STD_C11
 167         union {
 168                 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
 169                 struct {
 170                         /** Committed Information Rate (CIR) (bytes/second). */
 171                         uint64_t cir;
 172
 173                         /** Committed Burst Size (CBS) (bytes). */
 174                         uint64_t cbs;
 175
 176                         /** Excess Burst Size (EBS) (bytes). */
 177                         uint64_t ebs;
 178                 } srtcm_rfc2697;
 179
 180                 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
 181                 struct {
 182                         /** Committed Information Rate (CIR) (bytes/second). */
 183                         uint64_t cir;
 184
 185                         /** Peak Information Rate (PIR) (bytes/second). */
 186                         uint64_t pir;
 187
 188                         /** Committed Burst Size (CBS) (byes). */
 189                         uint64_t cbs;
 190
 191                         /** Peak Burst Size (PBS) (bytes). */
 192                         uint64_t pbs;
 193                 } trtcm_rfc2698;
 194
 195                 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
 196                 struct {
 197                         /** Committed Information Rate (CIR) (bytes/second). */
 198                         uint64_t cir;
 199
 200                         /** Excess Information Rate (EIR) (bytes/second). */
 201                         uint64_t eir;
 202
 203                         /** Committed Burst Size (CBS) (byes). */
 204                         uint64_t cbs;
 205
 206                         /** Excess Burst Size (EBS) (bytes). */
 207                         uint64_t ebs;
 208                 } trtcm_rfc4115;
 209         };
 210 };
 211
 212 /**
 213  * Policer actions
 214  */
 215 enum rte_mtr_policer_action {
 216         /** Recolor the packet as green. */
 217         MTR_POLICER_ACTION_COLOR_GREEN = 0,
 218
 219         /** Recolor the packet as yellow. */
 220         MTR_POLICER_ACTION_COLOR_YELLOW,
 221
 222         /** Recolor the packet as red. */
 223         MTR_POLICER_ACTION_COLOR_RED,
 224
 225         /** Drop the packet. */
 226         MTR_POLICER_ACTION_DROP,
 227 };
 228
 229 /**
 230  * Parameters for each traffic metering & policing object
 231  *
 232  * @see enum rte_mtr_stats_type
 233  */
 234 struct rte_mtr_params {
 235         /** Meter profile ID. */
 236         uint32_t meter_profile_id;
 237
 238         /** Meter input color in case of MTR object chaining. When non-zero: if
 239          * a previous MTR object is enabled in the same flow, then the color
 240          * determined by the latest MTR object in the same flow is used as the
 241          * input color by the current MTR object, otherwise the current MTR
 242          * object uses the *dscp_table* to determine the input color. When zero:
 243          * the color determined by any previous MTR object in same flow is
 244          * ignored by the current MTR object, which uses the *dscp_table* to
 245          * determine the input color.
 246          */
 247         int use_prev_mtr_color;
 248
 249         /** Meter input color. When non-NULL: it points to a pre-allocated and
 250          * pre-populated table with exactly 64 elements providing the input
 251          * color for each value of the IPv4/IPv6 Differentiated Services Code
 252          * Point (DSCP) input packet field. When NULL: it is equivalent to
 253          * setting this parameter to an all-green populated table (i.e. table
 254          * with all the 64 elements set to green color). The color blind mode
 255          * is configured by setting *use_prev_mtr_color* to 0 and *dscp_table*
 256          * to either NULL or to an all-green populated table. When
 257          * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
 258          * at least one yellow or red color element, then the color aware mode
 259          * is configured.
 260          */
 261         enum rte_mtr_color *dscp_table;
 262
 263         /** Non-zero to enable the meter, zero to disable the meter at the time
 264          * of MTR object creation. Ignored when the meter profile indicated by
 265          * *meter_profile_id* is set to NONE.
 266          * @see rte_mtr_meter_disable()
 267          */
 268         int meter_enable;
 269
 270         /** Policer actions (per meter output color). */
 271         enum rte_mtr_policer_action action[RTE_MTR_COLORS];
 272
 273         /** Set of stats counters to be enabled.
 274          * @see enum rte_mtr_stats_type
 275          */
 276         uint64_t stats_mask;
 277 };
 278
 279 /**
 280  * MTR capabilities
 281  */
 282 struct rte_mtr_capabilities {
 283         /** Maximum number of MTR objects. */
 284         uint32_t n_max;
 285
 286         /** Maximum number of MTR objects that can be shared by multiple flows.
 287          * The value of zero indicates that shared MTR objects are not
 288          * supported. The maximum value is *n_max*.
 289          */
 290         uint32_t n_shared_max;
 291
 292         /** When non-zero, this flag indicates that all the MTR objects that
 293          * cannot be shared by multiple flows have identical capability set.
 294          */
 295         int identical;
 296
 297         /** When non-zero, this flag indicates that all the MTR objects that
 298          * can be shared by multiple flows have identical capability set.
 299          */
 300         int shared_identical;
 301
 302         /** Maximum number of flows that can share the same MTR object. The
 303          * value of zero is invalid. The value of 1 means that shared MTR
 304          * objects not supported.
 305          */
 306         uint32_t shared_n_flows_per_mtr_max;
 307
 308         /** Maximum number of MTR objects that can be part of the same flow. The
 309          * value of zero is invalid. The value of 1 indicates that MTR object
 310          * chaining is not supported. The maximum value is *n_max*.
 311          */
 312         uint32_t chaining_n_mtrs_per_flow_max;
 313
 314         /**
 315          * When non-zero, it indicates that the packet color identified by one
 316          * MTR object can be used as the packet input color by any subsequent
 317          * MTR object from the same flow. When zero, it indicates that the color
 318          * determined by one MTR object is always ignored by any subsequent MTR
 319          * object from the same flow. Only valid when MTR chaining is supported,
 320          * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
 321          * it also means that the color aware mode is supported by at least one
 322          * metering algorithm.
 323          */
 324         int chaining_use_prev_mtr_color_supported;
 325
 326         /**
 327          * When non-zero, it indicates that the packet color identified by one
 328          * MTR object is always used as the packet input color by any subsequent
 329          * MTR object that is part of the same flow. When zero, it indicates
 330          * that whether the color determined by one MTR object is either ignored
 331          * or used as the packet input color by any subsequent MTR object from
 332          * the same flow is individually configurable for each MTR object. Only
 333          * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
 334          */
 335         int chaining_use_prev_mtr_color_enforced;
 336
 337         /** Maximum number of MTR objects that can have their meter configured
 338          * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
 339          * metering algorithm is not supported. The maximum value is *n_max*.
 340          */
 341         uint32_t meter_srtcm_rfc2697_n_max;
 342
 343         /** Maximum number of MTR objects that can have their meter configured
 344          * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
 345          * metering algorithm is not supported. The maximum value is *n_max*.
 346          */
 347         uint32_t meter_trtcm_rfc2698_n_max;
 348
 349         /** Maximum number of MTR objects that can have their meter configured
 350          * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
 351          * metering algorithm is not supported. The maximum value is *n_max*.
 352          */
 353         uint32_t meter_trtcm_rfc4115_n_max;
 354
 355         /** Maximum traffic rate that can be metered by a single MTR object. For
 356          * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
 357          * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
 358          * value for the sum of PIR and EIR rates.
 359          */
 360         uint64_t meter_rate_max;
 361
 362         /**
 363          * When non-zero, it indicates that color aware mode is supported for
 364          * the srTCM RFC 2697 metering algorithm.
 365          */
 366         int color_aware_srtcm_rfc2697_supported;
 367
 368         /**
 369          * When non-zero, it indicates that color aware mode is supported for
 370          * the trTCM RFC 2698 metering algorithm.
 371          */
 372         int color_aware_trtcm_rfc2698_supported;
 373
 374         /**
 375          * When non-zero, it indicates that color aware mode is supported for
 376          * the trTCM RFC 4115 metering algorithm.
 377          */
 378         int color_aware_trtcm_rfc4115_supported;
 379
 380         /** When non-zero, it indicates that the policer packet recolor actions
 381          * are supported.
 382          * @see enum rte_mtr_policer_action
 383          */
 384         int policer_action_recolor_supported;
 385
 386         /** When non-zero, it indicates that the policer packet drop action is
 387          * supported.
 388          * @see enum rte_mtr_policer_action
 389          */
 390         int policer_action_drop_supported;
 391
 392         /** Set of supported statistics counter types.
 393          * @see enum rte_mtr_stats_type
 394          */
 395         uint64_t stats_mask;
 396 };
 397
 398 /**
 399  * Verbose error types.
 400  *
 401  * Most of them provide the type of the object referenced by struct
 402  * rte_mtr_error::cause.
 403  */
 404 enum rte_mtr_error_type {
 405         RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
 406         RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 407         RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
 408         RTE_MTR_ERROR_TYPE_METER_PROFILE,
 409         RTE_MTR_ERROR_TYPE_MTR_ID,
 410         RTE_MTR_ERROR_TYPE_MTR_PARAMS,
 411         RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
 412         RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
 413         RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
 414         RTE_MTR_ERROR_TYPE_STATS_MASK,
 415         RTE_MTR_ERROR_TYPE_STATS,
 416         RTE_MTR_ERROR_TYPE_SHARED,
 417 };
 418
 419 /**
 420  * Verbose error structure definition.
 421  *
 422  * This object is normally allocated by applications and set by PMDs, the
 423  * message points to a constant string which does not need to be freed by
 424  * the application, however its pointer can be considered valid only as long
 425  * as its associated DPDK port remains configured. Closing the underlying
 426  * device or unloading the PMD invalidates it.
 427  *
 428  * Both cause and message may be NULL regardless of the error type.
 429  */
 430 struct rte_mtr_error {
 431         enum rte_mtr_error_type type; /**< Cause field and error type. */
 432         const void *cause; /**< Object responsible for the error. */
 433         const char *message; /**< Human-readable error message. */
 434 };
 435
 436 /**
 437  * MTR capabilities get
 438  *
 439  * @param[in] port_id
 440  *   The port identifier of the Ethernet device.
 441  * @param[out] cap
 442  *   MTR capabilities. Needs to be pre-allocated and valid.
 443  * @param[out] error
 444  *   Error details. Filled in only on error, when not NULL.
 445  * @return
 446  *   0 on success, non-zero error code otherwise.
 447  */
 448 int __rte_experimental
 449 rte_mtr_capabilities_get(uint16_t port_id,
 450         struct rte_mtr_capabilities *cap,
 451         struct rte_mtr_error *error);
 452
 453 /**
 454  * Meter profile add
 455  *
 456  * Create a new meter profile with ID set to *meter_profile_id*. The new profile
 457  * is used to create one or several MTR objects.
 458  *
 459  * @param[in] port_id
 460  *   The port identifier of the Ethernet device.
 461  * @param[in] meter_profile_id
 462  *   ID for the new meter profile. Needs to be unused by any of the existing
 463  *   meter profiles added for the current port.
 464  * @param[in] profile
 465  *   Meter profile parameters. Needs to be pre-allocated and valid.
 466  * @param[out] error
 467  *   Error details. Filled in only on error, when not NULL.
 468  * @return
 469  *   0 on success, non-zero error code otherwise.
 470  */
 471 int __rte_experimental
 472 rte_mtr_meter_profile_add(uint16_t port_id,
 473         uint32_t meter_profile_id,
 474         struct rte_mtr_meter_profile *profile,
 475         struct rte_mtr_error *error);
 476
 477 /**
 478  * Meter profile delete
 479  *
 480  * Delete an existing meter profile. This operation fails when there is
 481  * currently at least one user (i.e. MTR object) of this profile.
 482  *
 483  * @param[in] port_id
 484  *   The port identifier of the Ethernet device.
 485  * @param[in] meter_profile_id
 486  *   Meter profile ID. Needs to be the valid.
 487  * @param[out] error
 488  *   Error details. Filled in only on error, when not NULL.
 489  * @return
 490  *   0 on success, non-zero error code otherwise.
 491  */
 492 int __rte_experimental
 493 rte_mtr_meter_profile_delete(uint16_t port_id,
 494         uint32_t meter_profile_id,
 495         struct rte_mtr_error *error);
 496
 497 /**
 498  * MTR object create
 499  *
 500  * Create a new MTR object for the current port. This object is run as part of
 501  * associated flow action for traffic metering and policing.
 502  *
 503  * @param[in] port_id
 504  *   The port identifier of the Ethernet device.
 505  * @param[in] mtr_id
 506  *   MTR object ID. Needs to be unused by any of the existing MTR objects.
 507  *   created for the current port.
 508  * @param[in] params
 509  *   MTR object params. Needs to be pre-allocated and valid.
 510  * @param[in] shared
 511  *   Non-zero when this MTR object can be shared by multiple flows, zero when
 512  *   this MTR object can be used by a single flow.
 513  * @param[out] error
 514  *   Error details. Filled in only on error, when not NULL.
 515  * @return
 516  *   0 on success, non-zero error code otherwise.
 517  *
 518  * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
 519  */
 520 int __rte_experimental
 521 rte_mtr_create(uint16_t port_id,
 522         uint32_t mtr_id,
 523         struct rte_mtr_params *params,
 524         int shared,
 525         struct rte_mtr_error *error);
 526
 527 /**
 528  * MTR object destroy
 529  *
 530  * Delete an existing MTR object. This operation fails when there is currently
 531  * at least one user (i.e. flow) of this MTR object.
 532  *
 533  * @param[in] port_id
 534  *   The port identifier of the Ethernet device.
 535  * @param[in] mtr_id
 536  *   MTR object ID. Needs to be valid.
 537  *   created for the current port.
 538  * @param[out] error
 539  *   Error details. Filled in only on error, when not NULL.
 540  * @return
 541  *   0 on success, non-zero error code otherwise.
 542  */
 543 int __rte_experimental
 544 rte_mtr_destroy(uint16_t port_id,
 545         uint32_t mtr_id,
 546         struct rte_mtr_error *error);
 547
 548 /**
 549  * MTR object meter disable
 550  *
 551  * Disable the meter of an existing MTR object. In disabled state, the meter of
 552  * the current MTR object works in pass-through mode, meaning that for each
 553  * input packet the meter output color is always the same as the input color. In
 554  * particular, when the meter of the current MTR object is configured in color
 555  * blind mode, the input color is always green, so the meter output color is
 556  * also always green. Note that the policer and the statistics of the current
 557  * MTR object are working as usual while the meter is disabled. No action is
 558  * taken and this function returns successfully when the meter of the current
 559  * MTR object is already disabled.
 560  *
 561  * @param[in] port_id
 562  *   The port identifier of the Ethernet device.
 563  * @param[in] mtr_id
 564  *   MTR object ID.
 565  * @param[out] error
 566  *   Error details. Filled in only on error, when not NULL.
 567  * @return
 568  *   0 on success, non-zero error code otherwise.
 569  */
 570 int __rte_experimental
 571 rte_mtr_meter_disable(uint16_t port_id,
 572         uint32_t mtr_id,
 573         struct rte_mtr_error *error);
 574
 575 /**
 576  * MTR object meter enable
 577  *
 578  * Enable the meter of an existing MTR object. If the MTR object has its meter
 579  * already enabled, then no action is taken and this function returns
 580  * successfully.
 581  *
 582  * @param[in] port_id
 583  *   The port identifier of the Ethernet device.
 584  * @param[in] mtr_id
 585  *   MTR object ID.
 586  * @param[out] error
 587  *   Error details. Filled in only on error, when not NULL.
 588  * @return
 589  *   0 on success, non-zero error code otherwise.
 590  */
 591 int __rte_experimental
 592 rte_mtr_meter_enable(uint16_t port_id,
 593         uint32_t mtr_id,
 594         struct rte_mtr_error *error);
 595
 596 /**
 597  * MTR object meter profile update
 598  *
 599  * @param[in] port_id
 600  *   The port identifier of the Ethernet device.
 601  * @param[in] mtr_id
 602  *   MTR object ID. Needs to be valid.
 603  * @param[in] meter_profile_id
 604  *   Meter profile ID for the current MTR object. Needs to be valid.
 605  * @param[out] error
 606  *   Error details. Filled in only on error, when not NULL.
 607  * @return
 608  *   0 on success, non-zero error code otherwise.
 609  */
 610 int __rte_experimental
 611 rte_mtr_meter_profile_update(uint16_t port_id,
 612         uint32_t mtr_id,
 613         uint32_t meter_profile_id,
 614         struct rte_mtr_error *error);
 615
 616 /**
 617  * MTR object DSCP table update
 618  *
 619  * @param[in] port_id
 620  *   The port identifier of the Ethernet device.
 621  * @param[in] mtr_id
 622  *   MTR object ID. Needs to be valid.
 623  * @param[in] dscp_table
 624  *   When non-NULL: it points to a pre-allocated and pre-populated table with
 625  *   exactly 64 elements providing the input color for each value of the
 626  *   IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
 627  *   When NULL: it is equivalent to setting this parameter to an “all-green”
 628  *   populated table (i.e. table with all the 64 elements set to green color).
 629  * @param[out] error
 630  *   Error details. Filled in only on error, when not NULL.
 631  * @return
 632  *   0 on success, non-zero error code otherwise.
 633  */
 634 int __rte_experimental
 635 rte_mtr_meter_dscp_table_update(uint16_t port_id,
 636         uint32_t mtr_id,
 637         enum rte_mtr_color *dscp_table,
 638         struct rte_mtr_error *error);
 639
 640 /**
 641  * MTR object policer actions update
 642  *
 643  * @param[in] port_id
 644  *   The port identifier of the Ethernet device.
 645  * @param[in] mtr_id
 646  *   MTR object ID. Needs to be valid.
 647  * @param[in] action_mask
 648  *   Bit mask indicating which policer actions need to be updated. One or more
 649  *   policer actions can be updated in a single function invocation. To update
 650  *   the policer action associated with color C, bit (1 << C) needs to be set in
 651  *   *action_mask* and element at position C in the *actions* array needs to be
 652  *   valid.
 653  * @param[in] actions
 654  *   Pre-allocated and pre-populated array of policer actions.
 655  * @param[out] error
 656  *   Error details. Filled in only on error, when not NULL.
 657  * @return
 658  *   0 on success, non-zero error code otherwise.
 659  */
 660 int __rte_experimental
 661 rte_mtr_policer_actions_update(uint16_t port_id,
 662         uint32_t mtr_id,
 663         uint32_t action_mask,
 664         enum rte_mtr_policer_action *actions,
 665         struct rte_mtr_error *error);
 666
 667 /**
 668  * MTR object enabled statistics counters update
 669  *
 670  * @param[in] port_id
 671  *   The port identifier of the Ethernet device.
 672  * @param[in] mtr_id
 673  *   MTR object ID. Needs to be valid.
 674  * @param[in] stats_mask
 675  *   Mask of statistics counter types to be enabled for the current MTR object.
 676  *   Any statistics counter type not included in this set is to be disabled for
 677  *   the current MTR object.
 678  * @param[out] error
 679  *   Error details. Filled in only on error, when not NULL.
 680  * @return
 681  *   0 on success, non-zero error code otherwise.
 682  *
 683  * @see enum rte_mtr_stats_type
 684  */
 685 int __rte_experimental
 686 rte_mtr_stats_update(uint16_t port_id,
 687         uint32_t mtr_id,
 688         uint64_t stats_mask,
 689         struct rte_mtr_error *error);
 690
 691 /**
 692  * MTR object statistics counters read
 693  *
 694  * @param[in] port_id
 695  *   The port identifier of the Ethernet device.
 696  * @param[in] mtr_id
 697  *   MTR object ID. Needs to be valid.
 698  * @param[out] stats
 699  *   When non-NULL, it contains the current value for the statistics counters
 700  *   enabled for the current MTR object.
 701  * @param[out] stats_mask
 702  *   When non-NULL, it contains the mask of statistics counter types that are
 703  *   currently enabled for this MTR object, indicating which of the counters
 704  *   retrieved with the *stats* structure are valid.
 705  * @param[in] clear
 706  *   When this parameter has a non-zero value, the statistics counters are
 707  *   cleared (i.e. set to zero) immediately after they have been read,
 708  *   otherwise the statistics counters are left untouched.
 709  * @param[out] error
 710  *   Error details. Filled in only on error, when not NULL.
 711  * @return
 712  *   0 on success, non-zero error code otherwise.
 713  *
 714  * @see enum rte_mtr_stats_type
 715  */
 716 int __rte_experimental
 717 rte_mtr_stats_read(uint16_t port_id,
 718         uint32_t mtr_id,
 719         struct rte_mtr_stats *stats,
 720         uint64_t *stats_mask,
 721         int clear,
 722         struct rte_mtr_error *error);
 723
 724 #ifdef __cplusplus
 725 }
 726 #endif
 727
 728 #endif /* __INCLUDE_RTE_MTR_H__ */