-.. BSD LICENSE
- Copyright (C) NXP. 2016.
- 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 NXP 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.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2016,2020-2021 NXP
+
DPAA2 Poll Mode Driver
======================
-The DPAA2 NIC PMD (**librte_pmd_dpaa2**) provides poll mode driver
+The DPAA2 NIC PMD (**librte_net_dpaa2**) provides poll mode driver
support for the inbuilt NIC found in the **NXP DPAA2** SoC family.
More information can be found at `NXP Official Website
- Overview of DPAA2 objects
- DPAA2 driver architecture overview
+.. _dpaa2_overview:
+
DPAA2 Overview
~~~~~~~~~~~~~~
scenario and the objects bound to each driver. A brief description
of each driver follows.
-.. code-block: console
+.. code-block:: console
+------------+
DPBP based Mempool driver
~~~~~~~~~~~~~~~~~~~~~~~~~
-The DPBP driver is bound to a DPBP objects and provides sevices to
+The DPBP driver is bound to a DPBP objects and provides services to
create a hardware offloaded packet buffer mempool.
DPAA2 NIC Driver
- Multiple queues for TX and RX
- Receive Side Scaling (RSS)
+- MAC/VLAN filtering
- Packet type information
- Checksum offload
- Promiscuous mode
+- Multicast mode
+- Port hardware statistics
+- Jumbo frames
+- Link flow control
+- Scattered and gather for TX and RX
+- :ref:`Traffic Management API <dptmapi>`
+
Supported DPAA2 SoCs
--------------------
-
-- LS2080A/LS2040A
+- LX2160A
- LS2084A/LS2044A
- LS2088A/LS2048A
- LS1088A/LS1048A
Prerequisites
-------------
-There are three main pre-requisities for executing DPAA2 PMD on a DPAA2
-compatible board:
+See :doc:`../platform/dpaa2` for setup information
-1. **ARM 64 Tool Chain**
+Currently supported by DPDK:
- For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
+- NXP LSDK **19.08+**.
+- MC Firmware version **10.18.0** and higher.
+- Supported architectures: **arm64 LE**.
-2. **Linux Kernel**
+- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
- It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
+.. note::
-3. **Rootfile system**
+ Some part of fslmc bus code (mc flib - object library) routines are
+ dual licensed (BSD & GPLv2), however they are used as BSD in DPDK in userspace.
- Any *aarch64* supporting filesystem can be used. For example,
- Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
- from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
-As an alternative method, DPAA2 PMD can also be executed using images provided
-as part of SDK from NXP. The SDK includes all the above prerequisites necessary
-to bring up a DPAA2 board.
+Driver compilation and testing
+------------------------------
-The following dependencies are not part of DPDK and must be installed
-separately:
+Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+for details.
-- **NXP Linux SDK**
+#. Running testpmd:
- NXP Linux software development kit (SDK) includes support for family
- of QorIQ® ARM-Architecture-based system on chip (SoC) processors
- and corresponding boards.
+ Follow instructions available in the document
+ :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+ to run testpmd.
- It includes the Linux board support packages (BSPs) for NXP SoCs,
- a fully operational tool chain, kernel and board specific modules.
+ Example output:
- SDK and related information can be obtained from: `NXP QorIQ SDK <http://www.nxp.com/products/software-and-tools/run-time-software/linux-sdk/linux-sdk-for-qoriq-processors:SDKLINUX>`_.
+ .. code-block:: console
-- **DPDK Helper Scripts**
+ ./dpdk-testpmd -c 0xff -n 1 -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
+
+ .....
+ EAL: Registered [pci] bus.
+ EAL: Registered [fslmc] bus.
+ EAL: Detected 8 lcore(s)
+ EAL: Probing VFIO support...
+ EAL: VFIO support initialized
+ .....
+ PMD: DPAA2: Processing Container = dprc.2
+ EAL: fslmc: DPRC contains = 51 devices
+ EAL: fslmc: Bus scan completed
+ .....
+ Configuring Port 0 (socket 0)
+ Port 0: 00:00:00:00:00:01
+ Configuring Port 1 (socket 0)
+ Port 1: 00:00:00:00:00:02
+ .....
+ Checking link statuses...
+ Port 0 Link Up - speed 10000 Mbps - full-duplex
+ Port 1 Link Up - speed 10000 Mbps - full-duplex
+ Done
+ testpmd>
+
+
+* Use dev arg option ``drv_loopback=1`` to loopback packets at
+ driver level. Any packet received will be reflected back by the
+ driver on same port. e.g. ``fslmc:dpni.1,drv_loopback=1``
+
+* Use dev arg option ``drv_no_prefetch=1`` to disable prefetching
+ of the packet pull command which is issued in the previous cycle.
+ e.g. ``fslmc:dpni.1,drv_no_prefetch=1``
+
+* Use dev arg option ``drv_tx_conf=1`` to enable TX confirmation mode.
+ In this mode tx conf queues need to be polled to free the buffers.
+ e.g. ``fslmc:dpni.1,drv_tx_conf=1``
+
+* Use dev arg option ``drv_error_queue=1`` to enable Packets in Error queue.
+ DPAA2 hardware drops the error packet in hardware. This option enables the
+ hardware to not drop the error packet and let the driver dump the error
+ packets, so that user can check what is wrong with those packets.
+ e.g. ``fslmc:dpni.1,drv_error_queue=1``
+
+Enabling logs
+-------------
- DPAA2 based resources can be configured easily with the help of ready scripts
- as provided in the DPDK helper repository.
+For enabling logging for DPAA2 PMD, following log-level prefix can be used:
- `DPDK Helper Scripts <https://github.com/qoriq-open-source/dpdk-helper>`_.
+ .. code-block:: console
-Currently supported by DPDK:
+ <dpdk app> <EAL args> --log-level=bus.fslmc:<level> -- ...
-- NXP SDK **2.0+**.
-- MC Firmware version **10.0.0** and higher.
-- Supported architectures: **arm64 LE**.
+Using ``bus.fslmc`` as log matching criteria, all FSLMC bus logs can be enabled
+which are lower than logging ``level``.
-- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
+ Or
-.. note::
+ .. code-block:: console
- Some part of fslmc bus code (mc flib - object library) routines are
- dual licensed (BSD & GPLv2).
+ <dpdk app> <EAL args> --log-level=pmd.net.dpaa2:<level> -- ...
-Pre-Installation Configuration
-------------------------------
+Using ``pmd.net.dpaa2`` as log matching criteria, all PMD logs can be enabled
+which are lower than logging ``level``.
+
+Allowing & Blocking
+-------------------
+
+For blocking a DPAA2 device, following commands can be used.
+
+ .. code-block:: console
+
+ <dpdk app> <EAL args> -b "fslmc:dpni.x" -- ...
+
+Where x is the device object id as configured in resource container.
-Config File Options
-~~~~~~~~~~~~~~~~~~~
+Running secondary debug app without blocklist
+---------------------------------------------
-The following options can be modified in the ``config`` file.
-Please note that enabling debugging options may affect system performance.
+dpaa2 hardware imposes limits on some H/W access devices like Management
+Control Port and H/W portal. This causes issue in their shared usages in
+case of multi-process applications. It can overcome by using
+allowlist/blocklist in primary and secondary applications.
-- ``CONFIG_RTE_LIBRTE_FSLMC_BUS`` (default ``n``)
+In order to ease usage of standard debugging apps like dpdk-procinfo, dpaa2
+driver reserves extra Management Control Port and H/W portal which can be
+used by debug application to debug any existing application without
+blocking these devices in primary process.
- By default it is enabled only for defconfig_arm64-dpaa2-* config.
- Toggle compilation of the ``librte_bus_fslmc`` driver.
+Limitations
+-----------
-- ``CONFIG_RTE_LIBRTE_DPAA2_PMD`` (default ``n``)
+Platform Requirement
+~~~~~~~~~~~~~~~~~~~~
+DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the
+``Supported DPAA2 SoCs``.
- By default it is enabled only for defconfig_arm64-dpaa2-* config.
- Toggle compilation of the ``librte_pmd_dpaa2`` driver.
+Maximum packet length
+~~~~~~~~~~~~~~~~~~~~~
-- ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_DRIVER`` (default ``n``)
+The DPAA2 SoC family support a maximum of a 10240 jumbo frame. The value
+is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
+member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
+up to 10240 bytes can still reach the host interface.
- Toggle display of generic debugging messages
+Other Limitations
+~~~~~~~~~~~~~~~~~
-- ``CONFIG_RTE_LIBRTE_DPAA2_USE_PHYS_IOVA`` (default ``y``)
+- RSS hash key cannot be modified.
+- RSS RETA cannot be configured.
- Toggle to use physical address vs virtual address for hardware accelerators.
+.. _dptmapi:
-- ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_INIT`` (default ``n``)
+Traffic Management API
+----------------------
- Toggle display of initialization related messages.
+DPAA2 PMD supports generic DPDK Traffic Management API which allows to
+configure the following features:
-- ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_RX`` (default ``n``)
+1. Hierarchical scheduling
+2. Traffic shaping
- Toggle display of receive fast path run-time message
+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).
-- ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX`` (default ``n``)
+Nodes hold following types of settings:
- Toggle display of transmit fast path run-time message
+- for egress scheduler configuration: weight
+- for egress rate limiter: private shaper
-- ``CONFIG_RTE_LIBRTE_DPAA2_DEBUG_TX_FREE`` (default ``n``)
+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.
- Toggle display of transmit fast path buffer free run-time message
+After hierarchy is complete it can be committed.
+For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`.
-Driver Compilation
+Supported Features
~~~~~~~~~~~~~~~~~~
-To compile the DPAA2 PMD for Linux arm64 gcc target, run the
-following ``make`` command:
+The following capabilities are supported:
-.. code-block:: console
+- Level0 (root node) and Level1 are supported.
+- 1 private shaper at root node (port level) is supported.
+- 8 TX queues per port supported (1 channel per port)
+- Both SP and WFQ scheduling mechanisms are supported on all 8 queues.
+- Congestion notification is supported. It means if there is congestion on
+ the network, DPDK driver will not enqueue any packet (no taildrop or WRED)
- cd <DPDK-source-directory>
- make config T=arm64-dpaa2-linuxapp-gcc install
+ User can also check node, level capabilities using testpmd commands.
-.. _dpaa2_testpmd_example:
+Usage example
+~~~~~~~~~~~~~
-Running testpmd
-~~~~~~~~~~~~~~~
+For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`.
-This section demonstrates how to launch ``testpmd`` with DPAA2 device
-managed by ``librte_pmd_dpaa2`` in the Linux operating system.
+1. Run testpmd as follows:
-#. Configure the resource container:
+ .. code-block:: console
+
+ ./dpdk-testpmd -c 0xf -n 1 -- -i --portmask 0x3 --nb-cores=1 --txq=4 --rxq=4
- Configure resources in MC and create the DPRC container:
+2. Stop all ports:
.. code-block:: console
- export the DPRC container
- e.g. export DPRCT=dprc.2
+ testpmd> port stop all
-#. Start ``testpmd`` with basic parameters:
+3. Add shaper profile:
+
+ One port level shaper and strict priority on all 4 queues of port 0:
.. code-block:: console
- ./arm64-dpaa2-linuxapp-gcc/testpmd -c 0xff -n 1 \
- -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
+ add port tm node shaper profile 0 1 104857600 64 100 0 0
+ add port tm nonleaf node 0 8 -1 0 1 0 1 1 1 0
+ add port tm leaf node 0 0 8 0 1 1 -1 0 0 0 0
+ add port tm leaf node 0 1 8 1 1 1 -1 0 0 0 0
+ add port tm leaf node 0 2 8 2 1 1 -1 0 0 0 0
+ add port tm leaf node 0 3 8 3 1 1 -1 0 0 0 0
+ port tm hierarchy commit 0 no
- Example output:
+ or
+
+ One port level shaper and WFQ on all 4 queues of port 0:
.. code-block:: console
- .....
- EAL: Registered [pci] bus.
- EAL: Registered [fslmc] bus.
- EAL: Detected 8 lcore(s)
- EAL: Probing VFIO support...
- EAL: VFIO support initialized
- .....
- PMD: DPAA2: Processing Container = dprc.2
- EAL: fslmc: DPRC contains = 51 devices
- EAL: fslmc: Bus scan completed
- .....
- Configuring Port 0 (socket 0)
- Port 0: 00:00:00:00:00:01
- Configuring Port 1 (socket 0)
- Port 1: 00:00:00:00:00:02
- .....
- Checking link statuses...
- Port 0 Link Up - speed 10000 Mbps - full-duplex
- Port 1 Link Up - speed 10000 Mbps - full-duplex
- Done
- testpmd>
+ add port tm node shaper profile 0 1 104857600 64 100 0 0
+ add port tm nonleaf node 0 8 -1 0 1 0 1 1 1 0
+ add port tm leaf node 0 0 8 0 200 1 -1 0 0 0 0
+ add port tm leaf node 0 1 8 0 300 1 -1 0 0 0 0
+ add port tm leaf node 0 2 8 0 400 1 -1 0 0 0 0
+ add port tm leaf node 0 3 8 0 500 1 -1 0 0 0 0
+ port tm hierarchy commit 0 no
-Limitations
------------
+4. Create flows as per the source IP addresses:
-Platform Requirement
-~~~~~~~~~~~~~~~~~~~~
-DPAA2 drivers for DPDK can only work on NXP SoCs as listed in the
-``Supported DPAA2 SoCs``.
+ .. code-block:: console
-Maximum packet length
-~~~~~~~~~~~~~~~~~~~~~
+ flow create 1 group 0 priority 1 ingress pattern ipv4 src is \
+ 10.10.10.1 / end actions queue index 0 / end
+ flow create 1 group 0 priority 2 ingress pattern ipv4 src is \
+ 10.10.10.2 / end actions queue index 1 / end
+ flow create 1 group 0 priority 3 ingress pattern ipv4 src is \
+ 10.10.10.3 / end actions queue index 2 / end
+ flow create 1 group 0 priority 4 ingress pattern ipv4 src is \
+ 10.10.10.4 / end actions queue index 3 / end
-The DPAA2 SoC family support a maximum of a 10240 jumbo frame. The value
-is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
-member of ``struct rte_eth_conf`` is set to a value lower than 10240, frames
-up to 10240 bytes can still reach the host interface.
+5. Start all ports
+
+ .. code-block:: console
+
+ testpmd> port start all
+
+
+
+6. Enable forwarding
+
+ .. code-block:: console
+
+ testpmd> start
+
+7. Inject the traffic on port1 as per the configured flows, you will see shaped and scheduled forwarded traffic on port0