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