[v3,03/14] doc: add guide for ppfe net PMD
diff mbox series

Message ID 20191001110209.6047-4-g.singh@nxp.com
State Superseded, archived
Delegated to: Ferruh Yigit
Headers show
Series
  • introduces ppfe network PMD
Related show

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Gagandeep Singh Oct. 1, 2019, 11:01 a.m. UTC
This patch add documentation for ppfe network
poll mode driver.

PPFE is a hardware programmable packet
forwarding engine to provide high performance
ethernet interfaces.

Signed-off-by: Gagandeep Singh <g.singh@nxp.com>
Acked-by: Nipun Gupta <nipun.gupta@nxp.com>
Acked-by: Akhil Goyal <akhil.goyal@nxp.com>
---
 MAINTAINERS                       |   1 +
 doc/guides/nics/features/ppfe.ini |   1 +
 doc/guides/nics/index.rst         |   1 +
 doc/guides/nics/ppfe.rst          | 173 ++++++++++++++++++++++++++++++
 4 files changed, 176 insertions(+)
 create mode 100644 doc/guides/nics/ppfe.rst

Comments

Ferruh Yigit Oct. 4, 2019, 3:41 p.m. UTC | #1
On 10/1/2019 12:01 PM, Gagandeep Singh wrote:
> This patch add documentation for ppfe network
> poll mode driver.
> 
> PPFE is a hardware programmable packet
> forwarding engine to provide high performance
> ethernet interfaces.
> 
> Signed-off-by: Gagandeep Singh <g.singh@nxp.com>
> Acked-by: Nipun Gupta <nipun.gupta@nxp.com>
> Acked-by: Akhil Goyal <akhil.goyal@nxp.com>

<...>

> +Driver compilation and testing
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Follow instructions available in the document
> +:ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
> +to launch **testpmd**
> +
> +Additionally, PPFE driver needs `--vdev` as an input with value `eth_pfe`
> +to execute DPDK application. There is an optional parameter `intf` available
> +to specify port ID. PPFE driver supports only two interfaces, so valid values
> +for `intf` are 0 and 1.
> +see the command below:
> +
> + .. code-block:: console
> +
> +    <dpdk app> <EAL args> --vdev="eth_pfe0,intf=0" --vdev="eth_pfe1,intf=1" -- ...

Previously "eth_" was the prefix for the virtual devices, we have renamed it to
"net_" [1], for this new PMD, can you please use 'net_pfe' for consistency?

Also the driver name is 'ppfe', it is under 'net/ppfe' folder, but the device
name is 'pfe'. Is there any specific reason for this?
Would it be better to stick 'pfe' or 'ppfe' everywhere?


[1]
That is why we have alias device names, to keep backward compatibility for "eth_".
Gagandeep Singh Oct. 9, 2019, 6:54 a.m. UTC | #2
> <...>
> 
> > +Driver compilation and testing
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Follow instructions available in the document
> > +:ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
> > +to launch **testpmd**
> > +
> > +Additionally, PPFE driver needs `--vdev` as an input with value `eth_pfe`
> > +to execute DPDK application. There is an optional parameter `intf` available
> > +to specify port ID. PPFE driver supports only two interfaces, so valid values
> > +for `intf` are 0 and 1.
> > +see the command below:
> > +
> > + .. code-block:: console
> > +
> > +    <dpdk app> <EAL args> --vdev="eth_pfe0,intf=0" --vdev="eth_pfe1,intf=1"
> -- ...
> 
> Previously "eth_" was the prefix for the virtual devices, we have renamed it to
> "net_" [1], for this new PMD, can you please use 'net_pfe' for consistency?
> 
> Also the driver name is 'ppfe', it is under 'net/ppfe' folder, but the device
> name is 'pfe'. Is there any specific reason for this?
> Would it be better to stick 'pfe' or 'ppfe' everywhere?
Ok, I will change the interfaces names to net_pfe and will rename the ppfe to pfe everywhere. 

> 
> [1]
> That is why we have alias device names, to keep backward compatibility for
> "eth_".

Patch
diff mbox series

diff --git a/MAINTAINERS b/MAINTAINERS
index 655ccae83..83af78144 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -790,6 +790,7 @@  F: doc/guides/nics/features/enetc.ini
 NXP ppfe
 M: Gagandeep Singh <g.singh@nxp.com>
 M: Akhil Goyal <akhil.goyal@nxp.com>
+F: doc/guides/nics/ppfe.rst
 F: drivers/net/ppfe/
 F: doc/guides/nics/features/ppfe.ini
 
diff --git a/doc/guides/nics/features/ppfe.ini b/doc/guides/nics/features/ppfe.ini
index 4bcac779c..cd5f836a3 100644
--- a/doc/guides/nics/features/ppfe.ini
+++ b/doc/guides/nics/features/ppfe.ini
@@ -6,3 +6,4 @@ 
 [Features]
 Linux VFIO           = Y
 ARMv8                = Y
+Usage doc            = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index d477001d9..e0c931a3e 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -48,6 +48,7 @@  Network Interface Controller Drivers
     nfp
     octeontx
     octeontx2
+    ppfe
     qede
     sfc_efx
     softnic
diff --git a/doc/guides/nics/ppfe.rst b/doc/guides/nics/ppfe.rst
new file mode 100644
index 000000000..29b02957f
--- /dev/null
+++ b/doc/guides/nics/ppfe.rst
@@ -0,0 +1,173 @@ 
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright 2019 NXP
+
+PPFE Poll Mode Driver
+======================
+
+The PPFE NIC PMD (**librte_pmd_ppfe**) provides poll mode driver
+support for the inbuilt NIC found in the **NXP LS1012** SoC.
+
+More information can be found at `NXP Official Website
+<https://nxp.com/ls1012a>`_.
+
+PPFE
+-----
+
+This section provides an overview of the NXP PPFE
+and how it is integrated into the DPDK.
+
+Contents summary
+
+- PPFE overview
+- PPFE features
+- Supported PPFE SoCs
+- Prerequisites
+- Driver compilation and testing
+- Limitations
+
+PPFE Overview
+~~~~~~~~~~~~~~
+
+PPFE is a hardware programmable packet forwarding engine to provide
+high performance Ethernet interfaces. The diagram below shows a
+system level overview of PPFE:
+
+.. code-block:: console
+
+   ====================================================+===============
+   US   +-----------------------------------------+    | Kernel Space
+        |                                         |    |
+        |          PPFE Ethernet Driver           |    |
+        +-----------------------------------------+    |
+                  ^   |          ^     |               |
+   PPFE        RXQ|   |TXQ    RXQ|     |TXQ            |
+   PMD            |   |          |     |               |
+                  |   v          |     v               |   +----------+
+               +---------+     +----------+            |   | pfe.ko   |
+               | pfe_eth0|     | pfe_eth1 |            |   +----------+
+               +---------+     +----------+            |
+                  ^   |          ^     |               |
+               TXQ|   |RXQ    TXQ|     |RXQ            |
+                  |   |          |     |               |
+                  |   v          |     v               |
+                 +------------------------+            |
+                 |                        |            |
+                 |     PPFE HIF driver    |            |
+                 +------------------------+            |
+                       ^         |                     |
+                    RX |      TX |                     |
+                   RING|     RING|                     |
+                       |         v                     |
+                     +--------------+                  |
+                     |              |                  |
+   ==================|    HIF       |==================+===============
+         +-----------+              +--------------+
+         |           |              |              |        HW
+         | PPFE      +--------------+              |
+         |       +-----+                +-----+    |
+         |       | MAC |                | MAC |    |
+         |       |     |                |     |    |
+         +-------+-----+----------------+-----+----+
+                 | PHY |                | PHY |
+                 +-----+                +-----+
+
+
+The HIF, PPFE, MAC and PHY are the hardware blocks, the pfe.ko is a kernel
+module, the PPFE HIF driver and the PPFE ethernet driver combined represent
+as DPDK PPFE poll mode driver are running in the userspace.
+
+The PPFE hardware supports one HIF (host interface) RX ring and one TX ring
+to send and receive packets through packet forwarding engine. Both network
+interface traffic is multiplexed and send over HIF queue.
+
+pfe_eth0 and pfe_eth1 are logical ethernet interfaces, created by HIF client
+driver. HIF driver is responsible for send and receive packets between
+host interface and these logical interfaces. PPFE ethernet driver is a
+hardware independent and register with the HIF client driver to transmit and
+receive packets from HIF via logical interfaces.
+
+pfe.ko is required for PHY initialisation and also responsible for creating
+the character device "pfe_us_cdev" which will be used for interacting with
+the kernel layer for link status.
+
+PPFE Features
+~~~~~~~~~~~~~~
+
+- ARMv8
+
+Supported PPFE SoCs
+~~~~~~~~~~~~~~~~~~~~
+
+- LS1012
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Below are some pre-requisites for executing PPFE PMD on a PPFE
+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>`_.
+
+4. The ethernet device will be registered as virtual device, so ppfe has dependency on
+   **rte_bus_vdev** library and it is mandatory to use `--vdev` with value `eth_pfe` to
+   run DPDK application.
+
+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>`_
+
+- **pfe kernel module**
+
+  pfe kernel module can be obtained from NXP Layerscape software development kit at
+  location `/lib/modules/<kernel version>/kernel/drivers/staging/fsl_ppfe` in rootfs.
+  Module should be loaded using below command:
+
+  .. code-block:: console
+
+     insmod pfe.ko us=1
+
+
+Driver compilation and testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow instructions available in the document
+:ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+to launch **testpmd**
+
+Additionally, PPFE driver needs `--vdev` as an input with value `eth_pfe`
+to execute DPDK application. There is an optional parameter `intf` available
+to specify port ID. PPFE driver supports only two interfaces, so valid values
+for `intf` are 0 and 1.
+see the command below:
+
+ .. code-block:: console
+
+    <dpdk app> <EAL args> --vdev="eth_pfe0,intf=0" --vdev="eth_pfe1,intf=1" -- ...
+
+
+Limitations
+~~~~~~~~~~~
+
+- Multi buffer pool cannot be supported.