lib/librte_ethdev/rte_tm.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2017 Intel Corporation.
   5  *   Copyright(c) 2017 Cavium.
   6  *   Copyright(c) 2017 NXP.
   7  *   All rights reserved.
   8  *
   9  *   Redistribution and use in source and binary forms, with or without
  10  *   modification, are permitted provided that the following conditions
  11  *   are met:
  12  *
  13  *     * Redistributions of source code must retain the above copyright
  14  *       notice, this list of conditions and the following disclaimer.
  15  *     * Redistributions in binary form must reproduce the above copyright
  16  *       notice, this list of conditions and the following disclaimer in
  17  *       the documentation and/or other materials provided with the
  18  *       distribution.
  19  *     * Neither the name of Intel Corporation nor the names of its
  20  *       contributors may be used to endorse or promote products derived
  21  *       from this software without specific prior written permission.
  22  *
  23  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  29  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  30  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  31  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  33  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 #ifndef __INCLUDE_RTE_TM_H__
  37 #define __INCLUDE_RTE_TM_H__
  38
  39 /**
  40  * @file
  41  * RTE Generic Traffic Manager API
  42  *
  43  * This interface provides the ability to configure the traffic manager in a
  44  * generic way. It includes features such as: hierarchical scheduling,
  45  * traffic shaping, congestion management, packet marking, etc.
  46  *
  47  * @warning
  48  * @b EXPERIMENTAL: this API may change without prior notice
  49  */
  50
  51 #include <stdint.h>
  52
  53 #include <rte_common.h>
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /**
  60  * Ethernet framing overhead.
  61  *
  62  * Overhead fields per Ethernet frame:
  63  * 1. Preamble:                                            7 bytes;
  64  * 2. Start of Frame Delimiter (SFD):                      1 byte;
  65  * 3. Inter-Frame Gap (IFG):                              12 bytes.
  66  *
  67  * One of the typical values for the *pkt_length_adjust* field of the shaper
  68  * profile.
  69  *
  70  * @see struct rte_tm_shaper_params
  71  */
  72 #define RTE_TM_ETH_FRAMING_OVERHEAD                  20
  73
  74 /**
  75  * Ethernet framing overhead including the Frame Check Sequence (FCS) field.
  76  * Useful when FCS is generated and added at the end of the Ethernet frame on
  77  * TX side without any SW intervention.
  78  *
  79  * One of the typical values for the pkt_length_adjust field of the shaper
  80  * profile.
  81  *
  82  * @see struct rte_tm_shaper_params
  83  */
  84 #define RTE_TM_ETH_FRAMING_OVERHEAD_FCS              24
  85
  86 /**
  87  * Invalid WRED profile ID.
  88  *
  89  * @see struct rte_tm_node_params
  90  * @see rte_tm_node_add()
  91  * @see rte_tm_node_wred_context_update()
  92  */
  93 #define RTE_TM_WRED_PROFILE_ID_NONE                  UINT32_MAX
  94
  95 /**
  96  *Invalid shaper profile ID.
  97  *
  98  * @see struct rte_tm_node_params
  99  * @see rte_tm_node_add()
 100  * @see rte_tm_node_shaper_update()
 101  */
 102 #define RTE_TM_SHAPER_PROFILE_ID_NONE                UINT32_MAX
 103
 104 /**
 105  * Node ID for the parent of the root node.
 106  *
 107  * @see rte_tm_node_add()
 108  */
 109 #define RTE_TM_NODE_ID_NULL                          UINT32_MAX
 110
 111 /**
 112  * Node level ID used to disable level ID checking.
 113  *
 114  * @see rte_tm_node_add()
 115  */
 116 #define RTE_TM_NODE_LEVEL_ID_ANY                     UINT32_MAX
 117
 118 /**
 119  * Color
 120  */
 121 enum rte_tm_color {
 122         RTE_TM_GREEN = 0, /**< Green */
 123         RTE_TM_YELLOW, /**< Yellow */
 124         RTE_TM_RED, /**< Red */
 125         RTE_TM_COLORS /**< Number of colors */
 126 };
 127
 128 /**
 129  * Node statistics counter type
 130  */
 131 enum rte_tm_stats_type {
 132         /** Number of packets scheduled from current node. */
 133         RTE_TM_STATS_N_PKTS = 1 << 0,
 134
 135         /** Number of bytes scheduled from current node. */
 136         RTE_TM_STATS_N_BYTES = 1 << 1,
 137
 138         /** Number of green packets dropped by current leaf node.  */
 139         RTE_TM_STATS_N_PKTS_GREEN_DROPPED = 1 << 2,
 140
 141         /** Number of yellow packets dropped by current leaf node.  */
 142         RTE_TM_STATS_N_PKTS_YELLOW_DROPPED = 1 << 3,
 143
 144         /** Number of red packets dropped by current leaf node.  */
 145         RTE_TM_STATS_N_PKTS_RED_DROPPED = 1 << 4,
 146
 147         /** Number of green bytes dropped by current leaf node.  */
 148         RTE_TM_STATS_N_BYTES_GREEN_DROPPED = 1 << 5,
 149
 150         /** Number of yellow bytes dropped by current leaf node.  */
 151         RTE_TM_STATS_N_BYTES_YELLOW_DROPPED = 1 << 6,
 152
 153         /** Number of red bytes dropped by current leaf node.  */
 154         RTE_TM_STATS_N_BYTES_RED_DROPPED = 1 << 7,
 155
 156         /** Number of packets currently waiting in the packet queue of current
 157          * leaf node.
 158          */
 159         RTE_TM_STATS_N_PKTS_QUEUED = 1 << 8,
 160
 161         /** Number of bytes currently waiting in the packet queue of current
 162          * leaf node.
 163          */
 164         RTE_TM_STATS_N_BYTES_QUEUED = 1 << 9,
 165 };
 166
 167 /**
 168  * Node statistics counters
 169  */
 170 struct rte_tm_node_stats {
 171         /** Number of packets scheduled from current node. */
 172         uint64_t n_pkts;
 173
 174         /** Number of bytes scheduled from current node. */
 175         uint64_t n_bytes;
 176
 177         /** Statistics counters for leaf nodes only. */
 178         struct {
 179                 /** Number of packets dropped by current leaf node per each
 180                  * color.
 181                  */
 182                 uint64_t n_pkts_dropped[RTE_TM_COLORS];
 183
 184                 /** Number of bytes dropped by current leaf node per each
 185                  * color.
 186                  */
 187                 uint64_t n_bytes_dropped[RTE_TM_COLORS];
 188
 189                 /** Number of packets currently waiting in the packet queue of
 190                  * current leaf node.
 191                  */
 192                 uint64_t n_pkts_queued;
 193
 194                 /** Number of bytes currently waiting in the packet queue of
 195                  * current leaf node.
 196                  */
 197                 uint64_t n_bytes_queued;
 198         } leaf;
 199 };
 200
 201 /**
 202  * Traffic manager dynamic updates
 203  */
 204 enum rte_tm_dynamic_update_type {
 205         /** Dynamic parent node update. The new parent node is located on same
 206          * hierarchy level as the former parent node. Consequently, the node
 207          * whose parent is changed preserves its hierarchy level.
 208          */
 209         RTE_TM_UPDATE_NODE_PARENT_KEEP_LEVEL = 1 << 0,
 210
 211         /** Dynamic parent node update. The new parent node is located on
 212          * different hierarchy level than the former parent node. Consequently,
 213          * the node whose parent is changed also changes its hierarchy level.
 214          */
 215         RTE_TM_UPDATE_NODE_PARENT_CHANGE_LEVEL = 1 << 1,
 216
 217         /** Dynamic node add/delete. */
 218         RTE_TM_UPDATE_NODE_ADD_DELETE = 1 << 2,
 219
 220         /** Suspend/resume nodes. */
 221         RTE_TM_UPDATE_NODE_SUSPEND_RESUME = 1 << 3,
 222
 223         /** Dynamic switch between byte-based and packet-based WFQ weights. */
 224         RTE_TM_UPDATE_NODE_WFQ_WEIGHT_MODE = 1 << 4,
 225
 226         /** Dynamic update on number of SP priorities. */
 227         RTE_TM_UPDATE_NODE_N_SP_PRIORITIES = 1 << 5,
 228
 229         /** Dynamic update of congestion management mode for leaf nodes. */
 230         RTE_TM_UPDATE_NODE_CMAN = 1 << 6,
 231
 232         /** Dynamic update of the set of enabled stats counter types. */
 233         RTE_TM_UPDATE_NODE_STATS = 1 << 7,
 234 };
 235
 236 /**
 237  * Traffic manager capabilities
 238  */
 239 struct rte_tm_capabilities {
 240         /** Maximum number of nodes. */
 241         uint32_t n_nodes_max;
 242
 243         /** Maximum number of levels (i.e. number of nodes connecting the root
 244          * node with any leaf node, including the root and the leaf).
 245          */
 246         uint32_t n_levels_max;
 247
 248         /** When non-zero, this flag indicates that all the non-leaf nodes
 249          * (with the exception of the root node) have identical capability set.
 250          */
 251         int non_leaf_nodes_identical;
 252
 253         /** When non-zero, this flag indicates that all the leaf nodes have
 254          * identical capability set.
 255          */
 256         int leaf_nodes_identical;
 257
 258         /** Maximum number of shapers, either private or shared. In case the
 259          * implementation does not share any resources between private and
 260          * shared shapers, it is typically equal to the sum of
 261          * *shaper_private_n_max* and *shaper_shared_n_max*. The
 262          * value of zero indicates that traffic shaping is not supported.
 263          */
 264         uint32_t shaper_n_max;
 265
 266         /** Maximum number of private shapers. Indicates the maximum number of
 267          * nodes that can concurrently have their private shaper enabled. The
 268          * value of zero indicates that private shapers are not supported.
 269          */
 270         uint32_t shaper_private_n_max;
 271
 272         /** Maximum number of private shapers that support dual rate shaping.
 273          * Indicates the maximum number of nodes that can concurrently have
 274          * their private shaper enabled with dual rate support. Only valid when
 275          * private shapers are supported. The value of zero indicates that dual
 276          * rate shaping is not available for private shapers. The maximum value
 277          * is *shaper_private_n_max*.
 278          */
 279         int shaper_private_dual_rate_n_max;
 280
 281         /** Minimum committed/peak rate (bytes per second) for any private
 282          * shaper. Valid only when private shapers are supported.
 283          */
 284         uint64_t shaper_private_rate_min;
 285
 286         /** Maximum committed/peak rate (bytes per second) for any private
 287          * shaper. Valid only when private shapers are supported.
 288          */
 289         uint64_t shaper_private_rate_max;
 290
 291         /** Maximum number of shared shapers. The value of zero indicates that
 292          * shared shapers are not supported.
 293          */
 294         uint32_t shaper_shared_n_max;
 295
 296         /** Maximum number of nodes that can share the same shared shaper.
 297          * Only valid when shared shapers are supported.
 298          */
 299         uint32_t shaper_shared_n_nodes_per_shaper_max;
 300
 301         /** Maximum number of shared shapers a node can be part of. This
 302          * parameter indicates that there is at least one node that can be
 303          * configured with this many shared shapers, which might not be true for
 304          * all the nodes. Only valid when shared shapers are supported, in which
 305          * case it ranges from 1 to *shaper_shared_n_max*.
 306          */
 307         uint32_t shaper_shared_n_shapers_per_node_max;
 308
 309         /** Maximum number of shared shapers that can be configured with dual
 310          * rate shaping. The value of zero indicates that dual rate shaping
 311          * support is not available for shared shapers.
 312          */
 313         uint32_t shaper_shared_dual_rate_n_max;
 314
 315         /** Minimum committed/peak rate (bytes per second) for any shared
 316          * shaper. Only valid when shared shapers are supported.
 317          */
 318         uint64_t shaper_shared_rate_min;
 319
 320         /** Maximum committed/peak rate (bytes per second) for any shared
 321          * shaper. Only valid when shared shapers are supported.
 322          */
 323         uint64_t shaper_shared_rate_max;
 324
 325         /** Minimum value allowed for packet length adjustment for any private
 326          * or shared shaper.
 327          */
 328         int shaper_pkt_length_adjust_min;
 329
 330         /** Maximum value allowed for packet length adjustment for any private
 331          * or shared shaper.
 332          */
 333         int shaper_pkt_length_adjust_max;
 334
 335         /** Maximum number of children nodes. This parameter indicates that
 336          * there is at least one non-leaf node that can be configured with this
 337          * many children nodes, which might not be true for all the non-leaf
 338          * nodes.
 339          */
 340         uint32_t sched_n_children_max;
 341
 342         /** Maximum number of supported priority levels. This parameter
 343          * indicates that there is at least one non-leaf node that can be
 344          * configured with this many priority levels for managing its children
 345          * nodes, which might not be true for all the non-leaf nodes. The value
 346          * of zero is invalid. The value of 1 indicates that only priority 0 is
 347          * supported, which essentially means that Strict Priority (SP)
 348          * algorithm is not supported.
 349          */
 350         uint32_t sched_sp_n_priorities_max;
 351
 352         /** Maximum number of sibling nodes that can have the same priority at
 353          * any given time, i.e. maximum size of the WFQ sibling node group. This
 354          * parameter indicates there is at least one non-leaf node that meets
 355          * this condition, which might not be true for all the non-leaf nodes.
 356          * The value of zero is invalid. The value of 1 indicates that WFQ
 357          * algorithm is not supported. The maximum value is
 358          * *sched_n_children_max*.
 359          */
 360         uint32_t sched_wfq_n_children_per_group_max;
 361
 362         /** Maximum number of priority levels that can have more than one child
 363          * node at any given time, i.e. maximum number of WFQ sibling node
 364          * groups that have two or more members. This parameter indicates there
 365          * is at least one non-leaf node that meets this condition, which might
 366          * not be true for all the non-leaf nodes. The value of zero states that
 367          * WFQ algorithm is not supported. The value of 1 indicates that
 368          * (*sched_sp_n_priorities_max* - 1) priority levels have at most one
 369          * child node, so there can be only one priority level with two or
 370          * more sibling nodes making up a WFQ group. The maximum value is:
 371          * min(floor(*sched_n_children_max* / 2), *sched_sp_n_priorities_max*).
 372          */
 373         uint32_t sched_wfq_n_groups_max;
 374
 375         /** Maximum WFQ weight. The value of 1 indicates that all sibling nodes
 376          * with same priority have the same WFQ weight, so WFQ is reduced to FQ.
 377          */
 378         uint32_t sched_wfq_weight_max;
 379
 380         /** WRED packet mode support. When non-zero, this parameter indicates
 381          * that there is atleast one leaf node that supports the WRED packet
 382          * mode, which might not be true for all the leaf nodes. In packet
 383          * mode, the WRED thresholds specify the queue length in packets, as
 384          * opposed to bytes.
 385          */
 386         int cman_wred_packet_mode_supported;
 387
 388         /** WRED byte mode support. When non-zero, this parameter indicates that
 389          * there is atleast one leaf node that supports the WRED byte mode,
 390          * which might not be true for all the leaf nodes. In byte mode, the
 391          * WRED thresholds specify the queue length in bytes, as opposed to
 392          * packets.
 393          */
 394         int cman_wred_byte_mode_supported;
 395
 396         /** Head drop algorithm support. When non-zero, this parameter
 397          * indicates that there is at least one leaf node that supports the head
 398          * drop algorithm, which might not be true for all the leaf nodes.
 399          */
 400         int cman_head_drop_supported;
 401
 402         /** Maximum number of WRED contexts, either private or shared. In case
 403          * the implementation does not share any resources between private and
 404          * shared WRED contexts, it is typically equal to the sum of
 405          * *cman_wred_context_private_n_max* and
 406          * *cman_wred_context_shared_n_max*. The value of zero indicates that
 407          * WRED is not supported.
 408          */
 409         uint32_t cman_wred_context_n_max;
 410
 411         /** Maximum number of private WRED contexts. Indicates the maximum
 412          * number of leaf nodes that can concurrently have their private WRED
 413          * context enabled. The value of zero indicates that private WRED
 414          * contexts are not supported.
 415          */
 416         uint32_t cman_wred_context_private_n_max;
 417
 418         /** Maximum number of shared WRED contexts. The value of zero
 419          * indicates that shared WRED contexts are not supported.
 420          */
 421         uint32_t cman_wred_context_shared_n_max;
 422
 423         /** Maximum number of leaf nodes that can share the same WRED context.
 424          * Only valid when shared WRED contexts are supported.
 425          */
 426         uint32_t cman_wred_context_shared_n_nodes_per_context_max;
 427
 428         /** Maximum number of shared WRED contexts a leaf node can be part of.
 429          * This parameter indicates that there is at least one leaf node that
 430          * can be configured with this many shared WRED contexts, which might
 431          * not be true for all the leaf nodes. Only valid when shared WRED
 432          * contexts are supported, in which case it ranges from 1 to
 433          * *cman_wred_context_shared_n_max*.
 434          */
 435         uint32_t cman_wred_context_shared_n_contexts_per_node_max;
 436
 437         /** Support for VLAN DEI packet marking (per color). */
 438         int mark_vlan_dei_supported[RTE_TM_COLORS];
 439
 440         /** Support for IPv4/IPv6 ECN marking of TCP packets (per color). */
 441         int mark_ip_ecn_tcp_supported[RTE_TM_COLORS];
 442
 443         /** Support for IPv4/IPv6 ECN marking of SCTP packets (per color). */
 444         int mark_ip_ecn_sctp_supported[RTE_TM_COLORS];
 445
 446         /** Support for IPv4/IPv6 DSCP packet marking (per color). */
 447         int mark_ip_dscp_supported[RTE_TM_COLORS];
 448
 449         /** Set of supported dynamic update operations.
 450          * @see enum rte_tm_dynamic_update_type
 451          */
 452         uint64_t dynamic_update_mask;
 453
 454         /** Set of supported statistics counter types.
 455          * @see enum rte_tm_stats_type
 456          */
 457         uint64_t stats_mask;
 458 };
 459
 460 /**
 461  * Traffic manager level capabilities
 462  */
 463 struct rte_tm_level_capabilities {
 464         /** Maximum number of nodes for the current hierarchy level. */
 465         uint32_t n_nodes_max;
 466
 467         /** Maximum number of non-leaf nodes for the current hierarchy level.
 468          * The value of 0 indicates that current level only supports leaf
 469          * nodes. The maximum value is *n_nodes_max*.
 470          */
 471         uint32_t n_nodes_nonleaf_max;
 472
 473         /** Maximum number of leaf nodes for the current hierarchy level. The
 474          * value of 0 indicates that current level only supports non-leaf
 475          * nodes. The maximum value is *n_nodes_max*.
 476          */
 477         uint32_t n_nodes_leaf_max;
 478
 479         /** When non-zero, this flag indicates that all the non-leaf nodes on
 480          * this level have identical capability set. Valid only when
 481          * *n_nodes_nonleaf_max* is non-zero.
 482          */
 483         int non_leaf_nodes_identical;
 484
 485         /** When non-zero, this flag indicates that all the leaf nodes on this
 486          * level have identical capability set. Valid only when
 487          * *n_nodes_leaf_max* is non-zero.
 488          */
 489         int leaf_nodes_identical;
 490
 491         RTE_STD_C11
 492         union {
 493                 /** Items valid only for the non-leaf nodes on this level. */
 494                 struct {
 495                         /** Private shaper support. When non-zero, it indicates
 496                          * there is at least one non-leaf node on this level
 497                          * with private shaper support, which may not be the
 498                          * case for all the non-leaf nodes on this level.
 499                          */
 500                         int shaper_private_supported;
 501
 502                         /** Dual rate support for private shaper. Valid only
 503                          * when private shaper is supported for the non-leaf
 504                          * nodes on the current level. When non-zero, it
 505                          * indicates there is at least one non-leaf node on this
 506                          * level with dual rate private shaper support, which
 507                          * may not be the case for all the non-leaf nodes on
 508                          * this level.
 509                          */
 510                         int shaper_private_dual_rate_supported;
 511
 512                         /** Minimum committed/peak rate (bytes per second) for
 513                          * private shapers of the non-leaf nodes of this level.
 514                          * Valid only when private shaper is supported on this
 515                          * level.
 516                          */
 517                         uint64_t shaper_private_rate_min;
 518
 519                         /** Maximum committed/peak rate (bytes per second) for
 520                          * private shapers of the non-leaf nodes on this level.
 521                          * Valid only when private shaper is supported on this
 522                          * level.
 523                          */
 524                         uint64_t shaper_private_rate_max;
 525
 526                         /** Maximum number of shared shapers that any non-leaf
 527                          * node on this level can be part of. The value of zero
 528                          * indicates that shared shapers are not supported by
 529                          * the non-leaf nodes on this level. When non-zero, it
 530                          * indicates there is at least one non-leaf node on this
 531                          * level that meets this condition, which may not be the
 532                          * case for all the non-leaf nodes on this level.
 533                          */
 534                         uint32_t shaper_shared_n_max;
 535
 536                         /** Maximum number of children nodes. This parameter
 537                          * indicates that there is at least one non-leaf node on
 538                          * this level that can be configured with this many
 539                          * children nodes, which might not be true for all the
 540                          * non-leaf nodes on this level.
 541                          */
 542                         uint32_t sched_n_children_max;
 543
 544                         /** Maximum number of supported priority levels. This
 545                          * parameter indicates that there is at least one
 546                          * non-leaf node on this level that can be configured
 547                          * with this many priority levels for managing its
 548                          * children nodes, which might not be true for all the
 549                          * non-leaf nodes on this level. The value of zero is
 550                          * invalid. The value of 1 indicates that only priority
 551                          * 0 is supported, which essentially means that Strict
 552                          * Priority (SP) algorithm is not supported on this
 553                          * level.
 554                          */
 555                         uint32_t sched_sp_n_priorities_max;
 556
 557                         /** Maximum number of sibling nodes that can have the
 558                          * same priority at any given time, i.e. maximum size of
 559                          * the WFQ sibling node group. This parameter indicates
 560                          * there is at least one non-leaf node on this level
 561                          * that meets this condition, which may not be true for
 562                          * all the non-leaf nodes on this level. The value of
 563                          * zero is invalid. The value of 1 indicates that WFQ
 564                          * algorithm is not supported on this level. The maximum
 565                          * value is *sched_n_children_max*.
 566                          */
 567                         uint32_t sched_wfq_n_children_per_group_max;
 568
 569                         /** Maximum number of priority levels that can have
 570                          * more than one child node at any given time, i.e.
 571                          * maximum number of WFQ sibling node groups that
 572                          * have two or more members. This parameter indicates
 573                          * there is at least one non-leaf node on this level
 574                          * that meets this condition, which might not be true
 575                          * for all the non-leaf nodes. The value of zero states
 576                          * that WFQ algorithm is not supported on this level.
 577                          * The value of 1 indicates that
 578                          * (*sched_sp_n_priorities_max* - 1) priority levels on
 579                          * this level have at most one child node, so there can
 580                          * be only one priority level with two or more sibling
 581                          * nodes making up a WFQ group on this level. The
 582                          * maximum value is:
 583                          * min(floor(*sched_n_children_max* / 2),
 584                          * *sched_sp_n_priorities_max*).
 585                          */
 586                         uint32_t sched_wfq_n_groups_max;
 587
 588                         /** Maximum WFQ weight. The value of 1 indicates that
 589                          * all sibling nodes on this level with same priority
 590                          * have the same WFQ weight, so on this level WFQ is
 591                          * reduced to FQ.
 592                          */
 593                         uint32_t sched_wfq_weight_max;
 594
 595                         /** Mask of statistics counter types supported by the
 596                          * non-leaf nodes on this level. Every supported
 597                          * statistics counter type is supported by at least one
 598                          * non-leaf node on this level, which may not be true
 599                          * for all the non-leaf nodes on this level.
 600                          * @see enum rte_tm_stats_type
 601                          */
 602                         uint64_t stats_mask;
 603                 } nonleaf;
 604
 605                 /** Items valid only for the leaf nodes on this level. */
 606                 struct {
 607                         /** Private shaper support. When non-zero, it indicates
 608                          * there is at least one leaf node on this level with
 609                          * private shaper support, which may not be the case for
 610                          * all the leaf nodes on this level.
 611                          */
 612                         int shaper_private_supported;
 613
 614                         /** Dual rate support for private shaper. Valid only
 615                          * when private shaper is supported for the leaf nodes
 616                          * on this level. When non-zero, it indicates there is
 617                          * at least one leaf node on this level with dual rate
 618                          * private shaper support, which may not be the case for
 619                          * all the leaf nodes on this level.
 620                          */
 621                         int shaper_private_dual_rate_supported;
 622
 623                         /** Minimum committed/peak rate (bytes per second) for
 624                          * private shapers of the leaf nodes of this level.
 625                          * Valid only when private shaper is supported for the
 626                          * leaf nodes on this level.
 627                          */
 628                         uint64_t shaper_private_rate_min;
 629
 630                         /** Maximum committed/peak rate (bytes per second) for
 631                          * private shapers of the leaf nodes on this level.
 632                          * Valid only when private shaper is supported for the
 633                          * leaf nodes on this level.
 634                          */
 635                         uint64_t shaper_private_rate_max;
 636
 637                         /** Maximum number of shared shapers that any leaf node
 638                          * on this level can be part of. The value of zero
 639                          * indicates that shared shapers are not supported by
 640                          * the leaf nodes on this level. When non-zero, it
 641                          * indicates there is at least one leaf node on this
 642                          * level that meets this condition, which may not be the
 643                          * case for all the leaf nodes on this level.
 644                          */
 645                         uint32_t shaper_shared_n_max;
 646
 647                         /** WRED packet mode support. When non-zero, this
 648                          * parameter indicates that there is atleast one leaf
 649                          * node on this level that supports the WRED packet
 650                          * mode, which might not be true for all the leaf
 651                          * nodes. In packet mode, the WRED thresholds specify
 652                          * the queue length in packets, as opposed to bytes.
 653                          */
 654                         int cman_wred_packet_mode_supported;
 655
 656                         /** WRED byte mode support. When non-zero, this
 657                          * parameter indicates that there is atleast one leaf
 658                          * node on this level that supports the WRED byte mode,
 659                          * which might not be true for all the leaf nodes. In
 660                          * byte mode, the WRED thresholds specify the queue
 661                          * length in bytes, as opposed to packets.
 662                          */
 663                         int cman_wred_byte_mode_supported;
 664
 665                         /** Head drop algorithm support. When non-zero, this
 666                          * parameter indicates that there is at least one leaf
 667                          * node on this level that supports the head drop
 668                          * algorithm, which might not be true for all the leaf
 669                          * nodes on this level.
 670                          */
 671                         int cman_head_drop_supported;
 672
 673                         /** Private WRED context support. When non-zero, it
 674                          * indicates there is at least one node on this level
 675                          * with private WRED context support, which may not be
 676                          * true for all the leaf nodes on this level.
 677                          */
 678                         int cman_wred_context_private_supported;
 679
 680                         /** Maximum number of shared WRED contexts that any
 681                          * leaf node on this level can be part of. The value of
 682                          * zero indicates that shared WRED contexts are not
 683                          * supported by the leaf nodes on this level. When
 684                          * non-zero, it indicates there is at least one leaf
 685                          * node on this level that meets this condition, which
 686                          * may not be the case for all the leaf nodes on this
 687                          * level.
 688                          */
 689                         uint32_t cman_wred_context_shared_n_max;
 690
 691                         /** Mask of statistics counter types supported by the
 692                          * leaf nodes on this level. Every supported statistics
 693                          * counter type is supported by at least one leaf node
 694                          * on this level, which may not be true for all the leaf
 695                          * nodes on this level.
 696                          * @see enum rte_tm_stats_type
 697                          */
 698                         uint64_t stats_mask;
 699                 } leaf;
 700         };
 701 };
 702
 703 /**
 704  * Traffic manager node capabilities
 705  */
 706 struct rte_tm_node_capabilities {
 707         /** Private shaper support for the current node. */
 708         int shaper_private_supported;
 709
 710         /** Dual rate shaping support for private shaper of current node.
 711          * Valid only when private shaper is supported by the current node.
 712          */
 713         int shaper_private_dual_rate_supported;
 714
 715         /** Minimum committed/peak rate (bytes per second) for private
 716          * shaper of current node. Valid only when private shaper is supported
 717          * by the current node.
 718          */
 719         uint64_t shaper_private_rate_min;
 720
 721         /** Maximum committed/peak rate (bytes per second) for private
 722          * shaper of current node. Valid only when private shaper is supported
 723          * by the current node.
 724          */
 725         uint64_t shaper_private_rate_max;
 726
 727         /** Maximum number of shared shapers the current node can be part of.
 728          * The value of zero indicates that shared shapers are not supported by
 729          * the current node.
 730          */
 731         uint32_t shaper_shared_n_max;
 732
 733         RTE_STD_C11
 734         union {
 735                 /** Items valid only for non-leaf nodes. */
 736                 struct {
 737                         /** Maximum number of children nodes. */
 738                         uint32_t sched_n_children_max;
 739
 740                         /** Maximum number of supported priority levels. The
 741                          * value of zero is invalid. The value of 1 indicates
 742                          * that only priority 0 is supported, which essentially
 743                          * means that Strict Priority (SP) algorithm is not
 744                          * supported.
 745                          */
 746                         uint32_t sched_sp_n_priorities_max;
 747
 748                         /** Maximum number of sibling nodes that can have the
 749                          * same priority at any given time, i.e. maximum size
 750                          * of the WFQ sibling node group. The value of zero
 751                          * is invalid. The value of 1 indicates that WFQ
 752                          * algorithm is not supported. The maximum value is
 753                          * *sched_n_children_max*.
 754                          */
 755                         uint32_t sched_wfq_n_children_per_group_max;
 756
 757                         /** Maximum number of priority levels that can have
 758                          * more than one child node at any given time, i.e.
 759                          * maximum number of WFQ sibling node groups that have
 760                          * two or more members. The value of zero states that
 761                          * WFQ algorithm is not supported. The value of 1
 762                          * indicates that (*sched_sp_n_priorities_max* - 1)
 763                          * priority levels have at most one child node, so there
 764                          * can be only one priority level with two or more
 765                          * sibling nodes making up a WFQ group. The maximum
 766                          * value is: min(floor(*sched_n_children_max* / 2),
 767                          * *sched_sp_n_priorities_max*).
 768                          */
 769                         uint32_t sched_wfq_n_groups_max;
 770
 771                         /** Maximum WFQ weight. The value of 1 indicates that
 772                          * all sibling nodes with same priority have the same
 773                          * WFQ weight, so WFQ is reduced to FQ.
 774                          */
 775                         uint32_t sched_wfq_weight_max;
 776                 } nonleaf;
 777
 778                 /** Items valid only for leaf nodes. */
 779                 struct {
 780                         /** WRED packet mode support for current node. */
 781                         int cman_wred_packet_mode_supported;
 782
 783                         /** WRED byte mode support for current node. */
 784                         int cman_wred_byte_mode_supported;
 785
 786                         /** Head drop algorithm support for current node. */
 787                         int cman_head_drop_supported;
 788
 789                         /** Private WRED context support for current node. */
 790                         int cman_wred_context_private_supported;
 791
 792                         /** Maximum number of shared WRED contexts the current
 793                          * node can be part of. The value of zero indicates that
 794                          * shared WRED contexts are not supported by the current
 795                          * node.
 796                          */
 797                         uint32_t cman_wred_context_shared_n_max;
 798                 } leaf;
 799         };
 800
 801         /** Mask of statistics counter types supported by the current node.
 802          * @see enum rte_tm_stats_type
 803          */
 804         uint64_t stats_mask;
 805 };
 806
 807 /**
 808  * Congestion management (CMAN) mode
 809  *
 810  * This is used for controlling the admission of packets into a packet queue or
 811  * group of packet queues on congestion. On request of writing a new packet
 812  * into the current queue while the queue is full, the *tail drop* algorithm
 813  * drops the new packet while leaving the queue unmodified, as opposed to *head
 814  * drop* algorithm, which drops the packet at the head of the queue (the oldest
 815  * packet waiting in the queue) and admits the new packet at the tail of the
 816  * queue.
 817  *
 818  * The *Random Early Detection (RED)* algorithm works by proactively dropping
 819  * more and more input packets as the queue occupancy builds up. When the queue
 820  * is full or almost full, RED effectively works as *tail drop*. The *Weighted
 821  * RED* algorithm uses a separate set of RED thresholds for each packet color.
 822  */
 823 enum rte_tm_cman_mode {
 824         RTE_TM_CMAN_TAIL_DROP = 0, /**< Tail drop */
 825         RTE_TM_CMAN_HEAD_DROP, /**< Head drop */
 826         RTE_TM_CMAN_WRED, /**< Weighted Random Early Detection (WRED) */
 827 };
 828
 829 /**
 830  * Random Early Detection (RED) profile
 831  */
 832 struct rte_tm_red_params {
 833         /** Minimum queue threshold */
 834         uint64_t min_th;
 835
 836         /** Maximum queue threshold */
 837         uint64_t max_th;
 838
 839         /** Inverse of packet marking probability maximum value (maxp), i.e.
 840          * maxp_inv = 1 / maxp
 841          */
 842         uint16_t maxp_inv;
 843
 844         /** Negated log2 of queue weight (wq), i.e. wq = 1 / (2 ^ wq_log2) */
 845         uint16_t wq_log2;
 846 };
 847
 848 /**
 849  * Weighted RED (WRED) profile
 850  *
 851  * Multiple WRED contexts can share the same WRED profile. Each leaf node with
 852  * WRED enabled as its congestion management mode has zero or one private WRED
 853  * context (only one leaf node using it) and/or zero, one or several shared
 854  * WRED contexts (multiple leaf nodes use the same WRED context). A private
 855  * WRED context is used to perform congestion management for a single leaf
 856  * node, while a shared WRED context is used to perform congestion management
 857  * for a group of leaf nodes.
 858  *
 859  * @see struct rte_tm_capabilities::cman_wred_packet_mode_supported
 860  * @see struct rte_tm_capabilities::cman_wred_byte_mode_supported
 861  */
 862 struct rte_tm_wred_params {
 863         /** One set of RED parameters per packet color */
 864         struct rte_tm_red_params red_params[RTE_TM_COLORS];
 865
 866         /** When non-zero, the *min_th* and *max_th* thresholds are specified
 867          * in packets (WRED packet mode). When zero, the *min_th* and *max_th*
 868          * thresholds are specified in bytes (WRED byte mode)
 869          */
 870         int packet_mode;
 871 };
 872
 873 /**
 874  * Token bucket
 875  */
 876 struct rte_tm_token_bucket {
 877         /** Token bucket rate (bytes per second) */
 878         uint64_t rate;
 879
 880         /** Token bucket size (bytes), a.k.a. max burst size */
 881         uint64_t size;
 882 };
 883
 884 /**
 885  * Shaper (rate limiter) profile
 886  *
 887  * Multiple shaper instances can share the same shaper profile. Each node has
 888  * zero or one private shaper (only one node using it) and/or zero, one or
 889  * several shared shapers (multiple nodes use the same shaper instance).
 890  * A private shaper is used to perform traffic shaping for a single node, while
 891  * a shared shaper is used to perform traffic shaping for a group of nodes.
 892  *
 893  * Single rate shapers use a single token bucket. A single rate shaper can be
 894  * configured by setting the rate of the committed bucket to zero, which
 895  * effectively disables this bucket. The peak bucket is used to limit the rate
 896  * and the burst size for the current shaper.
 897  *
 898  * Dual rate shapers use both the committed and the peak token buckets. The
 899  * rate of the peak bucket has to be bigger than zero, as well as greater than
 900  * or equal to the rate of the committed bucket.
 901  */
 902 struct rte_tm_shaper_params {
 903         /** Committed token bucket */
 904         struct rte_tm_token_bucket committed;
 905
 906         /** Peak token bucket */
 907         struct rte_tm_token_bucket peak;
 908
 909         /** Signed value to be added to the length of each packet for the
 910          * purpose of shaping. Can be used to correct the packet length with
 911          * the framing overhead bytes that are also consumed on the wire (e.g.
 912          * RTE_TM_ETH_FRAMING_OVERHEAD_FCS).
 913          */
 914         int32_t pkt_length_adjust;
 915 };
 916
 917 /**
 918  * Node parameters
 919  *
 920  * Each non-leaf node has multiple inputs (its children nodes) and single output
 921  * (which is input to its parent node). It arbitrates its inputs using Strict
 922  * Priority (SP) and Weighted Fair Queuing (WFQ) algorithms to schedule input
 923  * packets to its output while observing its shaping (rate limiting)
 924  * constraints.
 925  *
 926  * Algorithms such as Weighted Round Robin (WRR), Byte-level WRR, Deficit WRR
 927  * (DWRR), etc. are considered approximations of the WFQ ideal and are
 928  * assimilated to WFQ, although an associated implementation-dependent trade-off
 929  * on accuracy, performance and resource usage might exist.
 930  *
 931  * Children nodes with different priorities are scheduled using the SP algorithm
 932  * based on their priority, with zero (0) as the highest priority. Children with
 933  * the same priority are scheduled using the WFQ algorithm according to their
 934  * weights. The WFQ weight of a given child node is relative to the sum of the
 935  * weights of all its sibling nodes that have the same priority, with one (1) as
 936  * the lowest weight. For each SP priority, the WFQ weight mode can be set as
 937  * either byte-based or packet-based.
 938  *
 939  * Each leaf node sits on top of a TX queue of the current Ethernet port. Hence,
 940  * the leaf nodes are predefined, with their node IDs set to 0 .. (N-1), where N
 941  * is the number of TX queues configured for the current Ethernet port. The
 942  * non-leaf nodes have their IDs generated by the application.
 943  */
 944 struct rte_tm_node_params {
 945         /** Shaper profile for the private shaper. The absence of the private
 946          * shaper for the current node is indicated by setting this parameter
 947          * to RTE_TM_SHAPER_PROFILE_ID_NONE.
 948          */
 949         uint32_t shaper_profile_id;
 950
 951         /** User allocated array of valid shared shaper IDs. */
 952         uint32_t *shared_shaper_id;
 953
 954         /** Number of shared shaper IDs in the *shared_shaper_id* array. */
 955         uint32_t n_shared_shapers;
 956
 957         RTE_STD_C11
 958         union {
 959                 /** Parameters only valid for non-leaf nodes. */
 960                 struct {
 961                         /** WFQ weight mode for each SP priority. When NULL, it
 962                          * indicates that WFQ is to be used for all priorities.
 963                          * When non-NULL, it points to a pre-allocated array of
 964                          * *n_sp_priorities* values, with non-zero value for
 965                          * byte-mode and zero for packet-mode.
 966                          */
 967                         int *wfq_weight_mode;
 968
 969                         /** Number of SP priorities. */
 970                         uint32_t n_sp_priorities;
 971                 } nonleaf;
 972
 973                 /** Parameters only valid for leaf nodes. */
 974                 struct {
 975                         /** Congestion management mode */
 976                         enum rte_tm_cman_mode cman;
 977
 978                         /** WRED parameters (only valid when *cman* is set to
 979                          * WRED).
 980                          */
 981                         struct {
 982                                 /** WRED profile for private WRED context. The
 983                                  * absence of a private WRED context for the
 984                                  * current leaf node is indicated by value
 985                                  * RTE_TM_WRED_PROFILE_ID_NONE.
 986                                  */
 987                                 uint32_t wred_profile_id;
 988
 989                                 /** User allocated array of shared WRED context
 990                                  * IDs. When set to NULL, it indicates that the
 991                                  * current leaf node should not currently be
 992                                  * part of any shared WRED contexts.
 993                                  */
 994                                 uint32_t *shared_wred_context_id;
 995
 996                                 /** Number of elements in the
 997                                  * *shared_wred_context_id* array. Only valid
 998                                  * when *shared_wred_context_id* is non-NULL,
 999                                  * in which case it should be non-zero.
1000                                  */
1001                                 uint32_t n_shared_wred_contexts;
1002                         } wred;
1003                 } leaf;
1004         };
1005
1006         /** Mask of statistics counter types to be enabled for this node. This
1007          * needs to be a subset of the statistics counter types available for
1008          * the current node. Any statistics counter type not included in this
1009          * set is to be disabled for the current node.
1010          * @see enum rte_tm_stats_type
1011          */
1012         uint64_t stats_mask;
1013 };
1014
1015 /**
1016  * Verbose error types.
1017  *
1018  * Most of them provide the type of the object referenced by struct
1019  * rte_tm_error::cause.
1020  */
1021 enum rte_tm_error_type {
1022         RTE_TM_ERROR_TYPE_NONE, /**< No error. */
1023         RTE_TM_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
1024         RTE_TM_ERROR_TYPE_CAPABILITIES,
1025         RTE_TM_ERROR_TYPE_LEVEL_ID,
1026         RTE_TM_ERROR_TYPE_WRED_PROFILE,
1027         RTE_TM_ERROR_TYPE_WRED_PROFILE_GREEN,
1028         RTE_TM_ERROR_TYPE_WRED_PROFILE_YELLOW,
1029         RTE_TM_ERROR_TYPE_WRED_PROFILE_RED,
1030         RTE_TM_ERROR_TYPE_WRED_PROFILE_ID,
1031         RTE_TM_ERROR_TYPE_SHARED_WRED_CONTEXT_ID,
1032         RTE_TM_ERROR_TYPE_SHAPER_PROFILE,
1033         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_COMMITTED_RATE,
1034         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_COMMITTED_SIZE,
1035         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PEAK_RATE,
1036         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PEAK_SIZE,
1037         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PKT_ADJUST_LEN,
1038         RTE_TM_ERROR_TYPE_SHAPER_PROFILE_ID,
1039         RTE_TM_ERROR_TYPE_SHARED_SHAPER_ID,
1040         RTE_TM_ERROR_TYPE_NODE_PARENT_NODE_ID,
1041         RTE_TM_ERROR_TYPE_NODE_PRIORITY,
1042         RTE_TM_ERROR_TYPE_NODE_WEIGHT,
1043         RTE_TM_ERROR_TYPE_NODE_PARAMS,
1044         RTE_TM_ERROR_TYPE_NODE_PARAMS_SHAPER_PROFILE_ID,
1045         RTE_TM_ERROR_TYPE_NODE_PARAMS_SHARED_SHAPER_ID,
1046         RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SHARED_SHAPERS,
1047         RTE_TM_ERROR_TYPE_NODE_PARAMS_WFQ_WEIGHT_MODE,
1048         RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SP_PRIORITIES,
1049         RTE_TM_ERROR_TYPE_NODE_PARAMS_CMAN,
1050         RTE_TM_ERROR_TYPE_NODE_PARAMS_WRED_PROFILE_ID,
1051         RTE_TM_ERROR_TYPE_NODE_PARAMS_SHARED_WRED_CONTEXT_ID,
1052         RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SHARED_WRED_CONTEXTS,
1053         RTE_TM_ERROR_TYPE_NODE_PARAMS_STATS,
1054         RTE_TM_ERROR_TYPE_NODE_ID,
1055 };
1056
1057 /**
1058  * Verbose error structure definition.
1059  *
1060  * This object is normally allocated by applications and set by PMDs, the
1061  * message points to a constant string which does not need to be freed by
1062  * the application, however its pointer can be considered valid only as long
1063  * as its associated DPDK port remains configured. Closing the underlying
1064  * device or unloading the PMD invalidates it.
1065  *
1066  * Both cause and message may be NULL regardless of the error type.
1067  */
1068 struct rte_tm_error {
1069         enum rte_tm_error_type type; /**< Cause field and error type. */
1070         const void *cause; /**< Object responsible for the error. */
1071         const char *message; /**< Human-readable error message. */
1072 };
1073
1074 /**
1075  * Traffic manager get number of leaf nodes
1076  *
1077  * Each leaf node sits on on top of a TX queue of the current Ethernet port.
1078  * Therefore, the set of leaf nodes is predefined, their number is always equal
1079  * to N (where N is the number of TX queues configured for the current port)
1080  * and their IDs are 0 .. (N-1).
1081  *
1082  * @param[in] port_id
1083  *   The port identifier of the Ethernet device.
1084  * @param[out] n_leaf_nodes
1085  *   Number of leaf nodes for the current port.
1086  * @param[out] error
1087  *   Error details. Filled in only on error, when not NULL.
1088  * @return
1089  *   0 on success, non-zero error code otherwise.
1090  */
1091 int
1092 rte_tm_get_number_of_leaf_nodes(uint16_t port_id,
1093         uint32_t *n_leaf_nodes,
1094         struct rte_tm_error *error);
1095
1096 /**
1097  * Traffic manager node ID validate and type (i.e. leaf or non-leaf) get
1098  *
1099  * The leaf nodes have predefined IDs in the range of 0 .. (N-1), where N is
1100  * the number of TX queues of the current Ethernet port. The non-leaf nodes
1101  * have their IDs generated by the application outside of the above range,
1102  * which is reserved for leaf nodes.
1103  *
1104  * @param[in] port_id
1105  *   The port identifier of the Ethernet device.
1106  * @param[in] node_id
1107  *   Node ID value. Needs to be valid.
1108  * @param[out] is_leaf
1109  *   Set to non-zero value when node is leaf and to zero otherwise (non-leaf).
1110  * @param[out] error
1111  *   Error details. Filled in only on error, when not NULL.
1112  * @return
1113  *   0 on success, non-zero error code otherwise.
1114  */
1115 int
1116 rte_tm_node_type_get(uint16_t port_id,
1117         uint32_t node_id,
1118         int *is_leaf,
1119         struct rte_tm_error *error);
1120
1121 /**
1122  * Traffic manager capabilities get
1123  *
1124  * @param[in] port_id
1125  *   The port identifier of the Ethernet device.
1126  * @param[out] cap
1127  *   Traffic manager capabilities. Needs to be pre-allocated and valid.
1128  * @param[out] error
1129  *   Error details. Filled in only on error, when not NULL.
1130  * @return
1131  *   0 on success, non-zero error code otherwise.
1132  */
1133 int
1134 rte_tm_capabilities_get(uint16_t port_id,
1135         struct rte_tm_capabilities *cap,
1136         struct rte_tm_error *error);
1137
1138 /**
1139  * Traffic manager level capabilities get
1140  *
1141  * @param[in] port_id
1142  *   The port identifier of the Ethernet device.
1143  * @param[in] level_id
1144  *   The hierarchy level identifier. The value of 0 identifies the level of the
1145  *   root node.
1146  * @param[out] cap
1147  *   Traffic manager level capabilities. Needs to be pre-allocated and valid.
1148  * @param[out] error
1149  *   Error details. Filled in only on error, when not NULL.
1150  * @return
1151  *   0 on success, non-zero error code otherwise.
1152  */
1153 int
1154 rte_tm_level_capabilities_get(uint16_t port_id,
1155         uint32_t level_id,
1156         struct rte_tm_level_capabilities *cap,
1157         struct rte_tm_error *error);
1158
1159 /**
1160  * Traffic manager node capabilities get
1161  *
1162  * @param[in] port_id
1163  *   The port identifier of the Ethernet device.
1164  * @param[in] node_id
1165  *   Node ID. Needs to be valid.
1166  * @param[out] cap
1167  *   Traffic manager node capabilities. Needs to be pre-allocated and valid.
1168  * @param[out] error
1169  *   Error details. Filled in only on error, when not NULL.
1170  * @return
1171  *   0 on success, non-zero error code otherwise.
1172  */
1173 int
1174 rte_tm_node_capabilities_get(uint16_t port_id,
1175         uint32_t node_id,
1176         struct rte_tm_node_capabilities *cap,
1177         struct rte_tm_error *error);
1178
1179 /**
1180  * Traffic manager WRED profile add
1181  *
1182  * Create a new WRED profile with ID set to *wred_profile_id*. The new profile
1183  * is used to create one or several WRED contexts.
1184  *
1185  * @param[in] port_id
1186  *   The port identifier of the Ethernet device.
1187  * @param[in] wred_profile_id
1188  *   WRED profile ID for the new profile. Needs to be unused.
1189  * @param[in] profile
1190  *   WRED profile parameters. Needs to be pre-allocated and valid.
1191  * @param[out] error
1192  *   Error details. Filled in only on error, when not NULL.
1193  * @return
1194  *   0 on success, non-zero error code otherwise.
1195  *
1196  * @see struct rte_tm_capabilities::cman_wred_context_n_max
1197  */
1198 int
1199 rte_tm_wred_profile_add(uint16_t port_id,
1200         uint32_t wred_profile_id,
1201         struct rte_tm_wred_params *profile,
1202         struct rte_tm_error *error);
1203
1204 /**
1205  * Traffic manager WRED profile delete
1206  *
1207  * Delete an existing WRED profile. This operation fails when there is
1208  * currently at least one user (i.e. WRED context) of this WRED profile.
1209  *
1210  * @param[in] port_id
1211  *   The port identifier of the Ethernet device.
1212  * @param[in] wred_profile_id
1213  *   WRED profile ID. Needs to be the valid.
1214  * @param[out] error
1215  *   Error details. Filled in only on error, when not NULL.
1216  * @return
1217  *   0 on success, non-zero error code otherwise.
1218  *
1219  * @see struct rte_tm_capabilities::cman_wred_context_n_max
1220  */
1221 int
1222 rte_tm_wred_profile_delete(uint16_t port_id,
1223         uint32_t wred_profile_id,
1224         struct rte_tm_error *error);
1225
1226 /**
1227  * Traffic manager shared WRED context add or update
1228  *
1229  * When *shared_wred_context_id* is invalid, a new WRED context with this ID is
1230  * created by using the WRED profile identified by *wred_profile_id*.
1231  *
1232  * When *shared_wred_context_id* is valid, this WRED context is no longer using
1233  * the profile previously assigned to it and is updated to use the profile
1234  * identified by *wred_profile_id*.
1235  *
1236  * A valid shared WRED context can be assigned to several hierarchy leaf nodes
1237  * configured to use WRED as the congestion management mode.
1238  *
1239  * @param[in] port_id
1240  *   The port identifier of the Ethernet device.
1241  * @param[in] shared_wred_context_id
1242  *   Shared WRED context ID
1243  * @param[in] wred_profile_id
1244  *   WRED profile ID. Needs to be the valid.
1245  * @param[out] error
1246  *   Error details. Filled in only on error, when not NULL.
1247  * @return
1248  *   0 on success, non-zero error code otherwise.
1249  *
1250  * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1251  */
1252 int
1253 rte_tm_shared_wred_context_add_update(uint16_t port_id,
1254         uint32_t shared_wred_context_id,
1255         uint32_t wred_profile_id,
1256         struct rte_tm_error *error);
1257
1258 /**
1259  * Traffic manager shared WRED context delete
1260  *
1261  * Delete an existing shared WRED context. This operation fails when there is
1262  * currently at least one user (i.e. hierarchy leaf node) of this shared WRED
1263  * context.
1264  *
1265  * @param[in] port_id
1266  *   The port identifier of the Ethernet device.
1267  * @param[in] shared_wred_context_id
1268  *   Shared WRED context ID. Needs to be the valid.
1269  * @param[out] error
1270  *   Error details. Filled in only on error, when not NULL.
1271  * @return
1272  *   0 on success, non-zero error code otherwise.
1273  *
1274  * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1275  */
1276 int
1277 rte_tm_shared_wred_context_delete(uint16_t port_id,
1278         uint32_t shared_wred_context_id,
1279         struct rte_tm_error *error);
1280
1281 /**
1282  * Traffic manager shaper profile add
1283  *
1284  * Create a new shaper profile with ID set to *shaper_profile_id*. The new
1285  * shaper profile is used to create one or several shapers.
1286  *
1287  * @param[in] port_id
1288  *   The port identifier of the Ethernet device.
1289  * @param[in] shaper_profile_id
1290  *   Shaper profile ID for the new profile. Needs to be unused.
1291  * @param[in] profile
1292  *   Shaper profile parameters. Needs to be pre-allocated and valid.
1293  * @param[out] error
1294  *   Error details. Filled in only on error, when not NULL.
1295  * @return
1296  *   0 on success, non-zero error code otherwise.
1297  *
1298  * @see struct rte_tm_capabilities::shaper_n_max
1299  */
1300 int
1301 rte_tm_shaper_profile_add(uint16_t port_id,
1302         uint32_t shaper_profile_id,
1303         struct rte_tm_shaper_params *profile,
1304         struct rte_tm_error *error);
1305
1306 /**
1307  * Traffic manager shaper profile delete
1308  *
1309  * Delete an existing shaper profile. This operation fails when there is
1310  * currently at least one user (i.e. shaper) of this shaper profile.
1311  *
1312  * @param[in] port_id
1313  *   The port identifier of the Ethernet device.
1314  * @param[in] shaper_profile_id
1315  *   Shaper profile ID. Needs to be the valid.
1316  * @param[out] error
1317  *   Error details. Filled in only on error, when not NULL.
1318  * @return
1319  *   0 on success, non-zero error code otherwise.
1320  *
1321  * @see struct rte_tm_capabilities::shaper_n_max
1322  */
1323 int
1324 rte_tm_shaper_profile_delete(uint16_t port_id,
1325         uint32_t shaper_profile_id,
1326         struct rte_tm_error *error);
1327
1328 /**
1329  * Traffic manager shared shaper add or update
1330  *
1331  * When *shared_shaper_id* is not a valid shared shaper ID, a new shared shaper
1332  * with this ID is created using the shaper profile identified by
1333  * *shaper_profile_id*.
1334  *
1335  * When *shared_shaper_id* is a valid shared shaper ID, this shared shaper is
1336  * no longer using the shaper profile previously assigned to it and is updated
1337  * to use the shaper profile identified by *shaper_profile_id*.
1338  *
1339  * @param[in] port_id
1340  *   The port identifier of the Ethernet device.
1341  * @param[in] shared_shaper_id
1342  *   Shared shaper ID
1343  * @param[in] shaper_profile_id
1344  *   Shaper profile ID. Needs to be the valid.
1345  * @param[out] error
1346  *   Error details. Filled in only on error, when not NULL.
1347  * @return
1348  *   0 on success, non-zero error code otherwise.
1349  *
1350  * @see struct rte_tm_capabilities::shaper_shared_n_max
1351  */
1352 int
1353 rte_tm_shared_shaper_add_update(uint16_t port_id,
1354         uint32_t shared_shaper_id,
1355         uint32_t shaper_profile_id,
1356         struct rte_tm_error *error);
1357
1358 /**
1359  * Traffic manager shared shaper delete
1360  *
1361  * Delete an existing shared shaper. This operation fails when there is
1362  * currently at least one user (i.e. hierarchy node) of this shared shaper.
1363  *
1364  * @param[in] port_id
1365  *   The port identifier of the Ethernet device.
1366  * @param[in] shared_shaper_id
1367  *   Shared shaper ID. Needs to be the valid.
1368  * @param[out] error
1369  *   Error details. Filled in only on error, when not NULL.
1370  * @return
1371  *   0 on success, non-zero error code otherwise.
1372  *
1373  * @see struct rte_tm_capabilities::shaper_shared_n_max
1374  */
1375 int
1376 rte_tm_shared_shaper_delete(uint16_t port_id,
1377         uint32_t shared_shaper_id,
1378         struct rte_tm_error *error);
1379
1380 /**
1381  * Traffic manager node add
1382  *
1383  * Create new node and connect it as child of an existing node. The new node is
1384  * further identified by *node_id*, which needs to be unused by any of the
1385  * existing nodes. The parent node is identified by *parent_node_id*, which
1386  * needs to be the valid ID of an existing non-leaf node. The parent node is
1387  * going to use the provided SP *priority* and WFQ *weight* to schedule its new
1388  * child node.
1389  *
1390  * This function has to be called for both leaf and non-leaf nodes. In the case
1391  * of leaf nodes (i.e. *node_id* is within the range of 0 .. (N-1), with N as
1392  * the number of configured TX queues of the current port), the leaf node is
1393  * configured rather than created (as the set of leaf nodes is predefined) and
1394  * it is also connected as child of an existing node.
1395  *
1396  * The first node that is added becomes the root node and all the nodes that
1397  * are subsequently added have to be added as descendants of the root node. The
1398  * parent of the root node has to be specified as RTE_TM_NODE_ID_NULL and there
1399  * can only be one node with this parent ID (i.e. the root node). Further
1400  * restrictions for root node: needs to be non-leaf, its private shaper profile
1401  * needs to be valid and single rate, cannot use any shared shapers.
1402  *
1403  * When called before rte_tm_hierarchy_commit() invocation, this function is
1404  * typically used to define the initial start-up hierarchy for the port.
1405  * Provided that dynamic hierarchy updates are supported by the current port (as
1406  * advertised in the port capability set), this function can be also called
1407  * after the rte_tm_hierarchy_commit() invocation.
1408  *
1409  * @param[in] port_id
1410  *   The port identifier of the Ethernet device.
1411  * @param[in] node_id
1412  *   Node ID. Needs to be unused by any of the existing nodes.
1413  * @param[in] parent_node_id
1414  *   Parent node ID. Needs to be the valid.
1415  * @param[in] priority
1416  *   Node priority. The highest node priority is zero. Used by the SP algorithm
1417  *   running on the parent of the current node for scheduling this child node.
1418  * @param[in] weight
1419  *   Node weight. The node weight is relative to the weight sum of all siblings
1420  *   that have the same priority. The lowest weight is one. Used by the WFQ
1421  *   algorithm running on the parent of the current node for scheduling this
1422  *   child node.
1423  * @param[in] level_id
1424  *   Level ID that should be met by this node. The hierarchy level of the
1425  *   current node is already fully specified through its parent node (i.e. the
1426  *   level of this node is equal to the level of its parent node plus one),
1427  *   therefore the reason for providing this parameter is to enable the
1428  *   application to perform step-by-step checking of the node level during
1429  *   successive invocations of this function. When not desired, this check can
1430  *   be disabled by assigning value RTE_TM_NODE_LEVEL_ID_ANY to this parameter.
1431  * @param[in] params
1432  *   Node parameters. Needs to be pre-allocated and valid.
1433  * @param[out] error
1434  *   Error details. Filled in only on error, when not NULL.
1435  * @return
1436  *   0 on success, non-zero error code otherwise.
1437  *
1438  * @see rte_tm_hierarchy_commit()
1439  * @see RTE_TM_UPDATE_NODE_ADD_DELETE
1440  * @see RTE_TM_NODE_LEVEL_ID_ANY
1441  * @see struct rte_tm_capabilities
1442  */
1443 int
1444 rte_tm_node_add(uint16_t port_id,
1445         uint32_t node_id,
1446         uint32_t parent_node_id,
1447         uint32_t priority,
1448         uint32_t weight,
1449         uint32_t level_id,
1450         struct rte_tm_node_params *params,
1451         struct rte_tm_error *error);
1452
1453 /**
1454  * Traffic manager node delete
1455  *
1456  * Delete an existing node. This operation fails when this node currently has
1457  * at least one user (i.e. child node).
1458  *
1459  * When called before rte_tm_hierarchy_commit() invocation, this function is
1460  * typically used to define the initial start-up hierarchy for the port.
1461  * Provided that dynamic hierarchy updates are supported by the current port (as
1462  * advertised in the port capability set), this function can be also called
1463  * after the rte_tm_hierarchy_commit() invocation.
1464  *
1465  * @param[in] port_id
1466  *   The port identifier of the Ethernet device.
1467  * @param[in] node_id
1468  *   Node ID. Needs to be valid.
1469  * @param[out] error
1470  *   Error details. Filled in only on error, when not NULL.
1471  * @return
1472  *   0 on success, non-zero error code otherwise.
1473  *
1474  * @see RTE_TM_UPDATE_NODE_ADD_DELETE
1475  */
1476 int
1477 rte_tm_node_delete(uint16_t port_id,
1478         uint32_t node_id,
1479         struct rte_tm_error *error);
1480
1481 /**
1482  * Traffic manager node suspend
1483  *
1484  * Suspend an existing node. While the node is in suspended state, no packet is
1485  * scheduled from this node and its descendants. The node exits the suspended
1486  * state through the node resume operation.
1487  *
1488  * @param[in] port_id
1489  *   The port identifier of the Ethernet device.
1490  * @param[in] node_id
1491  *   Node ID. Needs to be valid.
1492  * @param[out] error
1493  *   Error details. Filled in only on error, when not NULL.
1494  * @return
1495  *   0 on success, non-zero error code otherwise.
1496  *
1497  * @see rte_tm_node_resume()
1498  * @see RTE_TM_UPDATE_NODE_SUSPEND_RESUME
1499  */
1500 int
1501 rte_tm_node_suspend(uint16_t port_id,
1502         uint32_t node_id,
1503         struct rte_tm_error *error);
1504
1505 /**
1506  * Traffic manager node resume
1507  *
1508  * Resume an existing node that is currently in suspended state. The node
1509  * entered the suspended state as result of a previous node suspend operation.
1510  *
1511  * @param[in] port_id
1512  *   The port identifier of the Ethernet device.
1513  * @param[in] node_id
1514  *   Node ID. Needs to be valid.
1515  * @param[out] error
1516  *   Error details. Filled in only on error, when not NULL.
1517  * @return
1518  *   0 on success, non-zero error code otherwise.
1519  *
1520  * @see rte_tm_node_suspend()
1521  * @see RTE_TM_UPDATE_NODE_SUSPEND_RESUME
1522  */
1523 int
1524 rte_tm_node_resume(uint16_t port_id,
1525         uint32_t node_id,
1526         struct rte_tm_error *error);
1527
1528 /**
1529  * Traffic manager hierarchy commit
1530  *
1531  * This function is called during the port initialization phase (before the
1532  * Ethernet port is started) to freeze the start-up hierarchy.
1533  *
1534  * This function typically performs the following steps:
1535  *    a) It validates the start-up hierarchy that was previously defined for the
1536  *       current port through successive rte_tm_node_add() invocations;
1537  *    b) Assuming successful validation, it performs all the necessary port
1538  *       specific configuration operations to install the specified hierarchy on
1539  *       the current port, with immediate effect once the port is started.
1540  *
1541  * This function fails when the currently configured hierarchy is not supported
1542  * by the Ethernet port, in which case the user can abort or try out another
1543  * hierarchy configuration (e.g. a hierarchy with less leaf nodes), which can be
1544  * build from scratch (when *clear_on_fail* is enabled) or by modifying the
1545  * existing hierarchy configuration (when *clear_on_fail* is disabled).
1546  *
1547  * Note that this function can still fail due to other causes (e.g. not enough
1548  * memory available in the system, etc), even though the specified hierarchy is
1549  * supported in principle by the current port.
1550  *
1551  * @param[in] port_id
1552  *   The port identifier of the Ethernet device.
1553  * @param[in] clear_on_fail
1554  *   On function call failure, hierarchy is cleared when this parameter is
1555  *   non-zero and preserved when this parameter is equal to zero.
1556  * @param[out] error
1557  *   Error details. Filled in only on error, when not NULL.
1558  * @return
1559  *   0 on success, non-zero error code otherwise.
1560  *
1561  * @see rte_tm_node_add()
1562  * @see rte_tm_node_delete()
1563  */
1564 int
1565 rte_tm_hierarchy_commit(uint16_t port_id,
1566         int clear_on_fail,
1567         struct rte_tm_error *error);
1568
1569 /**
1570  * Traffic manager node parent update
1571  *
1572  * This function may be used to move a node and its children to a different
1573  * parent.  Additionally, if the new parent is the same as the current parent,
1574  * this function will update the priority/weight of an existing node.
1575  *
1576  * Restriction for root node: its parent cannot be changed.
1577  *
1578  * This function can only be called after the rte_tm_hierarchy_commit()
1579  * invocation. Its success depends on the port support for this operation, as
1580  * advertised through the port capability set.
1581  *
1582  * @param[in] port_id
1583  *   The port identifier of the Ethernet device.
1584  * @param[in] node_id
1585  *   Node ID. Needs to be valid.
1586  * @param[in] parent_node_id
1587  *   Node ID for the new parent. Needs to be valid.
1588  * @param[in] priority
1589  *   Node priority. The highest node priority is zero. Used by the SP algorithm
1590  *   running on the parent of the current node for scheduling this child node.
1591  * @param[in] weight
1592  *   Node weight. The node weight is relative to the weight sum of all siblings
1593  *   that have the same priority. The lowest weight is zero. Used by the WFQ
1594  *   algorithm running on the parent of the current node for scheduling this
1595  *   child node.
1596  * @param[out] error
1597  *   Error details. Filled in only on error, when not NULL.
1598  * @return
1599  *   0 on success, non-zero error code otherwise.
1600  *
1601  * @see RTE_TM_UPDATE_NODE_PARENT_KEEP_LEVEL
1602  * @see RTE_TM_UPDATE_NODE_PARENT_CHANGE_LEVEL
1603  */
1604 int
1605 rte_tm_node_parent_update(uint16_t port_id,
1606         uint32_t node_id,
1607         uint32_t parent_node_id,
1608         uint32_t priority,
1609         uint32_t weight,
1610         struct rte_tm_error *error);
1611
1612 /**
1613  * Traffic manager node private shaper update
1614  *
1615  * Restriction for the root node: its private shaper profile needs to be valid
1616  * and single rate.
1617  *
1618  * @param[in] port_id
1619  *   The port identifier of the Ethernet device.
1620  * @param[in] node_id
1621  *   Node ID. Needs to be valid.
1622  * @param[in] shaper_profile_id
1623  *   Shaper profile ID for the private shaper of the current node. Needs to be
1624  *   either valid shaper profile ID or RTE_TM_SHAPER_PROFILE_ID_NONE, with
1625  *   the latter disabling the private shaper of the current node.
1626  * @param[out] error
1627  *   Error details. Filled in only on error, when not NULL.
1628  * @return
1629  *   0 on success, non-zero error code otherwise.
1630  *
1631  * @see struct rte_tm_capabilities::shaper_private_n_max
1632  */
1633 int
1634 rte_tm_node_shaper_update(uint16_t port_id,
1635         uint32_t node_id,
1636         uint32_t shaper_profile_id,
1637         struct rte_tm_error *error);
1638
1639 /**
1640  * Traffic manager node shared shapers update
1641  *
1642  * Restriction for root node: cannot use any shared rate shapers.
1643  *
1644  * @param[in] port_id
1645  *   The port identifier of the Ethernet device.
1646  * @param[in] node_id
1647  *   Node ID. Needs to be valid.
1648  * @param[in] shared_shaper_id
1649  *   Shared shaper ID. Needs to be valid.
1650  * @param[in] add
1651  *   Set to non-zero value to add this shared shaper to current node or to zero
1652  *   to delete this shared shaper from current node.
1653  * @param[out] error
1654  *   Error details. Filled in only on error, when not NULL.
1655  * @return
1656  *   0 on success, non-zero error code otherwise.
1657  *
1658  * @see struct rte_tm_capabilities::shaper_shared_n_max
1659  */
1660 int
1661 rte_tm_node_shared_shaper_update(uint16_t port_id,
1662         uint32_t node_id,
1663         uint32_t shared_shaper_id,
1664         int add,
1665         struct rte_tm_error *error);
1666
1667 /**
1668  * Traffic manager node enabled statistics counters update
1669  *
1670  * @param[in] port_id
1671  *   The port identifier of the Ethernet device.
1672  * @param[in] node_id
1673  *   Node ID. Needs to be valid.
1674  * @param[in] stats_mask
1675  *   Mask of statistics counter types to be enabled for the current node. This
1676  *   needs to be a subset of the statistics counter types available for the
1677  *   current node. Any statistics counter type not included in this set is to
1678  *   be disabled for the current node.
1679  * @param[out] error
1680  *   Error details. Filled in only on error, when not NULL.
1681  * @return
1682  *   0 on success, non-zero error code otherwise.
1683  *
1684  * @see enum rte_tm_stats_type
1685  * @see RTE_TM_UPDATE_NODE_STATS
1686  */
1687 int
1688 rte_tm_node_stats_update(uint16_t port_id,
1689         uint32_t node_id,
1690         uint64_t stats_mask,
1691         struct rte_tm_error *error);
1692
1693 /**
1694  * Traffic manager node WFQ weight mode update
1695  *
1696  * @param[in] port_id
1697  *   The port identifier of the Ethernet device.
1698  * @param[in] node_id
1699  *   Node ID. Needs to be valid non-leaf node ID.
1700  * @param[in] wfq_weight_mode
1701  *   WFQ weight mode for each SP priority. When NULL, it indicates that WFQ is
1702  *   to be used for all priorities. When non-NULL, it points to a pre-allocated
1703  *   array of *n_sp_priorities* values, with non-zero value for byte-mode and
1704  *   zero for packet-mode.
1705  * @param[in] n_sp_priorities
1706  *   Number of SP priorities.
1707  * @param[out] error
1708  *   Error details. Filled in only on error, when not NULL.
1709  * @return
1710  *   0 on success, non-zero error code otherwise.
1711  *
1712  * @see RTE_TM_UPDATE_NODE_WFQ_WEIGHT_MODE
1713  * @see RTE_TM_UPDATE_NODE_N_SP_PRIORITIES
1714  */
1715 int
1716 rte_tm_node_wfq_weight_mode_update(uint16_t port_id,
1717         uint32_t node_id,
1718         int *wfq_weight_mode,
1719         uint32_t n_sp_priorities,
1720         struct rte_tm_error *error);
1721
1722 /**
1723  * Traffic manager node congestion management mode update
1724  *
1725  * @param[in] port_id
1726  *   The port identifier of the Ethernet device.
1727  * @param[in] node_id
1728  *   Node ID. Needs to be valid leaf node ID.
1729  * @param[in] cman
1730  *   Congestion management mode.
1731  * @param[out] error
1732  *   Error details. Filled in only on error, when not NULL.
1733  * @return
1734  *   0 on success, non-zero error code otherwise.
1735  *
1736  * @see RTE_TM_UPDATE_NODE_CMAN
1737  */
1738 int
1739 rte_tm_node_cman_update(uint16_t port_id,
1740         uint32_t node_id,
1741         enum rte_tm_cman_mode cman,
1742         struct rte_tm_error *error);
1743
1744 /**
1745  * Traffic manager node private WRED context update
1746  *
1747  * @param[in] port_id
1748  *   The port identifier of the Ethernet device.
1749  * @param[in] node_id
1750  *   Node ID. Needs to be valid leaf node ID.
1751  * @param[in] wred_profile_id
1752  *   WRED profile ID for the private WRED context of the current node. Needs to
1753  *   be either valid WRED profile ID or RTE_TM_WRED_PROFILE_ID_NONE, with the
1754  *   latter disabling the private WRED context of the current node.
1755  * @param[out] error
1756  *   Error details. Filled in only on error, when not NULL.
1757  * @return
1758  *   0 on success, non-zero error code otherwise.
1759   *
1760  * @see struct rte_tm_capabilities::cman_wred_context_private_n_max
1761 */
1762 int
1763 rte_tm_node_wred_context_update(uint16_t port_id,
1764         uint32_t node_id,
1765         uint32_t wred_profile_id,
1766         struct rte_tm_error *error);
1767
1768 /**
1769  * Traffic manager node shared WRED context update
1770  *
1771  * @param[in] port_id
1772  *   The port identifier of the Ethernet device.
1773  * @param[in] node_id
1774  *   Node ID. Needs to be valid leaf node ID.
1775  * @param[in] shared_wred_context_id
1776  *   Shared WRED context ID. Needs to be valid.
1777  * @param[in] add
1778  *   Set to non-zero value to add this shared WRED context to current node or
1779  *   to zero to delete this shared WRED context from current node.
1780  * @param[out] error
1781  *   Error details. Filled in only on error, when not NULL.
1782  * @return
1783  *   0 on success, non-zero error code otherwise.
1784  *
1785  * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1786  */
1787 int
1788 rte_tm_node_shared_wred_context_update(uint16_t port_id,
1789         uint32_t node_id,
1790         uint32_t shared_wred_context_id,
1791         int add,
1792         struct rte_tm_error *error);
1793
1794 /**
1795  * Traffic manager node statistics counters read
1796  *
1797  * @param[in] port_id
1798  *   The port identifier of the Ethernet device.
1799  * @param[in] node_id
1800  *   Node ID. Needs to be valid.
1801  * @param[out] stats
1802  *   When non-NULL, it contains the current value for the statistics counters
1803  *   enabled for the current node.
1804  * @param[out] stats_mask
1805  *   When non-NULL, it contains the mask of statistics counter types that are
1806  *   currently enabled for this node, indicating which of the counters
1807  *   retrieved with the *stats* structure are valid.
1808  * @param[in] clear
1809  *   When this parameter has a non-zero value, the statistics counters are
1810  *   cleared (i.e. set to zero) immediately after they have been read,
1811  *   otherwise the statistics counters are left untouched.
1812  * @param[out] error
1813  *   Error details. Filled in only on error, when not NULL.
1814  * @return
1815  *   0 on success, non-zero error code otherwise.
1816  *
1817  * @see enum rte_tm_stats_type
1818  */
1819 int
1820 rte_tm_node_stats_read(uint16_t port_id,
1821         uint32_t node_id,
1822         struct rte_tm_node_stats *stats,
1823         uint64_t *stats_mask,
1824         int clear,
1825         struct rte_tm_error *error);
1826
1827 /**
1828  * Traffic manager packet marking - VLAN DEI (IEEE 802.1Q)
1829  *
1830  * IEEE 802.1p maps the traffic class to the VLAN Priority Code Point (PCP)
1831  * field (3 bits), while IEEE 802.1q maps the drop priority to the VLAN Drop
1832  * Eligible Indicator (DEI) field (1 bit), which was previously named Canonical
1833  * Format Indicator (CFI).
1834  *
1835  * All VLAN frames of a given color get their DEI bit set if marking is enabled
1836  * for this color; otherwise, their DEI bit is left as is (either set or not).
1837  *
1838  * @param[in] port_id
1839  *   The port identifier of the Ethernet device.
1840  * @param[in] mark_green
1841  *   Set to non-zero value to enable marking of green packets and to zero to
1842  *   disable it.
1843  * @param[in] mark_yellow
1844  *   Set to non-zero value to enable marking of yellow packets and to zero to
1845  *   disable it.
1846  * @param[in] mark_red
1847  *   Set to non-zero value to enable marking of red packets and to zero to
1848  *   disable it.
1849  * @param[out] error
1850  *   Error details. Filled in only on error, when not NULL.
1851  * @return
1852  *   0 on success, non-zero error code otherwise.
1853  *
1854  * @see struct rte_tm_capabilities::mark_vlan_dei_supported
1855  */
1856 int
1857 rte_tm_mark_vlan_dei(uint16_t port_id,
1858         int mark_green,
1859         int mark_yellow,
1860         int mark_red,
1861         struct rte_tm_error *error);
1862
1863 /**
1864  * Traffic manager packet marking - IPv4 / IPv6 ECN (IETF RFC 3168)
1865  *
1866  * IETF RFCs 2474 and 3168 reorganize the IPv4 Type of Service (TOS) field
1867  * (8 bits) and the IPv6 Traffic Class (TC) field (8 bits) into Differentiated
1868  * Services Codepoint (DSCP) field (6 bits) and Explicit Congestion
1869  * Notification (ECN) field (2 bits). The DSCP field is typically used to
1870  * encode the traffic class and/or drop priority (RFC 2597), while the ECN
1871  * field is used by RFC 3168 to implement a congestion notification mechanism
1872  * to be leveraged by transport layer protocols such as TCP and SCTP that have
1873  * congestion control mechanisms.
1874  *
1875  * When congestion is experienced, as alternative to dropping the packet,
1876  * routers can change the ECN field of input packets from 2'b01 or 2'b10
1877  * (values indicating that source endpoint is ECN-capable) to 2'b11 (meaning
1878  * that congestion is experienced). The destination endpoint can use the
1879  * ECN-Echo (ECE) TCP flag to relay the congestion indication back to the
1880  * source endpoint, which acknowledges it back to the destination endpoint with
1881  * the Congestion Window Reduced (CWR) TCP flag.
1882  *
1883  * All IPv4/IPv6 packets of a given color with ECN set to 2’b01 or 2’b10
1884  * carrying TCP or SCTP have their ECN set to 2’b11 if the marking feature is
1885  * enabled for the current color, otherwise the ECN field is left as is.
1886  *
1887  * @param[in] port_id
1888  *   The port identifier of the Ethernet device.
1889  * @param[in] mark_green
1890  *   Set to non-zero value to enable marking of green packets and to zero to
1891  *   disable it.
1892  * @param[in] mark_yellow
1893  *   Set to non-zero value to enable marking of yellow packets and to zero to
1894  *   disable it.
1895  * @param[in] mark_red
1896  *   Set to non-zero value to enable marking of red packets and to zero to
1897  *   disable it.
1898  * @param[out] error
1899  *   Error details. Filled in only on error, when not NULL.
1900  * @return
1901  *   0 on success, non-zero error code otherwise.
1902  *
1903  * @see struct rte_tm_capabilities::mark_ip_ecn_tcp_supported
1904  * @see struct rte_tm_capabilities::mark_ip_ecn_sctp_supported
1905  */
1906 int
1907 rte_tm_mark_ip_ecn(uint16_t port_id,
1908         int mark_green,
1909         int mark_yellow,
1910         int mark_red,
1911         struct rte_tm_error *error);
1912
1913 /**
1914  * Traffic manager packet marking - IPv4 / IPv6 DSCP (IETF RFC 2597)
1915  *
1916  * IETF RFC 2597 maps the traffic class and the drop priority to the IPv4/IPv6
1917  * Differentiated Services Codepoint (DSCP) field (6 bits). Here are the DSCP
1918  * values proposed by this RFC:
1919  *
1920  * <pre>                   Class 1    Class 2    Class 3    Class 4   </pre>
1921  * <pre>                 +----------+----------+----------+----------+</pre>
1922  * <pre>Low Drop Prec    |  001010  |  010010  |  011010  |  100010  |</pre>
1923  * <pre>Medium Drop Prec |  001100  |  010100  |  011100  |  100100  |</pre>
1924  * <pre>High Drop Prec   |  001110  |  010110  |  011110  |  100110  |</pre>
1925  * <pre>                 +----------+----------+----------+----------+</pre>
1926  *
1927  * There are 4 traffic classes (classes 1 .. 4) encoded by DSCP bits 1 and 2,
1928  * as well as 3 drop priorities (low/medium/high) encoded by DSCP bits 3 and 4.
1929  *
1930  * All IPv4/IPv6 packets have their color marked into DSCP bits 3 and 4 as
1931  * follows: green mapped to Low Drop Precedence (2’b01), yellow to Medium
1932  * (2’b10) and red to High (2’b11). Marking needs to be explicitly enabled
1933  * for each color; when not enabled for a given color, the DSCP field of all
1934  * packets with that color is left as is.
1935  *
1936  * @param[in] port_id
1937  *   The port identifier of the Ethernet device.
1938  * @param[in] mark_green
1939  *   Set to non-zero value to enable marking of green packets and to zero to
1940  *   disable it.
1941  * @param[in] mark_yellow
1942  *   Set to non-zero value to enable marking of yellow packets and to zero to
1943  *   disable it.
1944  * @param[in] mark_red
1945  *   Set to non-zero value to enable marking of red packets and to zero to
1946  *   disable it.
1947  * @param[out] error
1948  *   Error details. Filled in only on error, when not NULL.
1949  * @return
1950  *   0 on success, non-zero error code otherwise.
1951  *
1952  * @see struct rte_tm_capabilities::mark_ip_dscp_supported
1953  */
1954 int
1955 rte_tm_mark_ip_dscp(uint16_t port_id,
1956         int mark_green,
1957         int mark_yellow,
1958         int mark_red,
1959         struct rte_tm_error *error);
1960
1961 #ifdef __cplusplus
1962 }
1963 #endif
1964
1965 #endif /* __INCLUDE_RTE_TM_H__ */