From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 4DCEDA0032;
Wed, 16 Mar 2022 14:46:39 +0100 (CET)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id E2EF741174;
Wed, 16 Mar 2022 14:46:14 +0100 (CET)
Received: from mga14.intel.com (mga14.intel.com [192.55.52.115])
by mails.dpdk.org (Postfix) with ESMTP id C3104410F6;
Wed, 16 Mar 2022 14:46:07 +0100 (CET)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
t=1647438368; x=1678974368;
h=from:to:cc:subject:date:message-id:in-reply-to:
references:mime-version:content-transfer-encoding;
bh=6T7m2SDFr6Ll49aO5uLStzvMbZCAJFecSt/Wpj1zHcA=;
b=UB85sJSnsBEw3fba8IKIC1WW3DhQGr9tXPMfYi/tE5Awn9zyBUfIBeRF
M4xKcY5zYRN6/MTKfQm4zIb0E0k2bQzUSkH+Q0QXOyGXbBP01Ahoh/BR2
yCZrUTtxyuEEcY0XBjhsob0QtXT/Q0p2OFUtwrIH0sMLun/TevPppCp1C
C1Mvw/AOStzb3L+lTu2Mcjdf7OyRg3s3qlRPNsOOAN/HFNEOyLv+0fY8b
yhJCzTkry8ENiKlkDivFTO4wIJIiNto9n7GAUAJw13S3UmeNFtXc1BE8w
7urzgZ7A0yH/EbW3iAHsMM+XWvcGmXi07tnCsWRwcivTJHX6g7vpM3OIT A==;
X-IronPort-AV: E=McAfee;i="6200,9189,10286"; a="256780570"
X-IronPort-AV: E=Sophos;i="5.90,186,1643702400"; d="scan'208";a="256780570"
Received: from orsmga005.jf.intel.com ([10.7.209.41])
by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
16 Mar 2022 06:46:07 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.90,186,1643702400"; d="scan'208";a="714606501"
Received: from silpixa00399126.ir.intel.com ([10.237.223.34])
by orsmga005.jf.intel.com with ESMTP; 16 Mar 2022 06:46:06 -0700
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
Message-Id: <20220316134551.1099599-6-bruce.richardson@intel.com>
X-Mailer: git-send-email 2.32.0
In-Reply-To: <20220316134551.1099599-1-bruce.richardson@intel.com>
References: <20220302172217.472279-1-bruce.richardson@intel.com>
<20220316134551.1099599-1-bruce.richardson@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
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