[PATCH 0/5] Small Doc improvements for Linux GSG

[PATCH 0/5] Small Doc improvements for Linux GSG

[Bruce Richardson]

This patchset contains a number of small documentation improvements for
the linux GSG, spread across a few sections.

Bruce Richardson (5):
  doc/linux_gsg: add driver guides to document list
  doc/linux_gsg: drop note about old chipset
  doc/linux_gsg: remove duplicated note
  doc/linux_gsg: merge requirements section for app building
  doc/linux_gsg: expand list of directories

 doc/guides/linux_gsg/build_dpdk.rst | 13 +++++++++-
 doc/guides/linux_gsg/intro.rst      | 25 +++++++++++++++++++
 doc/guides/linux_gsg/sys_reqs.rst   | 38 ++++++++---------------------
 3 files changed, 47 insertions(+), 29 deletions(-)

--
2.32.0

[PATCH 1/5] doc/linux_gsg: add driver guides to document list

[Bruce Richardson]

The document roadmap section was missing any mention of the individual
drivers guides which are important for users. Add them to list.

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

diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.rst
index 890169e97f..ea98ac7425 100644
--- a/doc/guides/linux_gsg/intro.rst
+++ b/doc/guides/linux_gsg/intro.rst
@@ -34,3 +34,28 @@ The following is a list of DPDK documents in the suggested reading order:
 
 *   Sample Applications User Guide: Describes a set of sample applications.
     Each chapter describes a sample application that showcases specific functionality and provides instructions on how to compile, run and use the sample application.
+
+*   Driver Reference Guides: Provides details on each driver inside a particular category.
+    Separate guides exist for each of:
+
+    * Baseband devices
+
+    * Compression devices
+
+    * Cryptographic accelerator devices
+
+    * DMA devices
+
+    * Event-based scheduling devices
+
+    * General purpose GPU devices
+
+    * Mempool drivers
+
+    * Network (NIC) devices
+
+    * "Raw" devices i.e. those not fitting into any other category
+
+    * Regular expression devices
+
+    * vDPA (vhost data path acceleration) devices
\ No newline at end of file
-- 
2.32.0

[PATCH 2/5] doc/linux_gsg: drop note about old chipset

[Bruce Richardson]

The chipsets referenced in the note[1] were all launched in 2012 and are
now discontinued, so we can drop the note about them at this stage.

[1] https://ark.intel.com/content/www/us/en/ark/products/codename/44946/products-formerly-cave-creek.html

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index 9dccd54d9c..6f8799504a 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -8,11 +8,6 @@ System Requirements
 
 This chapter describes the packages required to compile the DPDK.
 
-.. note::
-
-    If the DPDK is being used on an Intel\ |reg| Communications Chipset 89xx Series platform,
-    please consult the *Intel\ |reg| Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
-
 BIOS Setting Prerequisite on x86
 --------------------------------
 
-- 
2.32.0

[PATCH 3/5] doc/linux_gsg: remove duplicated note

[Bruce Richardson]

A note about secure boot not allowing uio is present in both the system
requirements section and the driver binding section. This fits better in
the driver binding section, so the copy in system requirements can be
removed. The document in general now also emphasises vfio over uio more
than when this note was first added, reducing the need for this warning
to be repeated.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index 6f8799504a..df367742cc 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -17,13 +17,6 @@ and high performance of small packets, BIOS setting changes may be needed.
 Consult the section on :ref:`Enabling Additional Functionality <Enabling_Additional_Functionality>`
 for more information on the required changes.
 
-.. note::
-
-   If UEFI secure boot is enabled, the Linux kernel may disallow the use of
-   UIO on the system. Therefore, devices for use by DPDK should be bound to the
-   ``vfio-pci`` kernel module rather than ``igb_uio`` or ``uio_pci_generic``.
-   For more details see :ref:`linux_gsg_binding_kernel`.
-
 Compilation of the DPDK
 -----------------------
 
-- 
2.32.0

[PATCH 4/5] doc/linux_gsg: merge requirements section for app building

[Bruce Richardson]

When building end-applications linked with DPDK, the only additional
tool needed is pkg-config/pkgconf. However, the standard development
tools meta-packages on most distro's include this as standard, meaning
it does not really require its own section. The one outlier in the
existing text is "alpine" where it is not present when using "libc-dev"
target. However, changing "gcc" and "libc-dev" to "alpine-sdk"
metapackage aligns alpine with the other distros in this regard.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 26 ++++++++++----------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index df367742cc..08d45898f0 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -27,11 +27,19 @@ Compilation of the DPDK
     The setup commands and installed packages needed on various systems may be different.
     For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
 
-*   General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+).
+*   General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+),
+    and ``pkg-config`` or ``pkgconf`` to be used when building end-user binaries against DPDK.
 
     * For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
     * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
-    * For Alpine Linux, ``apk add gcc libc-dev bsd-compat-headers libexecinfo-dev``
+    * For Alpine Linux, ``apk add alpine-sdk bsd-compat-headers libexecinfo-dev``
+
+.. note::
+
+   pkg-config 0.27, supplied with RHEL-7,
+   does not process the Libs.private section correctly,
+   resulting in statically linked applications not being linked properly.
+   Use an updated version of ``pkg-config`` or ``pkgconf`` instead when building applications
 
 *   Python 3.5 or later.
 
@@ -87,20 +95,6 @@ For poll-mode drivers, the additional dependencies for each driver can be
 found in that driver's documentation in the relevant DPDK guide document,
 e.g. :doc:`../nics/index`
 
-
-Building DPDK Applications
---------------------------
-
-The tool pkg-config or pkgconf, integrated in most build systems,
-must be used to parse options and dependencies from libdpdk.pc.
-
-.. note::
-
-   pkg-config 0.27, supplied with RHEL-7,
-   does not process the Libs.private section correctly,
-   resulting in statically linked applications not being linked properly.
-
-
 Running DPDK Applications
 -------------------------
 
-- 
2.32.0

[PATCH 5/5] doc/linux_gsg: expand list of directories

[Bruce Richardson]

Not all directories were given in the GSG document, but many of those
omitted would be of interest to users, e.g. "doc", "license" and
"usertools" directories. Adding these leaves only "devtools", and
"kernel" as the only undocumented directories, so add them in too for
completeness.

When updating the section, add "including" to the line leading up to the
directory list, indicating that, while the list is currently complete,
it is not guaranteed to always be.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/build_dpdk.rst | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 0b08492ca2..4f2def15ed 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -16,7 +16,11 @@ First, uncompress the archive and move to the uncompressed DPDK source directory
     tar xJf dpdk-<version>.tar.xz
     cd dpdk-<version>
 
-The DPDK is composed of several directories:
+The DPDK is composed of several directories, including:
+
+*   doc: DPDK Documentation
+
+*   license: DPDK license information
 
 *   lib: Source code of DPDK libraries
 
@@ -28,6 +32,13 @@ The DPDK is composed of several directories:
 
 *   config, buildtools: Framework-related scripts and configuration
 
+*   usertools: Utility scripts for end-users of DPDK applications
+
+*   devtools: Scripts for use by DPDK developers
+
+*   kernel: Kernel modules needed for some operating systems
+
+
 Compiling and Installing DPDK System-wide
 -----------------------------------------
 
-- 
2.32.0

[PATCH v2 0/8] Linux GSG doc updates

[Bruce Richardson]

This patchset contains a number of small documentation improvements for
the linux GSG, spread across a few sections.

V2: Include additional patches removing or shortening content from
    the "Enabling Additional Functionality" section

Bruce Richardson (8):
  doc/linux_gsg: add driver guides to document list
  doc/linux_gsg: drop note about old chipset
  doc/linux_gsg: remove duplicated note
  doc/linux_gsg: merge requirements section for app building
  doc/linux_gsg: expand list of directories
  doc/linux_gsg: shorten details on HPET use
  doc/linux_gsg: drop reference to KNI
  doc/linux_gsg: remove section on IOMMU pass-through

 doc/guides/linux_gsg/build_dpdk.rst    |  13 +++-
 doc/guides/linux_gsg/enable_func.rst   | 102 ++++++-------------------
 doc/guides/linux_gsg/intro.rst         |  25 ++++++
 doc/guides/linux_gsg/linux_drivers.rst |   2 +-
 doc/guides/linux_gsg/sys_reqs.rst      |  38 +++------
 5 files changed, 70 insertions(+), 110 deletions(-)

--
2.32.0

[PATCH v2 1/8] doc/linux_gsg: add driver guides to document list

[Bruce Richardson]

The document roadmap section was missing any mention of the individual
drivers guides which are important for users. Add them to list.

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

diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.rst
index 890169e97f..ea98ac7425 100644
--- a/doc/guides/linux_gsg/intro.rst
+++ b/doc/guides/linux_gsg/intro.rst
@@ -34,3 +34,28 @@ The following is a list of DPDK documents in the suggested reading order:
 
 *   Sample Applications User Guide: Describes a set of sample applications.
     Each chapter describes a sample application that showcases specific functionality and provides instructions on how to compile, run and use the sample application.
+
+*   Driver Reference Guides: Provides details on each driver inside a particular category.
+    Separate guides exist for each of:
+
+    * Baseband devices
+
+    * Compression devices
+
+    * Cryptographic accelerator devices
+
+    * DMA devices
+
+    * Event-based scheduling devices
+
+    * General purpose GPU devices
+
+    * Mempool drivers
+
+    * Network (NIC) devices
+
+    * "Raw" devices i.e. those not fitting into any other category
+
+    * Regular expression devices
+
+    * vDPA (vhost data path acceleration) devices
\ No newline at end of file
-- 
2.32.0

[PATCH v2 2/8] doc/linux_gsg: drop note about old chipset

[Bruce Richardson]

The chipsets referenced in the note[1] were all launched in 2012 and are
now discontinued, so we can drop the note about them at this stage.

[1] https://ark.intel.com/content/www/us/en/ark/products/codename/44946/products-formerly-cave-creek.html

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index 9dccd54d9c..6f8799504a 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -8,11 +8,6 @@ System Requirements
 
 This chapter describes the packages required to compile the DPDK.
 
-.. note::
-
-    If the DPDK is being used on an Intel\ |reg| Communications Chipset 89xx Series platform,
-    please consult the *Intel\ |reg| Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
-
 BIOS Setting Prerequisite on x86
 --------------------------------
 
-- 
2.32.0

[PATCH v2 3/8] doc/linux_gsg: remove duplicated note

[Bruce Richardson]

A note about secure boot not allowing uio is present in both the system
requirements section and the driver binding section. This fits better in
the driver binding section, so the copy in system requirements can be
removed. The document in general now also emphasises vfio over uio more
than when this note was first added, reducing the need for this warning
to be repeated.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index 6f8799504a..df367742cc 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -17,13 +17,6 @@ and high performance of small packets, BIOS setting changes may be needed.
 Consult the section on :ref:`Enabling Additional Functionality <Enabling_Additional_Functionality>`
 for more information on the required changes.
 
-.. note::
-
-   If UEFI secure boot is enabled, the Linux kernel may disallow the use of
-   UIO on the system. Therefore, devices for use by DPDK should be bound to the
-   ``vfio-pci`` kernel module rather than ``igb_uio`` or ``uio_pci_generic``.
-   For more details see :ref:`linux_gsg_binding_kernel`.
-
 Compilation of the DPDK
 -----------------------
 
-- 
2.32.0

[PATCH v2 4/8] doc/linux_gsg: merge requirements section for app building

[Bruce Richardson]

When building end-applications linked with DPDK, the only additional
tool needed is pkg-config/pkgconf. However, the standard development
tools meta-packages on most distro's include this as standard, meaning
it does not really require its own section. The one outlier in the
existing text is "alpine" where it is not present when using "libc-dev"
target. However, changing "gcc" and "libc-dev" to "alpine-sdk"
metapackage aligns alpine with the other distros in this regard.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/sys_reqs.rst | 26 ++++++++++----------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst
index df367742cc..08d45898f0 100644
--- a/doc/guides/linux_gsg/sys_reqs.rst
+++ b/doc/guides/linux_gsg/sys_reqs.rst
@@ -27,11 +27,19 @@ Compilation of the DPDK
     The setup commands and installed packages needed on various systems may be different.
     For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
 
-*   General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+).
+*   General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+),
+    and ``pkg-config`` or ``pkgconf`` to be used when building end-user binaries against DPDK.
 
     * For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
     * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
-    * For Alpine Linux, ``apk add gcc libc-dev bsd-compat-headers libexecinfo-dev``
+    * For Alpine Linux, ``apk add alpine-sdk bsd-compat-headers libexecinfo-dev``
+
+.. note::
+
+   pkg-config 0.27, supplied with RHEL-7,
+   does not process the Libs.private section correctly,
+   resulting in statically linked applications not being linked properly.
+   Use an updated version of ``pkg-config`` or ``pkgconf`` instead when building applications
 
 *   Python 3.5 or later.
 
@@ -87,20 +95,6 @@ For poll-mode drivers, the additional dependencies for each driver can be
 found in that driver's documentation in the relevant DPDK guide document,
 e.g. :doc:`../nics/index`
 
-
-Building DPDK Applications
---------------------------
-
-The tool pkg-config or pkgconf, integrated in most build systems,
-must be used to parse options and dependencies from libdpdk.pc.
-
-.. note::
-
-   pkg-config 0.27, supplied with RHEL-7,
-   does not process the Libs.private section correctly,
-   resulting in statically linked applications not being linked properly.
-
-
 Running DPDK Applications
 -------------------------
 
-- 
2.32.0

[PATCH v2 5/8] doc/linux_gsg: expand list of directories

[Bruce Richardson]

Not all directories were given in the GSG document, but many of those
omitted would be of interest to users, e.g. "doc", "license" and
"usertools" directories. Adding these leaves only "devtools", and
"kernel" as the only undocumented directories, so add them in too for
completeness.

When updating the section, add "including" to the line leading up to the
directory list, indicating that, while the list is currently complete,
it is not guaranteed to always be.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/build_dpdk.rst | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 0b08492ca2..4f2def15ed 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -16,7 +16,11 @@ First, uncompress the archive and move to the uncompressed DPDK source directory
     tar xJf dpdk-<version>.tar.xz
     cd dpdk-<version>
 
-The DPDK is composed of several directories:
+The DPDK is composed of several directories, including:
+
+*   doc: DPDK Documentation
+
+*   license: DPDK license information
 
 *   lib: Source code of DPDK libraries
 
@@ -28,6 +32,13 @@ The DPDK is composed of several directories:
 
 *   config, buildtools: Framework-related scripts and configuration
 
+*   usertools: Utility scripts for end-users of DPDK applications
+
+*   devtools: Scripts for use by DPDK developers
+
+*   kernel: Kernel modules needed for some operating systems
+
+
 Compiling and Installing DPDK System-wide
 -----------------------------------------
 
-- 
2.32.0

[PATCH v2 6/8] doc/linux_gsg: shorten details on HPET use

[Bruce Richardson]

As best we can tell, the HPET timers are not commonly used, so there is
little need to give extensive detail and commentry on them in the Linux
GSG. As such, we can reduce the GSG section to just a single subsection
and also move it down the page below items which are likely of greater
importance.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/enable_func.rst | 80 ++++++++++------------------
 1 file changed, 27 insertions(+), 53 deletions(-)

diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index b5c4c652d7..0036c542f5 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -8,59 +8,6 @@
 Enabling Additional Functionality
 =================================
 
-.. _High_Precision_Event_Timer:
-
-High Precision Event Timer (HPET) Functionality
------------------------------------------------
-
-BIOS Support
-~~~~~~~~~~~~
-
-The High Precision Timer (HPET) must be enabled in the platform BIOS if the HPET is to be used.
-Otherwise, the Time Stamp Counter (TSC) is used by default.
-The BIOS is typically accessed by pressing F2 while the platform is starting up.
-The user can then navigate to the HPET option. On the Crystal Forest platform BIOS, the path is:
-**Advanced -> PCH-IO Configuration -> High Precision Timer ->** (Change from Disabled to Enabled if necessary).
-
-On a system that has already booted, the following command can be issued to check if HPET is enabled::
-
-   grep hpet /proc/timer_list
-
-If no entries are returned, HPET must be enabled in the BIOS (as per the instructions above) and the system rebooted.
-
-Linux Kernel Support
-~~~~~~~~~~~~~~~~~~~~
-
-The DPDK makes use of the platform HPET timer by mapping the timer counter into the process address space, and as such,
-requires that the ``HPET_MMAP`` kernel configuration option be enabled.
-
-.. warning::
-
-    On Fedora, and other common distributions such as Ubuntu, the ``HPET_MMAP`` kernel option is not enabled by default.
-    To recompile the Linux kernel with this option enabled, please consult the distributions documentation for the relevant instructions.
-
-Enabling HPET in the DPDK
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, HPET support is disabled in the DPDK build configuration files.
-To use HPET, use the following meson build option which will enable the HPET settings at compile time::
-
-   meson configure -Duse_hpet=true
-
-For an application to use the ``rte_get_hpet_cycles()`` and ``rte_get_hpet_hz()`` API calls,
-and optionally to make the HPET the default time source for the rte_timer library,
-the new ``rte_eal_hpet_init()`` API call should be called at application initialization.
-This API call will ensure that the HPET is accessible, returning an error to the application if it is not,
-for example, if ``HPET_MMAP`` is not enabled in the kernel.
-The application can then determine what action to take, if any, if the HPET is not available at run-time.
-
-.. note::
-
-    For applications that require timing APIs, but not the HPET timer specifically,
-    it is recommended that the ``rte_get_timer_cycles()`` and ``rte_get_timer_hz()`` API calls be used instead of the HPET-specific APIs.
-    These generic APIs can work with either TSC or HPET time sources, depending on what is requested by an application call to ``rte_eal_hpet_init()``,
-    if any, and on what is available on the system at runtime.
-
 .. _Running_Without_Root_Privileges:
 
 Running DPDK Applications Without Root Privileges
@@ -154,6 +101,33 @@ the following should be added to the kernel parameter list:
 
     isolcpus=2,4,6
 
+.. _High_Precision_Event_Timer:
+
+High Precision Event Timer (HPET) Functionality
+-----------------------------------------------
+
+DPDK can support the system HPET as a timer source rather than the system default timers,
+such as the core Time-Stamp Counter (TSC) on x86 systems.
+To enable HPET support in DPDK:
+
+1. Ensure that HPET is enabled in BIOS settings.
+2. Enable ``HPET_MMAP`` support in kernel configuration.
+   Note that this my involve doing a kernel rebuild,
+   as many common linux distributions do *not* have this setting enabled by default in their kernel builds.
+3. Enable DPDK support for HPET by using the build-time meson option ``use_hpet``,
+   for example, ``meson configure -Duse_hpet=true``
+
+For an application to use the ``rte_get_hpet_cycles()`` and ``rte_get_hpet_hz()`` API calls,
+and optionally to make the HPET the default time source for the rte_timer library,
+the ``rte_eal_hpet_init()`` API call should be called at application initialization.
+This API call will ensure that the HPET is accessible, returning an error to the application if it is not.
+
+For applications that require timing APIs, but not the HPET timer specifically,
+it is recommended that the ``rte_get_timer_cycles()`` and ``rte_get_timer_hz()`` API calls be used instead of the HPET-specific APIs.
+These generic APIs can work with either TSC or HPET time sources,
+depending on what is requested by an application call to ``rte_eal_hpet_init()``,
+if any, and on what is available on the system at runtime.
+
 Loading the DPDK KNI Kernel Module
 ----------------------------------
 
-- 
2.32.0

[PATCH v2 7/8] doc/linux_gsg: drop reference to KNI

[Bruce Richardson]

The KNI library is disabled by default in DPDK and is already documented
in the programmers guide and also in the sample application guide. There
are also in-kernel alternatives to it.  Therefore, we can drop the
(already fairly minimal) reference to it from the Linux GSG.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/enable_func.rst | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index 0036c542f5..1f19842ddc 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -128,19 +128,6 @@ These generic APIs can work with either TSC or HPET time sources,
 depending on what is requested by an application call to ``rte_eal_hpet_init()``,
 if any, and on what is available on the system at runtime.
 
-Loading the DPDK KNI Kernel Module
-----------------------------------
-
-To run the DPDK Kernel NIC Interface (KNI) sample application, an extra kernel module (the kni module) must be loaded into the running kernel.
-The module is found in the kernel/linux sub-directory of the DPDK build directory.
-It should be loaded using the insmod command::
-
-   insmod <build_dir>/kernel/linux/kni/rte_kni.ko
-
-.. note::
-
-   See the "Kernel NIC Interface Sample Application" chapter in the *DPDK Sample Applications User Guide* for more details.
-
 Using Linux IOMMU Pass-Through to Run DPDK with Intel\ |reg| VT-d
 ------------------------------------------------------------------
 
-- 
2.32.0

[PATCH v2 8/8] doc/linux_gsg: remove section on IOMMU pass-through

[Bruce Richardson]

The "Linux Drivers" section of the GSG already notes that, for use of
UIO, the IOMMU must be disabled or put into pass-through mode.
Therefore, there is no need to duplicate this information in the
"additional functionality" section.  Also the kernel configuration
options documented in the section are enabled as standard on all common
distro kernels, so the information should not be needed in a GSG doc.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/linux_gsg/enable_func.rst   | 19 -------------------
 doc/guides/linux_gsg/linux_drivers.rst |  2 +-
 2 files changed, 1 insertion(+), 20 deletions(-)

diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index 1f19842ddc..338c33290b 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -127,22 +127,3 @@ it is recommended that the ``rte_get_timer_cycles()`` and ``rte_get_timer_hz()``
 These generic APIs can work with either TSC or HPET time sources,
 depending on what is requested by an application call to ``rte_eal_hpet_init()``,
 if any, and on what is available on the system at runtime.
-
-Using Linux IOMMU Pass-Through to Run DPDK with Intel\ |reg| VT-d
-------------------------------------------------------------------
-
-To enable Intel\ |reg| VT-d in a Linux kernel, a number of kernel configuration options must be set. These include:
-
-*   ``IOMMU_SUPPORT``
-
-*   ``IOMMU_API``
-
-*   ``INTEL_IOMMU``
-
-In addition, to run the DPDK with Intel\ |reg| VT-d, the ``iommu=pt`` kernel parameter must be used when using ``igb_uio`` driver.
-This results in pass-through of the DMAR (DMA Remapping) lookup in the host.
-Also, if ``INTEL_IOMMU_DEFAULT_ON`` is not set in the kernel, the ``intel_iommu=on`` kernel parameter must be used too.
-This ensures that the Intel IOMMU is being initialized as expected.
-
-Please note that while using ``iommu=pt`` is compulsory for ``igb_uio`` driver,
-the ``vfio-pci`` driver can actually work with both ``iommu=pt`` and ``iommu=on``.
diff --git a/doc/guides/linux_gsg/linux_drivers.rst b/doc/guides/linux_gsg/linux_drivers.rst
index 03cf264a0a..2e4c80ebd3 100644
--- a/doc/guides/linux_gsg/linux_drivers.rst
+++ b/doc/guides/linux_gsg/linux_drivers.rst
@@ -367,7 +367,7 @@ It can be loaded as shown below:
 
 .. note::
 
-   If the devices used for DPDK are bound to the ``uio_pci_generic`` kernel module,
+   If the devices used for DPDK are bound to a UIO-based kernel module,
    please make sure that the IOMMU is disabled or is in passthrough mode.
    One can add ``intel_iommu=off`` or ``amd_iommu=off`` or ``intel_iommu=on iommu=pt``
    in GRUB command line on x86_64 systems,
-- 
2.32.0

Re: [PATCH v2 0/8] Linux GSG doc updates

[Thomas Monjalon]

10/03/2022 13:38, Bruce Richardson:
> This patchset contains a number of small documentation improvements for
> the linux GSG, spread across a few sections.
> 
> V2: Include additional patches removing or shortening content from
>     the "Enabling Additional Functionality" section
> 
> Bruce Richardson (8):
>   doc/linux_gsg: add driver guides to document list

This first patch would deserve some links to other guides.

>   doc/linux_gsg: drop note about old chipset
>   doc/linux_gsg: remove duplicated note
>   doc/linux_gsg: merge requirements section for app building
>   doc/linux_gsg: expand list of directories
>   doc/linux_gsg: shorten details on HPET use
>   doc/linux_gsg: drop reference to KNI
>   doc/linux_gsg: remove section on IOMMU pass-through

Applied, except first patch, thanks.

Re: [PATCH v2 0/8] Linux GSG doc updates

[Bruce Richardson]

On Tue, Mar 15, 2022 at 07:46:39PM +0100, Thomas Monjalon wrote:
> 10/03/2022 13:38, Bruce Richardson:
> > This patchset contains a number of small documentation improvements for
> > the linux GSG, spread across a few sections.
> > 
> > V2: Include additional patches removing or shortening content from
> >     the "Enabling Additional Functionality" section
> > 
> > Bruce Richardson (8):
> >   doc/linux_gsg: add driver guides to document list
> 
> This first patch would deserve some links to other guides.
> 
Agreed. I'll try and do up a new set for both Linux and BSD docs and send
it out tomorrow (Wed)

> >   doc/linux_gsg: drop note about old chipset
> >   doc/linux_gsg: remove duplicated note
> >   doc/linux_gsg: merge requirements section for app building
> >   doc/linux_gsg: expand list of directories
> >   doc/linux_gsg: shorten details on HPET use
> >   doc/linux_gsg: drop reference to KNI
> >   doc/linux_gsg: remove section on IOMMU pass-through
> 
> Applied, except first patch, thanks.
> 
Thanks.