lib/librte_ethdev/rte_tm.h

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