From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 6D3E1A04A5 for ; Wed, 2 Mar 2022 18:24:21 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 661EC42765; Wed, 2 Mar 2022 18:24:21 +0100 (CET) Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by mails.dpdk.org (Postfix) with ESMTP id EFCA442760; Wed, 2 Mar 2022 18:24:17 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1646241858; x=1677777858; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=bFvqrLNhBGM0Fo7KXqq0nS6eDPeU99gaY/oomaeqgc4=; b=PQIOnvoMlqOjV1xMhWA8euPH51jn56Z3C+H/HP9sFavm/Bo77h5T2XKl 3H0ZyLAiewQyO1eec3bGm6Nt39o7mH/PXYFH9TWRGb7hHB7ZDVsPzS07C +ryxjUMkU0+IYnGVFB8UywJg4MXwpAeKvdYRhtdCM8vVJRknhOL2vbQlJ tcfu67BE8KESWKYw537nz2YfwB3H6lW5HxYtzZm3GJtl7bGzydMMu23iS zX9iepC5u1BUeYVN2tGsVktInxxmkx3hsruZlraIMkveaGQfAmnDDYCL4 HZyGxRWYJSEEZBR1GTjFQipuPTw8+8J51vLpdWzb7fcRVEjWbWPwKav0p w==; X-IronPort-AV: E=McAfee;i="6200,9189,10274"; a="253651989" X-IronPort-AV: E=Sophos;i="5.90,149,1643702400"; d="scan'208";a="253651989" Received: from orsmga008.jf.intel.com ([10.7.209.65]) by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Mar 2022 09:24:14 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.90,149,1643702400"; d="scan'208";a="551348133" Received: from silpixa00399126.ir.intel.com ([10.237.223.34]) by orsmga008.jf.intel.com with ESMTP; 02 Mar 2022 09:24:13 -0800 From: Bruce Richardson To: dev@dpdk.org Cc: stable@dpdk.org, Bruce Richardson Subject: [PATCH 5/9] doc/linux_gsg: emphasise VFIO over UIO-based modules Date: Wed, 2 Mar 2022 17:22:13 +0000 Message-Id: <20220302172217.472279-6-bruce.richardson@intel.com> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20220302172217.472279-1-bruce.richardson@intel.com> References: <20220302172217.472279-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: stable@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: patches for DPDK stable branches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: stable-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. Signed-off-by: Bruce Richardson --- 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 83f28d86fe..af7e3c4fbc 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` 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 ===================== -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