[dpdk-dev] [PATCH 1/3] doc: add usage doc for ENETC PMD

[Gagandeep Singh <g.singh@nxp.com>]

Add enetc usage document to compile and run the
DPDK application on enetc supported platform.
This document introduces the enetc driver, supported
platforms and supported features.

Signed-off-by: Gagandeep Singh <g.singh@nxp.com>
---
 MAINTAINERS                        |   5 +
 doc/guides/nics/enetc.rst          | 164 +++++++++++++++++++++++++++++
 doc/guides/nics/features/enetc.ini |   8 ++
 doc/guides/nics/index.rst          |   1 +
 4 files changed, 178 insertions(+)
 create mode 100644 doc/guides/nics/enetc.rst
 create mode 100644 doc/guides/nics/features/enetc.ini

diff --git a/MAINTAINERS b/MAINTAINERS
index 9fd258fad..eaf75b7bf 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -627,6 +627,11 @@ F: drivers/net/nfp/
 F: doc/guides/nics/nfp.rst
 F: doc/guides/nics/features/nfp*.ini
 
+NXP enetc
+M: Gagandeep Singh <g.singh@nxp.com>
+F: doc/guides/nics/enetc.rst
+F: doc/guides/nics/features/enetc.ini
+
 NXP dpaa
 M: Hemant Agrawal <hemant.agrawal@nxp.com>
 M: Shreyansh Jain <shreyansh.jain@nxp.com>
diff --git a/doc/guides/nics/enetc.rst b/doc/guides/nics/enetc.rst
new file mode 100644
index 000000000..067cd474b
--- /dev/null
+++ b/doc/guides/nics/enetc.rst
@@ -0,0 +1,164 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright 2018 NXP
+
+ENETC Poll Mode Driver
+======================
+
+The ENETC NIC PMD (**librte_pmd_enetc**) provides poll mode driver
+support for the inbuilt NIC found in the **NXP LS1028** SoC.
+
+More information can be found at `NXP Official Website
+<https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/qoriq-layerscape-arm-processors/qoriq-layerscape-1028a-industrial-applications-processor:LS1028A>`_.
+
+ENETC
+-----
+
+This section provides an overview of the NXP ENETC
+and how it is integrated into the DPDK.
+
+Contents summary
+
+- ENETC overview
+- ENETC features
+- PCI bus driver
+- NIC driver
+- Supported ENETC SoCs
+- Prerequisites
+- Driver compilation and testing
+
+ENETC Overview
+~~~~~~~~~~~~~~
+
+Reference: `NXP ENETC OVERVIEW <https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/qoriq-layerscape-arm-processors/qoriq-layerscape-1028a-industrial-applications-processor:LS1028A>`_.
+
+ENETC is a PCI Integrated End Point(IEP). IEP implements
+peripheral devices in an SoC such that software sees them as PCIe device.
+ENETC is an evolution of BDR(Buffer Descriptor Ring) based networking
+IPs, introducing several changes intended to bring NXP IP up to date
+with developments in the industry and support new areas like virtualization.
+A major development is the use of a PCI bus for presentation of the IP
+to software, which has implications to the software architecture.
+
+This infrastructure simplifies adding support for IEP and facilitates in following:
+
+- Device discovery and location
+- Resource requirement discovery and allocation (e.g. interrupt assignment,
+  device register address)
+- Event reporting
+
+ENETC Features
+~~~~~~~~~~~~~~
+
+
+NIC Driver (PMD)
+~~~~~~~~~~~~~~~~
+
+ENETC PMD is traditional DPDK PMD which provides necessary interface between
+RTE framework and ENETC internal drivers.
+
+- Driver registers the device vendor table in PCI subsystem.
+- RTE framework scans the PCI bus for connected devices.
+- This scanning will invoke the probe function of ENETC driver.
+- The probe function will set the basic device registers and also setups BD rings.
+- On packet Rx the respective BD Ring status bit is set which is then used for
+  packet processing.
+- Then Tx is done first followed by Rx.
+
+Supported ENETC SoCs
+~~~~~~~~~~~~~~~~~~~~
+
+- LS1028
+
+Prerequisites
+~~~~~~~~~~~~~
+
+There are three main pre-requisities for executing ENETC PMD on a ENETC
+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>`_.
+
+The following dependencies are not part of DPDK and must be installed
+separately:
+
+- **NXP Linux LSDK**
+
+  NXP Layerscape software development kit (LSDK) 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.
+
+  LSDK and related information can be obtained from:  `LSDK <https://www.nxp.com/support/developer-resources/run-time-software/linux-software-and-development-tools/layerscape-software-development-kit:LAYERSCAPE-SDK>`_
+
+Driver compilation and testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Please refer the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+   to compile the driver. Please use target "arm64-armv8a-linuxapp-gcc" and disable the below config flags
+   while compilation:
+
+   - ``CONFIG_RTE_EAL_IGB_UIO=n``
+   - ``CONFIG_RTE_KNI_KMOD=n``
+   - ``CONFIG_RTE_LIBRTE_VHOST_NUMA=n``
+   - ``CONFIG_RTE_EAL_NUMA_AWARE_HUGEPAGES=n``
+
+   Refer to the document :ref:`cross build dpdk for arm63 <configure_and_cross_compile_dpdk_build>` to
+   disable flags and for cross compilation
+
+#. To compile in performance mode, please also set ``CONFIG_RTE_CACHE_LINE_SIZE=64``
+
+#. Running l2fwd:
+
+   Follow instructions available in the document
+   :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+   to run l2fwd.
+
+   - First unbind the ports from kernel
+
+     - echo vfio-pci > /sys/bus/pci/devices/0000\:00\:00.1/driver_override
+     - echo 0000:00:00.1 > /sys/bus/pci/drivers/fsl_enetc/unbind
+     - echo vfio-pci > /sys/bus/pci/devices/0000\:00\:00.0/driver_override
+     - echo 0000:00:00.0 > /sys/bus/pci/drivers/fsl_enetc/unbind
+   - Then bind them to VFIO, so that DPDK application can use them
+
+     - echo 0000:00:00.1 > /sys/bus/pci/drivers/vfio-pci/bind
+     - echo 0000:00:00.0 > /sys/bus/pci/drivers/vfio-pci/bind
+   - Mount Hugepages
+
+     - mkdir /mnt/hugepages
+     - mount -t hugetlbfs none /mnt/hugepages
+   - Run l2fwd application
+
+Example output:
+
+   .. code-block:: console
+
+      ./l2fwd -c 0x3 -n 1  --log-level=8 -- -p 0x3 -q 1 -T 0
+
+      .....
+      EAL: Registered [pci] bus.
+      EAL: Detected 2 lcore(s)
+      .....
+      EAL: 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 0 Mbps - full-duplex
+      Port 1 Link Up - speed 0 Mbps - full-duplex
diff --git a/doc/guides/nics/features/enetc.ini b/doc/guides/nics/features/enetc.ini
new file mode 100644
index 000000000..fb1bf5989
--- /dev/null
+++ b/doc/guides/nics/features/enetc.ini
@@ -0,0 +1,8 @@
+;
+; Supported features of the 'enetc' network poll mode driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+ARMv8                = Y
+Usage doc            = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 59f6063dc..0323035d3 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -21,6 +21,7 @@ Network Interface Controller Drivers
     dpaa2
     e1000em
     ena
+    enetc
     enic
     fm10k
     i40e
-- 
2.17.1