4 * Copyright(c) 2017 Intel Corporation.
5 * Copyright(c) 2017 Cavium.
6 * Copyright(c) 2017 NXP.
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
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
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.
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.
36 #ifndef __INCLUDE_RTE_TM_H__
37 #define __INCLUDE_RTE_TM_H__
41 * RTE Generic Traffic Manager API
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.
48 * @b EXPERIMENTAL: this API may change without prior notice
58 * Ethernet framing overhead.
60 * Overhead fields per Ethernet frame:
61 * 1. Preamble: 7 bytes;
62 * 2. Start of Frame Delimiter (SFD): 1 byte;
63 * 3. Inter-Frame Gap (IFG): 12 bytes.
65 * One of the typical values for the *pkt_length_adjust* field of the shaper
68 * @see struct rte_tm_shaper_params
70 #define RTE_TM_ETH_FRAMING_OVERHEAD 20
73 * Ethernet framing overhead including the Frame Check Sequence (FCS) field.
74 * Useful when FCS is generated and added at the end of the Ethernet frame on
75 * TX side without any SW intervention.
77 * One of the typical values for the pkt_length_adjust field of the shaper
80 * @see struct rte_tm_shaper_params
82 #define RTE_TM_ETH_FRAMING_OVERHEAD_FCS 24
85 * Invalid WRED profile ID.
87 * @see struct rte_tm_node_params
88 * @see rte_tm_node_add()
89 * @see rte_tm_node_wred_context_update()
91 #define RTE_TM_WRED_PROFILE_ID_NONE UINT32_MAX
94 *Invalid shaper profile ID.
96 * @see struct rte_tm_node_params
97 * @see rte_tm_node_add()
98 * @see rte_tm_node_shaper_update()
100 #define RTE_TM_SHAPER_PROFILE_ID_NONE UINT32_MAX
103 * Node ID for the parent of the root node.
105 * @see rte_tm_node_add()
107 #define RTE_TM_NODE_ID_NULL UINT32_MAX
110 * Node level ID used to disable level ID checking.
112 * @see rte_tm_node_add()
114 #define RTE_TM_NODE_LEVEL_ID_ANY UINT32_MAX
120 RTE_TM_GREEN = 0, /**< Green */
121 RTE_TM_YELLOW, /**< Yellow */
122 RTE_TM_RED, /**< Red */
123 RTE_TM_COLORS /**< Number of colors */
127 * Node statistics counter type
129 enum rte_tm_stats_type {
130 /** Number of packets scheduled from current node. */
131 RTE_TM_STATS_N_PKTS = 1 << 0,
133 /** Number of bytes scheduled from current node. */
134 RTE_TM_STATS_N_BYTES = 1 << 1,
136 /** Number of green packets dropped by current leaf node. */
137 RTE_TM_STATS_N_PKTS_GREEN_DROPPED = 1 << 2,
139 /** Number of yellow packets dropped by current leaf node. */
140 RTE_TM_STATS_N_PKTS_YELLOW_DROPPED = 1 << 3,
142 /** Number of red packets dropped by current leaf node. */
143 RTE_TM_STATS_N_PKTS_RED_DROPPED = 1 << 4,
145 /** Number of green bytes dropped by current leaf node. */
146 RTE_TM_STATS_N_BYTES_GREEN_DROPPED = 1 << 5,
148 /** Number of yellow bytes dropped by current leaf node. */
149 RTE_TM_STATS_N_BYTES_YELLOW_DROPPED = 1 << 6,
151 /** Number of red bytes dropped by current leaf node. */
152 RTE_TM_STATS_N_BYTES_RED_DROPPED = 1 << 7,
154 /** Number of packets currently waiting in the packet queue of current
157 RTE_TM_STATS_N_PKTS_QUEUED = 1 << 8,
159 /** Number of bytes currently waiting in the packet queue of current
162 RTE_TM_STATS_N_BYTES_QUEUED = 1 << 9,
166 * Node statistics counters
168 struct rte_tm_node_stats {
169 /** Number of packets scheduled from current node. */
172 /** Number of bytes scheduled from current node. */
175 /** Statistics counters for leaf nodes only. */
177 /** Number of packets dropped by current leaf node per each
180 uint64_t n_pkts_dropped[RTE_TM_COLORS];
182 /** Number of bytes dropped by current leaf node per each
185 uint64_t n_bytes_dropped[RTE_TM_COLORS];
187 /** Number of packets currently waiting in the packet queue of
190 uint64_t n_pkts_queued;
192 /** Number of bytes currently waiting in the packet queue of
195 uint64_t n_bytes_queued;
200 * Traffic manager dynamic updates
202 enum rte_tm_dynamic_update_type {
203 /** Dynamic parent node update. The new parent node is located on same
204 * hierarchy level as the former parent node. Consequently, the node
205 * whose parent is changed preserves its hierarchy level.
207 RTE_TM_UPDATE_NODE_PARENT_KEEP_LEVEL = 1 << 0,
209 /** Dynamic parent node update. The new parent node is located on
210 * different hierarchy level than the former parent node. Consequently,
211 * the node whose parent is changed also changes its hierarchy level.
213 RTE_TM_UPDATE_NODE_PARENT_CHANGE_LEVEL = 1 << 1,
215 /** Dynamic node add/delete. */
216 RTE_TM_UPDATE_NODE_ADD_DELETE = 1 << 2,
218 /** Suspend/resume nodes. */
219 RTE_TM_UPDATE_NODE_SUSPEND_RESUME = 1 << 3,
221 /** Dynamic switch between byte-based and packet-based WFQ weights. */
222 RTE_TM_UPDATE_NODE_WFQ_WEIGHT_MODE = 1 << 4,
224 /** Dynamic update on number of SP priorities. */
225 RTE_TM_UPDATE_NODE_N_SP_PRIORITIES = 1 << 5,
227 /** Dynamic update of congestion management mode for leaf nodes. */
228 RTE_TM_UPDATE_NODE_CMAN = 1 << 6,
230 /** Dynamic update of the set of enabled stats counter types. */
231 RTE_TM_UPDATE_NODE_STATS = 1 << 7,
235 * Traffic manager capabilities
237 struct rte_tm_capabilities {
238 /** Maximum number of nodes. */
239 uint32_t n_nodes_max;
241 /** Maximum number of levels (i.e. number of nodes connecting the root
242 * node with any leaf node, including the root and the leaf).
244 uint32_t n_levels_max;
246 /** When non-zero, this flag indicates that all the non-leaf nodes
247 * (with the exception of the root node) have identical capability set.
249 int non_leaf_nodes_identical;
251 /** When non-zero, this flag indicates that all the leaf nodes have
252 * identical capability set.
254 int leaf_nodes_identical;
256 /** Maximum number of shapers, either private or shared. In case the
257 * implementation does not share any resources between private and
258 * shared shapers, it is typically equal to the sum of
259 * *shaper_private_n_max* and *shaper_shared_n_max*. The
260 * value of zero indicates that traffic shaping is not supported.
262 uint32_t shaper_n_max;
264 /** Maximum number of private shapers. Indicates the maximum number of
265 * nodes that can concurrently have their private shaper enabled. The
266 * value of zero indicates that private shapers are not supported.
268 uint32_t shaper_private_n_max;
270 /** Maximum number of private shapers that support dual rate shaping.
271 * Indicates the maximum number of nodes that can concurrently have
272 * their private shaper enabled with dual rate support. Only valid when
273 * private shapers are supported. The value of zero indicates that dual
274 * rate shaping is not available for private shapers. The maximum value
275 * is *shaper_private_n_max*.
277 int shaper_private_dual_rate_n_max;
279 /** Minimum committed/peak rate (bytes per second) for any private
280 * shaper. Valid only when private shapers are supported.
282 uint64_t shaper_private_rate_min;
284 /** Maximum committed/peak rate (bytes per second) for any private
285 * shaper. Valid only when private shapers are supported.
287 uint64_t shaper_private_rate_max;
289 /** Maximum number of shared shapers. The value of zero indicates that
290 * shared shapers are not supported.
292 uint32_t shaper_shared_n_max;
294 /** Maximum number of nodes that can share the same shared shaper.
295 * Only valid when shared shapers are supported.
297 uint32_t shaper_shared_n_nodes_per_shaper_max;
299 /** Maximum number of shared shapers a node can be part of. This
300 * parameter indicates that there is at least one node that can be
301 * configured with this many shared shapers, which might not be true for
302 * all the nodes. Only valid when shared shapers are supported, in which
303 * case it ranges from 1 to *shaper_shared_n_max*.
305 uint32_t shaper_shared_n_shapers_per_node_max;
307 /** Maximum number of shared shapers that can be configured with dual
308 * rate shaping. The value of zero indicates that dual rate shaping
309 * support is not available for shared shapers.
311 uint32_t shaper_shared_dual_rate_n_max;
313 /** Minimum committed/peak rate (bytes per second) for any shared
314 * shaper. Only valid when shared shapers are supported.
316 uint64_t shaper_shared_rate_min;
318 /** Maximum committed/peak rate (bytes per second) for any shared
319 * shaper. Only valid when shared shapers are supported.
321 uint64_t shaper_shared_rate_max;
323 /** Minimum value allowed for packet length adjustment for any private
326 int shaper_pkt_length_adjust_min;
328 /** Maximum value allowed for packet length adjustment for any private
331 int shaper_pkt_length_adjust_max;
333 /** Maximum number of children nodes. This parameter indicates that
334 * there is at least one non-leaf node that can be configured with this
335 * many children nodes, which might not be true for all the non-leaf
338 uint32_t sched_n_children_max;
340 /** Maximum number of supported priority levels. This parameter
341 * indicates that there is at least one non-leaf node that can be
342 * configured with this many priority levels for managing its children
343 * nodes, which might not be true for all the non-leaf nodes. The value
344 * of zero is invalid. The value of 1 indicates that only priority 0 is
345 * supported, which essentially means that Strict Priority (SP)
346 * algorithm is not supported.
348 uint32_t sched_sp_n_priorities_max;
350 /** Maximum number of sibling nodes that can have the same priority at
351 * any given time, i.e. maximum size of the WFQ sibling node group. This
352 * parameter indicates there is at least one non-leaf node that meets
353 * this condition, which might not be true for all the non-leaf nodes.
354 * The value of zero is invalid. The value of 1 indicates that WFQ
355 * algorithm is not supported. The maximum value is
356 * *sched_n_children_max*.
358 uint32_t sched_wfq_n_children_per_group_max;
360 /** Maximum number of priority levels that can have more than one child
361 * node at any given time, i.e. maximum number of WFQ sibling node
362 * groups that have two or more members. This parameter indicates there
363 * is at least one non-leaf node that meets this condition, which might
364 * not be true for all the non-leaf nodes. The value of zero states that
365 * WFQ algorithm is not supported. The value of 1 indicates that
366 * (*sched_sp_n_priorities_max* - 1) priority levels have at most one
367 * child node, so there can be only one priority level with two or
368 * more sibling nodes making up a WFQ group. The maximum value is:
369 * min(floor(*sched_n_children_max* / 2), *sched_sp_n_priorities_max*).
371 uint32_t sched_wfq_n_groups_max;
373 /** Maximum WFQ weight. The value of 1 indicates that all sibling nodes
374 * with same priority have the same WFQ weight, so WFQ is reduced to FQ.
376 uint32_t sched_wfq_weight_max;
378 /** Head drop algorithm support. When non-zero, this parameter
379 * indicates that there is at least one leaf node that supports the head
380 * drop algorithm, which might not be true for all the leaf nodes.
382 int cman_head_drop_supported;
384 /** Maximum number of WRED contexts, either private or shared. In case
385 * the implementation does not share any resources between private and
386 * shared WRED contexts, it is typically equal to the sum of
387 * *cman_wred_context_private_n_max* and
388 * *cman_wred_context_shared_n_max*. The value of zero indicates that
389 * WRED is not supported.
391 uint32_t cman_wred_context_n_max;
393 /** Maximum number of private WRED contexts. Indicates the maximum
394 * number of leaf nodes that can concurrently have their private WRED
395 * context enabled. The value of zero indicates that private WRED
396 * contexts are not supported.
398 uint32_t cman_wred_context_private_n_max;
400 /** Maximum number of shared WRED contexts. The value of zero
401 * indicates that shared WRED contexts are not supported.
403 uint32_t cman_wred_context_shared_n_max;
405 /** Maximum number of leaf nodes that can share the same WRED context.
406 * Only valid when shared WRED contexts are supported.
408 uint32_t cman_wred_context_shared_n_nodes_per_context_max;
410 /** Maximum number of shared WRED contexts a leaf node can be part of.
411 * This parameter indicates that there is at least one leaf node that
412 * can be configured with this many shared WRED contexts, which might
413 * not be true for all the leaf nodes. Only valid when shared WRED
414 * contexts are supported, in which case it ranges from 1 to
415 * *cman_wred_context_shared_n_max*.
417 uint32_t cman_wred_context_shared_n_contexts_per_node_max;
419 /** Support for VLAN DEI packet marking (per color). */
420 int mark_vlan_dei_supported[RTE_TM_COLORS];
422 /** Support for IPv4/IPv6 ECN marking of TCP packets (per color). */
423 int mark_ip_ecn_tcp_supported[RTE_TM_COLORS];
425 /** Support for IPv4/IPv6 ECN marking of SCTP packets (per color). */
426 int mark_ip_ecn_sctp_supported[RTE_TM_COLORS];
428 /** Support for IPv4/IPv6 DSCP packet marking (per color). */
429 int mark_ip_dscp_supported[RTE_TM_COLORS];
431 /** Set of supported dynamic update operations.
432 * @see enum rte_tm_dynamic_update_type
434 uint64_t dynamic_update_mask;
436 /** Set of supported statistics counter types.
437 * @see enum rte_tm_stats_type
443 * Traffic manager level capabilities
445 struct rte_tm_level_capabilities {
446 /** Maximum number of nodes for the current hierarchy level. */
447 uint32_t n_nodes_max;
449 /** Maximum number of non-leaf nodes for the current hierarchy level.
450 * The value of 0 indicates that current level only supports leaf
451 * nodes. The maximum value is *n_nodes_max*.
453 uint32_t n_nodes_nonleaf_max;
455 /** Maximum number of leaf nodes for the current hierarchy level. The
456 * value of 0 indicates that current level only supports non-leaf
457 * nodes. The maximum value is *n_nodes_max*.
459 uint32_t n_nodes_leaf_max;
461 /** When non-zero, this flag indicates that all the non-leaf nodes on
462 * this level have identical capability set. Valid only when
463 * *n_nodes_nonleaf_max* is non-zero.
465 int non_leaf_nodes_identical;
467 /** When non-zero, this flag indicates that all the leaf nodes on this
468 * level have identical capability set. Valid only when
469 * *n_nodes_leaf_max* is non-zero.
471 int leaf_nodes_identical;
474 /** Items valid only for the non-leaf nodes on this level. */
476 /** Private shaper support. When non-zero, it indicates
477 * there is at least one non-leaf node on this level
478 * with private shaper support, which may not be the
479 * case for all the non-leaf nodes on this level.
481 int shaper_private_supported;
483 /** Dual rate support for private shaper. Valid only
484 * when private shaper is supported for the non-leaf
485 * nodes on the current level. When non-zero, it
486 * indicates there is at least one non-leaf node on this
487 * level with dual rate private shaper support, which
488 * may not be the case for all the non-leaf nodes on
491 int shaper_private_dual_rate_supported;
493 /** Minimum committed/peak rate (bytes per second) for
494 * private shapers of the non-leaf nodes of this level.
495 * Valid only when private shaper is supported on this
498 uint64_t shaper_private_rate_min;
500 /** Maximum committed/peak rate (bytes per second) for
501 * private shapers of the non-leaf nodes on this level.
502 * Valid only when private shaper is supported on this
505 uint64_t shaper_private_rate_max;
507 /** Maximum number of shared shapers that any non-leaf
508 * node on this level can be part of. The value of zero
509 * indicates that shared shapers are not supported by
510 * the non-leaf nodes on this level. When non-zero, it
511 * indicates there is at least one non-leaf node on this
512 * level that meets this condition, which may not be the
513 * case for all the non-leaf nodes on this level.
515 uint32_t shaper_shared_n_max;
517 /** Maximum number of children nodes. This parameter
518 * indicates that there is at least one non-leaf node on
519 * this level that can be configured with this many
520 * children nodes, which might not be true for all the
521 * non-leaf nodes on this level.
523 uint32_t sched_n_children_max;
525 /** Maximum number of supported priority levels. This
526 * parameter indicates that there is at least one
527 * non-leaf node on this level that can be configured
528 * with this many priority levels for managing its
529 * children nodes, which might not be true for all the
530 * non-leaf nodes on this level. The value of zero is
531 * invalid. The value of 1 indicates that only priority
532 * 0 is supported, which essentially means that Strict
533 * Priority (SP) algorithm is not supported on this
536 uint32_t sched_sp_n_priorities_max;
538 /** Maximum number of sibling nodes that can have the
539 * same priority at any given time, i.e. maximum size of
540 * the WFQ sibling node group. This parameter indicates
541 * there is at least one non-leaf node on this level
542 * that meets this condition, which may not be true for
543 * all the non-leaf nodes on this level. The value of
544 * zero is invalid. The value of 1 indicates that WFQ
545 * algorithm is not supported on this level. The maximum
546 * value is *sched_n_children_max*.
548 uint32_t sched_wfq_n_children_per_group_max;
550 /** Maximum number of priority levels that can have
551 * more than one child node at any given time, i.e.
552 * maximum number of WFQ sibling node groups that
553 * have two or more members. This parameter indicates
554 * there is at least one non-leaf node on this level
555 * that meets this condition, which might not be true
556 * for all the non-leaf nodes. The value of zero states
557 * that WFQ algorithm is not supported on this level.
558 * The value of 1 indicates that
559 * (*sched_sp_n_priorities_max* - 1) priority levels on
560 * this level have at most one child node, so there can
561 * be only one priority level with two or more sibling
562 * nodes making up a WFQ group on this level. The
564 * min(floor(*sched_n_children_max* / 2),
565 * *sched_sp_n_priorities_max*).
567 uint32_t sched_wfq_n_groups_max;
569 /** Maximum WFQ weight. The value of 1 indicates that
570 * all sibling nodes on this level with same priority
571 * have the same WFQ weight, so on this level WFQ is
574 uint32_t sched_wfq_weight_max;
576 /** Mask of statistics counter types supported by the
577 * non-leaf nodes on this level. Every supported
578 * statistics counter type is supported by at least one
579 * non-leaf node on this level, which may not be true
580 * for all the non-leaf nodes on this level.
581 * @see enum rte_tm_stats_type
586 /** Items valid only for the leaf nodes on this level. */
588 /** Private shaper support. When non-zero, it indicates
589 * there is at least one leaf node on this level with
590 * private shaper support, which may not be the case for
591 * all the leaf nodes on this level.
593 int shaper_private_supported;
595 /** Dual rate support for private shaper. Valid only
596 * when private shaper is supported for the leaf nodes
597 * on this level. When non-zero, it indicates there is
598 * at least one leaf node on this level with dual rate
599 * private shaper support, which may not be the case for
600 * all the leaf nodes on this level.
602 int shaper_private_dual_rate_supported;
604 /** Minimum committed/peak rate (bytes per second) for
605 * private shapers of the leaf nodes of this level.
606 * Valid only when private shaper is supported for the
607 * leaf nodes on this level.
609 uint64_t shaper_private_rate_min;
611 /** Maximum committed/peak rate (bytes per second) for
612 * private shapers of the leaf nodes on this level.
613 * Valid only when private shaper is supported for the
614 * leaf nodes on this level.
616 uint64_t shaper_private_rate_max;
618 /** Maximum number of shared shapers that any leaf node
619 * on this level can be part of. The value of zero
620 * indicates that shared shapers are not supported by
621 * the leaf nodes on this level. When non-zero, it
622 * indicates there is at least one leaf node on this
623 * level that meets this condition, which may not be the
624 * case for all the leaf nodes on this level.
626 uint32_t shaper_shared_n_max;
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.
634 int cman_head_drop_supported;
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.
641 int cman_wred_context_private_supported;
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
652 uint32_t cman_wred_context_shared_n_max;
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
667 * Traffic manager node capabilities
669 struct rte_tm_node_capabilities {
670 /** Private shaper support for the current node. */
671 int shaper_private_supported;
673 /** Dual rate shaping support for private shaper of current node.
674 * Valid only when private shaper is supported by the current node.
676 int shaper_private_dual_rate_supported;
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.
682 uint64_t shaper_private_rate_min;
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.
688 uint64_t shaper_private_rate_max;
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
694 uint32_t shaper_shared_n_max;
697 /** Items valid only for non-leaf nodes. */
699 /** Maximum number of children nodes. */
700 uint32_t sched_n_children_max;
702 /** Maximum number of supported priority levels. The
703 * value of zero is invalid. The value of 1 indicates
704 * that only priority 0 is supported, which essentially
705 * means that Strict Priority (SP) algorithm is not
708 uint32_t sched_sp_n_priorities_max;
710 /** Maximum number of sibling nodes that can have the
711 * same priority at any given time, i.e. maximum size
712 * of the WFQ sibling node group. The value of zero
713 * is invalid. The value of 1 indicates that WFQ
714 * algorithm is not supported. The maximum value is
715 * *sched_n_children_max*.
717 uint32_t sched_wfq_n_children_per_group_max;
719 /** Maximum number of priority levels that can have
720 * more than one child node at any given time, i.e.
721 * maximum number of WFQ sibling node groups that have
722 * two or more members. The value of zero states that
723 * WFQ algorithm is not supported. The value of 1
724 * indicates that (*sched_sp_n_priorities_max* - 1)
725 * priority levels have at most one child node, so there
726 * can be only one priority level with two or more
727 * sibling nodes making up a WFQ group. The maximum
728 * value is: min(floor(*sched_n_children_max* / 2),
729 * *sched_sp_n_priorities_max*).
731 uint32_t sched_wfq_n_groups_max;
733 /** Maximum WFQ weight. The value of 1 indicates that
734 * all sibling nodes with same priority have the same
735 * WFQ weight, so WFQ is reduced to FQ.
737 uint32_t sched_wfq_weight_max;
740 /** Items valid only for leaf nodes. */
742 /** Head drop algorithm support for current node. */
743 int cman_head_drop_supported;
745 /** Private WRED context support for current node. */
746 int cman_wred_context_private_supported;
748 /** Maximum number of shared WRED contexts the current
749 * node can be part of. The value of zero indicates that
750 * shared WRED contexts are not supported by the current
753 uint32_t cman_wred_context_shared_n_max;
757 /** Mask of statistics counter types supported by the current node.
758 * @see enum rte_tm_stats_type
764 * Congestion management (CMAN) mode
766 * This is used for controlling the admission of packets into a packet queue or
767 * group of packet queues on congestion. On request of writing a new packet
768 * into the current queue while the queue is full, the *tail drop* algorithm
769 * drops the new packet while leaving the queue unmodified, as opposed to *head
770 * drop* algorithm, which drops the packet at the head of the queue (the oldest
771 * packet waiting in the queue) and admits the new packet at the tail of the
774 * The *Random Early Detection (RED)* algorithm works by proactively dropping
775 * more and more input packets as the queue occupancy builds up. When the queue
776 * is full or almost full, RED effectively works as *tail drop*. The *Weighted
777 * RED* algorithm uses a separate set of RED thresholds for each packet color.
779 enum rte_tm_cman_mode {
780 RTE_TM_CMAN_TAIL_DROP = 0, /**< Tail drop */
781 RTE_TM_CMAN_HEAD_DROP, /**< Head drop */
782 RTE_TM_CMAN_WRED, /**< Weighted Random Early Detection (WRED) */
786 * Random Early Detection (RED) profile
788 struct rte_tm_red_params {
789 /** Minimum queue threshold */
792 /** Maximum queue threshold */
795 /** Inverse of packet marking probability maximum value (maxp), i.e.
796 * maxp_inv = 1 / maxp
800 /** Negated log2 of queue weight (wq), i.e. wq = 1 / (2 ^ wq_log2) */
805 * Weighted RED (WRED) profile
807 * Multiple WRED contexts can share the same WRED profile. Each leaf node with
808 * WRED enabled as its congestion management mode has zero or one private WRED
809 * context (only one leaf node using it) and/or zero, one or several shared
810 * WRED contexts (multiple leaf nodes use the same WRED context). A private
811 * WRED context is used to perform congestion management for a single leaf
812 * node, while a shared WRED context is used to perform congestion management
813 * for a group of leaf nodes.
815 struct rte_tm_wred_params {
816 /** One set of RED parameters per packet color */
817 struct rte_tm_red_params red_params[RTE_TM_COLORS];
823 struct rte_tm_token_bucket {
824 /** Token bucket rate (bytes per second) */
827 /** Token bucket size (bytes), a.k.a. max burst size */
832 * Shaper (rate limiter) profile
834 * Multiple shaper instances can share the same shaper profile. Each node has
835 * zero or one private shaper (only one node using it) and/or zero, one or
836 * several shared shapers (multiple nodes use the same shaper instance).
837 * A private shaper is used to perform traffic shaping for a single node, while
838 * a shared shaper is used to perform traffic shaping for a group of nodes.
840 * Single rate shapers use a single token bucket. A single rate shaper can be
841 * configured by setting the rate of the committed bucket to zero, which
842 * effectively disables this bucket. The peak bucket is used to limit the rate
843 * and the burst size for the current shaper.
845 * Dual rate shapers use both the committed and the peak token buckets. The
846 * rate of the peak bucket has to be bigger than zero, as well as greater than
847 * or equal to the rate of the committed bucket.
849 struct rte_tm_shaper_params {
850 /** Committed token bucket */
851 struct rte_tm_token_bucket committed;
853 /** Peak token bucket */
854 struct rte_tm_token_bucket peak;
856 /** Signed value to be added to the length of each packet for the
857 * purpose of shaping. Can be used to correct the packet length with
858 * the framing overhead bytes that are also consumed on the wire (e.g.
859 * RTE_TM_ETH_FRAMING_OVERHEAD_FCS).
861 int32_t pkt_length_adjust;
867 * Each non-leaf node has multiple inputs (its children nodes) and single output
868 * (which is input to its parent node). It arbitrates its inputs using Strict
869 * Priority (SP) and Weighted Fair Queuing (WFQ) algorithms to schedule input
870 * packets to its output while observing its shaping (rate limiting)
873 * Algorithms such as Weighted Round Robin (WRR), Byte-level WRR, Deficit WRR
874 * (DWRR), etc. are considered approximations of the WFQ ideal and are
875 * assimilated to WFQ, although an associated implementation-dependent trade-off
876 * on accuracy, performance and resource usage might exist.
878 * Children nodes with different priorities are scheduled using the SP algorithm
879 * based on their priority, with zero (0) as the highest priority. Children with
880 * the same priority are scheduled using the WFQ algorithm according to their
881 * weights. The WFQ weight of a given child node is relative to the sum of the
882 * weights of all its sibling nodes that have the same priority, with one (1) as
883 * the lowest weight. For each SP priority, the WFQ weight mode can be set as
884 * either byte-based or packet-based.
886 * Each leaf node sits on top of a TX queue of the current Ethernet port. Hence,
887 * the leaf nodes are predefined, with their node IDs set to 0 .. (N-1), where N
888 * is the number of TX queues configured for the current Ethernet port. The
889 * non-leaf nodes have their IDs generated by the application.
891 struct rte_tm_node_params {
892 /** Shaper profile for the private shaper. The absence of the private
893 * shaper for the current node is indicated by setting this parameter
894 * to RTE_TM_SHAPER_PROFILE_ID_NONE.
896 uint32_t shaper_profile_id;
898 /** User allocated array of valid shared shaper IDs. */
899 uint32_t *shared_shaper_id;
901 /** Number of shared shaper IDs in the *shared_shaper_id* array. */
902 uint32_t n_shared_shapers;
905 /** Parameters only valid for non-leaf nodes. */
907 /** WFQ weight mode for each SP priority. When NULL, it
908 * indicates that WFQ is to be used for all priorities.
909 * When non-NULL, it points to a pre-allocated array of
910 * *n_sp_priorities* values, with non-zero value for
911 * byte-mode and zero for packet-mode.
913 int *wfq_weight_mode;
915 /** Number of SP priorities. */
916 uint32_t n_sp_priorities;
919 /** Parameters only valid for leaf nodes. */
921 /** Congestion management mode */
922 enum rte_tm_cman_mode cman;
924 /** WRED parameters (only valid when *cman* is set to
928 /** WRED profile for private WRED context. The
929 * absence of a private WRED context for the
930 * current leaf node is indicated by value
931 * RTE_TM_WRED_PROFILE_ID_NONE.
933 uint32_t wred_profile_id;
935 /** User allocated array of shared WRED context
936 * IDs. When set to NULL, it indicates that the
937 * current leaf node should not currently be
938 * part of any shared WRED contexts.
940 uint32_t *shared_wred_context_id;
942 /** Number of elements in the
943 * *shared_wred_context_id* array. Only valid
944 * when *shared_wred_context_id* is non-NULL,
945 * in which case it should be non-zero.
947 uint32_t n_shared_wred_contexts;
952 /** Mask of statistics counter types to be enabled for this node. This
953 * needs to be a subset of the statistics counter types available for
954 * the current node. Any statistics counter type not included in this
955 * set is to be disabled for the current node.
956 * @see enum rte_tm_stats_type
962 * Verbose error types.
964 * Most of them provide the type of the object referenced by struct
965 * rte_tm_error::cause.
967 enum rte_tm_error_type {
968 RTE_TM_ERROR_TYPE_NONE, /**< No error. */
969 RTE_TM_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
970 RTE_TM_ERROR_TYPE_CAPABILITIES,
971 RTE_TM_ERROR_TYPE_LEVEL_ID,
972 RTE_TM_ERROR_TYPE_WRED_PROFILE,
973 RTE_TM_ERROR_TYPE_WRED_PROFILE_GREEN,
974 RTE_TM_ERROR_TYPE_WRED_PROFILE_YELLOW,
975 RTE_TM_ERROR_TYPE_WRED_PROFILE_RED,
976 RTE_TM_ERROR_TYPE_WRED_PROFILE_ID,
977 RTE_TM_ERROR_TYPE_SHARED_WRED_CONTEXT_ID,
978 RTE_TM_ERROR_TYPE_SHAPER_PROFILE,
979 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_COMMITTED_RATE,
980 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_COMMITTED_SIZE,
981 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PEAK_RATE,
982 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PEAK_SIZE,
983 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PKT_ADJUST_LEN,
984 RTE_TM_ERROR_TYPE_SHAPER_PROFILE_ID,
985 RTE_TM_ERROR_TYPE_SHARED_SHAPER_ID,
986 RTE_TM_ERROR_TYPE_NODE_PARENT_NODE_ID,
987 RTE_TM_ERROR_TYPE_NODE_PRIORITY,
988 RTE_TM_ERROR_TYPE_NODE_WEIGHT,
989 RTE_TM_ERROR_TYPE_NODE_PARAMS,
990 RTE_TM_ERROR_TYPE_NODE_PARAMS_SHAPER_PROFILE_ID,
991 RTE_TM_ERROR_TYPE_NODE_PARAMS_SHARED_SHAPER_ID,
992 RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SHARED_SHAPERS,
993 RTE_TM_ERROR_TYPE_NODE_PARAMS_WFQ_WEIGHT_MODE,
994 RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SP_PRIORITIES,
995 RTE_TM_ERROR_TYPE_NODE_PARAMS_CMAN,
996 RTE_TM_ERROR_TYPE_NODE_PARAMS_WRED_PROFILE_ID,
997 RTE_TM_ERROR_TYPE_NODE_PARAMS_SHARED_WRED_CONTEXT_ID,
998 RTE_TM_ERROR_TYPE_NODE_PARAMS_N_SHARED_WRED_CONTEXTS,
999 RTE_TM_ERROR_TYPE_NODE_PARAMS_STATS,
1000 RTE_TM_ERROR_TYPE_NODE_ID,
1004 * Verbose error structure definition.
1006 * This object is normally allocated by applications and set by PMDs, the
1007 * message points to a constant string which does not need to be freed by
1008 * the application, however its pointer can be considered valid only as long
1009 * as its associated DPDK port remains configured. Closing the underlying
1010 * device or unloading the PMD invalidates it.
1012 * Both cause and message may be NULL regardless of the error type.
1014 struct rte_tm_error {
1015 enum rte_tm_error_type type; /**< Cause field and error type. */
1016 const void *cause; /**< Object responsible for the error. */
1017 const char *message; /**< Human-readable error message. */
1021 * Traffic manager get number of leaf nodes
1023 * Each leaf node sits on on top of a TX queue of the current Ethernet port.
1024 * Therefore, the set of leaf nodes is predefined, their number is always equal
1025 * to N (where N is the number of TX queues configured for the current port)
1026 * and their IDs are 0 .. (N-1).
1028 * @param[in] port_id
1029 * The port identifier of the Ethernet device.
1030 * @param[out] n_leaf_nodes
1031 * Number of leaf nodes for the current port.
1033 * Error details. Filled in only on error, when not NULL.
1035 * 0 on success, non-zero error code otherwise.
1038 rte_tm_get_number_of_leaf_nodes(uint8_t port_id,
1039 uint32_t *n_leaf_nodes,
1040 struct rte_tm_error *error);
1043 * Traffic manager node ID validate and type (i.e. leaf or non-leaf) get
1045 * The leaf nodes have predefined IDs in the range of 0 .. (N-1), where N is
1046 * the number of TX queues of the current Ethernet port. The non-leaf nodes
1047 * have their IDs generated by the application outside of the above range,
1048 * which is reserved for leaf nodes.
1050 * @param[in] port_id
1051 * The port identifier of the Ethernet device.
1052 * @param[in] node_id
1053 * Node ID value. Needs to be valid.
1054 * @param[out] is_leaf
1055 * Set to non-zero value when node is leaf and to zero otherwise (non-leaf).
1057 * Error details. Filled in only on error, when not NULL.
1059 * 0 on success, non-zero error code otherwise.
1062 rte_tm_node_type_get(uint8_t port_id,
1065 struct rte_tm_error *error);
1068 * Traffic manager capabilities get
1070 * @param[in] port_id
1071 * The port identifier of the Ethernet device.
1073 * Traffic manager capabilities. Needs to be pre-allocated and valid.
1075 * Error details. Filled in only on error, when not NULL.
1077 * 0 on success, non-zero error code otherwise.
1080 rte_tm_capabilities_get(uint8_t port_id,
1081 struct rte_tm_capabilities *cap,
1082 struct rte_tm_error *error);
1085 * Traffic manager level capabilities get
1087 * @param[in] port_id
1088 * The port identifier of the Ethernet device.
1089 * @param[in] level_id
1090 * The hierarchy level identifier. The value of 0 identifies the level of the
1093 * Traffic manager level capabilities. Needs to be pre-allocated and valid.
1095 * Error details. Filled in only on error, when not NULL.
1097 * 0 on success, non-zero error code otherwise.
1100 rte_tm_level_capabilities_get(uint8_t port_id,
1102 struct rte_tm_level_capabilities *cap,
1103 struct rte_tm_error *error);
1106 * Traffic manager node capabilities get
1108 * @param[in] port_id
1109 * The port identifier of the Ethernet device.
1110 * @param[in] node_id
1111 * Node ID. Needs to be valid.
1113 * Traffic manager node capabilities. Needs to be pre-allocated and valid.
1115 * Error details. Filled in only on error, when not NULL.
1117 * 0 on success, non-zero error code otherwise.
1120 rte_tm_node_capabilities_get(uint8_t port_id,
1122 struct rte_tm_node_capabilities *cap,
1123 struct rte_tm_error *error);
1126 * Traffic manager WRED profile add
1128 * Create a new WRED profile with ID set to *wred_profile_id*. The new profile
1129 * is used to create one or several WRED contexts.
1131 * @param[in] port_id
1132 * The port identifier of the Ethernet device.
1133 * @param[in] wred_profile_id
1134 * WRED profile ID for the new profile. Needs to be unused.
1135 * @param[in] profile
1136 * WRED profile parameters. Needs to be pre-allocated and valid.
1138 * Error details. Filled in only on error, when not NULL.
1140 * 0 on success, non-zero error code otherwise.
1142 * @see struct rte_tm_capabilities::cman_wred_context_n_max
1145 rte_tm_wred_profile_add(uint8_t port_id,
1146 uint32_t wred_profile_id,
1147 struct rte_tm_wred_params *profile,
1148 struct rte_tm_error *error);
1151 * Traffic manager WRED profile delete
1153 * Delete an existing WRED profile. This operation fails when there is
1154 * currently at least one user (i.e. WRED context) of this WRED profile.
1156 * @param[in] port_id
1157 * The port identifier of the Ethernet device.
1158 * @param[in] wred_profile_id
1159 * WRED profile ID. Needs to be the valid.
1161 * Error details. Filled in only on error, when not NULL.
1163 * 0 on success, non-zero error code otherwise.
1165 * @see struct rte_tm_capabilities::cman_wred_context_n_max
1168 rte_tm_wred_profile_delete(uint8_t port_id,
1169 uint32_t wred_profile_id,
1170 struct rte_tm_error *error);
1173 * Traffic manager shared WRED context add or update
1175 * When *shared_wred_context_id* is invalid, a new WRED context with this ID is
1176 * created by using the WRED profile identified by *wred_profile_id*.
1178 * When *shared_wred_context_id* is valid, this WRED context is no longer using
1179 * the profile previously assigned to it and is updated to use the profile
1180 * identified by *wred_profile_id*.
1182 * A valid shared WRED context can be assigned to several hierarchy leaf nodes
1183 * configured to use WRED as the congestion management mode.
1185 * @param[in] port_id
1186 * The port identifier of the Ethernet device.
1187 * @param[in] shared_wred_context_id
1188 * Shared WRED context ID
1189 * @param[in] wred_profile_id
1190 * WRED profile ID. Needs to be the valid.
1192 * Error details. Filled in only on error, when not NULL.
1194 * 0 on success, non-zero error code otherwise.
1196 * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1199 rte_tm_shared_wred_context_add_update(uint8_t port_id,
1200 uint32_t shared_wred_context_id,
1201 uint32_t wred_profile_id,
1202 struct rte_tm_error *error);
1205 * Traffic manager shared WRED context delete
1207 * Delete an existing shared WRED context. This operation fails when there is
1208 * currently at least one user (i.e. hierarchy leaf node) of this shared WRED
1211 * @param[in] port_id
1212 * The port identifier of the Ethernet device.
1213 * @param[in] shared_wred_context_id
1214 * Shared WRED context ID. Needs to be the valid.
1216 * Error details. Filled in only on error, when not NULL.
1218 * 0 on success, non-zero error code otherwise.
1220 * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1223 rte_tm_shared_wred_context_delete(uint8_t port_id,
1224 uint32_t shared_wred_context_id,
1225 struct rte_tm_error *error);
1228 * Traffic manager shaper profile add
1230 * Create a new shaper profile with ID set to *shaper_profile_id*. The new
1231 * shaper profile is used to create one or several shapers.
1233 * @param[in] port_id
1234 * The port identifier of the Ethernet device.
1235 * @param[in] shaper_profile_id
1236 * Shaper profile ID for the new profile. Needs to be unused.
1237 * @param[in] profile
1238 * Shaper profile parameters. Needs to be pre-allocated and valid.
1240 * Error details. Filled in only on error, when not NULL.
1242 * 0 on success, non-zero error code otherwise.
1244 * @see struct rte_tm_capabilities::shaper_n_max
1247 rte_tm_shaper_profile_add(uint8_t port_id,
1248 uint32_t shaper_profile_id,
1249 struct rte_tm_shaper_params *profile,
1250 struct rte_tm_error *error);
1253 * Traffic manager shaper profile delete
1255 * Delete an existing shaper profile. This operation fails when there is
1256 * currently at least one user (i.e. shaper) of this shaper profile.
1258 * @param[in] port_id
1259 * The port identifier of the Ethernet device.
1260 * @param[in] shaper_profile_id
1261 * Shaper profile ID. Needs to be the valid.
1263 * Error details. Filled in only on error, when not NULL.
1265 * 0 on success, non-zero error code otherwise.
1267 * @see struct rte_tm_capabilities::shaper_n_max
1270 rte_tm_shaper_profile_delete(uint8_t port_id,
1271 uint32_t shaper_profile_id,
1272 struct rte_tm_error *error);
1275 * Traffic manager shared shaper add or update
1277 * When *shared_shaper_id* is not a valid shared shaper ID, a new shared shaper
1278 * with this ID is created using the shaper profile identified by
1279 * *shaper_profile_id*.
1281 * When *shared_shaper_id* is a valid shared shaper ID, this shared shaper is
1282 * no longer using the shaper profile previously assigned to it and is updated
1283 * to use the shaper profile identified by *shaper_profile_id*.
1285 * @param[in] port_id
1286 * The port identifier of the Ethernet device.
1287 * @param[in] shared_shaper_id
1289 * @param[in] shaper_profile_id
1290 * Shaper profile ID. Needs to be the valid.
1292 * Error details. Filled in only on error, when not NULL.
1294 * 0 on success, non-zero error code otherwise.
1296 * @see struct rte_tm_capabilities::shaper_shared_n_max
1299 rte_tm_shared_shaper_add_update(uint8_t port_id,
1300 uint32_t shared_shaper_id,
1301 uint32_t shaper_profile_id,
1302 struct rte_tm_error *error);
1305 * Traffic manager shared shaper delete
1307 * Delete an existing shared shaper. This operation fails when there is
1308 * currently at least one user (i.e. hierarchy node) of this shared shaper.
1310 * @param[in] port_id
1311 * The port identifier of the Ethernet device.
1312 * @param[in] shared_shaper_id
1313 * Shared shaper ID. Needs to be the valid.
1315 * Error details. Filled in only on error, when not NULL.
1317 * 0 on success, non-zero error code otherwise.
1319 * @see struct rte_tm_capabilities::shaper_shared_n_max
1322 rte_tm_shared_shaper_delete(uint8_t port_id,
1323 uint32_t shared_shaper_id,
1324 struct rte_tm_error *error);
1327 * Traffic manager node add
1329 * Create new node and connect it as child of an existing node. The new node is
1330 * further identified by *node_id*, which needs to be unused by any of the
1331 * existing nodes. The parent node is identified by *parent_node_id*, which
1332 * needs to be the valid ID of an existing non-leaf node. The parent node is
1333 * going to use the provided SP *priority* and WFQ *weight* to schedule its new
1336 * This function has to be called for both leaf and non-leaf nodes. In the case
1337 * of leaf nodes (i.e. *node_id* is within the range of 0 .. (N-1), with N as
1338 * the number of configured TX queues of the current port), the leaf node is
1339 * configured rather than created (as the set of leaf nodes is predefined) and
1340 * it is also connected as child of an existing node.
1342 * The first node that is added becomes the root node and all the nodes that
1343 * are subsequently added have to be added as descendants of the root node. The
1344 * parent of the root node has to be specified as RTE_TM_NODE_ID_NULL and there
1345 * can only be one node with this parent ID (i.e. the root node). Further
1346 * restrictions for root node: needs to be non-leaf, its private shaper profile
1347 * needs to be valid and single rate, cannot use any shared shapers.
1349 * When called before rte_tm_hierarchy_commit() invocation, this function is
1350 * typically used to define the initial start-up hierarchy for the port.
1351 * Provided that dynamic hierarchy updates are supported by the current port (as
1352 * advertised in the port capability set), this function can be also called
1353 * after the rte_tm_hierarchy_commit() invocation.
1355 * @param[in] port_id
1356 * The port identifier of the Ethernet device.
1357 * @param[in] node_id
1358 * Node ID. Needs to be unused by any of the existing nodes.
1359 * @param[in] parent_node_id
1360 * Parent node ID. Needs to be the valid.
1361 * @param[in] priority
1362 * Node priority. The highest node priority is zero. Used by the SP algorithm
1363 * running on the parent of the current node for scheduling this child node.
1365 * Node weight. The node weight is relative to the weight sum of all siblings
1366 * that have the same priority. The lowest weight is one. Used by the WFQ
1367 * algorithm running on the parent of the current node for scheduling this
1369 * @param[in] level_id
1370 * Level ID that should be met by this node. The hierarchy level of the
1371 * current node is already fully specified through its parent node (i.e. the
1372 * level of this node is equal to the level of its parent node plus one),
1373 * therefore the reason for providing this parameter is to enable the
1374 * application to perform step-by-step checking of the node level during
1375 * successive invocations of this function. When not desired, this check can
1376 * be disabled by assigning value RTE_TM_NODE_LEVEL_ID_ANY to this parameter.
1378 * Node parameters. Needs to be pre-allocated and valid.
1380 * Error details. Filled in only on error, when not NULL.
1382 * 0 on success, non-zero error code otherwise.
1384 * @see rte_tm_hierarchy_commit()
1385 * @see RTE_TM_UPDATE_NODE_ADD_DELETE
1386 * @see RTE_TM_NODE_LEVEL_ID_ANY
1387 * @see struct rte_tm_capabilities
1390 rte_tm_node_add(uint8_t port_id,
1392 uint32_t parent_node_id,
1396 struct rte_tm_node_params *params,
1397 struct rte_tm_error *error);
1400 * Traffic manager node delete
1402 * Delete an existing node. This operation fails when this node currently has
1403 * at least one user (i.e. child node).
1405 * When called before rte_tm_hierarchy_commit() invocation, this function is
1406 * typically used to define the initial start-up hierarchy for the port.
1407 * Provided that dynamic hierarchy updates are supported by the current port (as
1408 * advertised in the port capability set), this function can be also called
1409 * after the rte_tm_hierarchy_commit() invocation.
1411 * @param[in] port_id
1412 * The port identifier of the Ethernet device.
1413 * @param[in] node_id
1414 * Node ID. Needs to be valid.
1416 * Error details. Filled in only on error, when not NULL.
1418 * 0 on success, non-zero error code otherwise.
1420 * @see RTE_TM_UPDATE_NODE_ADD_DELETE
1423 rte_tm_node_delete(uint8_t port_id,
1425 struct rte_tm_error *error);
1428 * Traffic manager node suspend
1430 * Suspend an existing node. While the node is in suspended state, no packet is
1431 * scheduled from this node and its descendants. The node exits the suspended
1432 * state through the node resume operation.
1434 * @param[in] port_id
1435 * The port identifier of the Ethernet device.
1436 * @param[in] node_id
1437 * Node ID. Needs to be valid.
1439 * Error details. Filled in only on error, when not NULL.
1441 * 0 on success, non-zero error code otherwise.
1443 * @see rte_tm_node_resume()
1444 * @see RTE_TM_UPDATE_NODE_SUSPEND_RESUME
1447 rte_tm_node_suspend(uint8_t port_id,
1449 struct rte_tm_error *error);
1452 * Traffic manager node resume
1454 * Resume an existing node that is currently in suspended state. The node
1455 * entered the suspended state as result of a previous node suspend operation.
1457 * @param[in] port_id
1458 * The port identifier of the Ethernet device.
1459 * @param[in] node_id
1460 * Node ID. Needs to be valid.
1462 * Error details. Filled in only on error, when not NULL.
1464 * 0 on success, non-zero error code otherwise.
1466 * @see rte_tm_node_suspend()
1467 * @see RTE_TM_UPDATE_NODE_SUSPEND_RESUME
1470 rte_tm_node_resume(uint8_t port_id,
1472 struct rte_tm_error *error);
1475 * Traffic manager hierarchy commit
1477 * This function is called during the port initialization phase (before the
1478 * Ethernet port is started) to freeze the start-up hierarchy.
1480 * This function typically performs the following steps:
1481 * a) It validates the start-up hierarchy that was previously defined for the
1482 * current port through successive rte_tm_node_add() invocations;
1483 * b) Assuming successful validation, it performs all the necessary port
1484 * specific configuration operations to install the specified hierarchy on
1485 * the current port, with immediate effect once the port is started.
1487 * This function fails when the currently configured hierarchy is not supported
1488 * by the Ethernet port, in which case the user can abort or try out another
1489 * hierarchy configuration (e.g. a hierarchy with less leaf nodes), which can be
1490 * build from scratch (when *clear_on_fail* is enabled) or by modifying the
1491 * existing hierarchy configuration (when *clear_on_fail* is disabled).
1493 * Note that this function can still fail due to other causes (e.g. not enough
1494 * memory available in the system, etc), even though the specified hierarchy is
1495 * supported in principle by the current port.
1497 * @param[in] port_id
1498 * The port identifier of the Ethernet device.
1499 * @param[in] clear_on_fail
1500 * On function call failure, hierarchy is cleared when this parameter is
1501 * non-zero and preserved when this parameter is equal to zero.
1503 * Error details. Filled in only on error, when not NULL.
1505 * 0 on success, non-zero error code otherwise.
1507 * @see rte_tm_node_add()
1508 * @see rte_tm_node_delete()
1511 rte_tm_hierarchy_commit(uint8_t port_id,
1513 struct rte_tm_error *error);
1516 * Traffic manager node parent update
1518 * Restriction for root node: its parent cannot be changed.
1520 * This function can only be called after the rte_tm_hierarchy_commit()
1521 * invocation. Its success depends on the port support for this operation, as
1522 * advertised through the port capability set.
1524 * @param[in] port_id
1525 * The port identifier of the Ethernet device.
1526 * @param[in] node_id
1527 * Node ID. Needs to be valid.
1528 * @param[in] parent_node_id
1529 * Node ID for the new parent. Needs to be valid.
1530 * @param[in] priority
1531 * Node priority. The highest node priority is zero. Used by the SP algorithm
1532 * running on the parent of the current node for scheduling this child node.
1534 * Node weight. The node weight is relative to the weight sum of all siblings
1535 * that have the same priority. The lowest weight is zero. Used by the WFQ
1536 * algorithm running on the parent of the current node for scheduling this
1539 * Error details. Filled in only on error, when not NULL.
1541 * 0 on success, non-zero error code otherwise.
1543 * @see RTE_TM_UPDATE_NODE_PARENT_KEEP_LEVEL
1544 * @see RTE_TM_UPDATE_NODE_PARENT_CHANGE_LEVEL
1547 rte_tm_node_parent_update(uint8_t port_id,
1549 uint32_t parent_node_id,
1552 struct rte_tm_error *error);
1555 * Traffic manager node private shaper update
1557 * Restriction for the root node: its private shaper profile needs to be valid
1560 * @param[in] port_id
1561 * The port identifier of the Ethernet device.
1562 * @param[in] node_id
1563 * Node ID. Needs to be valid.
1564 * @param[in] shaper_profile_id
1565 * Shaper profile ID for the private shaper of the current node. Needs to be
1566 * either valid shaper profile ID or RTE_TM_SHAPER_PROFILE_ID_NONE, with
1567 * the latter disabling the private shaper of the current node.
1569 * Error details. Filled in only on error, when not NULL.
1571 * 0 on success, non-zero error code otherwise.
1573 * @see struct rte_tm_capabilities::shaper_private_n_max
1576 rte_tm_node_shaper_update(uint8_t port_id,
1578 uint32_t shaper_profile_id,
1579 struct rte_tm_error *error);
1582 * Traffic manager node shared shapers update
1584 * Restriction for root node: cannot use any shared rate shapers.
1586 * @param[in] port_id
1587 * The port identifier of the Ethernet device.
1588 * @param[in] node_id
1589 * Node ID. Needs to be valid.
1590 * @param[in] shared_shaper_id
1591 * Shared shaper ID. Needs to be valid.
1593 * Set to non-zero value to add this shared shaper to current node or to zero
1594 * to delete this shared shaper from current node.
1596 * Error details. Filled in only on error, when not NULL.
1598 * 0 on success, non-zero error code otherwise.
1600 * @see struct rte_tm_capabilities::shaper_shared_n_max
1603 rte_tm_node_shared_shaper_update(uint8_t port_id,
1605 uint32_t shared_shaper_id,
1607 struct rte_tm_error *error);
1610 * Traffic manager node enabled statistics counters update
1612 * @param[in] port_id
1613 * The port identifier of the Ethernet device.
1614 * @param[in] node_id
1615 * Node ID. Needs to be valid.
1616 * @param[in] stats_mask
1617 * Mask of statistics counter types to be enabled for the current node. This
1618 * needs to be a subset of the statistics counter types available for the
1619 * current node. Any statistics counter type not included in this set is to
1620 * be disabled for the current node.
1622 * Error details. Filled in only on error, when not NULL.
1624 * 0 on success, non-zero error code otherwise.
1626 * @see enum rte_tm_stats_type
1627 * @see RTE_TM_UPDATE_NODE_STATS
1630 rte_tm_node_stats_update(uint8_t port_id,
1632 uint64_t stats_mask,
1633 struct rte_tm_error *error);
1636 * Traffic manager node WFQ weight mode update
1638 * @param[in] port_id
1639 * The port identifier of the Ethernet device.
1640 * @param[in] node_id
1641 * Node ID. Needs to be valid leaf node ID.
1642 * @param[in] wfq_weight_mode
1643 * WFQ weight mode for each SP priority. When NULL, it indicates that WFQ is
1644 * to be used for all priorities. When non-NULL, it points to a pre-allocated
1645 * array of *n_sp_priorities* values, with non-zero value for byte-mode and
1646 * zero for packet-mode.
1647 * @param[in] n_sp_priorities
1648 * Number of SP priorities.
1650 * Error details. Filled in only on error, when not NULL.
1652 * 0 on success, non-zero error code otherwise.
1654 * @see RTE_TM_UPDATE_NODE_WFQ_WEIGHT_MODE
1655 * @see RTE_TM_UPDATE_NODE_N_SP_PRIORITIES
1658 rte_tm_node_wfq_weight_mode_update(uint8_t port_id,
1660 int *wfq_weight_mode,
1661 uint32_t n_sp_priorities,
1662 struct rte_tm_error *error);
1665 * Traffic manager node congestion management mode update
1667 * @param[in] port_id
1668 * The port identifier of the Ethernet device.
1669 * @param[in] node_id
1670 * Node ID. Needs to be valid leaf node ID.
1672 * Congestion management mode.
1674 * Error details. Filled in only on error, when not NULL.
1676 * 0 on success, non-zero error code otherwise.
1678 * @see RTE_TM_UPDATE_NODE_CMAN
1681 rte_tm_node_cman_update(uint8_t port_id,
1683 enum rte_tm_cman_mode cman,
1684 struct rte_tm_error *error);
1687 * Traffic manager node private WRED context update
1689 * @param[in] port_id
1690 * The port identifier of the Ethernet device.
1691 * @param[in] node_id
1692 * Node ID. Needs to be valid leaf node ID.
1693 * @param[in] wred_profile_id
1694 * WRED profile ID for the private WRED context of the current node. Needs to
1695 * be either valid WRED profile ID or RTE_TM_WRED_PROFILE_ID_NONE, with the
1696 * latter disabling the private WRED context of the current node.
1698 * Error details. Filled in only on error, when not NULL.
1700 * 0 on success, non-zero error code otherwise.
1702 * @see struct rte_tm_capabilities::cman_wred_context_private_n_max
1705 rte_tm_node_wred_context_update(uint8_t port_id,
1707 uint32_t wred_profile_id,
1708 struct rte_tm_error *error);
1711 * Traffic manager node shared WRED context update
1713 * @param[in] port_id
1714 * The port identifier of the Ethernet device.
1715 * @param[in] node_id
1716 * Node ID. Needs to be valid leaf node ID.
1717 * @param[in] shared_wred_context_id
1718 * Shared WRED context ID. Needs to be valid.
1720 * Set to non-zero value to add this shared WRED context to current node or
1721 * to zero to delete this shared WRED context from current node.
1723 * Error details. Filled in only on error, when not NULL.
1725 * 0 on success, non-zero error code otherwise.
1727 * @see struct rte_tm_capabilities::cman_wred_context_shared_n_max
1730 rte_tm_node_shared_wred_context_update(uint8_t port_id,
1732 uint32_t shared_wred_context_id,
1734 struct rte_tm_error *error);
1737 * Traffic manager node statistics counters read
1739 * @param[in] port_id
1740 * The port identifier of the Ethernet device.
1741 * @param[in] node_id
1742 * Node ID. Needs to be valid.
1744 * When non-NULL, it contains the current value for the statistics counters
1745 * enabled for the current node.
1746 * @param[out] stats_mask
1747 * When non-NULL, it contains the mask of statistics counter types that are
1748 * currently enabled for this node, indicating which of the counters
1749 * retrieved with the *stats* structure are valid.
1751 * When this parameter has a non-zero value, the statistics counters are
1752 * cleared (i.e. set to zero) immediately after they have been read,
1753 * otherwise the statistics counters are left untouched.
1755 * Error details. Filled in only on error, when not NULL.
1757 * 0 on success, non-zero error code otherwise.
1759 * @see enum rte_tm_stats_type
1762 rte_tm_node_stats_read(uint8_t port_id,
1764 struct rte_tm_node_stats *stats,
1765 uint64_t *stats_mask,
1767 struct rte_tm_error *error);
1770 * Traffic manager packet marking - VLAN DEI (IEEE 802.1Q)
1772 * IEEE 802.1p maps the traffic class to the VLAN Priority Code Point (PCP)
1773 * field (3 bits), while IEEE 802.1q maps the drop priority to the VLAN Drop
1774 * Eligible Indicator (DEI) field (1 bit), which was previously named Canonical
1775 * Format Indicator (CFI).
1777 * All VLAN frames of a given color get their DEI bit set if marking is enabled
1778 * for this color; otherwise, their DEI bit is left as is (either set or not).
1780 * @param[in] port_id
1781 * The port identifier of the Ethernet device.
1782 * @param[in] mark_green
1783 * Set to non-zero value to enable marking of green packets and to zero to
1785 * @param[in] mark_yellow
1786 * Set to non-zero value to enable marking of yellow packets and to zero to
1788 * @param[in] mark_red
1789 * Set to non-zero value to enable marking of red packets and to zero to
1792 * Error details. Filled in only on error, when not NULL.
1794 * 0 on success, non-zero error code otherwise.
1796 * @see struct rte_tm_capabilities::mark_vlan_dei_supported
1799 rte_tm_mark_vlan_dei(uint8_t port_id,
1803 struct rte_tm_error *error);
1806 * Traffic manager packet marking - IPv4 / IPv6 ECN (IETF RFC 3168)
1808 * IETF RFCs 2474 and 3168 reorganize the IPv4 Type of Service (TOS) field
1809 * (8 bits) and the IPv6 Traffic Class (TC) field (8 bits) into Differentiated
1810 * Services Codepoint (DSCP) field (6 bits) and Explicit Congestion
1811 * Notification (ECN) field (2 bits). The DSCP field is typically used to
1812 * encode the traffic class and/or drop priority (RFC 2597), while the ECN
1813 * field is used by RFC 3168 to implement a congestion notification mechanism
1814 * to be leveraged by transport layer protocols such as TCP and SCTP that have
1815 * congestion control mechanisms.
1817 * When congestion is experienced, as alternative to dropping the packet,
1818 * routers can change the ECN field of input packets from 2'b01 or 2'b10
1819 * (values indicating that source endpoint is ECN-capable) to 2'b11 (meaning
1820 * that congestion is experienced). The destination endpoint can use the
1821 * ECN-Echo (ECE) TCP flag to relay the congestion indication back to the
1822 * source endpoint, which acknowledges it back to the destination endpoint with
1823 * the Congestion Window Reduced (CWR) TCP flag.
1825 * All IPv4/IPv6 packets of a given color with ECN set to 2’b01 or 2’b10
1826 * carrying TCP or SCTP have their ECN set to 2’b11 if the marking feature is
1827 * enabled for the current color, otherwise the ECN field is left as is.
1829 * @param[in] port_id
1830 * The port identifier of the Ethernet device.
1831 * @param[in] mark_green
1832 * Set to non-zero value to enable marking of green packets and to zero to
1834 * @param[in] mark_yellow
1835 * Set to non-zero value to enable marking of yellow packets and to zero to
1837 * @param[in] mark_red
1838 * Set to non-zero value to enable marking of red packets and to zero to
1841 * Error details. Filled in only on error, when not NULL.
1843 * 0 on success, non-zero error code otherwise.
1845 * @see struct rte_tm_capabilities::mark_ip_ecn_tcp_supported
1846 * @see struct rte_tm_capabilities::mark_ip_ecn_sctp_supported
1849 rte_tm_mark_ip_ecn(uint8_t port_id,
1853 struct rte_tm_error *error);
1856 * Traffic manager packet marking - IPv4 / IPv6 DSCP (IETF RFC 2597)
1858 * IETF RFC 2597 maps the traffic class and the drop priority to the IPv4/IPv6
1859 * Differentiated Services Codepoint (DSCP) field (6 bits). Here are the DSCP
1860 * values proposed by this RFC:
1862 * <pre> Class 1 Class 2 Class 3 Class 4 </pre>
1863 * <pre> +----------+----------+----------+----------+</pre>
1864 * <pre>Low Drop Prec | 001010 | 010010 | 011010 | 100010 |</pre>
1865 * <pre>Medium Drop Prec | 001100 | 010100 | 011100 | 100100 |</pre>
1866 * <pre>High Drop Prec | 001110 | 010110 | 011110 | 100110 |</pre>
1867 * <pre> +----------+----------+----------+----------+</pre>
1869 * There are 4 traffic classes (classes 1 .. 4) encoded by DSCP bits 1 and 2,
1870 * as well as 3 drop priorities (low/medium/high) encoded by DSCP bits 3 and 4.
1872 * All IPv4/IPv6 packets have their color marked into DSCP bits 3 and 4 as
1873 * follows: green mapped to Low Drop Precedence (2’b01), yellow to Medium
1874 * (2’b10) and red to High (2’b11). Marking needs to be explicitly enabled
1875 * for each color; when not enabled for a given color, the DSCP field of all
1876 * packets with that color is left as is.
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
1883 * @param[in] mark_yellow
1884 * Set to non-zero value to enable marking of yellow packets and to zero to
1886 * @param[in] mark_red
1887 * Set to non-zero value to enable marking of red packets and to zero to
1890 * Error details. Filled in only on error, when not NULL.
1892 * 0 on success, non-zero error code otherwise.
1894 * @see struct rte_tm_capabilities::mark_ip_dscp_supported
1897 rte_tm_mark_ip_dscp(uint8_t port_id,
1901 struct rte_tm_error *error);
1907 #endif /* __INCLUDE_RTE_TM_H__ */