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.si...@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 diff --git a/MAINTAINERS b/MAINTAINERS index 9fd258fad..b999230cc 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -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.si...@nxp.com> +F: doc/guides/nics/enetc.rst +F: doc/guides/nics/features/enetc.ini + QLogic bnx2x M: Harish Patil <harish.pa...@cavium.com> M: Rasesh Mody <rasesh.m...@cavium.com> diff --git a/doc/guides/nics/enetc.rst b/doc/guides/nics/enetc.rst new file mode 100644 index 000000000..da775ebeb --- /dev/null +++ b/doc/guides/nics/enetc.rst @@ -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 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
