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-linux-gcc
 184
 185    make config T=arm64-armv8a-linux-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
 414 The :ref:`flow_isolated_mode` is supported.
 415
 416 For an additional description please refer to DPDK :doc:`../prog_guide/rte_flow`.
 417
 418 Supported flow actions
 419 ~~~~~~~~~~~~~~~~~~~~~~
 420
 421 Following flow action items are supported by the driver:
 422
 423 * DROP
 424 * QUEUE
 425
 426 Supported flow items
 427 ~~~~~~~~~~~~~~~~~~~~
 428
 429 Following flow items and their respective fields are supported by the driver:
 430
 431 * ETH
 432
 433   * source MAC
 434   * destination MAC
 435   * ethertype
 436
 437 * VLAN
 438
 439   * PCP
 440   * VID
 441
 442 * IPV4
 443
 444   * DSCP
 445   * protocol
 446   * source address
 447   * destination address
 448
 449 * IPV6
 450
 451   * flow label
 452   * next header
 453   * source address
 454   * destination address
 455
 456 * UDP
 457
 458   * source port
 459   * destination port
 460
 461 * TCP
 462
 463   * source port
 464   * destination port
 465
 466 Classifier match engine
 467 ~~~~~~~~~~~~~~~~~~~~~~~
 468
 469 Classifier has an internal match engine which can be configured to
 470 operate in either exact or maskable mode.
 471
 472 Mode is selected upon creation of the first unique flow rule as follows:
 473
 474 * maskable, if key size is up to 8 bytes.
 475 * exact, otherwise, i.e for keys bigger than 8 bytes.
 476
 477 Where the key size equals the number of bytes of all fields specified
 478 in the flow items.
 479
 480 .. table:: Examples of key size calculation
 481
 482    +----------------------------------------------------------------------------+-------------------+-------------+
 483    | Flow pattern                                                               | Key size in bytes | Used engine |
 484    +============================================================================+===================+=============+
 485    | ETH (destination MAC) / VLAN (VID)                                         | 6 + 2 = 8         | Maskable    |
 486    +----------------------------------------------------------------------------+-------------------+-------------+
 487    | VLAN (VID) / IPV4 (source address)                                         | 2 + 4 = 6         | Maskable    |
 488    +----------------------------------------------------------------------------+-------------------+-------------+
 489    | TCP (source port, destination port)                                        | 2 + 2 = 4         | Maskable    |
 490    +----------------------------------------------------------------------------+-------------------+-------------+
 491    | VLAN (priority) / IPV4 (source address)                                    | 1 + 4 = 5         | Maskable    |
 492    +----------------------------------------------------------------------------+-------------------+-------------+
 493    | IPV4 (destination address) / UDP (source port, destination port)           | 6 + 2 + 2 = 10    | Exact       |
 494    +----------------------------------------------------------------------------+-------------------+-------------+
 495    | VLAN (VID) / IPV6 (flow label, destination address)                        | 2 + 3 + 16 = 21   | Exact       |
 496    +----------------------------------------------------------------------------+-------------------+-------------+
 497    | IPV4 (DSCP, source address, destination address)                           | 1 + 4 + 4 = 9     | Exact       |
 498    +----------------------------------------------------------------------------+-------------------+-------------+
 499    | IPV6 (flow label, source address, destination address)                     | 3 + 16 + 16 = 35  | Exact       |
 500    +----------------------------------------------------------------------------+-------------------+-------------+
 501
 502 From the user perspective maskable mode means that masks specified
 503 via flow rules are respected. In case of exact match mode, masks
 504 which do not provide exact matching (all bits masked) are ignored.
 505
 506 If the flow matches more than one classifier rule the first
 507 (with the lowest index) matched takes precedence.
 508
 509 Flow rules usage example
 510 ~~~~~~~~~~~~~~~~~~~~~~~~
 511
 512 Before proceeding run testpmd user application:
 513
 514 .. code-block:: console
 515
 516    ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 3 -- -i --p 3 -a --disable-hw-vlan-strip
 517
 518 Example #1
 519 ^^^^^^^^^^
 520
 521 .. code-block:: console
 522
 523    testpmd> flow create 0 ingress pattern eth src is 10:11:12:13:14:15 / end actions drop / end
 524
 525 In this case key size is 6 bytes thus maskable type is selected. Testpmd
 526 will set mask to ff:ff:ff:ff:ff:ff i.e traffic explicitly matching
 527 above rule will be dropped.
 528
 529 Example #2
 530 ^^^^^^^^^^
 531
 532 .. code-block:: console
 533
 534    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
 535
 536 In this case key size is 8 bytes thus maskable type is selected.
 537 Flows which have IPv4 source addresses ranging from 10.10.10.0 to 10.10.10.255
 538 and tcp source port set to 16 will be dropped.
 539
 540 Example #3
 541 ^^^^^^^^^^
 542
 543 .. code-block:: console
 544
 545    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
 546
 547 In this case key size is 10 bytes thus exact type is selected.
 548 Even though each item has partial mask set, masks will be ignored.
 549 As a result only flows with VID set to 16 and IPv4 source and destination
 550 addresses set to 10.10.1.1 and 11.11.11.1 respectively will be dropped.
 551
 552 Limitations
 553 ~~~~~~~~~~~
 554
 555 Following limitations need to be taken into account while creating flow rules:
 556
 557 * For IPv4 exact match type the key size must be up to 12 bytes.
 558 * For IPv6 exact match type the key size must be up to 36 bytes.
 559 * Following fields cannot be partially masked (all masks are treated as
 560   if they were exact):
 561
 562   * ETH: ethertype
 563   * VLAN: PCP, VID
 564   * IPv4: protocol
 565   * IPv6: next header
 566   * TCP/UDP: source port, destination port
 567
 568 * Only one classifier table can be created thus all rules in the table
 569   have to match table format. Table format is set during creation of
 570   the first unique flow rule.
 571 * Up to 5 fields can be specified per flow rule.
 572 * Up to 20 flow rules can be added.
 573
 574 For additional information about classifier please consult
 575 ``doc/musdk_cls_user_guide.txt``.
 576
 577 .. _mtrapi:
 578
 579 Traffic metering and policing
 580 -----------------------------
 581
 582 MVPP2 PMD supports DPDK traffic metering and policing that allows the following:
 583
 584 1. Meter ingress traffic.
 585 2. Do policing.
 586 3. Gather statistics.
 587
 588 For an additional description please refer to DPDK :doc:`Traffic Metering and Policing API <../prog_guide/traffic_metering_and_policing>`.
 589
 590 The policer objects defined by this feature can work with the default policer defined via config file as described in :ref:`QoS Support <qossupport>`.
 591
 592 Limitations
 593 ~~~~~~~~~~~
 594
 595 The following capabilities are not supported:
 596
 597 - MTR object meter DSCP table update
 598 - MTR object policer action update
 599 - MTR object enabled statistics
 600
 601 Usage example
 602 ~~~~~~~~~~~~~
 603
 604 1. Run testpmd user app:
 605
 606    .. code-block:: console
 607
 608                 ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 6 -- -i -p 3 -a --txd 1024 --rxd 1024
 609
 610 2. Create meter profile:
 611
 612    .. code-block:: console
 613
 614                 testpmd> add port meter profile 0 0 srtcm_rfc2697 2000 256 256
 615
 616 3. Create meter:
 617
 618    .. code-block:: console
 619
 620                 testpmd> create port meter 0 0 0 yes d d d 0 1 0
 621
 622 4. Create flow rule witch meter attached:
 623
 624    .. code-block:: console
 625
 626                 testpmd> flow create 0 ingress pattern ipv4 src is 10.10.10.1 / end actions meter mtr_id 0 / end
 627
 628 For a detailed usage description please refer to "Traffic Metering and Policing" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 629
 630
 631
 632 .. _tmapi:
 633
 634 Traffic Management API
 635 ----------------------
 636
 637 MVPP2 PMD supports generic DPDK Traffic Management API which allows to
 638 configure the following features:
 639
 640 1. Hierarchical scheduling
 641 2. Traffic shaping
 642 3. Congestion management
 643 4. Packet marking
 644
 645 Internally TM is represented by a hierarchy (tree) of nodes.
 646 Node which has a parent is called a leaf whereas node without
 647 parent is called a non-leaf (root).
 648 MVPP2 PMD supports two level hierarchy where level 0 represents ports and level 1 represents tx queues of a given port.
 649
 650 .. figure:: img/mvpp2_tm.*
 651
 652 Nodes hold following types of settings:
 653
 654 - for egress scheduler configuration: weight
 655 - for egress rate limiter: private shaper
 656 - bitmask indicating which statistics counters will be read
 657
 658 Hierarchy is always constructed from the top, i.e first a root node is added
 659 then some number of leaf nodes. Number of leaf nodes cannot exceed number
 660 of configured tx queues.
 661
 662 After hierarchy is complete it can be committed.
 663
 664
 665 For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`.
 666
 667 Limitations
 668 ~~~~~~~~~~~
 669
 670 The following capabilities are not supported:
 671
 672 - Traffic manager WRED profile and WRED context
 673 - Traffic manager shared shaper update
 674 - Traffic manager packet marking
 675 - Maximum number of levels in hierarchy is 2
 676 - Currently dynamic change of a hierarchy is not supported
 677
 678 Usage example
 679 ~~~~~~~~~~~~~
 680
 681 For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
 682
 683 1. Run testpmd as follows:
 684
 685    .. code-block:: console
 686
 687                 ./testpmd --vdev=net_mrvl,iface=eth0,iface=eth2,cfg=./qos_config -c 7 -- \
 688                 -i -p 3 --disable-hw-vlan-strip --rxq 3 --txq 3 --txd 1024 --rxd 1024
 689
 690 2. Stop all ports:
 691
 692    .. code-block:: console
 693
 694                 testpmd> port stop all
 695
 696 3. Add shaper profile:
 697
 698    .. code-block:: console
 699
 700                 testpmd> add port tm node shaper profile 0 0 900000 70000 0
 701
 702    Parameters have following meaning::
 703
 704                 0       - Id of a port.
 705                 0       - Id of a new shaper profile.
 706                 900000  - Shaper rate in bytes/s.
 707                 70000   - Bucket size in bytes.
 708                 0       - Packet length adjustment - ignored.
 709
 710 4. Add non-leaf node for port 0:
 711
 712    .. code-block:: console
 713
 714                 testpmd> add port tm nonleaf node 0 3 -1 0 0 0 0 0 1 3 0
 715
 716    Parameters have following meaning::
 717
 718                  0  - Id of a port
 719                  3  - Id of a new node.
 720                 -1  - Indicate that root does not have a parent.
 721                  0  - Priority of the node.
 722                  0  - Weight of the node.
 723                  0  - Id of a level. Since this is a root 0 is passed.
 724                  0  - Id of the shaper profile.
 725                  0  - Number of SP priorities.
 726                  3  - Enable statistics for both number of transmitted packets and bytes.
 727                  0  - Number of shared shapers.
 728
 729 5. Add leaf node for tx queue 0:
 730
 731    .. code-block:: console
 732
 733                 testpmd> add port tm leaf node 0 0 3 0 30 1 -1 0 0 1 0
 734
 735    Parameters have following meaning::
 736
 737                  0  - Id of a port.
 738                  0  - Id of a new node.
 739                  3  - Id of the parent node.
 740                  0  - Priority of a node.
 741                  30 - WRR weight.
 742                  1  - Id of a level. Since this is a leaf node 1 is passed.
 743                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 744                  0  - Congestion management is not supported.
 745                  0  - Congestion management is not supported.
 746                  1  - Enable statistics counter for number of transmitted packets.
 747                  0  - Number of shared shapers.
 748
 749 6. Add leaf node for tx queue 1:
 750
 751    .. code-block:: console
 752
 753         testpmd> add port tm leaf node 0 1 3 0 60 1 -1 0 0 1 0
 754
 755    Parameters have following meaning::
 756
 757                  0  - Id of a port.
 758                  1  - Id of a new node.
 759                  3  - Id of the parent node.
 760                  0  - Priority of a node.
 761                  60 - WRR weight.
 762                  1  - Id of a level. Since this is a leaf node 1 is passed.
 763                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 764                  0  - Congestion management is not supported.
 765                  0  - Congestion management is not supported.
 766                  1  - Enable statistics counter for number of transmitted packets.
 767                  0  - Number of shared shapers.
 768
 769 7. Add leaf node for tx queue 2:
 770
 771    .. code-block:: console
 772
 773                 testpmd> add port tm leaf node 0 2 3 0 99 1 -1 0 0 1 0
 774
 775    Parameters have following meaning::
 776
 777                  0  - Id of a port.
 778                  2  - Id of a new node.
 779                  3  - Id of the parent node.
 780                  0  - Priority of a node.
 781                  99 - WRR weight.
 782                  1  - Id of a level. Since this is a leaf node 1 is passed.
 783                 -1  - Id of a shaper. -1 indicates that shaper is not attached.
 784                  0  - Congestion management is not supported.
 785                  0  - Congestion management is not supported.
 786                  1  - Enable statistics counter for number of transmitted packets.
 787                  0  - Number of shared shapers.
 788
 789 8. Commit hierarchy:
 790
 791    .. code-block:: console
 792
 793                 testpmd> port tm hierarchy commit 0 no
 794
 795   Parameters have following meaning::
 796
 797                 0  - Id of a port.
 798                 no - Do not flush TM hierarchy if commit fails.
 799
 800 9. Start all ports
 801
 802    .. code-block:: console
 803
 804                 testpmd> port start all
 805
 806
 807
 808 10. Enable forwarding
 809
 810    .. code-block:: console
 811
 812                 testpmd> start