lib/ethdev/rte_mtr.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2017 Intel Corporation
   3  * Copyright 2017 NXP
   4  * Copyright 2017 Cavium
   5  */
   6
   7 #ifndef __INCLUDE_RTE_MTR_H__
   8 #define __INCLUDE_RTE_MTR_H__
   9
  10 /**
  11  * @file
  12  * RTE Generic Traffic Metering and Policing API
  13  *
  14  * This interface provides the ability to configure the traffic metering and
  15  * policing (MTR) in a generic way.
  16  *
  17  * The processing done for each input packet hitting a MTR object is:
  18  *    A) Traffic metering: The packet is assigned a color (the meter output
  19  *       color), based on the previous history of the flow reflected in the
  20  *       current state of the MTR object, according to the specific traffic
  21  *       metering algorithm. The traffic metering algorithm can typically work
  22  *       in color aware mode, in which case the input packet already has an
  23  *       initial color (the input color), or in color blind mode, which is
  24  *       equivalent to considering all input packets initially colored as green.
  25  *    B) Policing: There is a separate policer action configured for each meter
  26  *       output color, which can:
  27  *          a) Drop the packet.
  28  *          b) Keep the same packet color: the policer output color matches the
  29  *             meter output color (essentially a no-op action).
  30  *          c) Recolor the packet: the policer output color is different than
  31  *             the meter output color.
  32  *       The policer output color is the output color of the packet, which is
  33  *       set in the packet meta-data (i.e. struct rte_mbuf::sched::color).
  34  *    C) Statistics: The set of counters maintained for each MTR object is
  35  *       configurable and subject to the implementation support. This set
  36  *       includes the number of packets and bytes dropped or passed for each
  37  *       output color.
  38  *
  39  * Once successfully created, an MTR object is linked to one or several flows
  40  * through the meter action of the flow API.
  41  *    A) Whether an MTR object is private to a flow or potentially shared by
  42  *       several flows has to be specified at creation time.
  43  *    B) Several meter actions can be potentially registered for the same flow.
  44  *
  45  * @warning
  46  * @b EXPERIMENTAL: this API may change without prior notice
  47  */
  48 #include <stdint.h>
  49 #include <rte_compat.h>
  50 #include <rte_common.h>
  51 #include <rte_meter.h>
  52 #include <rte_flow.h>
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57
  58 /**
  59  * Statistics counter type
  60  */
  61 enum rte_mtr_stats_type {
  62         /** Number of packets passed as green by the policer. */
  63         RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
  64
  65         /** Number of packets passed as yellow by the policer. */
  66         RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
  67
  68         /** Number of packets passed as red by the policer. */
  69         RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
  70
  71         /** Number of packets dropped by the policer. */
  72         RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
  73
  74         /** Number of bytes passed as green by the policer. */
  75         RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
  76
  77         /** Number of bytes passed as yellow by the policer. */
  78         RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
  79
  80         /** Number of bytes passed as red by the policer. */
  81         RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
  82
  83         /** Number of bytes dropped by the policer. */
  84         RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
  85 };
  86
  87 /**
  88  * Statistics counters
  89  */
  90 struct rte_mtr_stats {
  91         /** Number of packets passed by the policer (per color). */
  92         uint64_t n_pkts[RTE_COLORS];
  93
  94         /** Number of bytes passed by the policer (per color). */
  95         uint64_t n_bytes[RTE_COLORS];
  96
  97         /** Number of packets dropped by the policer. */
  98         uint64_t n_pkts_dropped;
  99
 100         /** Number of bytes passed by the policer. */
 101         uint64_t n_bytes_dropped;
 102 };
 103
 104 /**
 105  * Traffic metering algorithms
 106  */
 107 enum rte_mtr_algorithm {
 108         /** No traffic metering performed, the output color is the same as the
 109          * input color for every input packet. The meter of the MTR object is
 110          * working in pass-through mode, having same effect as meter disable.
 111          * @see rte_mtr_meter_disable()
 112          */
 113         RTE_MTR_NONE = 0,
 114
 115         /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
 116         RTE_MTR_SRTCM_RFC2697,
 117
 118         /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
 119         RTE_MTR_TRTCM_RFC2698,
 120
 121         /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
 122         RTE_MTR_TRTCM_RFC4115,
 123 };
 124
 125 /**
 126  * Meter profile
 127  */
 128 struct rte_mtr_meter_profile {
 129         /** Traffic metering algorithm. */
 130         enum rte_mtr_algorithm alg;
 131
 132         RTE_STD_C11
 133         union {
 134                 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
 135                 struct {
 136                         /**
 137                          * Committed Information Rate (CIR)
 138                          * (bytes per second or packets per second).
 139                          */
 140                         uint64_t cir;
 141
 142                         /** Committed Burst Size (CBS) (bytes or packets). */
 143                         uint64_t cbs;
 144
 145                         /** Excess Burst Size (EBS) (bytes or packets). */
 146                         uint64_t ebs;
 147                 } srtcm_rfc2697;
 148
 149                 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
 150                 struct {
 151                         /**
 152                          * Committed Information Rate (CIR)
 153                          * (bytes per second or packets per second).
 154                          */
 155                         uint64_t cir;
 156
 157                         /**
 158                          * Peak Information Rate (PIR)
 159                          * (bytes per second or packets per second).
 160                          */
 161                         uint64_t pir;
 162
 163                         /** Committed Burst Size (CBS) (bytes or packets). */
 164                         uint64_t cbs;
 165
 166                         /** Peak Burst Size (PBS) (bytes or packets). */
 167                         uint64_t pbs;
 168                 } trtcm_rfc2698;
 169
 170                 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
 171                 struct {
 172                         /**
 173                          * Committed Information Rate (CIR)
 174                          * (bytes per second or packets per second).
 175                          */
 176                         uint64_t cir;
 177
 178                         /**
 179                          * Excess Information Rate (EIR)
 180                          * (bytes per second or packets per second).
 181                          */
 182                         uint64_t eir;
 183
 184                         /** Committed Burst Size (CBS) (bytes or packets). */
 185                         uint64_t cbs;
 186
 187                         /** Excess Burst Size (EBS) (bytes or packets). */
 188                         uint64_t ebs;
 189                 } trtcm_rfc4115;
 190         };
 191
 192         /**
 193          * When zero, the byte mode is enabled for the current profile, so the
 194          * *rate* and *size* fields are specified in bytes per second
 195          * and bytes, respectively.
 196          * When non-zero, the packet mode is enabled for the current profile,
 197          * so the *rate* and *size* fields are specified in packets per second
 198          * and packets, respectively.
 199          */
 200         int packet_mode;
 201 };
 202
 203 /**
 204  * Meter policy
 205  */
 206 struct rte_mtr_meter_policy_params {
 207         /**
 208          * Policy action list per color.
 209          * actions[i] potentially represents a chain of rte_flow actions
 210          * terminated by the END action, exactly as specified by the rte_flow
 211          * API for the flow definition, and not just a single action.
 212          */
 213         const struct rte_flow_action *actions[RTE_COLORS];
 214 };
 215
 216 /**
 217  * Parameters for each traffic metering & policing object
 218  *
 219  * @see enum rte_mtr_stats_type
 220  */
 221 struct rte_mtr_params {
 222         /** Meter profile ID. */
 223         uint32_t meter_profile_id;
 224
 225         /** Meter input color in case of MTR object chaining. When non-zero: if
 226          * a previous MTR object is enabled in the same flow, then the color
 227          * determined by the latest MTR object in the same flow is used as the
 228          * input color by the current MTR object, otherwise the current MTR
 229          * object uses the *dscp_table* to determine the input color. When zero:
 230          * the color determined by any previous MTR object in same flow is
 231          * ignored by the current MTR object, which uses the *dscp_table* to
 232          * determine the input color.
 233          */
 234         int use_prev_mtr_color;
 235
 236         /** Meter input color. When non-NULL: it points to a pre-allocated and
 237          * pre-populated table with exactly 64 elements providing the input
 238          * color for each value of the IPv4/IPv6 Differentiated Services Code
 239          * Point (DSCP) input packet field. When NULL: it is equivalent to
 240          * setting this parameter to an all-green populated table (i.e. table
 241          * with all the 64 elements set to green color). The color blind mode
 242          * is configured by setting *use_prev_mtr_color* to 0 and *dscp_table*
 243          * to either NULL or to an all-green populated table. When
 244          * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
 245          * at least one yellow or red color element, then the color aware mode
 246          * is configured.
 247          */
 248         enum rte_color *dscp_table;
 249
 250         /** Non-zero to enable the meter, zero to disable the meter at the time
 251          * of MTR object creation. Ignored when the meter profile indicated by
 252          * *meter_profile_id* is set to NONE.
 253          * @see rte_mtr_meter_disable()
 254          */
 255         int meter_enable;
 256
 257         /** Set of stats counters to be enabled.
 258          * @see enum rte_mtr_stats_type
 259          */
 260         uint64_t stats_mask;
 261
 262         /** Meter policy ID. */
 263         uint32_t meter_policy_id;
 264 };
 265
 266 /**
 267  * MTR capabilities
 268  */
 269 struct rte_mtr_capabilities {
 270         /** Maximum number of MTR objects. */
 271         uint32_t n_max;
 272
 273         /** Maximum number of MTR objects that can be shared by multiple flows.
 274          * The value of zero indicates that shared MTR objects are not
 275          * supported. The maximum value is *n_max*.
 276          */
 277         uint32_t n_shared_max;
 278
 279         /** When non-zero, this flag indicates that all the MTR objects that
 280          * cannot be shared by multiple flows have identical capability set.
 281          */
 282         int identical;
 283
 284         /** When non-zero, this flag indicates that all the MTR objects that
 285          * can be shared by multiple flows have identical capability set.
 286          */
 287         int shared_identical;
 288
 289         /** Maximum number of flows that can share the same MTR object. The
 290          * value of zero is invalid. The value of 1 means that shared MTR
 291          * objects not supported.
 292          */
 293         uint32_t shared_n_flows_per_mtr_max;
 294
 295         /** Maximum number of MTR objects that can be part of the same flow. The
 296          * value of zero is invalid. The value of 1 indicates that MTR object
 297          * chaining is not supported. The maximum value is *n_max*.
 298          */
 299         uint32_t chaining_n_mtrs_per_flow_max;
 300
 301         /**
 302          * When non-zero, it indicates that the packet color identified by one
 303          * MTR object can be used as the packet input color by any subsequent
 304          * MTR object from the same flow. When zero, it indicates that the color
 305          * determined by one MTR object is always ignored by any subsequent MTR
 306          * object from the same flow. Only valid when MTR chaining is supported,
 307          * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
 308          * it also means that the color aware mode is supported by at least one
 309          * metering algorithm.
 310          */
 311         int chaining_use_prev_mtr_color_supported;
 312
 313         /**
 314          * When non-zero, it indicates that the packet color identified by one
 315          * MTR object is always used as the packet input color by any subsequent
 316          * MTR object that is part of the same flow. When zero, it indicates
 317          * that whether the color determined by one MTR object is either ignored
 318          * or used as the packet input color by any subsequent MTR object from
 319          * the same flow is individually configurable for each MTR object. Only
 320          * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
 321          */
 322         int chaining_use_prev_mtr_color_enforced;
 323
 324         /** Maximum number of MTR objects that can have their meter configured
 325          * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
 326          * metering algorithm is not supported. The maximum value is *n_max*.
 327          */
 328         uint32_t meter_srtcm_rfc2697_n_max;
 329
 330         /** Maximum number of MTR objects that can have their meter configured
 331          * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
 332          * metering algorithm is not supported. The maximum value is *n_max*.
 333          */
 334         uint32_t meter_trtcm_rfc2698_n_max;
 335
 336         /** Maximum number of MTR objects that can have their meter configured
 337          * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
 338          * metering algorithm is not supported. The maximum value is *n_max*.
 339          */
 340         uint32_t meter_trtcm_rfc4115_n_max;
 341
 342         /** Maximum traffic rate that can be metered by a single MTR object. For
 343          * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
 344          * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
 345          * value for the sum of PIR and EIR rates.
 346          */
 347         uint64_t meter_rate_max;
 348
 349         /**
 350          * Maximum number of policy objects that can have.
 351          * The value of 0 is invalid. Policy must be supported for meter.
 352          * The maximum value is *n_max*.
 353          */
 354         uint64_t meter_policy_n_max;
 355
 356         /**
 357          * When non-zero, it indicates that color aware mode is supported for
 358          * the srTCM RFC 2697 metering algorithm.
 359          */
 360         int color_aware_srtcm_rfc2697_supported;
 361
 362         /**
 363          * When non-zero, it indicates that color aware mode is supported for
 364          * the trTCM RFC 2698 metering algorithm.
 365          */
 366         int color_aware_trtcm_rfc2698_supported;
 367
 368         /**
 369          * When non-zero, it indicates that color aware mode is supported for
 370          * the trTCM RFC 4115 metering algorithm.
 371          */
 372         int color_aware_trtcm_rfc4115_supported;
 373
 374         /**
 375          * srTCM rfc2697 byte mode supported.
 376          * When non-zero, it indicates that byte mode is supported for
 377          * the srTCM RFC 2697 metering algorithm.
 378          */
 379         int srtcm_rfc2697_byte_mode_supported;
 380
 381         /**
 382          * srTCM rfc2697 packet mode supported.
 383          * When non-zero, it indicates that packet mode is supported for
 384          * the srTCM RFC 2697 metering algorithm.
 385          */
 386         int srtcm_rfc2697_packet_mode_supported;
 387
 388         /**
 389          * trTCM rfc2698 byte mode supported.
 390          * When non-zero, it indicates that byte mode is supported for
 391          * the trTCM RFC 2698 metering algorithm.
 392          */
 393         int trtcm_rfc2698_byte_mode_supported;
 394
 395         /**
 396          * trTCM rfc2698 packet mode supported.
 397          * When non-zero, it indicates that packet mode is supported for
 398          * the trTCM RFC 2698 metering algorithm.
 399          */
 400         int trtcm_rfc2698_packet_mode_supported;
 401
 402         /**
 403          * trTCM rfc4115 byte mode supported.
 404          * When non-zero, it indicates that byte mode is supported for
 405          * the trTCM RFC 4115 metering algorithm.
 406          */
 407         int trtcm_rfc4115_byte_mode_supported;
 408
 409         /**
 410          * trTCM rfc4115 packet mode supported.
 411          * When non-zero, it indicates that packet mode is supported for
 412          * the trTCM RFC 4115 metering algorithm.
 413          */
 414         int trtcm_rfc4115_packet_mode_supported;
 415
 416         /** Set of supported statistics counter types.
 417          * @see enum rte_mtr_stats_type
 418          */
 419         uint64_t stats_mask;
 420 };
 421
 422 /**
 423  * Verbose error types.
 424  *
 425  * Most of them provide the type of the object referenced by struct
 426  * rte_mtr_error::cause.
 427  */
 428 enum rte_mtr_error_type {
 429         RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
 430         RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 431         RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
 432         RTE_MTR_ERROR_TYPE_METER_PROFILE,
 433         RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE,
 434         RTE_MTR_ERROR_TYPE_MTR_ID,
 435         RTE_MTR_ERROR_TYPE_MTR_PARAMS,
 436         RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
 437         RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
 438         RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
 439         RTE_MTR_ERROR_TYPE_STATS_MASK,
 440         RTE_MTR_ERROR_TYPE_STATS,
 441         RTE_MTR_ERROR_TYPE_SHARED,
 442         RTE_MTR_ERROR_TYPE_METER_POLICY_ID,
 443         RTE_MTR_ERROR_TYPE_METER_POLICY,
 444 };
 445
 446 /**
 447  * Verbose error structure definition.
 448  *
 449  * This object is normally allocated by applications and set by PMDs, the
 450  * message points to a constant string which does not need to be freed by
 451  * the application, however its pointer can be considered valid only as long
 452  * as its associated DPDK port remains configured. Closing the underlying
 453  * device or unloading the PMD invalidates it.
 454  *
 455  * Both cause and message may be NULL regardless of the error type.
 456  */
 457 struct rte_mtr_error {
 458         enum rte_mtr_error_type type; /**< Cause field and error type. */
 459         const void *cause; /**< Object responsible for the error. */
 460         const char *message; /**< Human-readable error message. */
 461 };
 462
 463 /**
 464  * MTR capabilities get
 465  *
 466  * @param[in] port_id
 467  *   The port identifier of the Ethernet device.
 468  * @param[out] cap
 469  *   MTR capabilities. Needs to be pre-allocated and valid.
 470  * @param[out] error
 471  *   Error details. Filled in only on error, when not NULL.
 472  * @return
 473  *   0 on success, non-zero error code otherwise.
 474  */
 475 __rte_experimental
 476 int
 477 rte_mtr_capabilities_get(uint16_t port_id,
 478         struct rte_mtr_capabilities *cap,
 479         struct rte_mtr_error *error);
 480
 481 /**
 482  * Meter profile add
 483  *
 484  * Create a new meter profile with ID set to *meter_profile_id*. The new profile
 485  * is used to create one or several MTR objects.
 486  *
 487  * @param[in] port_id
 488  *   The port identifier of the Ethernet device.
 489  * @param[in] meter_profile_id
 490  *   ID for the new meter profile. Needs to be unused by any of the existing
 491  *   meter profiles added for the current port.
 492  * @param[in] profile
 493  *   Meter profile parameters. Needs to be pre-allocated and valid.
 494  * @param[out] error
 495  *   Error details. Filled in only on error, when not NULL.
 496  * @return
 497  *   0 on success, non-zero error code otherwise.
 498  */
 499 __rte_experimental
 500 int
 501 rte_mtr_meter_profile_add(uint16_t port_id,
 502         uint32_t meter_profile_id,
 503         struct rte_mtr_meter_profile *profile,
 504         struct rte_mtr_error *error);
 505
 506 /**
 507  * Meter profile delete
 508  *
 509  * Delete an existing meter profile. This operation fails when there is
 510  * currently at least one user (i.e. MTR object) of this profile.
 511  *
 512  * @param[in] port_id
 513  *   The port identifier of the Ethernet device.
 514  * @param[in] meter_profile_id
 515  *   Meter profile ID. Needs to be the valid.
 516  * @param[out] error
 517  *   Error details. Filled in only on error, when not NULL.
 518  * @return
 519  *   0 on success, non-zero error code otherwise.
 520  */
 521 __rte_experimental
 522 int
 523 rte_mtr_meter_profile_delete(uint16_t port_id,
 524         uint32_t meter_profile_id,
 525         struct rte_mtr_error *error);
 526
 527 /**
 528  * Check whether a meter policy can be created on a given port.
 529  *
 530  * The meter policy is validated for correctness and
 531  * whether it could be accepted by the device given sufficient resources.
 532  * The policy is checked against the current capability information
 533  * meter_policy_n_max configuration.
 534  * The policy may also optionally be validated against existing
 535  * device policy resources.
 536  * This function has no effect on the target device.
 537  *
 538  * @param[in] port_id
 539  *   The port identifier of the Ethernet device.
 540  * @param[in] policy
 541  *   Associated action list per color.
 542  *   list NULL is legal and means no special action.
 543  *   (list terminated by the END action).
 544  * @param[out] error
 545  *   Error details. Filled in only on error, when not NULL.
 546  * @return
 547  *   0 on success, non-zero error code otherwise.
 548  */
 549 __rte_experimental
 550 int
 551 rte_mtr_meter_policy_validate(uint16_t port_id,
 552         struct rte_mtr_meter_policy_params *policy,
 553         struct rte_mtr_error *error);
 554
 555 /**
 556  * Meter policy add
 557  *
 558  * Create a new meter policy. The new policy
 559  * is used to create single or multiple MTR objects.
 560  * The same policy can be used to create multiple MTR objects.
 561  *
 562  * @param[in] port_id
 563  *   The port identifier of the Ethernet device.
 564  * @param[in] policy_id
 565  *   Policy identifier for the new meter policy.
 566  * @param[in] policy
 567  *   Associated actions per color.
 568  *   list NULL is legal and means no special action.
 569  *   Non-NULL list must be terminated.
 570  *   (list terminated by the END action).
 571  * @param[out] error
 572  *   Error details. Filled in only on error, when not NULL.
 573  * @return
 574  *   0 on success, non-zero error code otherwise.
 575  */
 576 __rte_experimental
 577 int
 578 rte_mtr_meter_policy_add(uint16_t port_id,
 579         uint32_t policy_id,
 580         struct rte_mtr_meter_policy_params *policy,
 581         struct rte_mtr_error *error);
 582
 583 /**
 584  * Define meter policy action list:
 585  * GREEN - GREEN, YELLOW - YELLOW, RED - RED
 586  */
 587 #define rte_mtr_policy_pass_color(policy) \
 588 struct rte_mtr_meter_policy_params policy = \
 589 { \
 590         .actions[RTE_COLOR_GREEN] = (struct rte_flow_action[]) { \
 591                 { \
 592                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 593                         .conf = &(struct rte_flow_action_meter_color) { \
 594                                 .color = RTE_COLOR_GREEN, \
 595                         }, \
 596                 }, \
 597                 { \
 598                         .type = RTE_FLOW_ACTION_TYPE_END, \
 599                 }, \
 600         }, \
 601         .actions[RTE_COLOR_YELLOW] = (struct rte_flow_action[]) { \
 602                 { \
 603                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 604                         .conf = &(struct rte_flow_action_meter_color) { \
 605                                 .color = RTE_COLOR_YELLOW, \
 606                         }, \
 607                 }, \
 608                 { \
 609                 .type = RTE_FLOW_ACTION_TYPE_END, \
 610                 }, \
 611         }, \
 612         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
 613                 { \
 614                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 615                         .conf = &(struct rte_flow_action_meter_color) { \
 616                                 .color = RTE_COLOR_RED, \
 617                         }, \
 618                 }, \
 619                 { \
 620                         .type = RTE_FLOW_ACTION_TYPE_END, \
 621                 }, \
 622         }, \
 623 }
 624
 625 /**
 626  * Define meter policy action list:
 627  * GREEN - Do nothing, YELLOW - Do nothing, RED - DROP
 628  */
 629 #define rte_mtr_policy_drop_red(policy) \
 630 struct rte_mtr_meter_policy_params policy = \
 631 { \
 632         .actions[RTE_COLOR_GREEN] = NULL, \
 633         .actions[RTE_COLOR_YELLOW] = NULL, \
 634         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
 635                 { \
 636                         .type = RTE_FLOW_ACTION_TYPE_DROP, \
 637                 }, \
 638                 { \
 639                         .type = RTE_FLOW_ACTION_TYPE_END, \
 640                 }, \
 641         }, \
 642 }
 643
 644 /**
 645  * Meter policy delete
 646  *
 647  * Delete an existing meter policy. This operation fails when there is
 648  * currently at least one user (i.e. MTR object) of this policy.
 649  *
 650  * @param[in] port_id
 651  *   The port identifier of the Ethernet device.
 652  * @param[in] policy_id
 653  *   Policy identifier.
 654  * @param[out] error
 655  *   Error details. Filled in only on error, when not NULL.
 656  * @return
 657  *   0 on success, non-zero error code otherwise.
 658  */
 659 __rte_experimental
 660 int
 661 rte_mtr_meter_policy_delete(uint16_t port_id,
 662         uint32_t policy_id,
 663         struct rte_mtr_error *error);
 664
 665 /**
 666  * MTR object create
 667  *
 668  * Create a new MTR object for the current port. This object is run as part of
 669  * associated flow action for traffic metering and policing.
 670  *
 671  * @param[in] port_id
 672  *   The port identifier of the Ethernet device.
 673  * @param[in] mtr_id
 674  *   MTR object ID. Needs to be unused by any of the existing MTR objects.
 675  *   created for the current port.
 676  * @param[in] params
 677  *   MTR object params. Needs to be pre-allocated and valid.
 678  * @param[in] shared
 679  *   Non-zero when this MTR object can be shared by multiple flows, zero when
 680  *   this MTR object can be used by a single flow.
 681  * @param[out] error
 682  *   Error details. Filled in only on error, when not NULL.
 683  * @return
 684  *   0 on success, non-zero error code otherwise.
 685  *
 686  * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
 687  */
 688 __rte_experimental
 689 int
 690 rte_mtr_create(uint16_t port_id,
 691         uint32_t mtr_id,
 692         struct rte_mtr_params *params,
 693         int shared,
 694         struct rte_mtr_error *error);
 695
 696 /**
 697  * MTR object destroy
 698  *
 699  * Delete an existing MTR object. This operation fails when there is currently
 700  * at least one user (i.e. flow) of this MTR object.
 701  *
 702  * @param[in] port_id
 703  *   The port identifier of the Ethernet device.
 704  * @param[in] mtr_id
 705  *   MTR object ID. Needs to be valid.
 706  *   created for the current port.
 707  * @param[out] error
 708  *   Error details. Filled in only on error, when not NULL.
 709  * @return
 710  *   0 on success, non-zero error code otherwise.
 711  */
 712 __rte_experimental
 713 int
 714 rte_mtr_destroy(uint16_t port_id,
 715         uint32_t mtr_id,
 716         struct rte_mtr_error *error);
 717
 718 /**
 719  * MTR object meter disable
 720  *
 721  * Disable the meter of an existing MTR object. In disabled state, the meter of
 722  * the current MTR object works in pass-through mode, meaning that for each
 723  * input packet the meter output color is always the same as the input color. In
 724  * particular, when the meter of the current MTR object is configured in color
 725  * blind mode, the input color is always green, so the meter output color is
 726  * also always green. Note that the policer and the statistics of the current
 727  * MTR object are working as usual while the meter is disabled. No action is
 728  * taken and this function returns successfully when the meter of the current
 729  * MTR object is already disabled.
 730  *
 731  * @param[in] port_id
 732  *   The port identifier of the Ethernet device.
 733  * @param[in] mtr_id
 734  *   MTR object ID.
 735  * @param[out] error
 736  *   Error details. Filled in only on error, when not NULL.
 737  * @return
 738  *   0 on success, non-zero error code otherwise.
 739  */
 740 __rte_experimental
 741 int
 742 rte_mtr_meter_disable(uint16_t port_id,
 743         uint32_t mtr_id,
 744         struct rte_mtr_error *error);
 745
 746 /**
 747  * MTR object meter enable
 748  *
 749  * Enable the meter of an existing MTR object. If the MTR object has its meter
 750  * already enabled, then no action is taken and this function returns
 751  * successfully.
 752  *
 753  * @param[in] port_id
 754  *   The port identifier of the Ethernet device.
 755  * @param[in] mtr_id
 756  *   MTR object ID.
 757  * @param[out] error
 758  *   Error details. Filled in only on error, when not NULL.
 759  * @return
 760  *   0 on success, non-zero error code otherwise.
 761  */
 762 __rte_experimental
 763 int
 764 rte_mtr_meter_enable(uint16_t port_id,
 765         uint32_t mtr_id,
 766         struct rte_mtr_error *error);
 767
 768 /**
 769  * MTR object meter profile update
 770  *
 771  * @param[in] port_id
 772  *   The port identifier of the Ethernet device.
 773  * @param[in] mtr_id
 774  *   MTR object ID. Needs to be valid.
 775  * @param[in] meter_profile_id
 776  *   Meter profile ID for the current MTR object. Needs to be valid.
 777  * @param[out] error
 778  *   Error details. Filled in only on error, when not NULL.
 779  * @return
 780  *   0 on success, non-zero error code otherwise.
 781  */
 782 __rte_experimental
 783 int
 784 rte_mtr_meter_profile_update(uint16_t port_id,
 785         uint32_t mtr_id,
 786         uint32_t meter_profile_id,
 787         struct rte_mtr_error *error);
 788
 789 /**
 790  * MTR object meter policy update
 791  *
 792  * @param[in] port_id
 793  *   The port identifier of the Ethernet device.
 794  * @param[in] mtr_id
 795  *   MTR object ID. Needs to be valid.
 796  * @param[in] meter_policy_id
 797  *   Meter policy ID for the current MTR object. Needs to be valid.
 798  * @param[out] error
 799  *   Error details. Filled in only on error, when not NULL.
 800  * @return
 801  *   0 on success, non-zero error code otherwise.
 802  */
 803 __rte_experimental
 804 int
 805 rte_mtr_meter_policy_update(uint16_t port_id,
 806         uint32_t mtr_id,
 807         uint32_t meter_policy_id,
 808         struct rte_mtr_error *error);
 809
 810 /**
 811  * MTR object DSCP table update
 812  *
 813  * @param[in] port_id
 814  *   The port identifier of the Ethernet device.
 815  * @param[in] mtr_id
 816  *   MTR object ID. Needs to be valid.
 817  * @param[in] dscp_table
 818  *   When non-NULL: it points to a pre-allocated and pre-populated table with
 819  *   exactly 64 elements providing the input color for each value of the
 820  *   IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
 821  *   When NULL: it is equivalent to setting this parameter to an "all-green"
 822  *   populated table (i.e. table with all the 64 elements set to green color).
 823  * @param[out] error
 824  *   Error details. Filled in only on error, when not NULL.
 825  * @return
 826  *   0 on success, non-zero error code otherwise.
 827  */
 828 __rte_experimental
 829 int
 830 rte_mtr_meter_dscp_table_update(uint16_t port_id,
 831         uint32_t mtr_id,
 832         enum rte_color *dscp_table,
 833         struct rte_mtr_error *error);
 834
 835 /**
 836  * MTR object enabled statistics counters update
 837  *
 838  * @param[in] port_id
 839  *   The port identifier of the Ethernet device.
 840  * @param[in] mtr_id
 841  *   MTR object ID. Needs to be valid.
 842  * @param[in] stats_mask
 843  *   Mask of statistics counter types to be enabled for the current MTR object.
 844  *   Any statistics counter type not included in this set is to be disabled for
 845  *   the current MTR object.
 846  * @param[out] error
 847  *   Error details. Filled in only on error, when not NULL.
 848  * @return
 849  *   0 on success, non-zero error code otherwise.
 850  *
 851  * @see enum rte_mtr_stats_type
 852  */
 853 __rte_experimental
 854 int
 855 rte_mtr_stats_update(uint16_t port_id,
 856         uint32_t mtr_id,
 857         uint64_t stats_mask,
 858         struct rte_mtr_error *error);
 859
 860 /**
 861  * MTR object statistics counters read
 862  *
 863  * @param[in] port_id
 864  *   The port identifier of the Ethernet device.
 865  * @param[in] mtr_id
 866  *   MTR object ID. Needs to be valid.
 867  * @param[out] stats
 868  *   When non-NULL, it contains the current value for the statistics counters
 869  *   enabled for the current MTR object.
 870  * @param[out] stats_mask
 871  *   When non-NULL, it contains the mask of statistics counter types that are
 872  *   currently enabled for this MTR object, indicating which of the counters
 873  *   retrieved with the *stats* structure are valid.
 874  * @param[in] clear
 875  *   When this parameter has a non-zero value, the statistics counters are
 876  *   cleared (i.e. set to zero) immediately after they have been read,
 877  *   otherwise the statistics counters are left untouched.
 878  * @param[out] error
 879  *   Error details. Filled in only on error, when not NULL.
 880  * @return
 881  *   0 on success, non-zero error code otherwise.
 882  *
 883  * @see enum rte_mtr_stats_type
 884  */
 885 __rte_experimental
 886 int
 887 rte_mtr_stats_read(uint16_t port_id,
 888         uint32_t mtr_id,
 889         struct rte_mtr_stats *stats,
 890         uint64_t *stats_mask,
 891         int clear,
 892         struct rte_mtr_error *error);
 893
 894 #ifdef __cplusplus
 895 }
 896 #endif
 897
 898 #endif /* __INCLUDE_RTE_MTR_H__ */