DPDK patches and discussions
 help / color / mirror / Atom feed
From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: Bruce Richardson <bruce.richardson@intel.com>, stable@dpdk.org
Subject: [PATCH v2 5/9] doc: emphasise VFIO over UIO-based modules in GSG
Date: Wed, 16 Mar 2022 13:45:47 +0000	[thread overview]
Message-ID: <20220316134551.1099599-6-bruce.richardson@intel.com> (raw)
In-Reply-To: <20220316134551.1099599-1-bruce.richardson@intel.com>

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.

Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/linux_drivers.rst | 47 +++++++++++++++-----------
 1 file changed, 28 insertions(+), 19 deletions(-)

diff --git a/doc/guides/linux_gsg/linux_drivers.rst b/doc/guides/linux_gsg/linux_drivers.rst
index b93feae7a1..bd649db929 100644
--- a/doc/guides/linux_gsg/linux_drivers.rst
+++ b/doc/guides/linux_gsg/linux_drivers.rst
@@ -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


  parent reply	other threads:[~2022-03-16 13:46 UTC|newest]

Thread overview: 21+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-03-02 17:22 [PATCH 0/9] Improve linux drivers GSG section Bruce Richardson
2022-03-02 17:22 ` [PATCH 1/9] doc/linux_gsg: replace special characters for (R) symbol Bruce Richardson
2022-03-02 17:22 ` [PATCH 2/9] doc/linux_gsg: fix missing note on UIO module Bruce Richardson
2022-03-02 17:22 ` [PATCH 3/9] doc/linux_gsg: make UIO safety warning more visible Bruce Richardson
2022-03-02 17:22 ` [PATCH 4/9] doc/linux_gsg: move section on binding drivers up the page Bruce Richardson
2022-03-02 17:22 ` [PATCH 5/9] doc/linux_gsg: emphasise VFIO over UIO-based modules Bruce Richardson
2022-03-02 17:22 ` [PATCH 6/9] doc/linux_gsg: split VFIO section into subsections Bruce Richardson
2022-03-02 17:22 ` [PATCH 7/9] doc/linux_gsg: move UIO section to the end Bruce Richardson
2022-03-02 17:22 ` [PATCH 8/9] doc/linux_gsg: consolidate all VFIO content Bruce Richardson
2022-03-02 17:22 ` [PATCH 9/9] doc/linux_gsg: change informational warnings to notes Bruce Richardson
2022-03-16 13:45 ` [PATCH v2 0/9] Improve Linux drivers GSG section Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 1/9] doc: replace special characters for (R) symbol in Linux GSG Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 2/9] doc: fix missing note on UIO module " Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 3/9] doc: make UIO safety warning more visible " Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 4/9] doc: move section on binding drivers up the page in GSG Bruce Richardson
2022-03-16 13:45   ` Bruce Richardson [this message]
2022-03-16 13:45   ` [PATCH v2 6/9] doc: split GSG VFIO section into subsections Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 7/9] doc: move GSG section on UIO to the end of drivers page Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 8/9] doc: consolidate all VFIO content on GSG driver page Bruce Richardson
2022-03-16 13:45   ` [PATCH v2 9/9] doc: change informational warnings to notes in Linux GSG Bruce Richardson
2022-03-16 17:41   ` [PATCH v2 0/9] Improve Linux drivers GSG section Thomas Monjalon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220316134551.1099599-6-bruce.richardson@intel.com \
    --to=bruce.richardson@intel.com \
    --cc=dev@dpdk.org \
    --cc=stable@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).