doc/guides: refer to generic binding devices section

Message ID 20231006125500.740299-1-david.marchand@redhat.com (mailing list archive)
State Accepted, archived
Delegated to: David Marchand
Headers
Series doc/guides: refer to generic binding devices section |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/loongarch-compilation success Compilation OK
ci/loongarch-unit-testing success Unit Testing PASS
ci/github-robot: build success github build: passed
ci/iol-broadcom-Performance success Performance Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-intel-Functional success Functional Testing PASS
ci/iol-compile-amd64-testing success Testing PASS
ci/iol-sample-apps-testing success Testing PASS
ci/iol-unit-amd64-testing success Testing PASS
ci/iol-unit-arm64-testing success Testing PASS
ci/iol-compile-arm64-testing success Testing PASS
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/intel-Functional success Functional PASS

Commit Message

David Marchand Oct. 6, 2023, 12:55 p.m. UTC
  Rather than copy/paste everywhere how to bind a device and create VF
devices, refer to the Linux GSG section about it.

Signed-off-by: David Marchand <david.marchand@redhat.com>
---
 doc/guides/bbdevs/acc100.rst        | 73 ++---------------------------
 doc/guides/bbdevs/fpga_5gnr_fec.rst | 71 ++--------------------------
 doc/guides/bbdevs/fpga_lte_fec.rst  | 70 ++-------------------------
 doc/guides/bbdevs/vrb1.rst          | 66 ++------------------------
 doc/guides/cryptodevs/ccp.rst       | 14 +-----
 doc/guides/nics/intel_vf.rst        | 57 ++++------------------
 6 files changed, 25 insertions(+), 326 deletions(-)
  

Comments

Maxime Coquelin Nov. 15, 2023, 10:10 a.m. UTC | #1
On 10/6/23 14:55, David Marchand wrote:
> Rather than copy/paste everywhere how to bind a device and create VF
> devices, refer to the Linux GSG section about it.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
>   doc/guides/bbdevs/acc100.rst        | 73 ++---------------------------
>   doc/guides/bbdevs/fpga_5gnr_fec.rst | 71 ++--------------------------
>   doc/guides/bbdevs/fpga_lte_fec.rst  | 70 ++-------------------------
>   doc/guides/bbdevs/vrb1.rst          | 66 ++------------------------
>   doc/guides/cryptodevs/ccp.rst       | 14 +-----
>   doc/guides/nics/intel_vf.rst        | 57 ++++------------------
>   6 files changed, 25 insertions(+), 326 deletions(-)
> 

Thanks David for working on this clean-up:

Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Maxime
  
David Marchand Nov. 24, 2023, 12:50 p.m. UTC | #2
On Wed, Nov 15, 2023 at 11:10 AM Maxime Coquelin
<maxime.coquelin@redhat.com> wrote:
> On 10/6/23 14:55, David Marchand wrote:
> > Rather than copy/paste everywhere how to bind a device and create VF
> > devices, refer to the Linux GSG section about it.
> >
> > Signed-off-by: David Marchand <david.marchand@redhat.com>
> Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Applied, thanks.
  

Patch

diff --git a/doc/guides/bbdevs/acc100.rst b/doc/guides/bbdevs/acc100.rst
index 8a275dcdd4..f26ce58f78 100644
--- a/doc/guides/bbdevs/acc100.rst
+++ b/doc/guides/bbdevs/acc100.rst
@@ -94,7 +94,7 @@  Initialization
 --------------
 
 When the device first powers up, its PCI Physical Functions (PF) can be listed through these
-commands for ACC100 and ACC101 respectively:
+commands for ACC100 (device id ``0d5c``) and ACC101 (device id ``57c4``) respectively:
 
 .. code-block:: console
 
@@ -102,76 +102,11 @@  commands for ACC100 and ACC101 respectively:
   sudo lspci -vd8086:57c4
 
 The physical and virtual functions are compatible with Linux UIO drivers:
-``vfio`` and ``igb_uio``. However, in order to work the 5G/4G
+``vfio_pci`` and ``igb_uio``. However, in order to work the 5G/4G
 FEC device first needs to be bound to one of these linux drivers through DPDK.
 
-
-Bind PF UIO driver(s)
-~~~~~~~~~~~~~~~~~~~~~
-
-Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use
-``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver.
-
-The igb_uio driver may be bound to the PF PCI device using one of two methods for ACC100
-(for ACC101 the device id ``57c4`` should be used in lieu of ``0d5c``):
-
-
-1. PCI functions (physical or virtual, depending on the use case) can be bound to
-the UIO driver by repeating this command for every function.
-
-.. code-block:: console
-
-  cd <dpdk-top-level-directory>
-  insmod ./build/kmod/igb_uio.ko
-  echo "8086 0d5c" > /sys/bus/pci/drivers/igb_uio/new_id
-  lspci -vd8086:0d5c
-
-
-2. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool
-
-.. code-block:: console
-
-  cd <dpdk-top-level-directory>
-  ./usertools/dpdk-devbind.py -b igb_uio 0000:06:00.0
-
-where the PCI device ID (example: 0000:06:00.0) is obtained using lspci -vd8086:0d5c
-
-
-In a similar way the 5G/4G FEC PF may be bound with vfio-pci as any PCIe device.
-
-
-Enable Virtual Functions
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now, it should be visible in the printouts that PCI PF is under igb_uio control
-"``Kernel driver in use: igb_uio``"
-
-To show the number of available VFs on the device, read ``sriov_totalvfs`` file..
-
-.. code-block:: console
-
-  cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs
-
-  where 0000\:<b>\:<d>.<f> is the PCI device ID
-
-
-To enable VFs via igb_uio, echo the number of virtual functions intended to
-enable to ``max_vfs`` file..
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs
-
-
-Afterwards, all VFs must be bound to appropriate UIO drivers as required, same
-way it was done with the physical function previously.
-
-Enabling SR-IOV via vfio driver is pretty much the same, except that the file
-name is different:
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs
+For more details on how to bind the PF device and create VF devices, see
+:ref:`linux_gsg_binding_kernel`.
 
 
 Configure the VFs through PF
diff --git a/doc/guides/bbdevs/fpga_5gnr_fec.rst b/doc/guides/bbdevs/fpga_5gnr_fec.rst
index 9d71585e9e..d126c9c3e4 100644
--- a/doc/guides/bbdevs/fpga_5gnr_fec.rst
+++ b/doc/guides/bbdevs/fpga_5gnr_fec.rst
@@ -72,76 +72,11 @@  When the device first powers up, its PCI Physical Functions (PF) can be listed t
   sudo lspci -vd8086:0d8f
 
 The physical and virtual functions are compatible with Linux UIO drivers:
-``vfio`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs
+``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs
 to be bound to one of these linux drivers through DPDK.
 
-
-Bind PF UIO driver(s)
-~~~~~~~~~~~~~~~~~~~~~
-
-Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use
-``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver.
-
-The igb_uio driver may be bound to the PF PCI device using one of two methods:
-
-
-1. PCI functions (physical or virtual, depending on the use case) can be bound to
-the UIO driver by repeating this command for every function.
-
-.. code-block:: console
-
-  insmod igb_uio.ko
-  echo "8086 0d8f" > /sys/bus/pci/drivers/igb_uio/new_id
-  lspci -vd8086:0d8f
-
-
-2. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool
-
-.. code-block:: console
-
-  cd <dpdk-top-level-directory>
-  ./usertools/dpdk-devbind.py -b igb_uio 0000:06:00.0
-
-where the PCI device ID (example: 0000:06:00.0) is obtained using lspci -vd8086:0d8f
-
-
-In the same way the FPGA 5GNR FEC PF can be bound with vfio, but vfio driver does not
-support SR-IOV configuration right out of the box, so it will need to be patched.
-
-
-Enable Virtual Functions
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now, it should be visible in the printouts that PCI PF is under igb_uio control
-"``Kernel driver in use: igb_uio``"
-
-To show the number of available VFs on the device, read ``sriov_totalvfs`` file..
-
-.. code-block:: console
-
-  cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs
-
-  where 0000\:<b>\:<d>.<f> is the PCI device ID
-
-
-To enable VFs via igb_uio, echo the number of virtual functions intended to
-enable to ``max_vfs`` file..
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs
-
-
-Afterwards, all VFs must be bound to appropriate UIO drivers as required, same
-way it was done with the physical function previously.
-
-Enabling SR-IOV via vfio driver is pretty much the same, except that the file
-name is different:
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs
-
+For more details on how to bind the PF device and create VF devices, see
+:ref:`linux_gsg_binding_kernel`.
 
 Configure the VFs through PF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/bbdevs/fpga_lte_fec.rst b/doc/guides/bbdevs/fpga_lte_fec.rst
index c3379c24e3..53b7cd5678 100644
--- a/doc/guides/bbdevs/fpga_lte_fec.rst
+++ b/doc/guides/bbdevs/fpga_lte_fec.rst
@@ -71,75 +71,11 @@  When the device first powers up, its PCI Physical Functions (PF) can be listed t
   sudo lspci -vd1172:5052
 
 The physical and virtual functions are compatible with Linux UIO drivers:
-``vfio`` and ``igb_uio``. However, in order to work the FPGA LTE FEC device firstly needs
+``vfio_pci`` and ``igb_uio``. However, in order to work the FPGA LTE FEC device firstly needs
 to be bound to one of these linux drivers through DPDK.
 
-
-Bind PF UIO driver(s)
-~~~~~~~~~~~~~~~~~~~~~
-
-Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use
-``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver.
-
-The igb_uio driver may be bound to the PF PCI device using one of two methods:
-
-
-1. PCI functions (physical or virtual, depending on the use case) can be bound to
-the UIO driver by repeating this command for every function.
-
-.. code-block:: console
-
-  insmod igb_uio.ko
-  echo "1172 5052" > /sys/bus/pci/drivers/igb_uio/new_id
-  lspci -vd1172:
-
-
-2. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool
-
-.. code-block:: console
-
-  cd <dpdk-top-level-directory>
-  ./usertools/dpdk-devbind.py -b igb_uio 0000:06:00.0
-
-where the PCI device ID (example: 0000:06:00.0) is obtained using lspci -vd1172:
-
-
-In the same way the FPGA LTE FEC PF can be bound with vfio, but vfio driver does not
-support SR-IOV configuration right out of the box, so it will need to be patched.
-
-
-Enable Virtual Functions
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now, it should be visible in the printouts that PCI PF is under igb_uio control
-"``Kernel driver in use: igb_uio``"
-
-To show the number of available VFs on the device, read ``sriov_totalvfs`` file..
-
-.. code-block:: console
-
-  cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs
-
-  where 0000\:<b>\:<d>.<f> is the PCI device ID
-
-
-To enable VFs via igb_uio, echo the number of virtual functions intended to
-enable to ``max_vfs`` file..
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs
-
-
-Afterwards, all VFs must be bound to appropriate UIO drivers as required, same
-way it was done with the physical function previously.
-
-Enabling SR-IOV via vfio driver is pretty much the same, except that the file
-name is different:
-
-.. code-block:: console
-
-  echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs
+For more details on how to bind the PF device and create VF devices, see
+:ref:`linux_gsg_binding_kernel`.
 
 
 Configure the VFs through PF
diff --git a/doc/guides/bbdevs/vrb1.rst b/doc/guides/bbdevs/vrb1.rst
index 9c48d30964..9d05772967 100644
--- a/doc/guides/bbdevs/vrb1.rst
+++ b/doc/guides/bbdevs/vrb1.rst
@@ -111,72 +111,12 @@  can be listed through these commands for Intel vRAN Boost v1:
    sudo lspci -vd8086:57c0
 
 The physical and virtual functions are compatible with Linux UIO drivers:
-``vfio`` and ``igb_uio``.
+``vfio_pci`` and ``igb_uio``.
 However, in order to work the 5G/4G FEC device first needs to be bound
 to one of these Linux drivers through DPDK.
 
-
-Bind PF UIO driver(s)
-~~~~~~~~~~~~~~~~~~~~~
-
-Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use
-``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver.
-
-The igb_uio driver may be bound to the PF PCI device using one of two methods
-for Intel vRAN Boost v1:
-
-#. PCI functions (physical or virtual, depending on the use case) can be bound
-to the UIO driver by repeating this command for every function.
-
-.. code-block:: console
-
-   cd <dpdk-top-level-directory>
-   insmod build/kmod/igb_uio.ko
-   echo "8086 57c0" > /sys/bus/pci/drivers/igb_uio/new_id
-   lspci -vd8086:57c0
-
-#. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool
-
-.. code-block:: console
-
-   cd <dpdk-top-level-directory>
-   usertools/dpdk-devbind.py -b igb_uio 0000:f7:00.0
-
-where the PCI device ID (example: 0000:f7:00.0) is obtained using ``lspci -vd8086:57c0``.
-
-In a similar way the PF may be bound with vfio-pci as any PCIe device.
-
-
-Enable Virtual Functions
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now, it should be visible in the printouts that PCI PF is under igb_uio control
-"``Kernel driver in use: igb_uio``"
-
-To show the number of available VFs on the device, read ``sriov_totalvfs`` file.
-
-.. code-block:: console
-
-   cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs
-
-where ``0000\:<b>\:<d>.<f>`` is the PCI device ID
-
-To enable VFs via igb_uio, echo the number of virtual functions intended
-to enable to ``max_vfs`` file.
-
-.. code-block:: console
-
-   echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs
-
-Afterwards, all VFs must be bound to appropriate UIO drivers as required,
-same way it was done with the physical function previously.
-
-Enabling SR-IOV via VFIO driver is pretty much the same,
-except that the file name is different:
-
-.. code-block:: console
-
-   echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs
+For more details on how to bind the PF device and create VF devices, see
+:ref:`linux_gsg_binding_kernel`.
 
 
 Configure the VFs through PF
diff --git a/doc/guides/cryptodevs/ccp.rst b/doc/guides/cryptodevs/ccp.rst
index 52e98b0859..a314fb6fd1 100644
--- a/doc/guides/cryptodevs/ccp.rst
+++ b/doc/guides/cryptodevs/ccp.rst
@@ -70,18 +70,8 @@  This code was verified on Ubuntu 16.04.
 Initialization
 --------------
 
-Bind the CCP devices to DPDK UIO driver module before running the CCP PMD stack.
-e.g. for the 0x1456 device::
-
-	modprobe uio
-	insmod igb_uio.ko
-	echo "1022 1456" > /sys/bus/pci/drivers/igb_uio/new_id
-
-Another way to bind the CCP devices to DPDK UIO driver is by using the ``dpdk-devbind.py`` script.
-The following command assumes ``BFD`` as ``0000:09:00.2``::
-
-	cd to the top-level DPDK directory
-	./usertools/dpdk-devbind.py -b igb_uio 0000:09:00.2
+Bind the CCP devices to ``vfio_pci`` or ``igb_uio`` (see :ref:`linux_gsg_binding_kernel`)
+before running the CCP PMD stack.
 
 To use the PMD in an application, user must:
 
diff --git a/doc/guides/nics/intel_vf.rst b/doc/guides/nics/intel_vf.rst
index d365dbc185..8d157ceaa4 100644
--- a/doc/guides/nics/intel_vf.rst
+++ b/doc/guides/nics/intel_vf.rst
@@ -150,16 +150,8 @@  For example,
         rmmod i40e (To remove the i40e module)
         insmod i40e.ko max_vfs=2,2 (To enable two Virtual Functions per port)
 
-*   Using the DPDK PMD PF i40e driver:
-
-    Kernel Params: iommu=pt, intel_iommu=on
-
-    .. code-block:: console
-
-        modprobe uio
-        insmod igb_uio
-        ./dpdk-devbind.py -b igb_uio bb:ss.f
-        echo 2 > /sys/bus/pci/devices/0000\:bb\:ss.f/max_vfs (To enable two VFs on a specific PCI device)
+*   Using the DPDK PMD PF i40e driver, bind the PF device to ``vfio_pci`` or ``igb_uio`` and
+    create VF devices. See :ref:`linux_gsg_binding_kernel`.
 
     Launch the DPDK testpmd/example or your own host daemon application using the DPDK PMD library.
 
@@ -200,22 +192,14 @@  For example,
         rmmod ixgbe (To remove the ixgbe module)
         insmod ixgbe max_vfs=2,2 (To enable two Virtual Functions per port)
 
-*   Using the DPDK PMD PF ixgbe driver:
-
-    Kernel Params: iommu=pt, intel_iommu=on
-
-    .. code-block:: console
-
-        modprobe uio
-        insmod igb_uio
-        ./dpdk-devbind.py -b igb_uio bb:ss.f
-        echo 2 > /sys/bus/pci/devices/0000\:bb\:ss.f/max_vfs (To enable two VFs on a specific PCI device)
+*   Using the DPDK PMD PF ixgbe driver, bind the PF device to ``vfio_pci`` or ``igb_uio`` and
+    create VF devices. See :ref:`linux_gsg_binding_kernel`.
 
     Launch the DPDK testpmd/example or your own host daemon application using the DPDK PMD library.
 
 *   Using the DPDK PMD PF ixgbe driver to enable VF RSS:
 
-    Same steps as above to install the modules of uio, igb_uio, specify max_vfs for PCI device, and
+    Same steps as above to bind the PF device, create VF devices, and
     launch the DPDK testpmd/example or your own host daemon application using the DPDK PMD library.
 
     The available queue number (at most 4) per VF depends on the total number of pool, which is
@@ -286,15 +270,8 @@  For example,
         rmmod igb (To remove the igb module)
         insmod igb max_vfs=2,2 (To enable two Virtual Functions per port)
 
-*   Using DPDK PMD PF igb driver:
-
-    Kernel Params: iommu=pt, intel_iommu=on modprobe uio
-
-    .. code-block:: console
-
-        insmod igb_uio
-        ./dpdk-devbind.py -b igb_uio bb:ss.f
-        echo 2 > /sys/bus/pci/devices/0000\:bb\:ss.f/max_vfs (To enable two VFs on a specific pci device)
+*   Using the DPDK PMD PF igb driver, bind the PF device to ``vfio_pci`` or ``igb_uio`` and
+    create VF devices. See :ref:`linux_gsg_binding_kernel`.
 
     Launch DPDK testpmd/example or your own host daemon application using the DPDK PMD library.
 
@@ -409,22 +386,8 @@  The setup procedure is as follows:
         rmmod ixgbe
         modprobe ixgbe max_vfs=2,2
 
-    When using DPDK PMD PF driver, insert DPDK kernel module igb_uio and set the number of VF by sysfs max_vfs:
-
-    .. code-block:: console
-
-        modprobe uio
-        insmod igb_uio
-        ./dpdk-devbind.py -b igb_uio 02:00.0 02:00.1 0e:00.0 0e:00.1
-        echo 2 > /sys/bus/pci/devices/0000\:02\:00.0/max_vfs
-        echo 2 > /sys/bus/pci/devices/0000\:02\:00.1/max_vfs
-        echo 2 > /sys/bus/pci/devices/0000\:0e\:00.0/max_vfs
-        echo 2 > /sys/bus/pci/devices/0000\:0e\:00.1/max_vfs
-
-    .. note::
-
-        You need to explicitly specify number of vfs for each port, for example,
-        in the command above, it creates two vfs for the first two ixgbe ports.
+    When using DPDK PMD PF driver, bind the PF device to ``vfio_pci`` or ``igb_uio`` and
+    create VF devices. See :ref:`linux_gsg_binding_kernel`.
 
     Let say we have a machine with four physical ixgbe ports:
 
@@ -437,7 +400,7 @@  The setup procedure is as follows:
 
         0000:0e:00.1
 
-    The command above creates two vfs for device 0000:02:00.0:
+    The mentioned steps above should result in two vfs for device 0000:02:00.0:
 
     .. code-block:: console