Skip to contentSkip to conversation

Improve linux drivers GSG section

PATCH Superseded Bruce Richardson 2 participants 21 messages Mar 2, 2022 – Mar 16, 2022

lore
Share & tools
lore
#0 lore raw

cover Improve linux drivers GSG section

This patchset reworks large parts of the linux drivers section of the Linux Getting Started Guide, so as to make it clearer and easier to read. The overall flow of the page is adjusted so that more important information is nearer the top, and so that all information on VFIO is consolidated into a single section. In terms of the content of the sections, there are some minor changes to adjust what is a warning vs just a "note" in the doc, and there are some updates to increase emphasis on VFIO ovs UIO.

Including stable on CC for the set, as all patches may be candidates for backport to help improve docs for older releases too.

Bruce Richardson (9):
doc/linux_gsg: replace special characters for (R) symbol doc/linux_gsg: fix missing note on UIO module doc/linux_gsg: make UIO safety warning more visible doc/linux_gsg: move section on binding drivers up the page doc/linux_gsg: emphasise VFIO over UIO-based modules doc/linux_gsg: split VFIO section into subsections doc/linux_gsg: move UIO section to the end doc/linux_gsg: consolidate all VFIO content doc/linux_gsg: change informational warnings to notes

 doc/guides/linux_gsg/enable_func.rst   |  16 +-
 doc/guides/linux_gsg/linux_drivers.rst | 396 +++++++++++++------------
 doc/guides/linux_gsg/sys_reqs.rst      |  10 +-
 3 files changed, 223 insertions(+), 199 deletions(-)

--
2.32.0

#1 lore raw

PATCH 1/9 doc/linux_gsg: replace special characters for (R) symbol

Some IDEs, such as eclipse, complained on save about the use of special characters in the (R) symbol in linux GSG doc. We can replace those with the equivalent "|reg|" text, and including isonum.txt.

---
 doc/guides/linux_gsg/enable_func.rst   | 16 +++++++++-------
 doc/guides/linux_gsg/linux_drivers.rst |  6 ++++--
 doc/guides/linux_gsg/sys_reqs.rst      | 10 ++++++----
 3 files changed, 19 insertions(+), 13 deletions(-)
doc/guides/linux_gsg/enable_func.rst +9 -7
index 7bd6b03f10..b5c4c652d7 100644
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2010-2014 Intel Corporation.
 
+.. include:: <isonum.txt>
+
 .. _Enabling_Additional_Functionality:
 
 Enabling Additional Functionality
@@ -119,15 +121,15 @@ system objects' permissions should be adjusted:
 Power Management and Power Saving Functionality
 -----------------------------------------------
 
-Enhanced Intel SpeedStep® Technology must be enabled in the platform BIOS if the power management feature of DPDK is to be used.
+Enhanced Intel SpeedStep\ |reg| Technology must be enabled in the platform BIOS if the power management feature of DPDK is to be used.
 Otherwise, the sys file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` will not exist, and the CPU frequency- based power management cannot be used.
 Consult the relevant BIOS documentation to determine how these settings can be accessed.
 
-For example, on some Intel reference platform BIOS variants, the path to Enhanced Intel SpeedStep® Technology is::
+For example, on some Intel reference platform BIOS variants, the path to Enhanced Intel SpeedStep\ |reg| Technology is::
 
    Advanced
      -> Processor Configuration
-     -> Enhanced Intel SpeedStep® Tech
+     -> Enhanced Intel SpeedStep\ |reg| Tech
 
 In addition, C3 and C6 should be enabled as well for power management. The path of C3 and C6 on the same platform BIOS is::
 
@@ -165,10 +167,10 @@ It should be loaded using the insmod command::
 
    See the "Kernel NIC Interface Sample Application" chapter in the *DPDK Sample Applications User Guide* for more details.
 
-Using Linux IOMMU Pass-Through to Run DPDK with Intel® VT-d
------------------------------------------------------------
+Using Linux IOMMU Pass-Through to Run DPDK with Intel\ |reg| VT-d
+------------------------------------------------------------------
 
-To enable Intel® VT-d in a Linux kernel, a number of kernel configuration options must be set. These include:
+To enable Intel\ |reg| VT-d in a Linux kernel, a number of kernel configuration options must be set. These include:
 
 *   ``IOMMU_SUPPORT``
 
@@ -176,7 +178,7 @@ To enable Intel® VT-d in a Linux kernel, a number of kernel configuration optio
 
 *   ``INTEL_IOMMU``
 
-In addition, to run the DPDK with Intel® VT-d, the ``iommu=pt`` kernel parameter must be used when using ``igb_uio`` driver.
+In addition, to run the DPDK with Intel\ |reg| VT-d, the ``iommu=pt`` kernel parameter must be used when using ``igb_uio`` driver.
 This results in pass-through of the DMAR (DMA Remapping) lookup in the host.
 Also, if ``INTEL_IOMMU_DEFAULT_ON`` is not set in the kernel, the ``intel_iommu=on`` kernel parameter must be used too.
 This ensures that the Intel IOMMU is being initialized as expected.
doc/guides/linux_gsg/linux_drivers.rst +4 -2
index 2dd711bb37..56564286ac 100644
@@ -3,6 +3,8 @@
     Copyright 2017 Mellanox Technologies, Ltd
     All rights reserved.
 
+.. include:: <isonum.txt>
+
 .. _linux_gsg_linux_drivers:
 
 Linux Drivers
@@ -99,7 +101,7 @@ The token will be used for all PF and VF ports within the application.
 
 To make use of full VFIO functionality,
 both kernel and BIOS must support and be configured
-to use IO virtualization (such as Intel® VT-d).
+to use IO virtualization (such as Intel\ |reg| VT-d).
 
 .. note::
 
@@ -335,7 +337,7 @@ Please refer to earlier sections on how to configure kernel parameters
 correctly for your system.
 
 If the kernel is configured correctly, one also has to make sure that
-the BIOS configuration has virtualization features (such as Intel® VT-d).
+the BIOS configuration has virtualization features (such as Intel\ |reg| VT-d).
 There is no standard way to check if the platform is configured correctly,
 so please check with your platform documentation to see if it has such features,
 and how to enable them.
doc/guides/linux_gsg/sys_reqs.rst +6 -4
index d95a78d156..9dccd54d9c 100644
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2010-2014 Intel Corporation.
 
+.. include:: <isonum.txt>
+
 System Requirements
 ===================
 
@@ -8,8 +10,8 @@ This chapter describes the packages required to compile the DPDK.
 
 .. note::
 
-    If the DPDK is being used on an Intel® Communications Chipset 89xx Series platform,
-    please consult the *Intel® Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
+    If the DPDK is being used on an Intel\ |reg| Communications Chipset 89xx Series platform,
+    please consult the *Intel\ |reg| Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
 
 BIOS Setting Prerequisite on x86
 --------------------------------
@@ -72,10 +74,10 @@ Compilation of the DPDK
 
 **Optional Tools:**
 
-*   Intel® C++ Compiler (icc). For installation, additional libraries may be required.
+*   Intel\ |reg| C++ Compiler (icc). For installation, additional libraries may be required.
     See the icc Installation Guide found in the Documentation directory under the compiler installation.
 
-*   IBM® Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
+*   IBM\ |reg| Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
     which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
     it, see the IBM official installation document.
 
Signature · 1 line
2.32.0
#2 lore raw

PATCH 2/9 doc/linux_gsg: fix missing note on UIO module

In reply to Bruce Richardson

The docs on binding drivers was updated as part of the removal of the igb_uio module from the main DPDK repo. As part of that update, a note about uio_pci_generic requiring legacy interrupts was removed, but should have been kept.

Fixes 56bb5841fd06 ("kernel/linux: remove igb_uio")
---
 doc/guides/linux_gsg/linux_drivers.rst | 5 +++++
 1 file changed, 5 insertions(+)
doc/guides/linux_gsg/linux_drivers.rst +5 -0
index 56564286ac..75af2f01e1 100644
@@ -174,6 +174,11 @@ It can be loaded as shown below:
    sudo modprobe uio
    sudo insmod igb_uio.ko
 
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
 .. note::
 
    If UEFI secure boot is enabled,
Signature · 1 line
2.32.0
#3 lore raw

PATCH 3/9 doc/linux_gsg: make UIO safety warning more visible

In reply to Bruce Richardson

The GSG has a note warning that use of UIO is inherently unsafe due to lack of IOMMU protection. However, this was only flagged as a "NOTE", meaning it could easily be missed. Changing the rst tag from "note" to "warning" and moving it to the top of the UIO subsection makes this a lot more visible to users.

---
 doc/guides/linux_gsg/linux_drivers.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +5 -5
index 75af2f01e1..2cdacf0961 100644
@@ -153,6 +153,11 @@ After that, VFIO can be used with hardware devices as usual.
 UIO
 ---
 
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
 In situations where using VFIO is not an option, there are alternative drivers one can use.
 In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
 can be used as a substitute for VFIO. This module can be loaded using the command:
@@ -195,11 +200,6 @@ It can be loaded as shown below:
    in GRUB command line on x86_64 systems,
    or add ``iommu.passthrough=1`` on aarch64 systems.
 
-.. note::
-
-   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
-   and can only be done by root user.
-
 .. _bifurcated_driver:
 
 Bifurcated Driver

--
2.32.0

#4 lore raw

PATCH 4/9 doc/linux_gsg: move section on binding drivers up the page

In reply to Bruce Richardson

While the details of VFIO and UIO may be of interest to some, most users of the doc are likely primarily interested in how to bind their devices to the kernel driver and then move on to running the app. Therefore, the most important part of the "Linux Drivers" section of the GSG is the subsection on "Binding and Unbinding", so put that first.

---
 doc/guides/linux_gsg/linux_drivers.rst | 179 +++++++++++++------------
 1 file changed, 90 insertions(+), 89 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +90 -89
index 2cdacf0961..83f28d86fe 100644
@@ -14,6 +14,96 @@ Different PMDs may require different kernel drivers in order to work properly.
 Depending on the PMD being used, a corresponding kernel driver should be loaded,
 and network ports should be bound to that driver.
 
+.. _linux_gsg_binding_kernel:
+
+Binding and Unbinding Network Ports to/from the Kernel Modules
+--------------------------------------------------------------
+
+.. note::
+
+   PMDs which use the bifurcated driver should not be unbound from their kernel drivers.
+   This section is for PMDs which use the UIO or VFIO drivers.
+   See :ref:`bifurcated_driver` section for more details.
+
+As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
+Instead, in case the PMD being used use the VFIO or UIO drivers,
+all ports that are to be used by a DPDK application must be bound to
+the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
+before the application is run.
+For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
+
+To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
+for DPDK use, or to return ports to Linux control,
+a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
+This utility can be used to provide a view of the current state of the network ports on the system,
+and to bind and unbind those ports from the different kernel modules,
+including the VFIO and UIO modules.
+The following are some examples of how the script can be used.
+A full description of the script and its parameters can be obtained
+by calling the script with the ``--help`` or ``--usage`` options.
+Note that the UIO or VFIO kernel modules to be used,
+should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
+
+.. warning::
+
+   Due to the way VFIO works, there are certain limitations
+   to which devices can be used with VFIO.
+   Mainly it comes down to how IOMMU groups work.
+   Any Virtual Function device can usually be used with VFIO on its own,
+   but physical devices may require either all ports bound to VFIO,
+   or some of them bound to VFIO while others not being bound to anything at all.
+
+   If your device is behind a PCI-to-PCI bridge,
+   the bridge will then be part of the IOMMU group in which your device is in.
+   Therefore, the bridge driver should also be unbound from the bridge PCI device
+   for VFIO to work with devices behind the bridge.
+
+.. warning::
+
+   While any user can run the ``dpdk-devbind.py`` script
+   to view the status of the network ports,
+   binding or unbinding network ports requires root privileges.
+
+To see the status of all network ports on the system:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --status
+
+    Network devices using DPDK-compatible driver
+    ============================================
+    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+
+    Network devices using kernel driver
+    ===================================
+    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
+    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
+    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
+    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
+
+    Other network devices
+    =====================
+    <none>
+
+To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
+
+or, alternatively,
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
+
+To restore device ``82:00.0`` to its original kernel binding:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
+
 VFIO
 ----
 
@@ -225,95 +315,6 @@ More about the bifurcated driver can be found in
 `Mellanox Bifurcated DPDK PMD
 <https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
 
-.. _linux_gsg_binding_kernel:
-
-Binding and Unbinding Network Ports to/from the Kernel Modules
---------------------------------------------------------------
-
-.. note::
-
-   PMDs which use the bifurcated driver should not be unbound from their kernel drivers.
-   This section is for PMDs which use the UIO or VFIO drivers.
-
-As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
-Instead, in case the PMD being used use the VFIO or UIO drivers,
-all ports that are to be used by a DPDK application must be bound to
-the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
-before the application is run.
-For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
-
-To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
-for DPDK use, or to return ports to Linux control,
-a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
-This utility can be used to provide a view of the current state of the network ports on the system,
-and to bind and unbind those ports from the different kernel modules,
-including the VFIO and UIO modules.
-The following are some examples of how the script can be used.
-A full description of the script and its parameters can be obtained
-by calling the script with the ``--help`` or ``--usage`` options.
-Note that the UIO or VFIO kernel modules to be used,
-should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
-
-.. warning::
-
-   Due to the way VFIO works, there are certain limitations
-   to which devices can be used with VFIO.
-   Mainly it comes down to how IOMMU groups work.
-   Any Virtual Function device can usually be used with VFIO on its own,
-   but physical devices may require either all ports bound to VFIO,
-   or some of them bound to VFIO while others not being bound to anything at all.
-
-   If your device is behind a PCI-to-PCI bridge,
-   the bridge will then be part of the IOMMU group in which your device is in.
-   Therefore, the bridge driver should also be unbound from the bridge PCI device
-   for VFIO to work with devices behind the bridge.
-
-.. warning::
-
-   While any user can run the ``dpdk-devbind.py`` script
-   to view the status of the network ports,
-   binding or unbinding network ports requires root privileges.
-
-To see the status of all network ports on the system:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --status
-
-    Network devices using DPDK-compatible driver
-    ============================================
-    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-
-    Network devices using kernel driver
-    ===================================
-    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
-    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
-    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
-    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
-
-    Other network devices
-    =====================
-    <none>
-
-To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
-
-or, alternatively,
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
-
-To restore device ``82:00.0`` to its original kernel binding:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
-
 Troubleshooting VFIO
 --------------------
 
Signature · 1 line
2.32.0
#5 lore raw

PATCH 5/9 doc/linux_gsg: emphasise VFIO over UIO-based modules

In reply to Bruce Richardson

VFIO is to be strongly preferred over uio-based modules, so update our text and examples to only refer to vfio, giving an initial reference at the start to uio as a fallback option.

---
 doc/guides/linux_gsg/linux_drivers.rst | 47 +++++++++++++++-----------
 1 file changed, 28 insertions(+), 19 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +28 -19
index 83f28d86fe..af7e3c4fbc 100644
@@ -25,14 +25,18 @@ Binding and Unbinding Network Ports to/from the Kernel Modules
    This section is for PMDs which use the UIO or VFIO drivers.
    See :ref:`bifurcated_driver` section for more details.
 
-As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
-Instead, in case the PMD being used use the VFIO or UIO drivers,
-all ports that are to be used by a DPDK application must be bound to
-the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
-before the application is run.
-For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
-
-To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
+.. note::
+
+   It is recommended that ``vfio-pci`` be used as the kernel module for DPDK-bound ports in all cases.
+   If an IOMMU is unavailable, the ``vfio-pci`` can be used in :ref:`no-iommu<vfio_noiommu>` mode.
+   If, for some reason, vfio is unavailable, then UIO-based modules, ``igb_uio`` and ``uio_pci_generic`` may be used.
+   See section :ref:`uio` for details.
+
+Most devices require that the hardware to be used by DPDK be unbound from the kernel driver it uses,
+and instead be bound to the ``vfio-pci`` kernel module before the application is run.
+For such PMDs, any network ports or other hardware under Linux* control will be ignored and cannot be used by the application.
+
+To bind ports to the ``vfio-pci`` module
 for DPDK use, or to return ports to Linux control,
 a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
 This utility can be used to provide a view of the current state of the network ports on the system,
@@ -72,37 +76,38 @@ To see the status of all network ports on the system:
 
     Network devices using DPDK-compatible driver
     ============================================
-    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+    0000:82:00.0 '82599EB 10-GbE NIC' drv=vfio-pci unused=ixgbe
+    0000:82:00.1 '82599EB 10-GbE NIC' drv=vfio-pci unused=ixgbe
 
     Network devices using kernel driver
     ===================================
-    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
-    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
-    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
-    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
+    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=vfio-pci *Active*
+    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=vfio-pci
+    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=vfio-pci
+    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=vfio-pci
 
     Other network devices
     =====================
     <none>
 
-To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
+To bind device ``eth1``,``04:00.1``, to the ``vfio-pci`` driver:
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
+    ./usertools/dpdk-devbind.py --bind=vfio-pci 04:00.1
 
 or, alternatively,
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
+    ./usertools/dpdk-devbind.py --bind=vfio-pci eth1
 
-To restore device ``82:00.0`` to its original kernel binding:
+When specifying device ids, wildcards can be used for the final part of the address.
+To restore device ``82:00.0`` and ``82:00.1`` to their original kernel binding:
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
+    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.*
 
 VFIO
 ----
@@ -210,6 +215,8 @@ to use IO virtualization (such as Intel\ |reg| VT-d).
 For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
 For more information, please refer to :ref:`Running_Without_Root_Privileges`.
 
+.. _vfio_noiommu:
+
 VFIO no-IOMMU mode
 ------------------
 
@@ -240,6 +247,8 @@ After that, VFIO can be used with hardware devices as usual.
    to keep the degree of device access and programming that VFIO has,
    in situations where IOMMU is not available.
 
+.. _uio:
+
 UIO
 ---
 
Signature · 1 line
2.32.0
#6 lore raw

PATCH 6/9 doc/linux_gsg: split VFIO section into subsections

In reply to Bruce Richardson

The VFIO section of the page about linux drivers was rather long and unstructured. This can be improved by splitting it up into subsections, to cover the specifics of memory limits and creating VFs. When moving the various text notes into the relevant subsections, we can drop the note about kernels earlier than 3.6, since DPDK no longer supports kernels that old.

---
 doc/guides/linux_gsg/linux_drivers.rst | 35 ++++++++++++++------------
 1 file changed, 19 insertions(+), 16 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +19 -16
index af7e3c4fbc..e29f79e385 100644
@@ -122,6 +122,22 @@ To make use of VFIO, the ``vfio-pci`` module must be loaded:
 VFIO kernel is usually present by default in all distributions,
 however please consult your distributions documentation to make sure that is the case.
 
+To make use of full VFIO functionality,
+both kernel and BIOS must support and be configured
+to use IO virtualization (such as Intel\ |reg| VT-d).
+
+.. note::
+
+   In most cases, specifying "iommu=on" as kernel parameter should be enough to
+   configure the Linux kernel to use IOMMU.
+
+For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
+For more information, please refer to :ref:`Running_Without_Root_Privileges`.
+
+
+VFIO Memory Mapping Limits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 For DMA mapping of either external memory or hugepages, VFIO interface is used.
 VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is
 mapped in hugepage granularity or system page granularity. Number of DMA
@@ -132,6 +148,9 @@ VFIO module parameter ``dma_entry_limit`` with a default value of 64K.
 When application is out of DMA entries, these limits need to be adjusted to
 increase the allowed limit.
 
+Creating Virtual Functions using vfio-pci
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Since Linux version 5.7,
 the ``vfio-pci`` module supports the creation of virtual functions.
 After the PF is bound to ``vfio-pci`` module,
@@ -194,27 +213,11 @@ The token will be used for all PF and VF ports within the application.
       <build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \
       --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i
 
-To make use of full VFIO functionality,
-both kernel and BIOS must support and be configured
-to use IO virtualization (such as Intel\ |reg| VT-d).
-
-.. note::
-
-   Linux versions earlier than version 3.6 do not support VFIO.
-
 .. note::
 
    Linux versions earlier than version 5.7 do not support the creation of
    virtual functions within the VFIO framework.
 
-.. note::
-
-   In most cases, specifying "iommu=on" as kernel parameter should be enough to
-   configure the Linux kernel to use IOMMU.
-
-For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
-For more information, please refer to :ref:`Running_Without_Root_Privileges`.
-
 .. _vfio_noiommu:
 
 VFIO no-IOMMU mode
Signature · 1 line
2.32.0
#7 lore raw

PATCH 7/9 doc/linux_gsg: move UIO section to the end

In reply to Bruce Richardson

To further de-emphasise UIO over the alternatives, we can move the UIO section of the drivers page to the end of the document, giving more prominence to VFIO and bifurcated drivers.

---
 doc/guides/linux_gsg/linux_drivers.rst | 104 ++++++++++++-------------
 1 file changed, 52 insertions(+), 52 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +52 -52
index e29f79e385..b2be442d27 100644
@@ -250,58 +250,6 @@ After that, VFIO can be used with hardware devices as usual.
    to keep the degree of device access and programming that VFIO has,
    in situations where IOMMU is not available.
 
-.. _uio:
-
-UIO
----
-
-.. warning::
-
-   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
-   and can only be done by root user.
-
-In situations where using VFIO is not an option, there are alternative drivers one can use.
-In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
-can be used as a substitute for VFIO. This module can be loaded using the command:
-
-.. code-block:: console
-
-   sudo modprobe uio_pci_generic
-
-.. note::
-
-   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
-
-As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
-which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
-It can be loaded as shown below:
-
-.. code-block:: console
-
-   sudo modprobe uio
-   sudo insmod igb_uio.ko
-
-.. note::
-
-    For some devices which lack support for legacy interrupts, e.g. virtual function
-    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
-
-.. note::
-
-   If UEFI secure boot is enabled,
-   the Linux kernel may disallow the use of UIO on the system.
-   Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module
-   rather than any UIO-based module.
-   For more details see :ref:`linux_gsg_binding_kernel` below.
-
-.. note::
-
-   If the devices used for DPDK are bound to the ``uio_pci_generic`` kernel module,
-   please make sure that the IOMMU is disabled or is in passthrough mode.
-   One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``
-   in GRUB command line on x86_64 systems,
-   or add ``iommu.passthrough=1`` on aarch64 systems.
-
 .. _bifurcated_driver:
 
 Bifurcated Driver
@@ -372,3 +320,55 @@ This can be checked in the boot configuration of your system:
 If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
 VFIO driver will not support the no-IOMMU mode,
 and other alternatives (such as UIO drivers) will have to be used.
+
+.. _uio:
+
+UIO
+---
+
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
+In situations where using VFIO is not an option, there are alternative drivers one can use.
+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
+can be used as a substitute for VFIO. This module can be loaded using the command:
+
+.. code-block:: console
+
+   sudo modprobe uio_pci_generic
+
+.. note::
+
+   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
+
+As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
+which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
+It can be loaded as shown below:
+
+.. code-block:: console
+
+   sudo modprobe uio
+   sudo insmod igb_uio.ko
+
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
+.. note::
+
+   If UEFI secure boot is enabled,
+   the Linux kernel may disallow the use of UIO on the system.
+   Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module
+   rather than any UIO-based module.
+   For more details see :ref:`linux_gsg_binding_kernel` below.
+
+.. note::
+
+   If the devices used for DPDK are bound to the ``uio_pci_generic`` kernel module,
+   please make sure that the IOMMU is disabled or is in passthrough mode.
+   One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``
+   in GRUB command line on x86_64 systems,
+   or add ``iommu.passthrough=1`` on aarch64 systems.
Signature · 1 line
2.32.0
#8 lore raw

PATCH 8/9 doc/linux_gsg: consolidate all VFIO content

In reply to Bruce Richardson

Rather than having separate sections for VFIO and VFIO no-iommu mode, as well as a separate section further down the document on troubleshooting VFIO, we can consolidate all these as subsections into a primary VFIO section. This section starts with the basics of VFIO use, then covers no-iommu mode, before moving on to the more advanced topics such as creating VFs and ending with the troubleshooting subsection.

---
 doc/guides/linux_gsg/linux_drivers.rst | 116 ++++++++++++-------------
 1 file changed, 58 insertions(+), 58 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +58 -58
index b2be442d27..ef91999dd9 100644
@@ -135,6 +135,38 @@ For proper operation of VFIO when running DPDK applications as a non-privileged
 For more information, please refer to :ref:`Running_Without_Root_Privileges`.
 
 
+.. _vfio_noiommu:
+
+VFIO no-IOMMU mode
+~~~~~~~~~~~~~~~~~~
+
+If there is no IOMMU available on the system, VFIO can still be used,
+but it has to be loaded with an additional module parameter:
+
+.. code-block:: console
+
+   modprobe vfio enable_unsafe_noiommu_mode=1
+
+Alternatively, one can also enable this option in an already loaded kernel module:
+
+.. code-block:: console
+
+   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
+
+After that, VFIO can be used with hardware devices as usual.
+
+.. note::
+
+   It may be required to unload all VFIO related-modules before probing
+   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
+
+.. warning::
+
+   Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe.
+   That said, it does make it possible for the user
+   to keep the degree of device access and programming that VFIO has,
+   in situations where IOMMU is not available.
+
 VFIO Memory Mapping Limits
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -218,65 +250,8 @@ The token will be used for all PF and VF ports within the application.
    Linux versions earlier than version 5.7 do not support the creation of
    virtual functions within the VFIO framework.
 
-.. _vfio_noiommu:
-
-VFIO no-IOMMU mode
-------------------
-
-If there is no IOMMU available on the system, VFIO can still be used,
-but it has to be loaded with an additional module parameter:
-
-.. code-block:: console
-
-   modprobe vfio enable_unsafe_noiommu_mode=1
-
-Alternatively, one can also enable this option in an already loaded kernel module:
-
-.. code-block:: console
-
-   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
-
-After that, VFIO can be used with hardware devices as usual.
-
-.. note::
-
-   It may be required to unload all VFIO related-modules before probing
-   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
-
-.. warning::
-
-   Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe.
-   That said, it does make it possible for the user
-   to keep the degree of device access and programming that VFIO has,
-   in situations where IOMMU is not available.
-
-.. _bifurcated_driver:
-
-Bifurcated Driver
------------------
-
-PMDs which use the bifurcated driver co-exists with the device kernel driver.
-On such model the NIC is controlled by the kernel, while the data
-path is performed by the PMD directly on top of the device.
-
-Such model has the following benefits:
-
- - It is secure and robust, as the memory management and isolation
-   is done by the kernel.
- - It enables the user to use legacy linux tools such as ``ethtool`` or
-   ``ifconfig`` while running DPDK application on the same network ports.
- - It enables the DPDK application to filter only part of the traffic,
-   while the rest will be directed and handled by the kernel driver.
-   The flow bifurcation is performed by the NIC hardware.
-   As an example, using :ref:`flow_isolated_mode` allows to choose
-   strictly what is received in DPDK.
-
-More about the bifurcated driver can be found in
-`Mellanox Bifurcated DPDK PMD
-<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
-
 Troubleshooting VFIO
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 In certain situations, using ``dpdk-devbind.py`` script
 to bind a device to VFIO driver may fail.
@@ -321,6 +296,31 @@ If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
 VFIO driver will not support the no-IOMMU mode,
 and other alternatives (such as UIO drivers) will have to be used.
 
+.. _bifurcated_driver:
+
+Bifurcated Driver
+-----------------
+
+PMDs which use the bifurcated driver co-exists with the device kernel driver.
+On such model the NIC is controlled by the kernel, while the data
+path is performed by the PMD directly on top of the device.
+
+Such model has the following benefits:
+
+ - It is secure and robust, as the memory management and isolation
+   is done by the kernel.
+ - It enables the user to use legacy linux tools such as ``ethtool`` or
+   ``ifconfig`` while running DPDK application on the same network ports.
+ - It enables the DPDK application to filter only part of the traffic,
+   while the rest will be directed and handled by the kernel driver.
+   The flow bifurcation is performed by the NIC hardware.
+   As an example, using :ref:`flow_isolated_mode` allows to choose
+   strictly what is received in DPDK.
+
+More about the bifurcated driver can be found in
+`Mellanox Bifurcated DPDK PMD
+<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
+
 .. _uio:
 
 UIO
Signature · 1 line
2.32.0
#9 lore raw

PATCH 9/9 doc/linux_gsg: change informational warnings to notes

In reply to Bruce Richardson

There are two warnings in the VFIO section about limitations of VFIO and limitations on who can bind/unbind devices. Since these don't actually describe any unsafe conditions, and are more informational, we can change these to notes. This also helps emphasise the other warnings in the documents which flag genuine security concerns.

---
 doc/guides/linux_gsg/linux_drivers.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +2 -2
index ef91999dd9..03cf264a0a 100644
@@ -48,7 +48,7 @@ by calling the script with the ``--help`` or ``--usage`` options.
 Note that the UIO or VFIO kernel modules to be used,
 should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
 
-.. warning::
+.. note::
 
    Due to the way VFIO works, there are certain limitations
    to which devices can be used with VFIO.
@@ -62,7 +62,7 @@ should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
    Therefore, the bridge driver should also be unbound from the bridge PCI device
    for VFIO to work with devices behind the bridge.
 
-.. warning::
+.. note::
 
    While any user can run the ``dpdk-devbind.py`` script
    to view the status of the network ports,
Signature · 1 line
2.32.0
#10 lore raw

v2 cover Improve Linux drivers GSG section

In reply to Bruce Richardson

This patchset reworks large parts of the linux drivers section of the Linux Getting Started Guide, so as to make it clearer and easier to read. The overall flow of the page is adjusted so that more important information is nearer the top, and so that all information on VFIO is consolidated into a single section. In terms of the content of the sections, there are some minor changes to adjust what is a warning vs just a "note" in the doc, and there are some updates to increase emphasis on VFIO ovs UIO.

Including stable on CC for the set, as all patches may be candidates for backport to help improve docs for older releases too.

V2:
* Rebased on top of main, now that other doc patches are applied
* Reworded commit titles to use "doc:" prefix

Bruce Richardson (9):
doc: replace special characters for (R) symbol in Linux GSG
doc: fix missing note on UIO module in Linux GSG
doc: make UIO safety warning more visible in Linux GSG
doc: move section on binding drivers up the page in GSG
doc: emphasise VFIO over UIO-based modules in GSG
doc: split GSG VFIO section into subsections
doc: move GSG section on UIO to the end of drivers page
doc: consolidate all VFIO content on GSG driver page
doc: change informational warnings to notes in Linux GSG

 doc/guides/linux_gsg/enable_func.rst   |   8 +-
 doc/guides/linux_gsg/linux_drivers.rst | 396 +++++++++++++------------
 doc/guides/linux_gsg/sys_reqs.rst      |   6 +-
 3 files changed, 217 insertions(+), 193 deletions(-)

--
2.32.0

#11 lore raw

PATCH v2 1/9 doc: replace special characters for (R) symbol in Linux GSG

Some IDEs, such as eclipse, complained on save about the use of special characters in the (R) symbol in linux GSG doc. We can replace those with the equivalent "|reg|" text, and including isonum.txt.

---
 doc/guides/linux_gsg/enable_func.rst   | 8 +++++---
 doc/guides/linux_gsg/linux_drivers.rst | 6 ++++--
 doc/guides/linux_gsg/sys_reqs.rst      | 6 ++++--
 3 files changed, 13 insertions(+), 7 deletions(-)
doc/guides/linux_gsg/enable_func.rst +5 -3
index 44c3b05130..1df3ab0255 100644
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2010-2014 Intel Corporation.
 
+.. include:: <isonum.txt>
+
 .. _Enabling_Additional_Functionality:
 
 Enabling Additional Functionality
@@ -66,15 +68,15 @@ system objects' permissions should be adjusted:
 Power Management and Power Saving Functionality
 -----------------------------------------------
 
-Enhanced Intel SpeedStep® Technology must be enabled in the platform BIOS if the power management feature of DPDK is to be used.
+Enhanced Intel SpeedStep\ |reg| Technology must be enabled in the platform BIOS if the power management feature of DPDK is to be used.
 Otherwise, the sys file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` will not exist, and the CPU frequency- based power management cannot be used.
 Consult the relevant BIOS documentation to determine how these settings can be accessed.
 
-For example, on some Intel reference platform BIOS variants, the path to Enhanced Intel SpeedStep® Technology is::
+For example, on some Intel reference platform BIOS variants, the path to Enhanced Intel SpeedStep\ |reg| Technology is::
 
    Advanced
      -> Processor Configuration
-     -> Enhanced Intel SpeedStep® Tech
+     -> Enhanced Intel SpeedStep\ |reg| Tech
 
 In addition, C3 and C6 should be enabled as well for power management. The path of C3 and C6 on the same platform BIOS is::
 
doc/guides/linux_gsg/linux_drivers.rst +4 -2
index 006a9df83e..ef6fec10d7 100644
@@ -3,6 +3,8 @@
     Copyright 2017 Mellanox Technologies, Ltd
     All rights reserved.
 
+.. include:: <isonum.txt>
+
 .. _linux_gsg_linux_drivers:
 
 Linux Drivers
@@ -99,7 +101,7 @@ The token will be used for all PF and VF ports within the application.
 
 To make use of full VFIO functionality,
 both kernel and BIOS must support and be configured
-to use IO virtualization (such as Intel® VT-d).
+to use IO virtualization (such as Intel\ |reg| VT-d).
 
 .. note::
 
@@ -335,7 +337,7 @@ Please refer to earlier sections on how to configure kernel parameters
 correctly for your system.
 
 If the kernel is configured correctly, one also has to make sure that
-the BIOS configuration has virtualization features (such as Intel® VT-d).
+the BIOS configuration has virtualization features (such as Intel\ |reg| VT-d).
 There is no standard way to check if the platform is configured correctly,
 so please check with your platform documentation to see if it has such features,
 and how to enable them.
doc/guides/linux_gsg/sys_reqs.rst +4 -2
index b2eacac6dc..08d45898f0 100644
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2010-2014 Intel Corporation.
 
+.. include:: <isonum.txt>
+
 System Requirements
 ===================
 
@@ -68,10 +70,10 @@ Compilation of the DPDK
 
 **Optional Tools:**
 
-*   Intel® C++ Compiler (icc). For installation, additional libraries may be required.
+*   Intel\ |reg| C++ Compiler (icc). For installation, additional libraries may be required.
     See the icc Installation Guide found in the Documentation directory under the compiler installation.
 
-*   IBM® Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
+*   IBM\ |reg| Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
     which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
     it, see the IBM official installation document.
 

--
2.32.0

#12 lore raw

PATCH v2 2/9 doc: fix missing note on UIO module in Linux GSG

In reply to Bruce Richardson

The docs on binding drivers was updated as part of the removal of the igb_uio module from the main DPDK repo. As part of that update, a note about uio_pci_generic requiring legacy interrupts was removed, but should have been kept.

Fixes 56bb5841fd06 ("kernel/linux: remove igb_uio")
---
 doc/guides/linux_gsg/linux_drivers.rst | 5 +++++
 1 file changed, 5 insertions(+)
doc/guides/linux_gsg/linux_drivers.rst +5 -0
index ef6fec10d7..bd983b4d81 100644
@@ -174,6 +174,11 @@ It can be loaded as shown below:
    sudo modprobe uio
    sudo insmod igb_uio.ko
 
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
 .. note::
 
    If UEFI secure boot is enabled,
Signature · 1 line
2.32.0
#13 lore raw

PATCH v2 3/9 doc: make UIO safety warning more visible in Linux GSG

In reply to Bruce Richardson

The GSG has a note warning that use of UIO is inherently unsafe due to lack of IOMMU protection. However, this was only flagged as a "NOTE", meaning it could easily be missed. Changing the rst tag from "note" to "warning" and moving it to the top of the UIO subsection makes this a lot more visible to users.

---
 doc/guides/linux_gsg/linux_drivers.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +5 -5
index bd983b4d81..f0a274df6a 100644
@@ -153,6 +153,11 @@ After that, VFIO can be used with hardware devices as usual.
 UIO
 ---
 
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
 In situations where using VFIO is not an option, there are alternative drivers one can use.
 In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
 can be used as a substitute for VFIO. This module can be loaded using the command:
@@ -195,11 +200,6 @@ It can be loaded as shown below:
    in GRUB command line on x86_64 systems,
    or add ``iommu.passthrough=1`` on aarch64 systems.
 
-.. note::
-
-   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
-   and can only be done by root user.
-
 .. _bifurcated_driver:
 
 Bifurcated Driver

--
2.32.0

#14 lore raw

PATCH v2 4/9 doc: move section on binding drivers up the page in GSG

In reply to Bruce Richardson

While the details of VFIO and UIO may be of interest to some, most users of the doc are likely primarily interested in how to bind their devices to the kernel driver and then move on to running the app. Therefore, the most important part of the "Linux Drivers" section of the GSG is the subsection on "Binding and Unbinding", so put that first.

---
 doc/guides/linux_gsg/linux_drivers.rst | 179 +++++++++++++------------
 1 file changed, 90 insertions(+), 89 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +90 -89
index f0a274df6a..b93feae7a1 100644
@@ -14,6 +14,96 @@ Different PMDs may require different kernel drivers in order to work properly.
 Depending on the PMD being used, a corresponding kernel driver should be loaded,
 and network ports should be bound to that driver.
 
+.. _linux_gsg_binding_kernel:
+
+Binding and Unbinding Network Ports to/from the Kernel Modules
+--------------------------------------------------------------
+
+.. note::
+
+   PMDs which use the bifurcated driver should not be unbound from their kernel drivers.
+   This section is for PMDs which use the UIO or VFIO drivers.
+   See :ref:`bifurcated_driver` section for more details.
+
+As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
+Instead, in case the PMD being used use the VFIO or UIO drivers,
+all ports that are to be used by a DPDK application must be bound to
+the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
+before the application is run.
+For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
+
+To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
+for DPDK use, or to return ports to Linux control,
+a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
+This utility can be used to provide a view of the current state of the network ports on the system,
+and to bind and unbind those ports from the different kernel modules,
+including the VFIO and UIO modules.
+The following are some examples of how the script can be used.
+A full description of the script and its parameters can be obtained
+by calling the script with the ``--help`` or ``--usage`` options.
+Note that the UIO or VFIO kernel modules to be used,
+should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
+
+.. warning::
+
+   Due to the way VFIO works, there are certain limitations
+   to which devices can be used with VFIO.
+   Mainly it comes down to how IOMMU groups work.
+   Any Virtual Function device can usually be used with VFIO on its own,
+   but physical devices may require either all ports bound to VFIO,
+   or some of them bound to VFIO while others not being bound to anything at all.
+
+   If your device is behind a PCI-to-PCI bridge,
+   the bridge will then be part of the IOMMU group in which your device is in.
+   Therefore, the bridge driver should also be unbound from the bridge PCI device
+   for VFIO to work with devices behind the bridge.
+
+.. warning::
+
+   While any user can run the ``dpdk-devbind.py`` script
+   to view the status of the network ports,
+   binding or unbinding network ports requires root privileges.
+
+To see the status of all network ports on the system:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --status
+
+    Network devices using DPDK-compatible driver
+    ============================================
+    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+
+    Network devices using kernel driver
+    ===================================
+    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
+    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
+    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
+    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
+
+    Other network devices
+    =====================
+    <none>
+
+To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
+
+or, alternatively,
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
+
+To restore device ``82:00.0`` to its original kernel binding:
+
+.. code-block:: console
+
+    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
+
 VFIO
 ----
 
@@ -225,95 +315,6 @@ More about the bifurcated driver can be found in
 `Mellanox Bifurcated DPDK PMD
 <https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
 
-.. _linux_gsg_binding_kernel:
-
-Binding and Unbinding Network Ports to/from the Kernel Modules
---------------------------------------------------------------
-
-.. note::
-
-   PMDs which use the bifurcated driver should not be unbound from their kernel drivers.
-   This section is for PMDs which use the UIO or VFIO drivers.
-
-As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
-Instead, in case the PMD being used use the VFIO or UIO drivers,
-all ports that are to be used by a DPDK application must be bound to
-the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
-before the application is run.
-For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
-
-To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
-for DPDK use, or to return ports to Linux control,
-a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
-This utility can be used to provide a view of the current state of the network ports on the system,
-and to bind and unbind those ports from the different kernel modules,
-including the VFIO and UIO modules.
-The following are some examples of how the script can be used.
-A full description of the script and its parameters can be obtained
-by calling the script with the ``--help`` or ``--usage`` options.
-Note that the UIO or VFIO kernel modules to be used,
-should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
-
-.. warning::
-
-   Due to the way VFIO works, there are certain limitations
-   to which devices can be used with VFIO.
-   Mainly it comes down to how IOMMU groups work.
-   Any Virtual Function device can usually be used with VFIO on its own,
-   but physical devices may require either all ports bound to VFIO,
-   or some of them bound to VFIO while others not being bound to anything at all.
-
-   If your device is behind a PCI-to-PCI bridge,
-   the bridge will then be part of the IOMMU group in which your device is in.
-   Therefore, the bridge driver should also be unbound from the bridge PCI device
-   for VFIO to work with devices behind the bridge.
-
-.. warning::
-
-   While any user can run the ``dpdk-devbind.py`` script
-   to view the status of the network ports,
-   binding or unbinding network ports requires root privileges.
-
-To see the status of all network ports on the system:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --status
-
-    Network devices using DPDK-compatible driver
-    ============================================
-    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-
-    Network devices using kernel driver
-    ===================================
-    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
-    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
-    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
-    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
-
-    Other network devices
-    =====================
-    <none>
-
-To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
-
-or, alternatively,
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
-
-To restore device ``82:00.0`` to its original kernel binding:
-
-.. code-block:: console
-
-    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
-
 Troubleshooting VFIO
 --------------------
 

--
2.32.0

#15 lore raw

PATCH v2 5/9 doc: emphasise VFIO over UIO-based modules in GSG

In reply to Bruce Richardson

VFIO is to be strongly preferred over uio-based modules, so update our text and examples to only refer to vfio, giving an initial reference at the start to uio as a fallback option.

---
 doc/guides/linux_gsg/linux_drivers.rst | 47 +++++++++++++++-----------
 1 file changed, 28 insertions(+), 19 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +28 -19
index b93feae7a1..bd649db929 100644
@@ -25,14 +25,18 @@ Binding and Unbinding Network Ports to/from the Kernel Modules
    This section is for PMDs which use the UIO or VFIO drivers.
    See :ref:`bifurcated_driver` section for more details.
 
-As of release 1.4, DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
-Instead, in case the PMD being used use the VFIO or UIO drivers,
-all ports that are to be used by a DPDK application must be bound to
-the ``vfio-pci``, ``uio_pci_generic``, or ``igb_uio`` module
-before the application is run.
-For such PMDs, any network ports under Linux* control will be ignored and cannot be used by the application.
-
-To bind ports to the ``vfio-pci``, ``uio_pci_generic`` or ``igb_uio`` module
+.. note::
+
+   It is recommended that ``vfio-pci`` be used as the kernel module for DPDK-bound ports in all cases.
+   If an IOMMU is unavailable, the ``vfio-pci`` can be used in :ref:`no-iommu<vfio_noiommu>` mode.
+   If, for some reason, vfio is unavailable, then UIO-based modules, ``igb_uio`` and ``uio_pci_generic`` may be used.
+   See section :ref:`uio` for details.
+
+Most devices require that the hardware to be used by DPDK be unbound from the kernel driver it uses,
+and instead be bound to the ``vfio-pci`` kernel module before the application is run.
+For such PMDs, any network ports or other hardware under Linux* control will be ignored and cannot be used by the application.
+
+To bind ports to the ``vfio-pci`` module
 for DPDK use, or to return ports to Linux control,
 a utility script called ``dpdk-devbind.py`` is provided in the ``usertools`` subdirectory.
 This utility can be used to provide a view of the current state of the network ports on the system,
@@ -72,37 +76,38 @@ To see the status of all network ports on the system:
 
     Network devices using DPDK-compatible driver
     ============================================
-    0000:82:00.0 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
-    0000:82:00.1 '82599EB 10-GbE NIC' drv=uio_pci_generic unused=ixgbe
+    0000:82:00.0 '82599EB 10-GbE NIC' drv=vfio-pci unused=ixgbe
+    0000:82:00.1 '82599EB 10-GbE NIC' drv=vfio-pci unused=ixgbe
 
     Network devices using kernel driver
     ===================================
-    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=uio_pci_generic *Active*
-    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=uio_pci_generic
-    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=uio_pci_generic
-    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=uio_pci_generic
+    0000:04:00.0 'I350 1-GbE NIC' if=em0  drv=igb unused=vfio-pci *Active*
+    0000:04:00.1 'I350 1-GbE NIC' if=eth1 drv=igb unused=vfio-pci
+    0000:04:00.2 'I350 1-GbE NIC' if=eth2 drv=igb unused=vfio-pci
+    0000:04:00.3 'I350 1-GbE NIC' if=eth3 drv=igb unused=vfio-pci
 
     Other network devices
     =====================
     <none>
 
-To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver:
+To bind device ``eth1``,``04:00.1``, to the ``vfio-pci`` driver:
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic 04:00.1
+    ./usertools/dpdk-devbind.py --bind=vfio-pci 04:00.1
 
 or, alternatively,
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth1
+    ./usertools/dpdk-devbind.py --bind=vfio-pci eth1
 
-To restore device ``82:00.0`` to its original kernel binding:
+When specifying device ids, wildcards can be used for the final part of the address.
+To restore device ``82:00.0`` and ``82:00.1`` to their original kernel binding:
 
 .. code-block:: console
 
-    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.0
+    ./usertools/dpdk-devbind.py --bind=ixgbe 82:00.*
 
 VFIO
 ----
@@ -210,6 +215,8 @@ to use IO virtualization (such as Intel\ |reg| VT-d).
 For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
 For more information, please refer to :ref:`Running_Without_Root_Privileges`.
 
+.. _vfio_noiommu:
+
 VFIO no-IOMMU mode
 ------------------
 
@@ -240,6 +247,8 @@ After that, VFIO can be used with hardware devices as usual.
    to keep the degree of device access and programming that VFIO has,
    in situations where IOMMU is not available.
 
+.. _uio:
+
 UIO
 ---
 

--
2.32.0

#16 lore raw

PATCH v2 6/9 doc: split GSG VFIO section into subsections

In reply to Bruce Richardson

The VFIO section of the page about linux drivers was rather long and unstructured. This can be improved by splitting it up into subsections, to cover the specifics of memory limits and creating VFs. When moving the various text notes into the relevant subsections, we can drop the note about kernels earlier than 3.6, since DPDK no longer supports kernels that old.

---
 doc/guides/linux_gsg/linux_drivers.rst | 35 ++++++++++++++------------
 1 file changed, 19 insertions(+), 16 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +19 -16
index bd649db929..f9c24e9456 100644
@@ -122,6 +122,22 @@ To make use of VFIO, the ``vfio-pci`` module must be loaded:
 VFIO kernel is usually present by default in all distributions,
 however please consult your distributions documentation to make sure that is the case.
 
+To make use of full VFIO functionality,
+both kernel and BIOS must support and be configured
+to use IO virtualization (such as Intel\ |reg| VT-d).
+
+.. note::
+
+   In most cases, specifying "iommu=on" as kernel parameter should be enough to
+   configure the Linux kernel to use IOMMU.
+
+For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
+For more information, please refer to :ref:`Running_Without_Root_Privileges`.
+
+
+VFIO Memory Mapping Limits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 For DMA mapping of either external memory or hugepages, VFIO interface is used.
 VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is
 mapped in hugepage granularity or system page granularity. Number of DMA
@@ -132,6 +148,9 @@ VFIO module parameter ``dma_entry_limit`` with a default value of 64K.
 When application is out of DMA entries, these limits need to be adjusted to
 increase the allowed limit.
 
+Creating Virtual Functions using vfio-pci
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Since Linux version 5.7,
 the ``vfio-pci`` module supports the creation of virtual functions.
 After the PF is bound to ``vfio-pci`` module,
@@ -194,27 +213,11 @@ The token will be used for all PF and VF ports within the application.
       <build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \
       --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i
 
-To make use of full VFIO functionality,
-both kernel and BIOS must support and be configured
-to use IO virtualization (such as Intel\ |reg| VT-d).
-
-.. note::
-
-   Linux versions earlier than version 3.6 do not support VFIO.
-
 .. note::
 
    Linux versions earlier than version 5.7 do not support the creation of
    virtual functions within the VFIO framework.
 
-.. note::
-
-   In most cases, specifying "iommu=on" as kernel parameter should be enough to
-   configure the Linux kernel to use IOMMU.
-
-For proper operation of VFIO when running DPDK applications as a non-privileged user, correct permissions should also be set up.
-For more information, please refer to :ref:`Running_Without_Root_Privileges`.
-
 .. _vfio_noiommu:
 
 VFIO no-IOMMU mode

--
2.32.0

#17 lore raw

PATCH v2 7/9 doc: move GSG section on UIO to the end of drivers page

In reply to Bruce Richardson

To further de-emphasise UIO over the alternatives, we can move the UIO section of the drivers page to the end of the document, giving more prominence to VFIO and bifurcated drivers.

---
 doc/guides/linux_gsg/linux_drivers.rst | 104 ++++++++++++-------------
 1 file changed, 52 insertions(+), 52 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +52 -52
index f9c24e9456..6ff8586940 100644
@@ -250,58 +250,6 @@ After that, VFIO can be used with hardware devices as usual.
    to keep the degree of device access and programming that VFIO has,
    in situations where IOMMU is not available.
 
-.. _uio:
-
-UIO
----
-
-.. warning::
-
-   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
-   and can only be done by root user.
-
-In situations where using VFIO is not an option, there are alternative drivers one can use.
-In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
-can be used as a substitute for VFIO. This module can be loaded using the command:
-
-.. code-block:: console
-
-   sudo modprobe uio_pci_generic
-
-.. note::
-
-   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
-
-As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
-which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
-It can be loaded as shown below:
-
-.. code-block:: console
-
-   sudo modprobe uio
-   sudo insmod igb_uio.ko
-
-.. note::
-
-    For some devices which lack support for legacy interrupts, e.g. virtual function
-    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
-
-.. note::
-
-   If UEFI secure boot is enabled,
-   the Linux kernel may disallow the use of UIO on the system.
-   Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module
-   rather than any UIO-based module.
-   For more details see :ref:`linux_gsg_binding_kernel` below.
-
-.. note::
-
-   If the devices used for DPDK are bound to a UIO-based kernel module,
-   please make sure that the IOMMU is disabled or is in passthrough mode.
-   One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``
-   in GRUB command line on x86_64 systems,
-   or add ``iommu.passthrough=1`` on aarch64 systems.
-
 .. _bifurcated_driver:
 
 Bifurcated Driver
@@ -372,3 +320,55 @@ This can be checked in the boot configuration of your system:
 If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
 VFIO driver will not support the no-IOMMU mode,
 and other alternatives (such as UIO drivers) will have to be used.
+
+.. _uio:
+
+UIO
+---
+
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
+In situations where using VFIO is not an option, there are alternative drivers one can use.
+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
+can be used as a substitute for VFIO. This module can be loaded using the command:
+
+.. code-block:: console
+
+   sudo modprobe uio_pci_generic
+
+.. note::
+
+   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
+
+As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
+which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
+It can be loaded as shown below:
+
+.. code-block:: console
+
+   sudo modprobe uio
+   sudo insmod igb_uio.ko
+
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
+.. note::
+
+   If UEFI secure boot is enabled,
+   the Linux kernel may disallow the use of UIO on the system.
+   Therefore, devices for use by DPDK should be bound to the ``vfio-pci`` kernel module
+   rather than any UIO-based module.
+   For more details see :ref:`linux_gsg_binding_kernel` below.
+
+.. note::
+
+   If the devices used for DPDK are bound to a UIO-based kernel module,
+   please make sure that the IOMMU is disabled or is in passthrough mode.
+   One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``
+   in GRUB command line on x86_64 systems,
+   or add ``iommu.passthrough=1`` on aarch64 systems.

--
2.32.0

#18 lore raw

PATCH v2 8/9 doc: consolidate all VFIO content on GSG driver page

In reply to Bruce Richardson

Rather than having separate sections for VFIO and VFIO no-iommu mode, as well as a separate section further down the document on troubleshooting VFIO, we can consolidate all these as subsections into a primary VFIO section. This section starts with the basics of VFIO use, then covers no-iommu mode, before moving on to the more advanced topics such as creating VFs and ending with the troubleshooting subsection.

---
 doc/guides/linux_gsg/linux_drivers.rst | 116 ++++++++++++-------------
 1 file changed, 58 insertions(+), 58 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +58 -58
index 6ff8586940..8320db44d9 100644
@@ -135,6 +135,38 @@ For proper operation of VFIO when running DPDK applications as a non-privileged
 For more information, please refer to :ref:`Running_Without_Root_Privileges`.
 
 
+.. _vfio_noiommu:
+
+VFIO no-IOMMU mode
+~~~~~~~~~~~~~~~~~~
+
+If there is no IOMMU available on the system, VFIO can still be used,
+but it has to be loaded with an additional module parameter:
+
+.. code-block:: console
+
+   modprobe vfio enable_unsafe_noiommu_mode=1
+
+Alternatively, one can also enable this option in an already loaded kernel module:
+
+.. code-block:: console
+
+   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
+
+After that, VFIO can be used with hardware devices as usual.
+
+.. note::
+
+   It may be required to unload all VFIO related-modules before probing
+   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
+
+.. warning::
+
+   Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe.
+   That said, it does make it possible for the user
+   to keep the degree of device access and programming that VFIO has,
+   in situations where IOMMU is not available.
+
 VFIO Memory Mapping Limits
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -218,65 +250,8 @@ The token will be used for all PF and VF ports within the application.
    Linux versions earlier than version 5.7 do not support the creation of
    virtual functions within the VFIO framework.
 
-.. _vfio_noiommu:
-
-VFIO no-IOMMU mode
-------------------
-
-If there is no IOMMU available on the system, VFIO can still be used,
-but it has to be loaded with an additional module parameter:
-
-.. code-block:: console
-
-   modprobe vfio enable_unsafe_noiommu_mode=1
-
-Alternatively, one can also enable this option in an already loaded kernel module:
-
-.. code-block:: console
-
-   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
-
-After that, VFIO can be used with hardware devices as usual.
-
-.. note::
-
-   It may be required to unload all VFIO related-modules before probing
-   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
-
-.. warning::
-
-   Since no-IOMMU mode forgoes IOMMU protection, it is inherently unsafe.
-   That said, it does make it possible for the user
-   to keep the degree of device access and programming that VFIO has,
-   in situations where IOMMU is not available.
-
-.. _bifurcated_driver:
-
-Bifurcated Driver
------------------
-
-PMDs which use the bifurcated driver co-exists with the device kernel driver.
-On such model the NIC is controlled by the kernel, while the data
-path is performed by the PMD directly on top of the device.
-
-Such model has the following benefits:
-
- - It is secure and robust, as the memory management and isolation
-   is done by the kernel.
- - It enables the user to use legacy linux tools such as ``ethtool`` or
-   ``ifconfig`` while running DPDK application on the same network ports.
- - It enables the DPDK application to filter only part of the traffic,
-   while the rest will be directed and handled by the kernel driver.
-   The flow bifurcation is performed by the NIC hardware.
-   As an example, using :ref:`flow_isolated_mode` allows to choose
-   strictly what is received in DPDK.
-
-More about the bifurcated driver can be found in
-`Mellanox Bifurcated DPDK PMD
-<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
-
 Troubleshooting VFIO
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 In certain situations, using ``dpdk-devbind.py`` script
 to bind a device to VFIO driver may fail.
@@ -321,6 +296,31 @@ If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
 VFIO driver will not support the no-IOMMU mode,
 and other alternatives (such as UIO drivers) will have to be used.
 
+.. _bifurcated_driver:
+
+Bifurcated Driver
+-----------------
+
+PMDs which use the bifurcated driver co-exists with the device kernel driver.
+On such model the NIC is controlled by the kernel, while the data
+path is performed by the PMD directly on top of the device.
+
+Such model has the following benefits:
+
+ - It is secure and robust, as the memory management and isolation
+   is done by the kernel.
+ - It enables the user to use legacy linux tools such as ``ethtool`` or
+   ``ifconfig`` while running DPDK application on the same network ports.
+ - It enables the DPDK application to filter only part of the traffic,
+   while the rest will be directed and handled by the kernel driver.
+   The flow bifurcation is performed by the NIC hardware.
+   As an example, using :ref:`flow_isolated_mode` allows to choose
+   strictly what is received in DPDK.
+
+More about the bifurcated driver can be found in
+`Mellanox Bifurcated DPDK PMD
+<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`__.
+
 .. _uio:
 
 UIO

--
2.32.0

#19 lore raw

PATCH v2 9/9 doc: change informational warnings to notes in Linux GSG

In reply to Bruce Richardson

There are two warnings in the VFIO section about limitations of VFIO and limitations on who can bind/unbind devices. Since these don't actually describe any unsafe conditions, and are more informational, we can change these to notes. This also helps emphasise the other warnings in the documents which flag genuine security concerns.

---
 doc/guides/linux_gsg/linux_drivers.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
doc/guides/linux_gsg/linux_drivers.rst +2 -2
index 8320db44d9..2e4c80ebd3 100644
@@ -48,7 +48,7 @@ by calling the script with the ``--help`` or ``--usage`` options.
 Note that the UIO or VFIO kernel modules to be used,
 should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
 
-.. warning::
+.. note::
 
    Due to the way VFIO works, there are certain limitations
    to which devices can be used with VFIO.
@@ -62,7 +62,7 @@ should be loaded into the kernel before running the ``dpdk-devbind.py`` script.
    Therefore, the bridge driver should also be unbound from the bridge PCI device
    for VFIO to work with devices behind the bridge.
 
-.. warning::
+.. note::
 
    While any user can run the ``dpdk-devbind.py`` script
    to view the status of the network ports,

--
2.32.0

#20 lore raw

Re: [PATCH v2 0/9] Improve Linux drivers GSG section

In reply to Bruce Richardson

16/03/2022 14:45, Bruce Richardson:

Quoted 16 lines

This patchset reworks large parts of the linux drivers section of the Linux Getting Started Guide, so as to make it clearer and easier to read. The overall flow of the page is adjusted so that more important information is nearer the top, and so that all information on VFIO is consolidated into a single section. In terms of the content of the sections, there are some minor changes to adjust what is a warning vs just a "note" in the doc, and there are some updates to increase emphasis on VFIO ovs UIO.

Including stable on CC for the set, as all patches may be candidates for backport to help improve docs for older releases too.

V2:
* Rebased on top of main, now that other doc patches are applied
* Reworded commit titles to use "doc:" prefix

Quoted 10 lines

Bruce Richardson (9):
doc: replace special characters for (R) symbol in Linux GSG
doc: fix missing note on UIO module in Linux GSG
doc: make UIO safety warning more visible in Linux GSG
doc: move section on binding drivers up the page in GSG
doc: emphasise VFIO over UIO-based modules in GSG
doc: split GSG VFIO section into subsections
doc: move GSG section on UIO to the end of drivers page
doc: consolidate all VFIO content on GSG driver page
doc: change informational warnings to notes in Linux GSG

Except for the first 2 patches, I think it is not mandatory to backport, so I've removed the tag Cc:stable.

Applied, thanks.