[v2,1/3] doc: add usage doc for ENETC PMD
Checks
Commit Message
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 | 153 +++++++++++++++++++++++++++++
doc/guides/nics/features/enetc.ini | 8 ++
doc/guides/nics/index.rst | 1 +
4 files changed, 167 insertions(+)
create mode 100644 doc/guides/nics/enetc.rst
create mode 100644 doc/guides/nics/features/enetc.ini
Comments
On 9/13/2018 10:41 AM, Gagandeep Singh wrote:
> 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 | 153 +++++++++++++++++++++++++++++
> doc/guides/nics/features/enetc.ini | 8 ++
> doc/guides/nics/index.rst | 1 +
Please also add a release note update.
And a web page patch to supported device list: https://core.dpdk.org/supported/
<...>
> +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. Use target "arm64-armv8a-linuxapp-gcc" in make command
> +
> +#. Refer to the document :ref:`cross build dpdk for arm64 <configure_and_cross_compile_dpdk_build>` to
> + disable flags and for cross compilation
> +
> +#. To compile in performance mode, please 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
We moved common part of documentation into " compiling and testing a PMD for a
NIC" section, check other PMD docs for usage, for example ena PMD, "Usage
example" section.
It is good to keep example output if it has PMD specific logs, but not required
to have generic output.
@@ -643,6 +643,11 @@ F: drivers/net/dpaa2/
F: doc/guides/nics/dpaa2.rst
F: doc/guides/nics/features/dpaa2.ini
+NXP enetc
+M: Gagandeep Singh <g.singh@nxp.com>
+F: doc/guides/nics/enetc.rst
+F: doc/guides/nics/features/enetc.ini
+
QLogic bnx2x
M: Harish Patil <harish.patil@cavium.com>
M: Rasesh Mody <rasesh.mody@cavium.com>
new file mode 100644
@@ -0,0 +1,153 @@
+.. 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
+~~~~~~~~~~~~~~
+
+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.
+
+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/7.3-2018.05/aarch64-linux-gnu/gcc-linaro-7.3.1-2018.05-i686_aarch64-linux-gnu.tar.xz>`_.
+
+2. **Linux Kernel**
+
+ It can be obtained from `NXP's Github hosting <https://source.codeaurora.org/external/qoriq/qoriq-components/linux>`_.
+
+3. **Rootfile system**
+
+ Any *aarch64* supporting filesystem can be used. For example,
+ Ubuntu 16.04 LTS (Xenial) or 18.04 (Bionic) userland which can be obtained
+ from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/18.04/release/ubuntu-base-18.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. Use target "arm64-armv8a-linuxapp-gcc" in make command
+
+#. Refer to the document :ref:`cross build dpdk for arm64 <configure_and_cross_compile_dpdk_build>` to
+ disable flags and for cross compilation
+
+#. To compile in performance mode, please 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
new file mode 100644
@@ -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
@@ -21,6 +21,7 @@ Network Interface Controller Drivers
dpaa2
e1000em
ena
+ enetc
enic
fm10k
i40e