[v4,2/3] doc: simplify the binding steps

Message ID 20221128231940.15961-3-nicolas.chautru@intel.com (mailing list archive)
State Superseded
Delegated to: Thomas Monjalon
Headers
Series doc: simplify bbdev PMD steps |

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Chautru, Nicolas Nov. 28, 2022, 11:19 p.m. UTC
  The steps for binding to kernel modules which are
generic are now only implicit and pointing towards
common documentation.

Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
---
 doc/guides/bbdevs/acc100.rst        | 78 ++++-------------------------
 doc/guides/bbdevs/acc200.rst        | 74 ++++-----------------------
 doc/guides/bbdevs/fpga_5gnr_fec.rst | 77 ++++------------------------
 doc/guides/bbdevs/fpga_lte_fec.rst  | 77 ++++------------------------
 4 files changed, 36 insertions(+), 270 deletions(-)
  

Patch

diff --git a/doc/guides/bbdevs/acc100.rst b/doc/guides/bbdevs/acc100.rst
index 8a275dcdd4..60fccd3bc8 100644
--- a/doc/guides/bbdevs/acc100.rst
+++ b/doc/guides/bbdevs/acc100.rst
@@ -101,77 +101,15 @@  commands for ACC100 and ACC101 respectively:
   sudo lspci -vd8086:0d5c
   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
-FEC device first needs to be bound to one of these linux drivers through DPDK.
 
+Binding and Virtual Functions enablement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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
+The PMD relies on kernel modules to interface with the device: both UIO and VFIO kernel modules
+are supported.
+See :ref:`linux_gsg_binding_kernel` section for more details, notably with regards to
+generic kernel modules binding and VF enablement.
+More details on usage model is captured in the :ref:`pf_bb_config_acc100` section.
 
 
 Configure the VFs through PF
@@ -232,6 +170,8 @@  of these tests will depend on the device 5G/4G FEC capabilities which may cause
 testcases to be skipped, but no failure should be reported.
 
 
+.. _pf_bb_config_acc100:
+
 Alternate Baseband Device configuration tool
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/guides/bbdevs/acc200.rst b/doc/guides/bbdevs/acc200.rst
index 012b3870a8..410f18d9bc 100644
--- a/doc/guides/bbdevs/acc200.rst
+++ b/doc/guides/bbdevs/acc200.rst
@@ -110,73 +110,15 @@  can be listed through these commands for ACC200:
 
    sudo lspci -vd8086:57c0
 
-The physical and virtual functions are compatible with Linux UIO drivers:
-``vfio`` 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.
 
+Binding and Virtual Functions enablement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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 ACC200:
-
-#. 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
+The PMD relies on kernel modules to interface with the device: both UIO and VFIO kernel modules
+are supported.
+See :ref:`linux_gsg_binding_kernel` section for more details, notably with regards to
+generic kernel modules binding and VF enablement.
+More details on usage model is captured in the :ref:`pf_bb_config_acc200` section.
 
 
 Configure the VFs through PF
@@ -241,6 +183,8 @@  The results of these tests will depend on the device capabilities which may
 cause some test cases to be skipped, but no failure should be reported.
 
 
+.. _pf_bb_config_acc200:
+
 Alternate Baseband Device configuration tool
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/guides/bbdevs/fpga_5gnr_fec.rst b/doc/guides/bbdevs/fpga_5gnr_fec.rst
index 9d71585e9e..b2afd1bb2a 100644
--- a/doc/guides/bbdevs/fpga_5gnr_fec.rst
+++ b/doc/guides/bbdevs/fpga_5gnr_fec.rst
@@ -71,76 +71,15 @@  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
-to be bound to one of these linux drivers through DPDK.
 
+Binding and Virtual Functions enablement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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
+The PMD relies on kernel modules to interface with the device: both UIO and VFIO kernel modules
+are supported.
+See :ref:`linux_gsg_binding_kernel` section for more details, notably with regards to
+generic kernel modules binding and VF enablement.
+More details on usage model is captured in the :ref:`pf_bb_config_fpga_5gnr` section.
 
 
 Configure the VFs through PF
@@ -274,6 +213,8 @@  a range of additional tests under the test_vectors folder, which may be useful.
 of these tests will depend on the FPGA 5GNR FEC capabilities.
 
 
+.. _pf_bb_config_fpga_5gnr:
+
 Alternate Baseband Device configuration tool
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/guides/bbdevs/fpga_lte_fec.rst b/doc/guides/bbdevs/fpga_lte_fec.rst
index c3379c24e3..5e867c6bbd 100644
--- a/doc/guides/bbdevs/fpga_lte_fec.rst
+++ b/doc/guides/bbdevs/fpga_lte_fec.rst
@@ -70,76 +70,15 @@  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
-to be bound to one of these linux drivers through DPDK.
 
+Binding and Virtual Functions enablement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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
+The PMD relies on kernel modules to interface with the device: both UIO and VFIO kernel modules
+are supported.
+See :ref:`linux_gsg_binding_kernel` section for more details, notably with regards to
+generic kernel modules binding and VF enablement.
+More details on usage model is captured in the :ref:`pf_bb_config_fpga_lte` section.
 
 
 Configure the VFs through PF
@@ -293,6 +232,8 @@  of these tests will depend on the FPGA LTE FEC capabilities:
    - ``turbo_enc_c4_k4800_r2_e14412_crc24b.data``
 
 
+.. _pf_bb_config_fpga_lte:
+
 Alternate Baseband Device configuration tool
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~