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  * Input color protocol method
 218  *
 219  * More than one of the method can be enabled for a given meter.
 220  * Even if enabled, a method might not be applicable to each input packet,
 221  * in case the associated protocol header is not present in the packet.
 222  * The highest priority method that is both enabled for the meter and also
 223  * applicable for the current input packet wins;
 224  * if none is both enabled and applicable, the default input color is used.
 225  * @see function rte_mtr_color_in_protocol_set()
 226  *
 227  */
 228 enum rte_mtr_color_in_protocol {
 229         /**
 230          * Enable the detection of the packet input color based on the outermost
 231          * VLAN header fields DEI (1 bit) and PCP (3 bits).
 232          * These fields are used as index into the VLAN table.
 233          *
 234          * @see struct rte_mtr_params::vlan_table
 235          */
 236         RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN = RTE_BIT64(0),
 237         /**
 238          * Enable the detection of the packet input color based on the innermost
 239          * VLAN header fields DEI (1 bit) and PCP (3 bits).
 240          * These fields are used as index into the VLAN table.
 241          *
 242          * @see struct rte_mtr_params::vlan_table
 243          */
 244         RTE_MTR_COLOR_IN_PROTO_INNER_VLAN = RTE_BIT64(1),
 245         /**
 246          * Enable the detection of the packet input color based on the outermost
 247          * IP DSCP field. These fields are used as index into the DSCP table.
 248          *
 249          * @see struct rte_mtr_params::dscp_table
 250          */
 251         RTE_MTR_COLOR_IN_PROTO_OUTER_IP = RTE_BIT64(2),
 252         /**
 253          * Enable the detection of the packet input color based on the innermost
 254          * IP DSCP field. These fields are used as index into the DSCP table.
 255          *
 256          * @see struct rte_mtr_params::dscp_table
 257          */
 258         RTE_MTR_COLOR_IN_PROTO_INNER_IP = RTE_BIT64(3),
 259 };
 260
 261 /**
 262  * Parameters for each traffic metering & policing object
 263  *
 264  * @see enum rte_mtr_stats_type
 265  */
 266 struct rte_mtr_params {
 267         /** Meter profile ID. @see rte_mtr_meter_profile_add() */
 268         uint32_t meter_profile_id;
 269
 270         /** Meter input color in case of MTR object chaining. When non-zero: if
 271          * a previous MTR object is enabled in the same flow, then the color
 272          * determined by the latest MTR object in the same flow is used as the
 273          * input color by the current MTR object, otherwise the current MTR
 274          * object uses the *dscp_table* to determine the input color. When zero:
 275          * the color determined by any previous MTR object in same flow is
 276          * ignored by the current MTR object, which uses the *dscp_table* to
 277          * determine the input color.
 278          */
 279         int use_prev_mtr_color;
 280
 281         /** Meter input color based on IP DSCP protocol field.
 282          *
 283          * Valid when *input_color_proto_mask* set to any of the following
 284          * RTE_MTR_COLOR_IN_PROTO_OUTER_IP,
 285          * RTE_MTR_COLOR_IN_PROTO_INNER_IP
 286          *
 287          * When non-NULL: it points to a pre-allocated and
 288          * pre-populated table with exactly 64 elements providing the input
 289          * color for each value of the IPv4/IPv6 Differentiated Services Code
 290          * Point (DSCP) input packet field.
 291          *
 292          * When NULL: it is equivalent to setting this parameter to an all-green
 293          * populated table (i.e. table with all the 64 elements set to green
 294          * color). The color blind mode is configured by setting
 295          * *use_prev_mtr_color* to 0 and *dscp_table* to either NULL or to an
 296          * all-green populated table.
 297          *
 298          * When *use_prev_mtr_color* is non-zero value or when *dscp_table*
 299          * contains at least one yellow or red color element, then the color
 300          * aware mode is configured.
 301          *
 302          * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_OUTER_IP
 303          * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_INNER_IP
 304          * @see struct rte_mtr_params::input_color_proto_mask
 305          */
 306         enum rte_color *dscp_table;
 307         /** Meter input color based on VLAN DEI(1bit), PCP(3 bits) protocol
 308          * fields.
 309          *
 310          * Valid when *input_color_proto_mask* set to any of the following
 311          * RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN,
 312          * RTE_MTR_COLOR_IN_PROTO_INNER_VLAN
 313          *
 314          * When non-NULL: it points to a pre-allocated and pre-populated
 315          * table with exactly 16 elements providing the input color for
 316          * each value of the DEI(1bit), PCP(3 bits) input packet field.
 317          *
 318          * When NULL: it is equivalent to setting this parameter to an
 319          * all-green populated table (i.e. table with
 320          * all the 16 elements set to green color). The color blind mode
 321          * is configured by setting *use_prev_mtr_color* to 0 and
 322          * *vlan_table* to either NULL or to an all-green populated table.
 323          *
 324          * When *use_prev_mtr_color* is non-zero value
 325          * or when *vlan_table* contains at least one yellow or
 326          * red color element, then the color aware mode is configured.
 327          *
 328          * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_OUTER_VLAN
 329          * @see enum rte_mtr_color_in_protocol::RTE_MTR_COLOR_IN_PROTO_INNER_VLAN
 330          * @see struct rte_mtr_params::input_color_proto_mask
 331          */
 332         enum rte_color *vlan_table;
 333         /** Non-zero to enable the meter, zero to disable the meter at the time
 334          * of MTR object creation. Ignored when the meter profile indicated by
 335          * *meter_profile_id* is set to NONE.
 336          * @see rte_mtr_meter_disable()
 337          */
 338         int meter_enable;
 339
 340         /** Set of stats counters to be enabled.
 341          * @see enum rte_mtr_stats_type
 342          */
 343         uint64_t stats_mask;
 344
 345         /** Meter policy ID. @see rte_mtr_meter_policy_add() */
 346         uint32_t meter_policy_id;
 347
 348         /** Input color to be set for the input packet when none of the
 349          * enabled input color methods is applicable to the input packet.
 350          * Ignored when this when *input_color_proto_mask* set to zero.
 351          */
 352         enum rte_color default_input_color;
 353 };
 354
 355 /**
 356  * MTR capabilities
 357  */
 358 struct rte_mtr_capabilities {
 359         /** Maximum number of MTR objects. */
 360         uint32_t n_max;
 361
 362         /** Maximum number of MTR objects that can be shared by multiple flows.
 363          * The value of zero indicates that shared MTR objects are not
 364          * supported. The maximum value is *n_max*.
 365          */
 366         uint32_t n_shared_max;
 367
 368         /** When non-zero, this flag indicates that all the MTR objects that
 369          * cannot be shared by multiple flows have identical capability set.
 370          */
 371         int identical;
 372
 373         /** When non-zero, this flag indicates that all the MTR objects that
 374          * can be shared by multiple flows have identical capability set.
 375          */
 376         int shared_identical;
 377
 378         /** Maximum number of flows that can share the same MTR object. The
 379          * value of zero is invalid. The value of 1 means that shared MTR
 380          * objects not supported.
 381          */
 382         uint32_t shared_n_flows_per_mtr_max;
 383
 384         /** Maximum number of MTR objects that can be part of the same flow. The
 385          * value of zero is invalid. The value of 1 indicates that MTR object
 386          * chaining is not supported. The maximum value is *n_max*.
 387          */
 388         uint32_t chaining_n_mtrs_per_flow_max;
 389
 390         /**
 391          * When non-zero, it indicates that the packet color identified by one
 392          * MTR object can be used as the packet input color by any subsequent
 393          * MTR object from the same flow. When zero, it indicates that the color
 394          * determined by one MTR object is always ignored by any subsequent MTR
 395          * object from the same flow. Only valid when MTR chaining is supported,
 396          * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
 397          * it also means that the color aware mode is supported by at least one
 398          * metering algorithm.
 399          */
 400         int chaining_use_prev_mtr_color_supported;
 401
 402         /**
 403          * When non-zero, it indicates that the packet color identified by one
 404          * MTR object is always used as the packet input color by any subsequent
 405          * MTR object that is part of the same flow. When zero, it indicates
 406          * that whether the color determined by one MTR object is either ignored
 407          * or used as the packet input color by any subsequent MTR object from
 408          * the same flow is individually configurable for each MTR object. Only
 409          * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
 410          */
 411         int chaining_use_prev_mtr_color_enforced;
 412
 413         /** Maximum number of MTR objects that can have their meter configured
 414          * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
 415          * metering algorithm is not supported. The maximum value is *n_max*.
 416          */
 417         uint32_t meter_srtcm_rfc2697_n_max;
 418
 419         /** Maximum number of MTR objects that can have their meter configured
 420          * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
 421          * metering algorithm is not supported. The maximum value is *n_max*.
 422          */
 423         uint32_t meter_trtcm_rfc2698_n_max;
 424
 425         /** Maximum number of MTR objects that can have their meter configured
 426          * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
 427          * metering algorithm is not supported. The maximum value is *n_max*.
 428          */
 429         uint32_t meter_trtcm_rfc4115_n_max;
 430
 431         /** Maximum traffic rate that can be metered by a single MTR object. For
 432          * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
 433          * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
 434          * value for the sum of PIR and EIR rates.
 435          */
 436         uint64_t meter_rate_max;
 437
 438         /**
 439          * Maximum number of policy objects that can have.
 440          * The value of 0 is invalid. Policy must be supported for meter.
 441          * The maximum value is *n_max*.
 442          */
 443         uint64_t meter_policy_n_max;
 444
 445         /**
 446          * When non-zero, it indicates that color aware mode is supported for
 447          * the srTCM RFC 2697 metering algorithm.
 448          */
 449         int color_aware_srtcm_rfc2697_supported;
 450
 451         /**
 452          * When non-zero, it indicates that color aware mode is supported for
 453          * the trTCM RFC 2698 metering algorithm.
 454          */
 455         int color_aware_trtcm_rfc2698_supported;
 456
 457         /**
 458          * When non-zero, it indicates that color aware mode is supported for
 459          * the trTCM RFC 4115 metering algorithm.
 460          */
 461         int color_aware_trtcm_rfc4115_supported;
 462
 463         /**
 464          * srTCM rfc2697 byte mode supported.
 465          * When non-zero, it indicates that byte mode is supported for
 466          * the srTCM RFC 2697 metering algorithm.
 467          */
 468         int srtcm_rfc2697_byte_mode_supported;
 469
 470         /**
 471          * srTCM rfc2697 packet mode supported.
 472          * When non-zero, it indicates that packet mode is supported for
 473          * the srTCM RFC 2697 metering algorithm.
 474          */
 475         int srtcm_rfc2697_packet_mode_supported;
 476
 477         /**
 478          * trTCM rfc2698 byte mode supported.
 479          * When non-zero, it indicates that byte mode is supported for
 480          * the trTCM RFC 2698 metering algorithm.
 481          */
 482         int trtcm_rfc2698_byte_mode_supported;
 483
 484         /**
 485          * trTCM rfc2698 packet mode supported.
 486          * When non-zero, it indicates that packet mode is supported for
 487          * the trTCM RFC 2698 metering algorithm.
 488          */
 489         int trtcm_rfc2698_packet_mode_supported;
 490
 491         /**
 492          * trTCM rfc4115 byte mode supported.
 493          * When non-zero, it indicates that byte mode is supported for
 494          * the trTCM RFC 4115 metering algorithm.
 495          */
 496         int trtcm_rfc4115_byte_mode_supported;
 497
 498         /**
 499          * trTCM rfc4115 packet mode supported.
 500          * When non-zero, it indicates that packet mode is supported for
 501          * the trTCM RFC 4115 metering algorithm.
 502          */
 503         int trtcm_rfc4115_packet_mode_supported;
 504
 505         /** Set of supported statistics counter types.
 506          * @see enum rte_mtr_stats_type
 507          */
 508         uint64_t stats_mask;
 509
 510         /** Set of supported input color protocol.
 511          * @see enum rte_mtr_color_in_protocol
 512          */
 513         uint64_t input_color_proto_mask;
 514
 515         /** When non-zero, it indicates that driver supports separate
 516          * input color table for given ethdev port.
 517          */
 518         int separate_input_color_table_per_port;
 519 };
 520
 521 /**
 522  * Verbose error types.
 523  *
 524  * Most of them provide the type of the object referenced by struct
 525  * rte_mtr_error::cause.
 526  */
 527 enum rte_mtr_error_type {
 528         RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
 529         RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 530         RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
 531         RTE_MTR_ERROR_TYPE_METER_PROFILE,
 532         RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE,
 533         RTE_MTR_ERROR_TYPE_MTR_ID,
 534         RTE_MTR_ERROR_TYPE_MTR_PARAMS,
 535         RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
 536         RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
 537         RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
 538         RTE_MTR_ERROR_TYPE_STATS_MASK,
 539         RTE_MTR_ERROR_TYPE_STATS,
 540         RTE_MTR_ERROR_TYPE_SHARED,
 541         RTE_MTR_ERROR_TYPE_METER_POLICY_ID,
 542         RTE_MTR_ERROR_TYPE_METER_POLICY,
 543 };
 544
 545 /**
 546  * Verbose error structure definition.
 547  *
 548  * This object is normally allocated by applications and set by PMDs, the
 549  * message points to a constant string which does not need to be freed by
 550  * the application, however its pointer can be considered valid only as long
 551  * as its associated DPDK port remains configured. Closing the underlying
 552  * device or unloading the PMD invalidates it.
 553  *
 554  * Both cause and message may be NULL regardless of the error type.
 555  */
 556 struct rte_mtr_error {
 557         enum rte_mtr_error_type type; /**< Cause field and error type. */
 558         const void *cause; /**< Object responsible for the error. */
 559         const char *message; /**< Human-readable error message. */
 560 };
 561
 562 /**
 563  * MTR capabilities get
 564  *
 565  * @param[in] port_id
 566  *   The port identifier of the Ethernet device.
 567  * @param[out] cap
 568  *   MTR capabilities. Needs to be pre-allocated and valid.
 569  * @param[out] error
 570  *   Error details. Filled in only on error, when not NULL.
 571  * @return
 572  *   0 on success, non-zero error code otherwise.
 573  */
 574 __rte_experimental
 575 int
 576 rte_mtr_capabilities_get(uint16_t port_id,
 577         struct rte_mtr_capabilities *cap,
 578         struct rte_mtr_error *error);
 579
 580 /**
 581  * Meter profile add
 582  *
 583  * Create a new meter profile with ID set to *meter_profile_id*. The new profile
 584  * is used to create one or several MTR objects.
 585  *
 586  * @param[in] port_id
 587  *   The port identifier of the Ethernet device.
 588  * @param[in] meter_profile_id
 589  *   ID for the new meter profile. Needs to be unused by any of the existing
 590  *   meter profiles added for the current port.
 591  * @param[in] profile
 592  *   Meter profile parameters. Needs to be pre-allocated and valid.
 593  * @param[out] error
 594  *   Error details. Filled in only on error, when not NULL.
 595  * @return
 596  *   0 on success, non-zero error code otherwise.
 597  */
 598 __rte_experimental
 599 int
 600 rte_mtr_meter_profile_add(uint16_t port_id,
 601         uint32_t meter_profile_id,
 602         struct rte_mtr_meter_profile *profile,
 603         struct rte_mtr_error *error);
 604
 605 /**
 606  * Meter profile delete
 607  *
 608  * Delete an existing meter profile. This operation fails when there is
 609  * currently at least one user (i.e. MTR object) of this profile.
 610  *
 611  * @param[in] port_id
 612  *   The port identifier of the Ethernet device.
 613  * @param[in] meter_profile_id
 614  *   Meter profile ID. Needs to be the valid.
 615  * @param[out] error
 616  *   Error details. Filled in only on error, when not NULL.
 617  * @return
 618  *   0 on success, non-zero error code otherwise.
 619  */
 620 __rte_experimental
 621 int
 622 rte_mtr_meter_profile_delete(uint16_t port_id,
 623         uint32_t meter_profile_id,
 624         struct rte_mtr_error *error);
 625
 626 /**
 627  * Check whether a meter policy can be created on a given port.
 628  *
 629  * The meter policy is validated for correctness and
 630  * whether it could be accepted by the device given sufficient resources.
 631  * The policy is checked against the current capability information
 632  * meter_policy_n_max configuration.
 633  * The policy may also optionally be validated against existing
 634  * device policy resources.
 635  * This function has no effect on the target device.
 636  *
 637  * @param[in] port_id
 638  *   The port identifier of the Ethernet device.
 639  * @param[in] policy
 640  *   Associated action list per color.
 641  *   list NULL is legal and means no special action.
 642  *   (list terminated by the END action).
 643  * @param[out] error
 644  *   Error details. Filled in only on error, when not NULL.
 645  * @return
 646  *   0 on success, non-zero error code otherwise.
 647  */
 648 __rte_experimental
 649 int
 650 rte_mtr_meter_policy_validate(uint16_t port_id,
 651         struct rte_mtr_meter_policy_params *policy,
 652         struct rte_mtr_error *error);
 653
 654 /**
 655  * Meter policy add
 656  *
 657  * Create a new meter policy. The new policy
 658  * is used to create single or multiple MTR objects.
 659  * The same policy can be used to create multiple MTR objects.
 660  *
 661  * @param[in] port_id
 662  *   The port identifier of the Ethernet device.
 663  * @param[in] policy_id
 664  *   Policy identifier for the new meter policy.
 665  * @param[in] policy
 666  *   Associated actions per color.
 667  *   list NULL is legal and means no special action.
 668  *   Non-NULL list must be terminated.
 669  *   (list terminated by the END action).
 670  * @param[out] error
 671  *   Error details. Filled in only on error, when not NULL.
 672  * @return
 673  *   0 on success, non-zero error code otherwise.
 674  */
 675 __rte_experimental
 676 int
 677 rte_mtr_meter_policy_add(uint16_t port_id,
 678         uint32_t policy_id,
 679         struct rte_mtr_meter_policy_params *policy,
 680         struct rte_mtr_error *error);
 681
 682 /**
 683  * Define meter policy action list:
 684  * GREEN - GREEN, YELLOW - YELLOW, RED - RED
 685  */
 686 #define rte_mtr_policy_pass_color(policy) \
 687 struct rte_mtr_meter_policy_params policy = \
 688 { \
 689         .actions[RTE_COLOR_GREEN] = (struct rte_flow_action[]) { \
 690                 { \
 691                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 692                         .conf = &(struct rte_flow_action_meter_color) { \
 693                                 .color = RTE_COLOR_GREEN, \
 694                         }, \
 695                 }, \
 696                 { \
 697                         .type = RTE_FLOW_ACTION_TYPE_END, \
 698                 }, \
 699         }, \
 700         .actions[RTE_COLOR_YELLOW] = (struct rte_flow_action[]) { \
 701                 { \
 702                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 703                         .conf = &(struct rte_flow_action_meter_color) { \
 704                                 .color = RTE_COLOR_YELLOW, \
 705                         }, \
 706                 }, \
 707                 { \
 708                 .type = RTE_FLOW_ACTION_TYPE_END, \
 709                 }, \
 710         }, \
 711         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
 712                 { \
 713                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
 714                         .conf = &(struct rte_flow_action_meter_color) { \
 715                                 .color = RTE_COLOR_RED, \
 716                         }, \
 717                 }, \
 718                 { \
 719                         .type = RTE_FLOW_ACTION_TYPE_END, \
 720                 }, \
 721         }, \
 722 }
 723
 724 /**
 725  * Define meter policy action list:
 726  * GREEN - Do nothing, YELLOW - Do nothing, RED - DROP
 727  */
 728 #define rte_mtr_policy_drop_red(policy) \
 729 struct rte_mtr_meter_policy_params policy = \
 730 { \
 731         .actions[RTE_COLOR_GREEN] = NULL, \
 732         .actions[RTE_COLOR_YELLOW] = NULL, \
 733         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
 734                 { \
 735                         .type = RTE_FLOW_ACTION_TYPE_DROP, \
 736                 }, \
 737                 { \
 738                         .type = RTE_FLOW_ACTION_TYPE_END, \
 739                 }, \
 740         }, \
 741 }
 742
 743 /**
 744  * Meter policy delete
 745  *
 746  * Delete an existing meter policy. This operation fails when there is
 747  * currently at least one user (i.e. MTR object) of this policy.
 748  *
 749  * @param[in] port_id
 750  *   The port identifier of the Ethernet device.
 751  * @param[in] policy_id
 752  *   Policy identifier.
 753  * @param[out] error
 754  *   Error details. Filled in only on error, when not NULL.
 755  * @return
 756  *   0 on success, non-zero error code otherwise.
 757  */
 758 __rte_experimental
 759 int
 760 rte_mtr_meter_policy_delete(uint16_t port_id,
 761         uint32_t policy_id,
 762         struct rte_mtr_error *error);
 763
 764 /**
 765  * MTR object create
 766  *
 767  * Create a new MTR object for the current port. This object is run as part of
 768  * associated flow action for traffic metering and policing.
 769  *
 770  * @param[in] port_id
 771  *   The port identifier of the Ethernet device.
 772  * @param[in] mtr_id
 773  *   MTR object ID. Needs to be unused by any of the existing MTR objects.
 774  *   created for the current port.
 775  * @param[in] params
 776  *   MTR object params. Needs to be pre-allocated and valid.
 777  * @param[in] shared
 778  *   Non-zero when this MTR object can be shared by multiple flows, zero when
 779  *   this MTR object can be used by a single flow.
 780  * @param[out] error
 781  *   Error details. Filled in only on error, when not NULL.
 782  * @return
 783  *   0 on success, non-zero error code otherwise.
 784  *
 785  * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
 786  */
 787 __rte_experimental
 788 int
 789 rte_mtr_create(uint16_t port_id,
 790         uint32_t mtr_id,
 791         struct rte_mtr_params *params,
 792         int shared,
 793         struct rte_mtr_error *error);
 794
 795 /**
 796  * MTR object destroy
 797  *
 798  * Delete an existing MTR object. This operation fails when there is currently
 799  * at least one user (i.e. flow) of this MTR object.
 800  *
 801  * @param[in] port_id
 802  *   The port identifier of the Ethernet device.
 803  * @param[in] mtr_id
 804  *   MTR object ID. Needs to be valid.
 805  *   created for the current port.
 806  * @param[out] error
 807  *   Error details. Filled in only on error, when not NULL.
 808  * @return
 809  *   0 on success, non-zero error code otherwise.
 810  */
 811 __rte_experimental
 812 int
 813 rte_mtr_destroy(uint16_t port_id,
 814         uint32_t mtr_id,
 815         struct rte_mtr_error *error);
 816
 817 /**
 818  * MTR object meter disable
 819  *
 820  * Disable the meter of an existing MTR object. In disabled state, the meter of
 821  * the current MTR object works in pass-through mode, meaning that for each
 822  * input packet the meter output color is always the same as the input color. In
 823  * particular, when the meter of the current MTR object is configured in color
 824  * blind mode, the input color is always green, so the meter output color is
 825  * also always green. Note that the policer and the statistics of the current
 826  * MTR object are working as usual while the meter is disabled. No action is
 827  * taken and this function returns successfully when the meter of the current
 828  * MTR object is already disabled.
 829  *
 830  * @param[in] port_id
 831  *   The port identifier of the Ethernet device.
 832  * @param[in] mtr_id
 833  *   MTR object ID.
 834  * @param[out] error
 835  *   Error details. Filled in only on error, when not NULL.
 836  * @return
 837  *   0 on success, non-zero error code otherwise.
 838  */
 839 __rte_experimental
 840 int
 841 rte_mtr_meter_disable(uint16_t port_id,
 842         uint32_t mtr_id,
 843         struct rte_mtr_error *error);
 844
 845 /**
 846  * MTR object meter enable
 847  *
 848  * Enable the meter of an existing MTR object. If the MTR object has its meter
 849  * already enabled, then no action is taken and this function returns
 850  * successfully.
 851  *
 852  * @param[in] port_id
 853  *   The port identifier of the Ethernet device.
 854  * @param[in] mtr_id
 855  *   MTR object ID.
 856  * @param[out] error
 857  *   Error details. Filled in only on error, when not NULL.
 858  * @return
 859  *   0 on success, non-zero error code otherwise.
 860  */
 861 __rte_experimental
 862 int
 863 rte_mtr_meter_enable(uint16_t port_id,
 864         uint32_t mtr_id,
 865         struct rte_mtr_error *error);
 866
 867 /**
 868  * MTR object meter profile update
 869  *
 870  * @param[in] port_id
 871  *   The port identifier of the Ethernet device.
 872  * @param[in] mtr_id
 873  *   MTR object ID. Needs to be valid.
 874  * @param[in] meter_profile_id
 875  *   Meter profile ID for the current MTR object. Needs to be valid.
 876  * @param[out] error
 877  *   Error details. Filled in only on error, when not NULL.
 878  * @return
 879  *   0 on success, non-zero error code otherwise.
 880  */
 881 __rte_experimental
 882 int
 883 rte_mtr_meter_profile_update(uint16_t port_id,
 884         uint32_t mtr_id,
 885         uint32_t meter_profile_id,
 886         struct rte_mtr_error *error);
 887
 888 /**
 889  * MTR object meter policy update
 890  *
 891  * @param[in] port_id
 892  *   The port identifier of the Ethernet device.
 893  * @param[in] mtr_id
 894  *   MTR object ID. Needs to be valid.
 895  * @param[in] meter_policy_id
 896  *   Meter policy ID for the current MTR object. Needs to be valid.
 897  * @param[out] error
 898  *   Error details. Filled in only on error, when not NULL.
 899  * @return
 900  *   0 on success, non-zero error code otherwise.
 901  */
 902 __rte_experimental
 903 int
 904 rte_mtr_meter_policy_update(uint16_t port_id,
 905         uint32_t mtr_id,
 906         uint32_t meter_policy_id,
 907         struct rte_mtr_error *error);
 908
 909 /**
 910  * MTR object DSCP table update
 911  *
 912  * @param[in] port_id
 913  *   The port identifier of the Ethernet device.
 914  * @param[in] mtr_id
 915  *   MTR object ID. Needs to be valid.
 916  * @param[in] dscp_table
 917  *   When non-NULL: it points to a pre-allocated and pre-populated table with
 918  *   exactly 64 elements providing the input color for each value of the
 919  *   IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
 920  *   When NULL: it is equivalent to setting this parameter to an "all-green"
 921  *   populated table (i.e. table with all the 64 elements set to green color).
 922  * @param[out] error
 923  *   Error details. Filled in only on error, when not NULL.
 924  * @return
 925  *   0 on success, non-zero error code otherwise.
 926  */
 927 __rte_experimental
 928 int
 929 rte_mtr_meter_dscp_table_update(uint16_t port_id,
 930         uint32_t mtr_id,
 931         enum rte_color *dscp_table,
 932         struct rte_mtr_error *error);
 933
 934 /**
 935  * MTR object VLAN table update
 936  *
 937  * @param[in] port_id
 938  *   The port identifier of the Ethernet device.
 939  * @param[in] mtr_id
 940  *   MTR object ID. Needs to be valid.
 941  * @param[in] vlan_table
 942  *   When non-NULL: it points to a pre-allocated and pre-populated table with
 943  *   exactly 16 elements providing the input color for each value of the
 944  *   each value of the DEI(1bit), PCP(3 bits) input packet field.
 945  *   When NULL: it is equivalent to setting this parameter to an "all-green"
 946  *   populated table (i.e. table with all the 16 elements set to green color).
 947  * @param[out] error
 948  *   Error details. Filled in only on error, when not NULL.
 949  * @return
 950  *   0 on success, non-zero error code otherwise.
 951  */
 952 __rte_experimental
 953 int
 954 rte_mtr_meter_vlan_table_update(uint16_t port_id, uint32_t mtr_id,
 955                                 enum rte_color *vlan_table,
 956                                 struct rte_mtr_error *error);
 957
 958 /**
 959  * Set the input color protocol for a given MTR object
 960  *
 961  * More than one of the method can be enabled for a given meter.
 962  * Even if enabled, a method might not be applicable to each input packet,
 963  * in case the associated protocol header is not present in the packet.
 964  * The highest priority method that is both enabled for the meter and also
 965  * applicable for the current input packet wins;
 966  * if none is both enabled and applicable, the default input color is used.
 967  *
 968  * @param[in] port_id
 969  *   The port identifier of the Ethernet device.
 970  * @param[in] mtr_id
 971  *   MTR object ID. Needs to be valid.
 972  * @param[in] proto
 973  *   Input color protocol.
 974  * @param[in] priority
 975  *   Input color protocol priority. Value zero indicates
 976  *   the highest priority.
 977  * @param[out] error
 978  *   Error details. Filled in only on error, when not NULL.
 979  * @return
 980  *   0 on success, non-zero error code otherwise.
 981  */
 982 __rte_experimental
 983 int
 984 rte_mtr_color_in_protocol_set(uint16_t port_id, uint32_t mtr_id,
 985         enum rte_mtr_color_in_protocol proto, uint32_t priority,
 986         struct rte_mtr_error *error);
 987
 988 /**
 989  * Get the input color protocol for a given MTR object
 990  *
 991  * @param[in] port_id
 992  *   The port identifier of the Ethernet device.
 993  * @param[in] mtr_id
 994  *   MTR object ID. Needs to be valid.
 995  * @param[out] proto_mask
 996  *   Selected input color protocols as bit mask.
 997  * @param[out] error
 998  *   Error details. Filled in only on error, when not NULL.
 999  * @return
1000  *   0 on success, non-zero error code otherwise.
1001  *
1002  */
1003 __rte_experimental
1004 int
1005 rte_mtr_color_in_protocol_get(uint16_t port_id, uint32_t mtr_id,
1006         uint64_t *proto_mask,
1007         struct rte_mtr_error *error);
1008
1009 /**
1010  * Get the priority associated with input color protocol for a given MTR object
1011  *
1012  * @param[in] port_id
1013  *   The port identifier of the Ethernet device.
1014  * @param[in] mtr_id
1015  *   MTR object ID. Needs to be valid.
1016  * @param[in] proto
1017  *   Input color protocol.
1018  * @param[out] priority
1019  *   Input color protocol priority associated with proto.
1020  * @param[out] error
1021  *   Error details. Filled in only on error, when not NULL.
1022  * @return
1023  *   0 on success, non-zero error code otherwise.
1024  */
1025 __rte_experimental
1026 int
1027 rte_mtr_color_in_protocol_priority_get(uint16_t port_id, uint32_t mtr_id,
1028         enum rte_mtr_color_in_protocol proto, uint32_t *priority,
1029         struct rte_mtr_error *error);
1030
1031 /**
1032  * MTR object enabled statistics counters update
1033  *
1034  * @param[in] port_id
1035  *   The port identifier of the Ethernet device.
1036  * @param[in] mtr_id
1037  *   MTR object ID. Needs to be valid.
1038  * @param[in] stats_mask
1039  *   Mask of statistics counter types to be enabled for the current MTR object.
1040  *   Any statistics counter type not included in this set is to be disabled for
1041  *   the current MTR object.
1042  * @param[out] error
1043  *   Error details. Filled in only on error, when not NULL.
1044  * @return
1045  *   0 on success, non-zero error code otherwise.
1046  *
1047  * @see enum rte_mtr_stats_type
1048  */
1049 __rte_experimental
1050 int
1051 rte_mtr_stats_update(uint16_t port_id,
1052         uint32_t mtr_id,
1053         uint64_t stats_mask,
1054         struct rte_mtr_error *error);
1055
1056 /**
1057  * MTR object statistics counters read
1058  *
1059  * @param[in] port_id
1060  *   The port identifier of the Ethernet device.
1061  * @param[in] mtr_id
1062  *   MTR object ID. Needs to be valid.
1063  * @param[out] stats
1064  *   When non-NULL, it contains the current value for the statistics counters
1065  *   enabled for the current MTR object.
1066  * @param[out] stats_mask
1067  *   When non-NULL, it contains the mask of statistics counter types that are
1068  *   currently enabled for this MTR object, indicating which of the counters
1069  *   retrieved with the *stats* structure are valid.
1070  * @param[in] clear
1071  *   When this parameter has a non-zero value, the statistics counters are
1072  *   cleared (i.e. set to zero) immediately after they have been read,
1073  *   otherwise the statistics counters are left untouched.
1074  * @param[out] error
1075  *   Error details. Filled in only on error, when not NULL.
1076  * @return
1077  *   0 on success, non-zero error code otherwise.
1078  *
1079  * @see enum rte_mtr_stats_type
1080  */
1081 __rte_experimental
1082 int
1083 rte_mtr_stats_read(uint16_t port_id,
1084         uint32_t mtr_id,
1085         struct rte_mtr_stats *stats,
1086         uint64_t *stats_mask,
1087         int clear,
1088         struct rte_mtr_error *error);
1089
1090 #ifdef __cplusplus
1091 }
1092 #endif
1093
1094 #endif /* __INCLUDE_RTE_MTR_H__ */