doc/guides/nics/mvpp2.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Marvell International Ltd.
   3     Copyright(c) 2017 Semihalf.
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without
   7     modification, are permitted provided that the following conditions
   8     are met:
   9
  10       * Redistributions of source code must retain the above copyright
  11         notice, this list of conditions and the following disclaimer.
  12       * Redistributions in binary form must reproduce the above copyright
  13         notice, this list of conditions and the following disclaimer in
  14         the documentation and/or other materials provided with the
  15         distribution.
  16       * Neither the name of the copyright holder nor the names of its
  17         contributors may be used to endorse or promote products derived
  18         from this software without specific prior written permission.
  19
  20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31
  32 .. _mvpp2_poll_mode_driver:
  33
  34 MVPP2 Poll Mode Driver
  35 ======================
  36
  37 The MVPP2 PMD (librte_pmd_mvpp2) provides poll mode driver support
  38 for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter.
  39
  40 Detailed information about SoCs that use PPv2 can be obtained here:
  41
  42 * https://www.marvell.com/embedded-processors/armada-70xx/
  43 * https://www.marvell.com/embedded-processors/armada-80xx/
  44
  45 .. Note::
  46
  47    Due to external dependencies, this driver is disabled by default. It must
  48    be enabled manually by setting relevant configuration option manually.
  49    Please refer to `Config File Options`_ section for further details.
  50
  51
  52 Features
  53 --------
  54
  55 Features of the MVPP2 PMD are:
  56
  57 - Speed capabilities
  58 - Link status
  59 - Tx Queue start/stop
  60 - MTU update
  61 - Jumbo frame
  62 - Promiscuous mode
  63 - Allmulticast mode
  64 - Unicast MAC filter
  65 - Multicast MAC filter
  66 - RSS hash
  67 - VLAN filter
  68 - CRC offload
  69 - L3 checksum offload
  70 - L4 checksum offload
  71 - Packet type parsing
  72 - Basic stats
  73 - :ref:`Extended stats <extstats>`
  74 - RX flow control
  75 - Scattered TX frames
  76 - :ref:`QoS <qossupport>`
  77 - :ref:`Flow API <flowapi>`
  78 - :ref:`Traffic metering and policing <mtrapi>`
  79 - :ref:`Traffic Management API <tmapi>`
  80
  81 Limitations
  82 -----------
  83
  84 - Number of lcores is limited to 9 by MUSDK internal design. If more lcores
  85   need to be allocated, locking will have to be considered. Number of available
  86   lcores can be changed via ``MRVL_MUSDK_HIFS_RESERVED`` define in
  87   ``mrvl_ethdev.c`` source file.
  88
  89 - Flushing vlans added for filtering is not possible due to MUSDK missing
  90   functionality. Current workaround is to reset board so that PPv2 has a
  91   chance to start in a sane state.
  92
  93 - MUSDK architecture does not support changing configuration in run time.
  94   All nessesary configurations should be done before first dev_start().
  95
  96 - RX queue start/stop is not supported.
  97
  98 - Current implementation does not support replacement of buffers in the HW buffer pool
  99   at run time, so it is responsibility of the application to ensure that MTU does not exceed the configured buffer size.
 100
 101 - Configuring TX flow control currently is not supported.
 102
 103 - In current implementation, mechanism for acknowledging transmitted packets (``tx_done_cleanup``) is not supported.
 104
 105 - Running more than one DPDK-MUSDK application simultaneously is not supported.
 106
 107
 108 Prerequisites
 109 -------------
 110
 111 - Custom Linux Kernel sources
 112
 113   .. code-block:: console
 114
 115      git clone https://github.com/MarvellEmbeddedProcessors/linux-marvell.git -b linux-4.4.120-armada-18.09
 116
 117 - Out of tree `mvpp2x_sysfs` kernel module sources
 118
 119   .. code-block:: console
 120
 121      git clone https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell.git -b mvpp2x-armada-18.09
 122
 123 - MUSDK (Marvell User-Space SDK) sources
 124
 125   .. code-block:: console
 126
 127      git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-18.09
 128
 129   MUSDK is a light-weight library that provides direct access to Marvell's
 130   PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
 131   requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
 132   approval has been granted, library can be found by typing ``musdk`` in
 133   the search box.
 134
 135   To get better understanding of the library one can consult documentation
 136   available in the ``doc`` top level directory of the MUSDK sources.
 137
 138 - DPDK environment
 139
 140   Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
 141   DPDK environment.
 142
 143
 144 Config File Options
 145 -------------------
 146
 147 The following options can be modified in the ``config`` file.
 148
 149 - ``CONFIG_RTE_LIBRTE_MVPP2_PMD`` (default ``n``)
 150
 151     Toggle compilation of the librte mvpp2 driver.
 152
 153     .. Note::
 154
 155        When MVPP2 PMD is enabled ``CONFIG_RTE_LIBRTE_MVNETA_PMD`` must be disabled
 156
 157
 158 Building DPDK
 159 -------------
 160
 161 Driver needs precompiled MUSDK library during compilation.
 162
 163 .. code-block:: console
 164
 165    export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
 166    ./bootstrap
 167    ./configure --host=aarch64-linux-gnu
 168    make install
 169
 170 MUSDK will be installed to `usr/local` under current directory.
 171 For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
 172
 173 Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
 174 the path to the MUSDK installation directory needs to be exported.
 175
 176 For additional instructions regarding DPDK cross compilation please refer to :doc:`Cross compile DPDK for ARM64 <../linux_gsg/cross_build_dpdk_for_arm64>`.
 177
 178 .. code-block:: console
 179
 180    export LIBMUSDK_PATH=<musdk>/usr/local
 181    export CROSS=<toolchain>/bin/aarch64-linux-gnu-
 182    export RTE_KERNELDIR=<kernel-dir>
 183    export RTE_TARGET=arm64-armv8a-linuxapp-gcc
 184
 185    make config T=arm64-armv8a-linuxapp-gcc
 186    sed -i "s/MVNETA_PMD=y/MVNETA_PMD=n/" build/.config
 187    sed -i "s/MVPP2_PMD=n/MVPP2_PMD=y/" build/.config
 188    make
 189
 190 Usage Example
 191 -------------
 192
 193 MVPP2 PMD requires extra out of tree kernel modules to function properly.
 194 `musdk_cma` sources are part of the MUSDK. Please consult
 195 ``doc/musdk_get_started.txt`` for the detailed build instructions.
 196 For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
 197 detailed build instructions.
 198
 199 .. code-block:: console
 200
 201    insmod musdk_cma.ko
 202    insmod mvpp2x_sysfs.ko
 203
 204 Additionally interfaces used by DPDK application need to be put up:
 205
 206 .. code-block:: console
 207
 208    ip link set eth0 up
 209    ip link set eth2 up
 210
 211 In order to run testpmd example application following command can be used:
 212
 213 .. code-block:: console
 214
 215    ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 7 -- \
 216      --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2  --nb-cores=2 \
 217      -i -a --rss-udp
 218
 219 .. _extstats:
 220
 221 Extended stats
 222 --------------
 223
 224 MVPP2 PMD supports the following extended statistics:
 225
 226         - ``rx_bytes``: number of RX bytes
 227         - ``rx_packets``: number of RX packets
 228         - ``rx_unicast_packets``: number of RX unicast packets
 229         - ``rx_errors``: number of RX MAC errors
 230         - ``rx_fullq_dropped``: number of RX packets dropped due to full RX queue
 231         - ``rx_bm_dropped``: number of RX packets dropped due to no available buffers in the HW pool
 232         - ``rx_early_dropped``: number of RX packets that were early dropped
 233         - ``rx_fifo_dropped``: number of RX packets dropped due to RX fifo overrun
 234         - ``rx_cls_dropped``: number of RX packets dropped by classifier
 235         - ``tx_bytes``: number of TX bytes
 236         - ``tx_packets``: number of TX packets
 237         - ``tx_unicast_packets``: number of TX unicast packets
 238         - ``tx_errors``: number of TX MAC errors
 239
 240
 241 .. _qossupport:
 242
 243 QoS Configuration
 244 -----------------
 245
 246 QoS configuration is done through external configuration file. Path to the
 247 file must be given as `cfg` in driver's vdev parameter list.
 248
 249 Configuration syntax
 250 ~~~~~~~~~~~~~~~~~~~~
 251
 252 .. code-block:: console
 253
 254    [policer <policer_id>]
 255    token_unit = <token_unit>
 256    color = <color_mode>
 257    cir = <cir>
 258    ebs = <ebs>
 259    cbs = <cbs>
 260
 261    [port <portnum> default]
 262    default_tc = <default_tc>
 263    mapping_priority = <mapping_priority>
 264
 265    rate_limit_enable = <rate_limit_enable>
 266    rate_limit = <rate_limit>
 267    burst_size = <burst_size>
 268
 269    default_policer = <policer_id>
 270
 271    [port <portnum> tc <traffic_class>]
 272    rxq = <rx_queue_list>
 273    pcp = <pcp_list>
 274    dscp = <dscp_list>
 275    default_color = <default_color>
 276
 277    [port <portnum> tc <traffic_class>]
 278    rxq = <rx_queue_list>
 279    pcp = <pcp_list>
 280    dscp = <dscp_list>
 281
 282    [port <portnum> txq <txqnum>]
 283    sched_mode = <sched_mode>
 284    wrr_weight = <wrr_weight>
 285
 286    rate_limit_enable = <rate_limit_enable>
 287    rate_limit = <rate_limit>
 288    burst_size = <burst_size>
 289
 290 Where:
 291
 292 - ``<portnum>``: DPDK Port number (0..n).
 293
 294 - ``<default_tc>``: Default traffic class (e.g. 0)
 295
 296 - ``<mapping_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
 297
 298 - ``<traffic_class>``: Traffic Class to be configured.
 299
 300 - ``<rx_queue_list>``: List of DPDK RX queues (e.g. 0 1 3-4)
 301
 302 - ``<pcp_list>``: List of PCP values to handle in particular TC (e.g. 0 1 3-4 7).
 303
 304 - ``<dscp_list>``: List of DSCP values to handle in particular TC (e.g. 0-12 32-48 63).
 305
 306 - ``<default_policer>``: Id of the policer configuration section to be used as default.
 307
 308 - ``<policer_id>``: Id of the policer configuration section (0..31).
 309
 310 - ``<token_unit>``: Policer token unit (`bytes` or `packets`).
 311
 312 - ``<color_mode>``: Policer color mode (`aware` or `blind`).
 313
 314 - ``<cir>``: Committed information rate in unit of kilo bits per second (data rate) or packets per second.
 315
 316 - ``<cbs>``: Committed burst size in unit of kilo bytes or number of packets.
 317
 318 - ``<ebs>``: Excess burst size in unit of kilo bytes or number of packets.
 319
 320 - ``<default_color>``: Default color for specific tc.
 321
 322 - ``<rate_limit_enable>``: Enables per port or per txq rate limiting (`0`/`1` to disable/enable).
 323
 324 - ``<rate_limit>``: Committed information rate, in kilo bits per second.
 325
 326 - ``<burst_size>``: Committed burst size, in kilo bytes.
 327
 328 - ``<sched_mode>``: Egress scheduler mode (`wrr` or `sp`).
 329
 330 - ``<wrr_weight>``: Txq weight.
 331
 332 Setting PCP/DSCP values for the default TC is not required. All PCP/DSCP
 333 values not assigned explicitly to particular TC will be handled by the
 334 default TC.
 335
 336 Configuration file example
 337 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 338
 339 .. code-block:: console
 340
 341    [policer 0]
 342    token_unit = bytes
 343    color = blind
 344    cir = 100000
 345    ebs = 64
 346    cbs = 64
 347
 348    [port 0 default]
 349    default_tc = 0
 350    mapping_priority = ip
 351
 352    rate_limit_enable = 1
 353    rate_limit = 1000
 354    burst_size = 2000
 355
 356    [port 0 tc 0]
 357    rxq = 0 1
 358
 359    [port 0 txq 0]
 360    sched_mode = wrr
 361    wrr_weight = 10
 362
 363    [port 0 txq 1]
 364    sched_mode = wrr
 365    wrr_weight = 100
 366
 367    [port 0 txq 2]
 368    sched_mode = sp
 369
 370    [port 0 tc 1]
 371    rxq = 2
 372    pcp = 5 6 7
 373    dscp = 26-38
 374
 375    [port 1 default]
 376    default_tc = 0
 377    mapping_priority = vlan/ip
 378
 379    default_policer = 0
 380
 381    [port 1 tc 0]
 382    rxq = 0
 383    dscp = 10
 384
 385    [port 1 tc 1]
 386    rxq = 1
 387    dscp = 11-20
 388
 389    [port 1 tc 2]
 390    rxq = 2
 391    dscp = 30
 392
 393    [port 1 txq 0]
 394    rate_limit_enable = 1
 395    rate_limit = 10000
 396    burst_size = 2000
 397
 398 Usage example
 399 ^^^^^^^^^^^^^
 400
 401 .. code-block:: console
 402
 403    ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
 404      -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3
 405
 406 .. _flowapi:
 407
 408 Flow API
 409 --------
 410
 411 PPv2 offers packet classification capabilities via classifier engine which
 412 can be configured via generic flow API offered by DPDK.
 413 For an additional description please refer to DPDK :ref:`Generic flow API <Generic_flow_API>`.
 414
 415 Supported flow actions
 416 ~~~~~~~~~~~~~~~~~~~~~~
 417
 418 Following flow action items are supported by the driver:
 419
 420 * DROP
 421 * QUEUE
 422
 423 Supported flow items
 424 ~~~~~~~~~~~~~~~~~~~~
 425
 426 Following flow items and their respective fields are supported by the driver:
 427
 428 * ETH
 429
 430   * source MAC
 431   * destination MAC
 432   * ethertype
 433
 434 * VLAN
 435
 436   * PCP
 437   * VID
 438
 439 * IPV4
 440
 441   * DSCP
 442   * protocol
 443   * source address
 444   * destination address
 445
 446 * IPV6
 447
 448   * flow label
 449   * next header
 450   * source address
 451   * destination address
 452
 453 * UDP
 454
 455   * source port
 456   * destination port
 457
 458 * TCP
 459
 460   * source port
 461   * destination port
 462
 463 Classifier match engine
 464 ~~~~~~~~~~~~~~~~~~~~~~~
 465
 466 Classifier has an internal match engine which can be configured to
 467 operate in either exact or maskable mode.
 468
 469 Mode is selected upon creation of the first unique flow rule as follows:
 470
 471 * maskable, if key size is up to 8 bytes.
 472 * exact, otherwise, i.e for keys bigger than 8 bytes.
 473
 474 Where the key size equals the number of bytes of all fields specified
 475 in the flow items.
 476
 477 .. table:: Examples of key size calculation
 478
 479    +----------------------------------------------------------------------------+-------------------+-------------+
 480    | Flow pattern                                                               | Key size in bytes | Used engine |
 481    +============================================================================+===================+=============+
 482    | ETH (destination MAC) / VLAN (VID)                                         | 6 + 2 = 8         | Maskable    |
 483    +----------------------------------------------------------------------------+-------------------+-------------+
 484    | VLAN (VID) / IPV4 (source address)                                         | 2 + 4 = 6         | Maskable    |
 485    +----------------------------------------------------------------------------+-------------------+-------------+
 486    | TCP (source port, destination port)                                        | 2 + 2 = 4         | Maskable    |
 487    +----------------------------------------------------------------------------+-------------------+-------------+
 488    | VLAN (priority) / IPV4 (source address)                                    | 1 + 4 = 5         | Maskable    |
 489    +----------------------------------------------------------------------------+-------------------+-------------+
 490    | IPV4 (destination address) / UDP (source port, destination port)           | 6 + 2 + 2 = 10    | Exact       |
 491    +----------------------------------------------------------------------------+-------------------+-------------+
 492    | VLAN (VID) / IPV6 (flow label, destination address)                        | 2 + 3 + 16 = 21   | Exact       |
 493    +----------------------------------------------------------------------------+-------------------+-------------+
 494    | IPV4 (DSCP, source address, destination address)                           | 1 + 4 + 4 = 9     | Exact       |
 495    +----------------------------------------------------------------------------+-------------------+-------------+
 496    | IPV6 (flow label, source address, destination address)                     | 3 + 16 + 16 = 35  | Exact       |
 497    +----------------------------------------------------------------------------+-------------------+-------------+
 498
 499 From the user perspective maskable mode means that masks specified
 500 via flow rules are respected. In case of exact match mode, masks
 501 which do not provide exact matching (all bits masked) are ignored.
 502
 503 If the flow matches more than one classifier rule the first
 504 (with the lowest index) matched takes precedence.
 505
 506 Flow rules usage example
 507 ~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509 Before proceeding run testpmd user application:
 510
 511 .. code-block:: console
 512
 513    ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 3 -- -i --p 3 -a --disable-hw-vlan-strip
 514
 515 Example #1
 516 ^^^^^^^^^^
 517
 518 .. code-block:: console
 519
 520    testpmd> flow create 0 ingress pattern eth src is 10:11:12:13:14:15 / end actions drop / end
 521
 522 In this case key size is 6 bytes thus maskable type is selected. Testpmd
 523 will set mask to ff:ff:ff:ff:ff:ff i.e traffic explicitly matching
 524 above rule will be dropped.
 525
 526 Example #2
 527 ^^^^^^^^^^
 528
 529 .. code-block:: console
 530
 531    testpmd> flow create 0 ingress pattern ipv4 src spec 10.10.10.0 src mask 255.255.255.0 / tcp src spec 0x10 src mask 0x10 / end action drop / end
 532
 533 In this case key size is 8 bytes thus maskable type is selected.
 534 Flows which have IPv4 source addresses ranging from 10.10.10.0 to 10.10.10.255
 535 and tcp source port set to 16 will be dropped.
 536
 537 Example #3
 538 ^^^^^^^^^^
 539
 540 .. code-block:: console
 541
 542    testpmd> flow create 0 ingress pattern vlan vid spec 0x10 vid mask 0x10 / ipv4 src spec 10.10.1.1 src mask 255.255.0.0 dst spec 11.11.11.1 dst mask 255.255.255.0 / end actions drop / end
 543
 544 In this case key size is 10 bytes thus exact type is selected.
 545 Even though each item has partial mask set, masks will be ignored.
 546 As a result only flows with VID set to 16 and IPv4 source and destination
 547 addresses set to 10.10.1.1 and 11.11.11.1 respectively will be dropped.
 548
 549 Limitations
 550 ~~~~~~~~~~~
 551
 552 Following limitations need to be taken into account while creating flow rules:
 553
 554 * For IPv4 exact match type the key size must be up to 12 bytes.
 555 * For IPv6 exact match type the key size must be up to 36 bytes.
 556 * Following fields cannot be partially masked (all masks are treated as
 557   if they were exact):
 558
 559   * ETH: ethertype
 560   * VLAN: PCP, VID
 561   * IPv4: protocol
 562   * IPv6: next header
 563   * TCP/UDP: source port, destination port
 564
 565 * Only one classifier table can be created thus all rules in the table
 566   have to match table format. Table format is set during creation of
 567   the first unique flow rule.
 568 * Up to 5 fields can be specified per flow rule.
 569 * Up to 20 flow rules can be added.
 570
 571 For additional information about classifier please consult
 572 ``doc/musdk_cls_user_guide.txt``.
 573
 574 .. _mtrapi:
 575
 576 Traffic metering and policing
 577 -----------------------------
 578
 579 MVPP2 PMD supports DPDK traffic metering and policing that allows the following:
 580
 581 1. Meter ingress traffic.
 582 2. Do policing.
 583 3. Gather statistics.
 584
 585 For an additional description please refer to DPDK :doc:`Traffic Metering and Policing API <../prog_guide/traffic_metering_and_policing>`.
 586
 587 The policer objects defined by this feature can work with the default policer defined via config file as described in :ref:`QoS Support <qossupport>`.
 588
 589 Limitations
 590 ~~~~~~~~~~~
 591
 592 The following capabilities are not supported:
 593
 594 - MTR object meter DSCP table update
 595 - MTR object policer action update
 596 - MTR object enabled statistics
 597
 598 Usage example
 599 ~~~~~~~~~~~~~
 600
 601 1. Run testpmd user app:
 602
 603    .. code-block:: console
 604
 605                 ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 6 -- -i -p 3 -a --txd 1024 --rxd 1024
 606
 607 2. Create meter profile:
 608
 609    .. code-block:: console
 610
 611                 testpmd> add port meter profile 0 0 srtcm_rfc2697 2000 256 256
 612
 613 3. Create meter:
 614
 615    .. code-block:: console
 616
 617                 testpmd> create port meter 0 0 0 yes d d d 0 1 0
 618
 619 4. Create flow rule witch meter attached:
 620
 621    .. code-block:: console
 622
 623                 testpmd> flow create 0 ingress pattern ipv4 src is 10.10.10.1 / end actions meter mtr_id 0 / end
 624
 625 For a detailed usage description please refer to "Traffic Metering and Policing" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 626
 627
 628
 629 .. _tmapi:
 630
 631 Traffic Management API
 632 ----------------------
 633
 634 MVPP2 PMD supports generic DPDK Traffic Management API which allows to
 635 configure the following features:
 636
 637 1. Hierarchical scheduling
 638 2. Traffic shaping
 639 3. Congestion management
 640 4. Packet marking
 641
 642 Internally TM is represented by a hierarchy (tree) of nodes.
 643 Node which has a parent is called a leaf whereas node without
 644 parent is called a non-leaf (root).
 645 MVPP2 PMD supports two level hierarchy where level 0 represents ports and level 1 represents tx queues of a given port.
 646
 647 .. figure:: img/mvpp2_tm.svg
 648
 649 Nodes hold following types of settings:
 650
 651 - for egress scheduler configuration: weight
 652 - for egress rate limiter: private shaper
 653 - bitmask indicating which statistics counters will be read
 654
 655 Hierarchy is always constructed from the top, i.e first a root node is added
 656 then some number of leaf nodes. Number of leaf nodes cannot exceed number
 657 of configured tx queues.
 658
 659 After hierarchy is complete it can be committed.
 660
 661
 662 For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`.
 663
 664 Limitations
 665 ~~~~~~~~~~~
 666
 667 The following capabilities are not supported:
 668
 669 - Traffic manager WRED profile and WRED context
 670 - Traffic manager shared shaper update
 671 - Traffic manager packet marking
 672 - Maximum number of levels in hierarchy is 2
 673 - Currently dynamic change of a hierarchy is not supported
 674
 675 Usage example
 676 ~~~~~~~~~~~~~
 677
 678 For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 679
 680 1. Run testpmd as follows:
 681
 682    .. code-block:: console
 683
 684                 ./testpmd --vdev=net_mrvl,iface=eth0,iface=eth2,cfg=./qos_config -c 7 -- \
 685                 -i -p 3 --disable-hw-vlan-strip --rxq 3 --txq 3 --txd 1024 --rxd 1024
 686
 687 2. Stop all ports:
 688
 689    .. code-block:: console
 690
 691                 testpmd> port stop all
 692
 693 3. Add shaper profile:
 694
 695    .. code-block:: console
 696
 697                 testpmd> add port tm node shaper profile 0 0 900000 70000 0
 698
 699    Parameters have following meaning::
 700
 701                 0       - Id of a port.
 702                 0       - Id of a new shaper profile.
 703                 900000  - Shaper rate in bytes/s.
 704                 70000   - Bucket size in bytes.
 705                 0       - Packet length adjustment - ignored.
 706
 707 4. Add non-leaf node for port 0:
 708
 709    .. code-block:: console
 710
 711                 testpmd> add port tm nonleaf node 0 3 -1 0 0 0 0 0 1 3 0
 712
 713    Parameters have following meaning::
 714
 715                  0  - Id of a port
 716                  3  - Id of a new node.
 717                 -1  - Indicate that root does not have a parent.
 718                  0  - Priority of the node.
 719                  0  - Weight of the node.
 720                  0  - Id of a level. Since this is a root 0 is passed.
 721                  0  - Id of the shaper profile.
 722                  0  - Number of SP priorities.
 723                  3  - Enable statistics for both number of transmitted packets and bytes.
 724                  0  - Number of shared shapers.
 725
 726 5. Add leaf node for tx queue 0:
 727
 728    .. code-block:: console
 729
 730                 testpmd> add port tm leaf node 0 0 3 0 30 1 -1 0 0 1 0
 731
 732    Parameters have following meaning::
 733
 734                  0  - Id of a port.
 735                  0  - Id of a new node.
 736                  3  - Id of the parent node.
 737                  0  - Priority of a node.
 738                  30 - WRR weight.
 739                  1  - Id of a level. Since this is a leaf node 1 is passed.
 740                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 741                  0  - Congestion management is not supported.
 742                  0  - Congestion management is not supported.
 743                  1  - Enable statistics counter for number of transmitted packets.
 744                  0  - Number of shared shapers.
 745
 746 6. Add leaf node for tx queue 1:
 747
 748    .. code-block:: console
 749
 750         testpmd> add port tm leaf node 0 1 3 0 60 1 -1 0 0 1 0
 751
 752    Parameters have following meaning::
 753
 754                  0  - Id of a port.
 755                  1  - Id of a new node.
 756                  3  - Id of the parent node.
 757                  0  - Priority of a node.
 758                  60 - WRR weight.
 759                  1  - Id of a level. Since this is a leaf node 1 is passed.
 760                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 761                  0  - Congestion management is not supported.
 762                  0  - Congestion management is not supported.
 763                  1  - Enable statistics counter for number of transmitted packets.
 764                  0  - Number of shared shapers.
 765
 766 7. Add leaf node for tx queue 2:
 767
 768    .. code-block:: console
 769
 770                 testpmd> add port tm leaf node 0 2 3 0 99 1 -1 0 0 1 0
 771
 772    Parameters have following meaning::
 773
 774                  0  - Id of a port.
 775                  2  - Id of a new node.
 776                  3  - Id of the parent node.
 777                  0  - Priority of a node.
 778                  99 - WRR weight.
 779                  1  - Id of a level. Since this is a leaf node 1 is passed.
 780                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 781                  0  - Congestion management is not supported.
 782                  0  - Congestion management is not supported.
 783                  1  - Enable statistics counter for number of transmitted packets.
 784                  0  - Number of shared shapers.
 785
 786 8. Commit hierarchy:
 787
 788    .. code-block:: console
 789
 790                 testpmd> port tm hierarchy commit 0 no
 791
 792   Parameters have following meaning::
 793
 794                 0  - Id of a port.
 795                 no - Do not flush TM hierarchy if commit fails.
 796
 797 9. Start all ports
 798
 799    .. code-block:: console
 800
 801                 testpmd> port start all
 802
 803
 804
 805 10. Enable forwarding
 806
 807    .. code-block:: console
 808
 809                 testpmd> start