[ceph.git] / ceph / src / spdk / dpdk / doc / guides / nics / pfe.rst

.. SPDX-License-Identifier: BSD-3-Clause
   Copyright 2019 NXP

PFE Poll Mode Driver
======================

The PFE NIC PMD (**librte_pmd_pfe**) 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>`_.

PFE
---

This section provides an overview of the NXP PFE
and how it is integrated into the DPDK.

Contents summary

- PFE overview
- PFE features
- Supported PFE SoCs
- Prerequisites
- Driver compilation and testing
- Limitations

PFE Overview
~~~~~~~~~~~~

PFE is a hardware programmable packet forwarding engine to provide
high performance Ethernet interfaces. The diagram below shows a
system level overview of PFE:

.. code-block:: console

   ====================================================+===============
   US   +-----------------------------------------+    | Kernel Space
        |                                         |    |
        |           PFE Ethernet Driver           |    |
        +-----------------------------------------+    |
                  ^   |          ^     |               |
   PFE         RXQ|   |TXQ    RXQ|     |TXQ            |
   PMD            |   |          |     |               |
                  |   v          |     v               |   +----------+
               +---------+     +----------+            |   | pfe.ko   |
               | net_pfe0|     | net_pfe1 |            |   +----------+
               +---------+     +----------+            |
                  ^   |          ^     |               |
               TXQ|   |RXQ    TXQ|     |RXQ            |
                  |   |          |     |               |
                  |   v          |     v               |
                 +------------------------+            |
                 |                        |            |
                 |      PFE HIF driver    |            |
                 +------------------------+            |
                       ^         |                     |
                    RX |      TX |                     |
                   RING|     RING|                     |
                       |         v                     |
                     +--------------+                  |
                     |              |                  |
   ==================|    HIF       |==================+===============
         +-----------+              +--------------+
         |           |              |              |        HW
         |  PFE      +--------------+              |
         |       +-----+                +-----+    |
         |       | MAC |                | MAC |    |
         |       |     |                |     |    |
         +-------+-----+----------------+-----+----+
                 | PHY |                | PHY |
                 +-----+                +-----+


The HIF, PFE, MAC and PHY are the hardware blocks, the pfe.ko is a kernel
module, the PFE HIF driver and the PFE ethernet driver combined represent
as DPDK PFE poll mode driver are running in the userspace.

The PFE 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.

net_pfe0 and net_pfe1 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. PFE 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.

PFE Features
~~~~~~~~~~~~

- L3/L4 checksum offload
- Packet type parsing
- Basic stats
- MTU update
- Promiscuous mode
- Allmulticast mode
- Link status
- ARMv8

Supported PFE SoCs
~~~~~~~~~~~~~~~~~~

- LS1012

Prerequisites
~~~~~~~~~~~~~

Below are some pre-requisites for executing PFE PMD on a PFE
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 pfe has dependency on
   **rte_bus_vdev** library and it is mandatory to use `--vdev` with value `net_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, PFE driver needs `--vdev` as an input with value `net_pfe`
to execute DPDK application. There is an optional parameter `intf` available
to specify port ID. PFE 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="net_pfe0,intf=0" --vdev="net_pfe1,intf=1" -- ...


Limitations
~~~~~~~~~~~

- Multi buffer pool cannot be supported.
Commit	Line	Data
f67539c2 TL	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.