net/txgbe: support DCB
[dpdk.git] / doc / guides / nics / dpaa.rst
index d331c05..ae1642b 100644 (file)
@@ -1,36 +1,11 @@
-..  BSD LICENSE
-    Copyright 2017 NXP.
-
-    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 2017,2020 NXP
+
 
 DPAA Poll Mode Driver
 =====================
 
-The DPAA NIC PMD (**librte_pmd_dpaa**) provides poll mode driver
+The DPAA NIC PMD (**librte_net_dpaa**) provides poll mode driver
 support for the inbuilt NIC found in the **NXP DPAA** SoC family.
 
 More information can be found at `NXP Official Website
@@ -46,6 +21,7 @@ Contents summary
 
 - DPAA overview
 - DPAA driver architecture overview
+- FMAN configuration tools and library
 
 .. _dpaa_overview:
 
@@ -187,6 +163,16 @@ Manager.
   this pool.
 
 
+Whitelisting & Blacklisting
+---------------------------
+
+For blacklisting a DPAA device, following commands can be used.
+
+ .. code-block:: console
+
+    <dpdk app> <EAL args> -b "dpaa_bus:fmX-macY" -- ...
+    e.g. "dpaa_bus:fm1-mac4"
+
 Supported DPAA SoCs
 -------------------
 
@@ -196,65 +182,8 @@ Supported DPAA SoCs
 Prerequisites
 -------------
 
-There are three main pre-requisities for executing DPAA PMD on a DPAA
-compatible board:
-
-1. **ARM 64 Tool Chain**
-
-   For example, the `*aarch64* Linaro Toolchain <https://releases.linaro.org/components/toolchain/binaries/6.4-2017.08/aarch64-linux-gnu/>`_.
-
-2. **Linux Kernel**
-
-   It can be obtained from `NXP's Github hosting <https://github.com/qoriq-open-source/linux>`_.
-
-3. **Rootfile system**
-
-   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>`_.
-
-4. **FMC Tool**
-
-   Before any DPDK application can be executed, the Frame Manager Configuration
-   Tool (FMC) need to be executed to set the configurations of the queues. This
-   includes the queue state, RSS and other policies.
-   This tool can be obtained from `NXP (Freescale) Public Git Repository <https://github.com/qoriq-open-source/fmc>`_.
-
-   This tool needs configuration files which are available in the
-   :ref:`DPDK Extra Scripts <extra_scripts>`, described below for DPDK usages.
-
-As an alternative method, DPAA 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 DPAA board.
-
-The following dependencies are not part of DPDK and must be installed
-separately:
-
-- **NXP Linux SDK**
-
-  NXP Linux software development kit (SDK) includes support for family
-  of QorIQ® ARM-Architecture-based system on chip (SoC) processors
-  and corresponding boards.
-
-  It includes the Linux board support packages (BSPs) for NXP SoCs,
-  a fully operational tool chain, kernel and board specific modules.
-
-  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>`_.
-
-
-.. _extra_scripts:
+See :doc:`../platform/dpaa` for setup information
 
-- **DPDK Extra Scripts**
-
-  DPAA based resources can be configured easily with the help of ready scripts
-  as provided in the DPDK Extra repository.
-
-  `DPDK Extras Scripts <https://github.com/qoriq-open-source/dpdk-extras>`_.
-
-Currently supported by DPDK:
-
-- NXP SDK **2.0+**.
-- Supported architectures:  **arm64 LE**.
 
 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>`
   to setup the basic DPDK environment.
@@ -267,39 +196,6 @@ Currently supported by DPDK:
 Pre-Installation Configuration
 ------------------------------
 
-Config File Options
-~~~~~~~~~~~~~~~~~~~
-
-The following options can be modified in the ``config`` file.
-Please note that enabling debugging options may affect system performance.
-
-- ``CONFIG_RTE_LIBRTE_DPAA_BUS`` (default ``n``)
-
-  By default it is enabled only for defconfig_arm64-dpaa-* config.
-  Toggle compilation of the ``librte_bus_dpaa`` driver.
-
-- ``CONFIG_RTE_LIBRTE_DPAA_PMD`` (default ``n``)
-
-  By default it is enabled only for defconfig_arm64-dpaa-* config.
-  Toggle compilation of the ``librte_pmd_dpaa`` driver.
-
-- ``CONFIG_RTE_LIBRTE_DPAA_DEBUG_DRIVER`` (default ``n``)
-
-  Toggles display of bus configurations and enables a debugging queue
-  to fetch error (Rx/Tx) packets to driver. By default, packets with errors
-  (like wrong checksum) are dropped by the hardware.
-
-- ``CONFIG_RTE_LIBRTE_DPAA_HWDEBUG`` (default ``n``)
-
-  Enables debugging of the Queue and Buffer Manager layer which interacts
-  with the DPAA hardware.
-
-- ``CONFIG_RTE_MBUF_DEFAULT_MEMPOOL_OPS`` (default ``dpaa``)
-
-  This is not a DPAA specific configuration - it is a generic RTE config.
-  For optimal performance and hardware utilization, it is expected that DPAA
-  Mempool driver is used for mempools. For that, this configuration needs to
-  enabled.
 
 Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~
@@ -315,6 +211,18 @@ state during application initialization:
   In case the application is configured to use lesser number of queues than
   configured above, it might result in packet loss (because of distribution).
 
+- ``DPAA_PUSH_QUEUES_NUMBER`` (default 4)
+
+  This defines the number of High performance queues to be used for ethdev Rx.
+  These queues use one private HW portal per queue configured, so they are
+  limited in the system. The first configured ethdev queues will be
+  automatically be assigned from the these high perf PUSH queues. Any queue
+  configuration beyond that will be standard Rx queues. The application can
+  choose to change their number if HW portals are limited.
+  The valid values are from '0' to '4'. The values shall be set to '0' if the
+  application want to use eventdev with DPAA device.
+  Currently these queues are not used for LS1023/LS1043 platform by default.
+
 
 Driver compilation and testing
 ------------------------------
@@ -332,7 +240,7 @@ for details.
 
    .. code-block:: console
 
-      ./arm64-dpaa-linuxapp-gcc/testpmd -c 0xff -n 1 \
+      ./<build_dir>/app/dpdk-testpmd -c 0xff -n 1 \
         -- -i --portmask=0x3 --nb-cores=1 --no-flush-rx
 
       .....
@@ -353,6 +261,67 @@ for details.
       Done
       testpmd>
 
+FMAN Config
+-----------
+
+Frame Manager is also responsible for parser, classify and distribute
+functionality in the DPAA.
+
+   FMAN supports:
+   Packet parsing at wire speed. It supports standard protocols parsing and
+   identification by HW (VLAN/IP/UDP/TCP/SCTP/PPPoE/PPP/MPLS/GRE/IPSec).
+   It supports non-standard UDF header parsing for custom protocols.
+   Classification / Distribution: Coarse classification based on Key generation
+   Hash and exact match lookup
+
+FMC - FMAN Configuration Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   This tool is available in User Space. The tool is used to configure FMAN
+   Physical (MAC) or Ephemeral (OH)ports for Parse/Classify/distribute.
+   The PCDs can be hash based where a set of fields are key input for hash
+   generation within FMAN keygen. The hash value is used to generate a FQID for
+   frame. There is a provision to setup exact match lookup too where field
+   values within a packet drives corresponding FQID.
+   Currently it works on XML file inputs.
+
+   Limitations:
+   1.For Dynamic Configuration change, currently no support is available.
+   E.g. enable/disable a port, a operator (set of VLANs and associate rules).
+
+   2.During FMC configuration, port for which policy is being configured is
+   brought down and the policy is flushed on port before new policy is updated
+   for the port. Support is required to add/append/delete etc.
+
+   3.FMC, being a separate user-space application, needs to be invoked from
+   Shell.
+
+
+   The details can be found in FMC Doc at:
+   `Frame Mnager Configuration Tool <https://www.nxp.com/docs/en/application-note/AN4760.pdf>`_.
+
+FMLIB
+~~~~~
+   The Frame Manager library provides an API on top of the Frame Manager driver
+   ioctl calls, that provides a user space application with a simple way to
+   configure driver parameters and PCD (parse - classify - distribute) rules.
+
+   This is an alternate to the FMC based configuration. This library provides
+   direct ioctl based interfaces for FMAN configuration as used by the FMC tool
+   as well. This helps in overcoming the main limitaiton of FMC - i.e. lack
+   of dynamic configuration.
+
+   The location for the fmd driver as used by FMLIB and FMC is as follows:
+   `Kernel FMD Driver
+   <https://source.codeaurora.org/external/qoriq/qoriq-components/linux/tree/drivers/net/ethernet/freescale/sdk_fman?h=linux-4.19-rt>`_.
+
+VSP (Virtual Storage Profile)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   The storage profiled are means to provide virtualized interface. A ranges of
+   storage profiles cab be associated to Ethernet ports.
+   They are selected during classification. Specify how the frame should be
+   written to memory and which buffer pool to select for packet storange in
+   queues. Start and End margin of buffer can also be configured.
+
 Limitations
 -----------