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. @see rte_mtr_meter_profile_add() */ 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. @see rte_mtr_meter_policy_add() */ 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__ */ 899