X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fnics%2Fmvpp2.rst;h=e40fed72868cc6ee954b4378e507c5209ef925a6;hb=cdf6a5fbc540cdaac576a2be6c8dac25ce173c65;hp=3b3f8c6d44925df37d56c1cb92ae845195fae217;hpb=e04ec42af0cbeefc65aa3f114e33c5159403a755;p=dpdk.git diff --git a/doc/guides/nics/mvpp2.rst b/doc/guides/nics/mvpp2.rst index 3b3f8c6d44..e40fed7286 100644 --- a/doc/guides/nics/mvpp2.rst +++ b/doc/guides/nics/mvpp2.rst @@ -1,40 +1,13 @@ -.. 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: @@ -42,12 +15,6 @@ 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 -------- @@ -56,7 +23,7 @@ Features of the MVPP2 PMD are: - Speed capabilities - Link status -- Queue start/stop +- Tx Queue start/stop - MTU update - Jumbo frame - Promiscuous mode @@ -70,12 +37,13 @@ Features of the MVPP2 PMD are: - L4 checksum offload - Packet type parsing - Basic stats -- Extended stats -- QoS +- :ref:`Extended stats ` - RX flow control -- TX queue start/stop - Scattered TX frames - +- :ref:`QoS ` +- :ref:`Flow API ` +- :ref:`Traffic metering and policing ` +- :ref:`Traffic Management API ` Limitations ----------- @@ -89,6 +57,20 @@ 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 ------------- @@ -109,7 +91,7 @@ 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 @@ -126,23 +108,92 @@ Prerequisites 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=/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=$/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 @@ -157,7 +208,17 @@ Configuration syntax ebs = cbs = + [parser udf ] + proto = + field = + key = + mask = + offset = + [port default] + start_hdr = + forward_bad_frames = + fill_bpool_buffs = default_tc = mapping_priority = @@ -188,8 +249,26 @@ Configuration syntax Where: +- ````: Logical UDF id. + +- ````: Indicate the preceding hdr before the UDF header (`eth` or `udp`). + +- ````: Indicate the field of the hdr (`type` (eth) or `dport` (udp). + +- ````: UDF key in string format starting with '0x'. + +- ````: UDF mask in string format starting with '0x'. + +- ````: Starting UDF offset from the hdr. + - ````: DPDK Port number (0..n). +- ````: Indicate what is the start header mode (`none` (eth), `dsa`, `ext_dsa` or `custom`). + +- ````: Indicate whether to forward or drop l2 bad packets (0 or 1). + +- ````: Control the amount of refill buffers (default is 64). + - ````: Default traffic class (e.g. 0) - ````: QoS priority for mapping (`ip`, `vlan`, `ip/vlan` or `vlan/ip`). @@ -294,41 +373,27 @@ Configuration file example 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=/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=/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 -------- @@ -336,6 +401,10 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~ @@ -343,6 +412,7 @@ Following flow action items are supported by the driver: * DROP * QUEUE +* METER Supported flow items ~~~~~~~~~~~~~~~~~~~~ @@ -434,7 +504,7 @@ Before proceeding run testpmd user application: .. 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 ^^^^^^^^^^ @@ -495,31 +565,239 @@ Following limitations need to be taken into account while creating flow rules: 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 `. - 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