-.. BSD LICENSE
+.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2017 Marvell International Ltd.
Copyright(c) 2017 Semihalf.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of the copyright holder nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.. _mvpp2_poll_mode_driver:
MVPP2 Poll Mode Driver
======================
-The MVPP2 PMD (librte_pmd_mvpp2) provides poll mode driver support
+The MVPP2 PMD (**librte_net_mvpp2**) provides poll mode driver support
for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter.
Detailed information about SoCs that use PPv2 can be obtained here:
* https://www.marvell.com/embedded-processors/armada-70xx/
* https://www.marvell.com/embedded-processors/armada-80xx/
-.. Note::
-
- Due to external dependencies, this driver is disabled by default. It must
- be enabled manually by setting relevant configuration option manually.
- Please refer to `Config File Options`_ section for further details.
-
Features
--------
- Speed capabilities
- Link status
-- Queue start/stop
+- Tx Queue start/stop
- MTU update
- Jumbo frame
- Promiscuous mode
- L4 checksum offload
- Packet type parsing
- Basic stats
-- Extended stats
-- QoS
+- :ref:`Extended stats <extstats>`
- RX flow control
-- TX queue start/stop
- Scattered TX frames
-
+- :ref:`QoS <extconf>`
+- :ref:`Flow API <flowapi>`
+- :ref:`Traffic metering and policing <mtrapi>`
+- :ref:`Traffic Management API <tmapi>`
Limitations
-----------
functionality. Current workaround is to reset board so that PPv2 has a
chance to start in a sane state.
+- MUSDK architecture does not support changing configuration in run time.
+ All necessary configurations should be done before first dev_start().
+
+- RX queue start/stop is not supported.
+
+- Current implementation does not support replacement of buffers in the HW buffer pool
+ at run time, so it is responsibility of the application to ensure that MTU does not exceed the configured buffer size.
+
+- Configuring TX flow control currently is not supported.
+
+- In current implementation, mechanism for acknowledging transmitted packets (``tx_done_cleanup``) is not supported.
+
+- Running more than one DPDK-MUSDK application simultaneously is not supported.
+
Prerequisites
-------------
.. code-block:: console
- git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-armada-18.09
+ git clone https://github.com/MarvellEmbeddedProcessors/musdk-marvell.git -b musdk-release-SDK-10.3.5.0-PR2
MUSDK is a light-weight library that provides direct access to Marvell's
PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
DPDK environment.
-Config File Options
--------------------
+Building MUSDK
+--------------
-The following options can be modified in the ``config`` file.
+Driver needs precompiled MUSDK library during compilation.
-- ``CONFIG_RTE_LIBRTE_MVPP2_PMD`` (default ``n``)
+.. code-block:: console
- Toggle compilation of the librte mvpp2 driver.
+ export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
+ ./bootstrap
+ ./configure --host=aarch64-linux-gnu
+ make install
+
+MUSDK will be installed to `usr/local` under current directory.
+For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
+
+
+Building DPDK
+-------------
+
+Add path to libmusdk.pc in PKG_CONFIG_PATH environment variable.
+
+.. code-block:: console
- .. Note::
+ export PKG_CONFIG_PATH=$<musdk_install_dir>/lib/pkgconfig/:$PKG_CONFIG_PATH
- When MVPP2 PMD is enabled ``CONFIG_RTE_LIBRTE_MVNETA_PMD`` must be disabled
+ meson build --cross-file config/arm/arm64_armada_linux_gcc
+ ninja -C build
-QoS Configuration
------------------
-QoS configuration is done through external configuration file. Path to the
+Usage Example
+-------------
+
+MVPP2 PMD requires extra out of tree kernel modules to function properly.
+`musdk_cma` sources are part of the MUSDK. Please consult
+``doc/musdk_get_started.txt`` for the detailed build instructions.
+For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
+detailed build instructions.
+
+.. code-block:: console
+
+ insmod musdk_cma.ko
+ insmod mvpp2x_sysfs.ko
+
+Additionally interfaces used by DPDK application need to be put up:
+
+.. code-block:: console
+
+ ip link set eth0 up
+ ip link set eth2 up
+
+In order to run testpmd example application following command can be used:
+
+.. code-block:: console
+
+ ./dpdk-testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 7 -- \
+ --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \
+ -i -a --rss-udp
+
+.. _extstats:
+
+Extended stats
+--------------
+
+MVPP2 PMD supports the following extended statistics:
+
+ - ``rx_bytes``: number of RX bytes
+ - ``rx_packets``: number of RX packets
+ - ``rx_unicast_packets``: number of RX unicast packets
+ - ``rx_errors``: number of RX MAC errors
+ - ``rx_fullq_dropped``: number of RX packets dropped due to full RX queue
+ - ``rx_bm_dropped``: number of RX packets dropped due to no available buffers in the HW pool
+ - ``rx_early_dropped``: number of RX packets that were early dropped
+ - ``rx_fifo_dropped``: number of RX packets dropped due to RX fifo overrun
+ - ``rx_cls_dropped``: number of RX packets dropped by classifier
+ - ``tx_bytes``: number of TX bytes
+ - ``tx_packets``: number of TX packets
+ - ``tx_unicast_packets``: number of TX unicast packets
+ - ``tx_errors``: number of TX MAC errors
+
+
+.. _extconf:
+
+External Configuration
+----------------------
+
+Several driver configuration (e.g. QoS) can be done through external configuration file. Path to the
file must be given as `cfg` in driver's vdev parameter list.
Configuration syntax
ebs = <ebs>
cbs = <cbs>
+ [parser udf <udf_id>]
+ proto = <proto>
+ field = <field>
+ key = <key>
+ mask = <mask>
+ offset = <offset>
+
[port <portnum> default]
+ start_hdr = <start_hdr>
+ forward_bad_frames = <forward_bad_frames>
+ fill_bpool_buffs = <fill_bpool_buffs>
default_tc = <default_tc>
mapping_priority = <mapping_priority>
Where:
+- ``<udf_id>``: Logical UDF id.
+
+- ``<proto>``: Indicate the preceding hdr before the UDF header (`eth` or `udp`).
+
+- ``<field>``: Indicate the field of the <proto> hdr (`type` (eth) or `dport` (udp).
+
+- ``<key>``: UDF key in string format starting with '0x'.
+
+- ``<mask>``: UDF mask in string format starting with '0x'.
+
+- ``<offset>``: Starting UDF offset from the <proto> hdr.
+
- ``<portnum>``: DPDK Port number (0..n).
+- ``<start_hdr>``: Indicate what is the start header mode (`none` (eth), `dsa`, `ext_dsa` or `custom`).
+
+- ``<forward_bad_frames>``: Indicate whether to forward or drop l2 bad packets (0 or 1).
+
+- ``<fill_bpool_buffs>``: Control the amount of refill buffers (default is 64).
+
- ``<default_tc>``: Default traffic class (e.g. 0)
- ``<mapping_priority>``: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`).
rate_limit = 10000
burst_size = 2000
-Usage example
-^^^^^^^^^^^^^
+Configuration file example with UDF
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
- ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
- -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3
-
-
-Building DPDK
--------------
+ [parser udf 0]
+ proto = eth
+ field = type
+ key = 0x8842
+ mask = 0xffff
+ offset = 6
-Driver needs precompiled MUSDK library during compilation.
+Usage example
+^^^^^^^^^^^^^
.. code-block:: console
- export CROSS_COMPILE=<toolchain>/bin/aarch64-linux-gnu-
- ./bootstrap
- ./configure --host=aarch64-linux-gnu
- make install
-
-MUSDK will be installed to `usr/local` under current directory.
-For the detailed build instructions please consult ``doc/musdk_get_started.txt``.
-
-Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
-the path to the MUSDK installation directory needs to be exported.
-
-.. code-block:: console
+ ./dpdk-testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2,cfg=/home/user/mrvl.conf \
+ -c 7 -- -i -a --disable-hw-vlan-strip --rxq=3 --txq=3
- export LIBMUSDK_PATH=<musdk>/usr/local
- export CROSS=aarch64-linux-gnu-
- make config T=arm64-armv8a-linuxapp-gcc
- sed -i "s/MVNETA_PMD=y/MVNETA_PMD=n/" build/.config
- sed -i "s/MVPP2_PMD=n/MVPP2_PMD=y/" build/.config
- make
+.. _flowapi:
Flow API
--------
PPv2 offers packet classification capabilities via classifier engine which
can be configured via generic flow API offered by DPDK.
+The :ref:`flow_isolated_mode` is supported.
+
+For an additional description please refer to DPDK :doc:`../prog_guide/rte_flow`.
+
Supported flow actions
~~~~~~~~~~~~~~~~~~~~~~
* DROP
* QUEUE
+* METER
Supported flow items
~~~~~~~~~~~~~~~~~~~~
.. code-block:: console
- ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 3 -- -i --p 3 -a --disable-hw-vlan-strip
+ ./dpdk-testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 3 -- -i --p 3 -a --disable-hw-vlan-strip
Example #1
^^^^^^^^^^
For additional information about classifier please consult
``doc/musdk_cls_user_guide.txt``.
-Usage Example
--------------
+.. _mtrapi:
-MVPP2 PMD requires extra out of tree kernel modules to function properly.
-`musdk_cma` sources are part of the MUSDK. Please consult
-``doc/musdk_get_started.txt`` for the detailed build instructions.
-For `mvpp2x_sysfs` please consult ``Documentation/pp22_sysfs.txt`` for the
-detailed build instructions.
+Traffic metering and policing
+-----------------------------
-.. code-block:: console
+MVPP2 PMD supports DPDK traffic metering and policing that allows the following:
- insmod musdk_cma.ko
- insmod mvpp2x_sysfs.ko
+1. Meter ingress traffic.
+2. Do policing.
+3. Gather statistics.
-Additionally interfaces used by DPDK application need to be put up:
+For an additional description please refer to DPDK :doc:`Traffic Metering and Policing API <../prog_guide/traffic_metering_and_policing>`.
-.. code-block:: console
+The policer objects defined by this feature can work with the default policer defined via config file as described in :ref:`QoS Support <extconf>`.
- ip link set eth0 up
- ip link set eth2 up
+Limitations
+~~~~~~~~~~~
-In order to run testpmd example application following command can be used:
+The following capabilities are not supported:
-.. code-block:: console
+- MTR object meter DSCP table update
+- MTR object policer action update
+- MTR object enabled statistics
- ./testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 7 -- \
- --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \
- -i -a --rss-udp
+Usage example
+~~~~~~~~~~~~~
+
+1. Run testpmd user app:
+
+ .. code-block:: console
+
+ ./dpdk-testpmd --vdev=eth_mvpp2,iface=eth0,iface=eth2 -c 6 -- -i -p 3 -a --txd 1024 --rxd 1024
+
+2. Create meter profile:
+
+ .. code-block:: console
+
+ testpmd> add port meter profile 0 0 srtcm_rfc2697 2000 256 256
+
+3. Create meter:
+
+ .. code-block:: console
+
+ testpmd> create port meter 0 0 0 yes d d d 0 1 0
+
+4. Create flow rule witch meter attached:
+
+ .. code-block:: console
+
+ testpmd> flow create 0 ingress pattern ipv4 src is 10.10.10.1 / end actions meter mtr_id 0 / end
+
+For a detailed usage description please refer to "Traffic Metering and Policing" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
+
+
+
+.. _tmapi:
+
+Traffic Management API
+----------------------
+
+MVPP2 PMD supports generic DPDK Traffic Management API which allows to
+configure the following features:
+
+1. Hierarchical scheduling
+2. Traffic shaping
+3. Congestion management
+4. Packet marking
+
+Internally TM is represented by a hierarchy (tree) of nodes.
+Node which has a parent is called a leaf whereas node without
+parent is called a non-leaf (root).
+MVPP2 PMD supports two level hierarchy where level 0 represents ports and level 1 represents tx queues of a given port.
+
+.. figure:: img/mvpp2_tm.*
+
+Nodes hold following types of settings:
+
+- for egress scheduler configuration: weight
+- for egress rate limiter: private shaper
+- bitmask indicating which statistics counters will be read
+
+Hierarchy is always constructed from the top, i.e first a root node is added
+then some number of leaf nodes. Number of leaf nodes cannot exceed number
+of configured tx queues.
+
+After hierarchy is complete it can be committed.
+
+
+For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`.
+
+Limitations
+~~~~~~~~~~~
+
+The following capabilities are not supported:
+
+- Traffic manager WRED profile and WRED context
+- Traffic manager shared shaper update
+- Traffic manager packet marking
+- Maximum number of levels in hierarchy is 2
+- Currently dynamic change of a hierarchy is not supported
+
+Usage example
+~~~~~~~~~~~~~
+
+For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
+
+1. Run testpmd as follows:
+
+ .. code-block:: console
+
+ ./dpdk-testpmd --vdev=net_mrvl,iface=eth0,iface=eth2,cfg=./qos_config -c 7 -- \
+ -i -p 3 --disable-hw-vlan-strip --rxq 3 --txq 3 --txd 1024 --rxd 1024
+
+2. Stop all ports:
+
+ .. code-block:: console
+
+ testpmd> port stop all
+
+3. Add shaper profile:
+
+ .. code-block:: console
+
+ testpmd> add port tm node shaper profile 0 0 900000 70000 0
+
+ Parameters have following meaning::
+
+ 0 - Id of a port.
+ 0 - Id of a new shaper profile.
+ 900000 - Shaper rate in bytes/s.
+ 70000 - Bucket size in bytes.
+ 0 - Packet length adjustment - ignored.
+
+4. Add non-leaf node for port 0:
+
+ .. code-block:: console
+
+ testpmd> add port tm nonleaf node 0 3 -1 0 0 0 0 0 1 3 0
+
+ Parameters have following meaning::
+
+ 0 - Id of a port
+ 3 - Id of a new node.
+ -1 - Indicate that root does not have a parent.
+ 0 - Priority of the node.
+ 0 - Weight of the node.
+ 0 - Id of a level. Since this is a root 0 is passed.
+ 0 - Id of the shaper profile.
+ 0 - Number of SP priorities.
+ 3 - Enable statistics for both number of transmitted packets and bytes.
+ 0 - Number of shared shapers.
+
+5. Add leaf node for tx queue 0:
+
+ .. code-block:: console
+
+ testpmd> add port tm leaf node 0 0 3 0 30 1 -1 0 0 1 0
+
+ Parameters have following meaning::
+
+ 0 - Id of a port.
+ 0 - Id of a new node.
+ 3 - Id of the parent node.
+ 0 - Priority of a node.
+ 30 - WRR weight.
+ 1 - Id of a level. Since this is a leaf node 1 is passed.
+ -1 - Id of a shaper. -1 indicates that shaper is not attached.
+ 0 - Congestion management is not supported.
+ 0 - Congestion management is not supported.
+ 1 - Enable statistics counter for number of transmitted packets.
+ 0 - Number of shared shapers.
+
+6. Add leaf node for tx queue 1:
+
+ .. code-block:: console
+
+ testpmd> add port tm leaf node 0 1 3 0 60 1 -1 0 0 1 0
+
+ Parameters have following meaning::
+
+ 0 - Id of a port.
+ 1 - Id of a new node.
+ 3 - Id of the parent node.
+ 0 - Priority of a node.
+ 60 - WRR weight.
+ 1 - Id of a level. Since this is a leaf node 1 is passed.
+ -1 - Id of a shaper. -1 indicates that shaper is not attached.
+ 0 - Congestion management is not supported.
+ 0 - Congestion management is not supported.
+ 1 - Enable statistics counter for number of transmitted packets.
+ 0 - Number of shared shapers.
+
+7. Add leaf node for tx queue 2:
+
+ .. code-block:: console
+
+ testpmd> add port tm leaf node 0 2 3 0 99 1 -1 0 0 1 0
+
+ Parameters have following meaning::
+
+ 0 - Id of a port.
+ 2 - Id of a new node.
+ 3 - Id of the parent node.
+ 0 - Priority of a node.
+ 99 - WRR weight.
+ 1 - Id of a level. Since this is a leaf node 1 is passed.
+ -1 - Id of a shaper. -1 indicates that shaper is not attached.
+ 0 - Congestion management is not supported.
+ 0 - Congestion management is not supported.
+ 1 - Enable statistics counter for number of transmitted packets.
+ 0 - Number of shared shapers.
+
+8. Commit hierarchy:
+
+ .. code-block:: console
+
+ testpmd> port tm hierarchy commit 0 no
+
+ Parameters have following meaning::
+
+ 0 - Id of a port.
+ no - Do not flush TM hierarchy if commit fails.
+
+9. Start all ports
+
+ .. code-block:: console
+
+ testpmd> port start all
+
+
+
+10. Enable forwarding
+
+ .. code-block:: console
+
+ testpmd> start
git.droids-corp.org / dpdk.git / blobdiff