doc/guides/nics/pfe.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright 2019 NXP
   3
   4 PFE Poll Mode Driver
   5 ======================
   6
   7 The PFE NIC PMD (**librte_pmd_pfe**) provides poll mode driver
   8 support for the inbuilt NIC found in the **NXP LS1012** SoC.
   9
  10 More information can be found at `NXP Official Website
  11 <https://nxp.com/ls1012a>`_.
  12
  13 PFE
  14 ---
  15
  16 This section provides an overview of the NXP PFE
  17 and how it is integrated into the DPDK.
  18
  19 Contents summary
  20
  21 - PFE overview
  22 - PFE features
  23 - Supported PFE SoCs
  24 - Prerequisites
  25 - Driver compilation and testing
  26 - Limitations
  27
  28 PFE Overview
  29 ~~~~~~~~~~~~
  30
  31 PFE is a hardware programmable packet forwarding engine to provide
  32 high performance Ethernet interfaces. The diagram below shows a
  33 system level overview of PFE:
  34
  35 .. code-block:: console
  36
  37    ====================================================+===============
  38    US   +-----------------------------------------+    | Kernel Space
  39         |                                         |    |
  40         |           PFE Ethernet Driver           |    |
  41         +-----------------------------------------+    |
  42                   ^   |          ^     |               |
  43    PFE         RXQ|   |TXQ    RXQ|     |TXQ            |
  44    PMD            |   |          |     |               |
  45                   |   v          |     v               |   +----------+
  46                +---------+     +----------+            |   | pfe.ko   |
  47                | net_pfe0|     | net_pfe1 |            |   +----------+
  48                +---------+     +----------+            |
  49                   ^   |          ^     |               |
  50                TXQ|   |RXQ    TXQ|     |RXQ            |
  51                   |   |          |     |               |
  52                   |   v          |     v               |
  53                  +------------------------+            |
  54                  |                        |            |
  55                  |      PFE HIF driver    |            |
  56                  +------------------------+            |
  57                        ^         |                     |
  58                     RX |      TX |                     |
  59                    RING|     RING|                     |
  60                        |         v                     |
  61                      +--------------+                  |
  62                      |              |                  |
  63    ==================|    HIF       |==================+===============
  64          +-----------+              +--------------+
  65          |           |              |              |        HW
  66          |  PFE      +--------------+              |
  67          |       +-----+                +-----+    |
  68          |       | MAC |                | MAC |    |
  69          |       |     |                |     |    |
  70          +-------+-----+----------------+-----+----+
  71                  | PHY |                | PHY |
  72                  +-----+                +-----+
  73
  74
  75 The HIF, PFE, MAC and PHY are the hardware blocks, the pfe.ko is a kernel
  76 module, the PFE HIF driver and the PFE ethernet driver combined represent
  77 as DPDK PFE poll mode driver are running in the userspace.
  78
  79 The PFE hardware supports one HIF (host interface) RX ring and one TX ring
  80 to send and receive packets through packet forwarding engine. Both network
  81 interface traffic is multiplexed and send over HIF queue.
  82
  83 net_pfe0 and net_pfe1 are logical ethernet interfaces, created by HIF client
  84 driver. HIF driver is responsible for send and receive packets between
  85 host interface and these logical interfaces. PFE ethernet driver is a
  86 hardware independent and register with the HIF client driver to transmit and
  87 receive packets from HIF via logical interfaces.
  88
  89 pfe.ko is required for PHY initialisation and also responsible for creating
  90 the character device "pfe_us_cdev" which will be used for interacting with
  91 the kernel layer for link status.
  92
  93 PFE Features
  94 ~~~~~~~~~~~~
  95
  96 - L3/L4 checksum offload
  97 - Packet type parsing
  98 - Basic stats
  99 - MTU update
 100 - Promiscuous mode
 101 - Allmulticast mode
 102 - Link status
 103 - ARMv8
 104
 105 Supported PFE SoCs
 106 ~~~~~~~~~~~~~~~~~~
 107
 108 - LS1012
 109
 110 Prerequisites
 111 ~~~~~~~~~~~~~
 112
 113 Below are some pre-requisites for executing PFE PMD on a PFE
 114 compatible board:
 115
 116 1. **ARM 64 Tool Chain**
 117
 118    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>`_.
 119
 120 2. **Linux Kernel**
 121
 122    It can be obtained from `NXP's Github hosting <https://source.codeaurora.org/external/qoriq/qoriq-components/linux>`_.
 123
 124 3. **Rootfile system**
 125
 126    Any *aarch64* supporting filesystem can be used. For example,
 127    Ubuntu 16.04 LTS (Xenial) or 18.04 (Bionic) userland which can be obtained
 128    from `here <http://cdimage.ubuntu.com/ubuntu-base/releases/18.04/release/ubuntu-base-18.04.1-base-arm64.tar.gz>`_.
 129
 130 4. The ethernet device will be registered as virtual device, so pfe has dependency on
 131    **rte_bus_vdev** library and it is mandatory to use `--vdev` with value `net_pfe` to
 132    run DPDK application.
 133
 134 The following dependencies are not part of DPDK and must be installed
 135 separately:
 136
 137 - **NXP Linux LSDK**
 138
 139   NXP Layerscape software development kit (LSDK) includes support for family
 140   of QorIQ® ARM-Architecture-based system on chip (SoC) processors
 141   and corresponding boards.
 142
 143   It includes the Linux board support packages (BSPs) for NXP SoCs,
 144   a fully operational tool chain, kernel and board specific modules.
 145
 146   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>`_
 147
 148 - **pfe kernel module**
 149
 150   pfe kernel module can be obtained from NXP Layerscape software development kit at
 151   location `/lib/modules/<kernel version>/kernel/drivers/staging/fsl_ppfe` in rootfs.
 152   Module should be loaded using below command:
 153
 154   .. code-block:: console
 155
 156      insmod pfe.ko us=1
 157
 158
 159 Driver compilation and testing
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 Follow instructions available in the document
 163 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 164 to launch **testpmd**
 165
 166 Additionally, PFE driver needs `--vdev` as an input with value `net_pfe`
 167 to execute DPDK application. There is an optional parameter `intf` available
 168 to specify port ID. PFE driver supports only two interfaces, so valid values
 169 for `intf` are 0 and 1.
 170 see the command below:
 171
 172  .. code-block:: console
 173
 174     <dpdk app> <EAL args> --vdev="net_pfe0,intf=0" --vdev="net_pfe1,intf=1" -- ...
 175
 176
 177 Limitations
 178 ~~~~~~~~~~~
 179
 180 - Multi buffer pool cannot be supported.