[PATCH v3 0/7] docs: getting started guide consolidation

[PATCH v3 0/7] docs: getting started guide consolidation

[David Young]

Updated based on latest v1 and v2 feedback.

David Young (7):
  Section 1: Introduction
  Section 2: Install and Build DPDK
  Section 3: Setting up a System to Run DPDK Applications
  Section 4: Running Applications
  Section 5: Appendix
  Added link to Getting Started Guide in index.rst
  Section 6: Glossary

 .../appendix/cross_compile_dpdk.rst           |  37 +++
 .../appendix/dpdk_meson_build_options.rst     |  57 ++++
 .../getting_started_guide/appendix/index.rst  |  17 +
 .../running_dpdk_apps_without_root.rst        |  36 +++
 .../appendix/vfio_advanced.rst                | 295 ++++++++++++++++++
 doc/guides/getting_started_guide/glossary.rst |  75 +++++
 .../building_from_sources.rst                 | 174 +++++++++++
 .../install_and_build/index.rst               |  14 +
 .../installing_prebuilt_packages.rst          |  54 ++++
 doc/guides/getting_started_guide/intro.rst    |  13 +
 .../getting_started_guide/run_apps/index.rst  |  10 +
 .../run_apps/run_apps.rst                     | 118 +++++++
 .../getting_started_guide/system_setup.rst    | 195 ++++++++++++
 doc/guides/index.rst                          |   1 +
 14 files changed, 1096 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst
 create mode 100644 doc/guides/getting_started_guide/glossary.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
 create mode 100644 doc/guides/getting_started_guide/intro.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst
 create mode 100644 doc/guides/getting_started_guide/system_setup.rst

-- 
2.41.0.windows.1

[PATCH v3 1/7] Section 1: Introduction

[David Young]

Edited copy to be simpler based on feedback.
---
 doc/guides/getting_started_guide/intro.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/intro.rst

diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst
new file mode 100644
index 0000000000..538b3bacec
--- /dev/null
+++ b/doc/guides/getting_started_guide/intro.rst
@@ -0,0 +1,13 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2014 Intel Corporation.
+
+Introduction
+============
+
+Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and
+drivers that accelerate packet processing and allow the user to create high-performance
+networking applications.
+
+The guide is structured to provide basic step-by-step instructions with OS-specific instructions for each operating system where necessary. 
+By the end of this guide, you should have a solid understanding of how to implement and
+use DPDK in your networking projects, regardless of the operating system you are using.
\ No newline at end of file
-- 
2.41.0.windows.1

Re: [PATCH v3 1/7] Section 1: Introduction

[Bruce Richardson]

On Fri, Nov 03, 2023 at 12:01:47AM -0400, David Young wrote:
> Edited copy to be simpler based on feedback.

Thanks David,
some small comments inline below.

> ---
>  doc/guides/getting_started_guide/intro.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/intro.rst
> 
> diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst
> new file mode 100644
> index 0000000000..538b3bacec
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/intro.rst
> @@ -0,0 +1,13 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2014 Intel Corporation.
> +
> +Introduction
> +============
> +
> +Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and
> +drivers that accelerate packet processing and allow the user to create high-performance
> +networking applications.

The line breaks are in odd places here. Since we track the documentation as
text files in our repository, like source-code, we want future changes to
minimise the lines being changed as much as possible.
Checking our contributors doc, I think our guidelines there for
documentation changes are out of date, so here are the "working guidelines"
I use for docs:

* line length can be up to ~100 chars, maybe a bit more if it makes sense
  to avoid breaks
* Start each sentence on a new line (unless you have two really short ones
  that both fit on one line!)
* When breaking a sentence across two lines, split at a punctuation mark,
  like a comma, or before an "and" or "but" etc. Each clause should be on a
  single line where possible.

> +
> +The guide is structured to provide basic step-by-step instructions with OS-specific instructions for each operating system where necessary. 

should we add "got setting up and using DPDK" after "instructions"?

for the OS-specific instructions, should be say that they are "only" where
necessary, to try and emphasise we have things as common as possible?

> +By the end of this guide, you should have a solid understanding of how to implement and
> +use DPDK in your networking projects, regardless of the operating system you are using.
> \ No newline at end of file

Please fix this little warning. POSIX standard specifies that all text
files should end with a newline character. Rather than having to add it
manually, many editors have a setting to ensure it is there automatically,
so that might be worth investigating.

[PATCH v3 2/7] Section 2: Install and Build DPDK

[David Young]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 7980 bytes --]

Section 2: Install and Build DPDK - Updated based on feedback; Merged windows_install_build.rst into building_from_sources.rst; Updated Meson 0.57.x to be required for Windows.
---
 .../building_from_sources.rst                 | 174 ++++++++++++++++++
 .../install_and_build/index.rst               |  14 ++
 .../installing_prebuilt_packages.rst          |  54 ++++++
 3 files changed, 242 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst

diff --git a/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
new file mode 100644
index 0000000000..fd7e2e9b30
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
@@ -0,0 +1,174 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _building_from_sources:
+
+Building and Installing DPDK from Sources
+=========================================
+
+This chapter provides a comprehensive guide for building DPDK from sources on Linux, FreeBSD, and Windows. It covers the necessary steps, prerequisites, 
+and considerations for different architectures and compilers.
+
+Required Tools
+--------------
+
+To build DPDK, you'll need the following tools:
+
+- A C compiler like ``gcc`` (version 5+) or ``clang`` (version 3.6+)
+- ``pkg-config`` or ``pkgconf``
+- Python 3.6 or later
+- ``meson`` (version 0.57.0) and ``ninja``
+- ``pyelftools`` (version 0.22+)
+
+Platform-Specific Tool Installation
+-----------------------------------
+
+Linux
+^^^^^
+
+Common Tools for All Distributions:
+
+.. code-block:: bash
+
+   sudo apt install gcc pkg-config python3 meson ninja pyelftools
+
+Alpine
+
+.. code-block:: bash
+
+   sudo apk add alpine-sdk bsd-compat-headers
+
+Debian, Ubuntu, and derivatives
+
+.. code-block:: bash
+
+   sudo apt install build-essential
+
+Fedora and RedHat Enterprise Linux RHEL
+
+.. code-block:: bash
+
+   sudo dnf groupinstall "Development Tools"
+
+openSUSE
+
+.. code-block:: bash
+
+   sudo zypper install -t pattern devel_basis python3-pyelftools
+
+FreeBSD
+^^^^^^^
+
+Common Tools for FreeBSD:
+
+.. code-block:: bash
+
+   pkg install gcc pkgconf python3 meson ninja pyelftools
+
+.. note::
+
+   If you're using FreeBSD, make sure kernel sources are included during the FreeBSD installation.
+
+Windows System Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Building the DPDK and its applications on Windows requires one of the following
+environments:
+
+- The Clang-LLVM C compiler and Microsoft MSVC linker.
+- The MinGW-w64 toolchain (either native or cross).
+
+The Meson Build system is used to prepare the sources for compilation with the Ninja backend.
+
+Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+1. Install the Compiler: Download and install the Clang compiler from the 
+   `LLVM website <http://releases.llvm.org/>`_.
+
+2. Install the Linker: Download and install the Build Tools for Visual Studio from the
+   `Microsoft website <https://visualstudio.microsoft.com/downloads/>`_.
+   When installing build tools, select the “Visual C++ build tools” option and make sure
+   the Windows SDK is selected.
+
+Option 2: MinGW-w64 Toolchain
+""""""""""""""""""""""""""""""
+
+1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. 
+   Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug.
+
+2. On Windows: Obtain the latest version installer from the
+   `MinGW-w64 repository <https://mingw-w64.org/doku.php>`_. 
+   Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it. 
+   Install to a folder without spaces in its name, like ``C:\MinGW``. 
+   This path is assumed for the rest of this guide.
+
+Install the Build System
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download and install the build system from the
+`Meson website <http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer>`_.
+A good option to choose is the MSI installer for both meson and ninja together.
+Required version is Meson 0.57.x (baseline).
+
+Getting the DPDK Source
+-----------------------
+
+Linux and FreeBSD
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
+   tar -xvf dpdk-<version>.tar.xz
+   cd dpdk-<version>
+
+Windows
+^^^^^^^
+
+Download the DPDK source code from `DPDK's official website <https://www.dpdk.org/>`_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory.
+
+Navigate to the directory where the DPDK source code is located:
+
+.. code-block:: bash
+
+   cd C:\path\to\dpdk-<version>
+
+Building DPDK
+-------------
+
+Linux and FreeBSD
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   meson build
+   ninja -C build
+
+Windows
+^^^^^^^
+
+**Option 1: Using Clang-LLVM**
+
+.. code-block:: bash
+
+   set CC=clang
+   meson setup -Dexamples=helloworld build
+   meson compile -C build
+
+**Option 2: Using MinGW-w64**
+
+.. code-block:: bash
+
+   set PATH=C:\MinGW\mingw64\bin;%PATH%
+   meson setup -Dexamples=helloworld build
+   meson compile -C build
+
+.. note::
+
+   For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`.
+
+Cross-Compilation Instructions for Different Architectures
+----------------------------------------------------------
+
+For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/install_and_build/index.rst b/doc/guides/getting_started_guide/install_and_build/index.rst
new file mode 100644
index 0000000000..48e438282f
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/index.rst
@@ -0,0 +1,14 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _install_and_build:
+
+Install and Build DPDK
+======================
+
+.. toctree::
+    :maxdepth: 2
+
+    
+    installing_prebuilt_packages
+    building_from_sources
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
new file mode 100644
index 0000000000..3e395d65f1
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
@@ -0,0 +1,54 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _installing_prebuilt_packages:
+
+Installing Pre-built Packages
+=============================
+
+Pre-built packages provide a convenient way to install DPDK without the need to compile
+the source code manually. These packages are created and maintained by the DPDK
+community or OS vendors and are available for various operating systems and
+distributions.
+
+Available Distributions
+-----------------------
+
+Linux
+^^^^^
+
+Pre-built DPDK packages are available for several popular Linux distributions,
+including but not limited to:
+
+Alpine
+
+.. code-block:: bash
+
+   sudo apk add dpdk
+
+Debian and Ubuntu and derivatives
+
+.. code-block:: bash
+
+   sudo apt-get install dpdk
+
+Fedora and RedHat Enterprise Linux RHEL
+
+.. code-block:: bash
+
+   sudo dnf install dpdk
+
+openSUSE
+
+.. code-block:: bash
+
+   sudo zypper install dpdk
+
+FreeBSD
+^^^^^^^
+
+To install DPDK on FreeBSD, use the following command:
+
+.. code-block:: bash
+
+   sudo pkg install dpdk
\ No newline at end of file
-- 
2.41.0.windows.1

Re: [PATCH v3 2/7] Section 2: Install and Build DPDK

[Bruce Richardson]

Thanks, David. More comments inline below.

/Bruce

On Fri, Nov 03, 2023 at 12:01:48AM -0400, David Young wrote:
> Section 2: Install and Build DPDK - Updated based on feedback; Merged windows_install_build.rst into building_from_sources.rst; Updated Meson 0.57.x to be required for Windows.

Please word-wrap commit log.

> ---
>  .../building_from_sources.rst                 | 174 ++++++++++++++++++
>  .../install_and_build/index.rst               |  14 ++
>  .../installing_prebuilt_packages.rst          |  54 ++++++
>  3 files changed, 242 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
>  create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
>  create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
> 
> diff --git a/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> new file mode 100644
> index 0000000000..fd7e2e9b30
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> @@ -0,0 +1,174 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _building_from_sources:
> +
> +Building and Installing DPDK from Sources
> +=========================================
> +
> +This chapter provides a comprehensive guide for building DPDK from sources on Linux, FreeBSD, and Windows. It covers the necessary steps, prerequisites, 
> +and considerations for different architectures and compilers.
> +

I wonder if we need so many repetitions of "Linux, FreeBSD and Windows". We
just referred to them in the previous intro section.

> +Required Tools
> +--------------
> +
> +To build DPDK, you'll need the following tools:
> +
> +- A C compiler like ``gcc`` (version 5+) or ``clang`` (version 3.6+)
> +- ``pkg-config`` or ``pkgconf``
> +- Python 3.6 or later
> +- ``meson`` (version 0.57.0) and ``ninja``
> +- ``pyelftools`` (version 0.22+)
> +
> +Platform-Specific Tool Installation
> +-----------------------------------
> +
> +Linux
> +^^^^^
> +
> +Common Tools for All Distributions:
> +
> +.. code-block:: bash
> +
> +   sudo apt install gcc pkg-config python3 meson ninja pyelftools
> +

The tools may be common, but the command is for debian and derivatives like
Ubuntu. Can you fold these packages into the individual lists per-distro
below, since "apt install" doesn't work on Fedora or openSUSE.

> +Alpine
> +
> +.. code-block:: bash
> +
> +   sudo apk add alpine-sdk bsd-compat-headers
> +
> +Debian, Ubuntu, and derivatives
> +
> +.. code-block:: bash
> +
> +   sudo apt install build-essential
> +
> +Fedora and RedHat Enterprise Linux RHEL
> +
> +.. code-block:: bash
> +
> +   sudo dnf groupinstall "Development Tools"
> +
> +openSUSE
> +
> +.. code-block:: bash
> +
> +   sudo zypper install -t pattern devel_basis python3-pyelftools
> +

Looking through these package lists, I think we need to add libnuma
development packages to them. For debian/ubuntu, that would be
"libnuma-dev". For Fedora, I think it's "numactl-devel".

> +FreeBSD
> +^^^^^^^
> +
> +Common Tools for FreeBSD:
> +
> +.. code-block:: bash
> +
> +   pkg install gcc pkgconf python3 meson ninja pyelftools

Actually, we don't need gcc here. FreeBSD comes with clang and uses it as
the default compiler.

> +
> +.. note::
> +
> +   If you're using FreeBSD, make sure kernel sources are included during the FreeBSD installation.
> +
> +Windows System Requirements
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Building the DPDK and its applications on Windows requires one of the following
> +environments:
> +
> +- The Clang-LLVM C compiler and Microsoft MSVC linker.
> +- The MinGW-w64 toolchain (either native or cross).
> +
> +The Meson Build system is used to prepare the sources for compilation with the Ninja backend.
> +
> +Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker
> +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
> +
> +1. Install the Compiler: Download and install the Clang compiler from the 
> +   `LLVM website <http://releases.llvm.org/>`_.
> +
> +2. Install the Linker: Download and install the Build Tools for Visual Studio from the
> +   `Microsoft website <https://visualstudio.microsoft.com/downloads/>`_.
> +   When installing build tools, select the “Visual C++ build tools” option and make sure
> +   the Windows SDK is selected.
> +
> +Option 2: MinGW-w64 Toolchain
> +""""""""""""""""""""""""""""""
> +
> +1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. 
> +   Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug.
> +
> +2. On Windows: Obtain the latest version installer from the
> +   `MinGW-w64 repository <https://mingw-w64.org/doku.php>`_. 
> +   Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it. 
> +   Install to a folder without spaces in its name, like ``C:\MinGW``. 
> +   This path is assumed for the rest of this guide.
> +
> +Install the Build System
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Download and install the build system from the
> +`Meson website <http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer>`_.
> +A good option to choose is the MSI installer for both meson and ninja together.
> +Required version is Meson 0.57.x (baseline).
> +
> +Getting the DPDK Source
> +-----------------------
> +
> +Linux and FreeBSD
> +^^^^^^^^^^^^^^^^^
> +
> +.. code-block:: bash
> +
> +   wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> +   tar -xvf dpdk-<version>.tar.xz

For "xz" files, I believe tar uses -J flag, so this should be "tar -xJf",
not "tar -xvf"

> +   cd dpdk-<version>
> +
> +Windows
> +^^^^^^^
> +
> +Download the DPDK source code from `DPDK's official website <https://www.dpdk.org/>`_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory.
> +
> +Navigate to the directory where the DPDK source code is located:
> +
> +.. code-block:: bash
> +
> +   cd C:\path\to\dpdk-<version>
> +
> +Building DPDK
> +-------------
> +
> +Linux and FreeBSD
> +^^^^^^^^^^^^^^^^^
> +
> +.. code-block:: bash
> +
> +   meson build

"meson build" now gives a warning with latest versions of meson, since we
don't specify and operation. Change this to "meson setup build".
You should add a note immediately after the "Building DPDK" header, stating
that in all examples "build" is used as the name of the build directory.
This should ensure readers don't think it's part of the command itself.

> +   ninja -C build

For consistency with windows, do we want to change this to "meson compile
-C build"?

If we do, it would allow us to have subsections only for "configuring the
build with meson" and have a common "build" section if we want. [I don't
think we should do this yet, but we may want to in future].

> +
> +Windows
> +^^^^^^^
> +
> +**Option 1: Using Clang-LLVM**
> +
> +.. code-block:: bash
> +
> +   set CC=clang
> +   meson setup -Dexamples=helloworld build
> +   meson compile -C build
> +
> +**Option 2: Using MinGW-w64**
> +
> +.. code-block:: bash
> +
> +   set PATH=C:\MinGW\mingw64\bin;%PATH%
> +   meson setup -Dexamples=helloworld build
> +   meson compile -C build
> +
> +.. note::
> +
> +   For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`.
> +
> +Cross-Compilation Instructions for Different Architectures
> +----------------------------------------------------------
> +
> +For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`.
> \ No newline at end of file
> diff --git a/doc/guides/getting_started_guide/install_and_build/index.rst b/doc/guides/getting_started_guide/install_and_build/index.rst
> new file mode 100644
> index 0000000000..48e438282f
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/index.rst
> @@ -0,0 +1,14 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _install_and_build:
> +
> +Install and Build DPDK
> +======================
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    
> +    installing_prebuilt_packages
> +    building_from_sources
> \ No newline at end of file
> diff --git a/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
> new file mode 100644
> index 0000000000..3e395d65f1
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
> @@ -0,0 +1,54 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _installing_prebuilt_packages:
> +
> +Installing Pre-built Packages
> +=============================
> +
> +Pre-built packages provide a convenient way to install DPDK without the need to compile
> +the source code manually. These packages are created and maintained by the DPDK
> +community or OS vendors and are available for various operating systems and
> +distributions.
> +
> +Available Distributions
> +-----------------------
> +
> +Linux
> +^^^^^
> +
> +Pre-built DPDK packages are available for several popular Linux distributions,
> +including but not limited to:
> +
> +Alpine
> +
> +.. code-block:: bash
> +
> +   sudo apk add dpdk
> +
> +Debian and Ubuntu and derivatives
> +
> +.. code-block:: bash
> +
> +   sudo apt-get install dpdk
> +
> +Fedora and RedHat Enterprise Linux RHEL
> +
> +.. code-block:: bash
> +
> +   sudo dnf install dpdk
> +
> +openSUSE
> +
> +.. code-block:: bash
> +
> +   sudo zypper install dpdk
> +
> +FreeBSD
> +^^^^^^^
> +
> +To install DPDK on FreeBSD, use the following command:
> +
> +.. code-block:: bash
> +
> +   sudo pkg install dpdk

Update this to dpdk-20.11, since that is the latest DPDK version available
(sadly) at this time. I need to chase up more on getting 22.11 merged
there, and soon 23.11!

> \ No newline at end of file
> -- 
> 2.41.0.windows.1
> 

[PATCH v3 3/7] Section 3: Setting up a System to Run DPDK Applications

[David Young]

---
 .../getting_started_guide/system_setup.rst    | 195 ++++++++++++++++++
 1 file changed, 195 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/system_setup.rst

diff --git a/doc/guides/getting_started_guide/system_setup.rst b/doc/guides/getting_started_guide/system_setup.rst
new file mode 100644
index 0000000000..fa9d249ec7
--- /dev/null
+++ b/doc/guides/getting_started_guide/system_setup.rst
@@ -0,0 +1,195 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _memory_setup:
+
+.. |reg| unicode:: U+000AE
+
+Setting up a System to Run DPDK Applications
+============================================
+
+This section provides step-by-step instructions for setting up your system to run DPDK applications. It covers system configurations for Linux, FreeBSD, and Windows. Each section details the necessary memory and device setups for these operating systems.
+
+Navigate to the section that corresponds to your operating system to begin the setup process.
+
+.. contents:: Table of Contents
+   :local:
+
+System Setup for Linux
+----------------------
+
+Memory Setup: Reserving Hugepages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For Linux, DPDK requires hugepages be reserved for its use on the system. To check if hugepages are are on your system, you can run the following command::
+
+        grep HugePages_Total /proc/meminfo
+
+If hugepages are not reserved, you will need to reserve them by following these steps:
+
+1. Determine the number of hugepages you want to allocate. For example, to allocate 1024 hugepages of 2MB each, you can use the following command::
+
+        echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+2. To make the hugepages configuration persistent across reboots, add the following line to your `/etc/sysctl.conf` file, adjusting the number of hugepages as needed::
+
+        vm.nr_hugepages = 1024
+
+3. Most distributions make hugepages available via `/dev/hugepages`, so this step may not be necessary. If you need to manually mount the hugepages filesystem, add the following line to your `/etc/fstab` file::
+
+        nodev /mnt/huge hugetlbfs defaults 0 0
+
+   Then, create the mount directory and mount the filesystem::
+
+        mkdir -p /mnt/huge
+        mount -a
+
+Device Setup: VFIO
+^^^^^^^^^^^^^^^^^^
+
+VFIO is a robust and secure driver that relies on IOMMU protection.
+To make use of VFIO on Linux, the ``vfio-pci`` module must be loaded:
+
+.. code-block:: console
+
+    sudo modprobe vfio-pci
+
+VFIO kernel is usually present by default in all distributions,
+however please consult your distribution's documentation to make sure that is the case.
+
+To make use of full VFIO functionality,
+both kernel and BIOS must support and be configured
+to use IO virtualization (such as Intel\ |reg| VT-d).
+
+.. note::
+
+   In most cases, specifying "iommu=on" as kernel parameter should be enough to
+   configure the Linux kernel to use IOMMU.
+
+For proper operation of VFIO when running DPDK applications as a non-privileged user,
+correct permissions should also be set up.
+For more information, refer to :ref:`running_dpdk_apps_without_root`.
+
+Refer to :ref:`vfio_no_iommu_mode` when there is no IOMMU available on the system.
+
+Binding and Unbinding Network Ports to/from VFIO-PCI Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To bind or unbind network ports to/from the `vfio-pci` module on Linux, follow these steps:
+
+Replace ``<module_id>`` with the appropriate module identifier.
+
+**Unbind from current module**:
+   If a device is bound to a kernel driver, unbind it:
+
+   .. code-block:: bash
+
+      sudo dpdk-devbind.py -u <module_id>
+
+**Bind to vfio-pci module**:
+   Bind the device to the `vfio-pci` module:
+
+   .. code-block:: bash
+
+      sudo dpdk-devbind.py -b vfio-pci <module_id>
+
+System Setup for FreeBSD
+------------------------
+
+.. _loading_contigmem_module:
+
+Memory Setup: Loading the DPDK contigmem Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run a DPDK application on FreeBSD, physically contiguous memory is required. In the absence of non-transparent superpages, the included sources for the `contigmem` kernel module provides the ability to present contiguous blocks of memory for the DPDK to use. 
+The ``contigmem`` module must be loaded into the running kernel before any DPDK is run.
+Once DPDK is installed on the system, the module can be found in the ``/boot/modules``
+directory.
+
+The amount of physically contiguous memory along with the number of physically
+contiguous blocks to be reserved by the module can be set at runtime prior to module
+loading using::
+
+    kenv hw.contigmem.num_buffers=n
+    kenv hw.contigmem.buffer_size=m
+
+The kernel environment variables can also be specified during boot by placing the
+following in ``/boot/loader.conf``::
+
+    hw.contigmem.num_buffers=n
+    hw.contigmem.buffer_size=m
+
+The variables can be inspected using the following command::
+
+    sysctl -a hw.contigmem
+
+The module can then be loaded using ``kldload``::
+
+    cd /boot/modules
+    kldload contigmem
+
+Device Setup: Loading the DPDK nic_uio Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After :ref:`loading_contigmem_module` on FreeBSD, the ``nic_uio`` module must also be loaded into the running kernel prior to running any DPDK application, e.g. using::
+
+    cd /boot/modules
+    kldload nic_uio
+
+By default, the ``nic_uio`` module will take ownership of network ports if they are
+recognized DPDK devices and are not owned by another module. 
+However, since the FreeBSD kernel includes support, either built-in, 
+or via a separate driver module, for most network card devices,
+it is likely that the ports to be used are already bound to a driver other than
+``nic_uio``.
+
+To re-bind the ports to the `nic_uio` module upon loading, use the following command::
+
+    kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..."
+
+Where a comma-separated list of selectors is set, the list must not contain any
+whitespace.
+
+The variable can also be specified during boot by placing the following into
+``/boot/loader.conf``, before the previously-described ``nic_uio_load`` line::
+
+    hw.nic_uio.bdfs="2:0:0,2:0:1"
+    nic_uio_load="YES"
+
+Binding and Unbinding Network Ports to/from nic_uio Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the original driver for a network port has been compiled into the kernel, 
+it is necessary to reboot FreeBSD to restore the original device binding. 
+Before doing so, update or remove the ``hw.nic_uio.bdfs`` in ``/boot/loader.conf``.
+
+If rebinding to a driver that is a loadable module, the network port binding can be
+reset without rebooting. To do so, unload both the target kernel module and the
+``nic_uio`` module, modify or clear the ``hw.nic_uio.bdfs`` kernel environment
+(``kenv``) value, and reload the two drivers - first the original kernel driver,
+and then the ``nic_uio`` driver.
+
+Example commands to perform these steps are shown below::
+
+    kldunload nic_uio
+    kldunload <original_driver>
+    kenv -u hw.nic_uio.bdfs
+    kldload <original_driver>
+    kldload nic_uio  # optional
+
+System Setup for Windows
+------------------------
+
+Memory Setup: Installing Windows Modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before running DPDK applications on Windows, certain kernel-mode drivers must be installed. Note that these drivers are not signed, so you'll need to disable signature enforcement. However, be cautious as this can weaken your OS security and is generally not recommended in production environments.
+
+Device Setup: Install Drivers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run DPDK applications on Windows, you'll need to install specific kernel-mode drivers:
+
+- **virt2phys**: This driver is essential for providing access to physical addresses and is mandatory for allocating physically-contiguous memory, which is required by hardware PMDs. Once loaded successfully, this driver will appear in the Device Manager as ``Virtual to physical address translator device`` under the Kernel bypass category. If DPDK cannot communicate with the driver, a warning will be printed during initialization.
+
+- **NetUIO**: This driver provides access to device hardware resources and is mandatory for all hardware PMDs, except for the mlx5 PMD. Devices supported by NetUIO are listed in ``netuio.inf``. You can extend this list to try running DPDK with new devices.
\ No newline at end of file
-- 
2.41.0.windows.1

Re: [PATCH v3 3/7] Section 3: Setting up a System to Run DPDK Applications

[Bruce Richardson]

As before, comments inline.

On Fri, Nov 03, 2023 at 12:01:49AM -0400, David Young wrote:
> ---
>  .../getting_started_guide/system_setup.rst    | 195 ++++++++++++++++++
>  1 file changed, 195 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/system_setup.rst
> 
> diff --git a/doc/guides/getting_started_guide/system_setup.rst b/doc/guides/getting_started_guide/system_setup.rst
> new file mode 100644
> index 0000000000..fa9d249ec7
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/system_setup.rst
> @@ -0,0 +1,195 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _memory_setup:
> +
> +.. |reg| unicode:: U+000AE

Better to get this character via ".. include:: <isonum.txt>". That is what
other files do.

> +
> +Setting up a System to Run DPDK Applications
> +============================================
> +
> +This section provides step-by-step instructions for setting up your system to run DPDK applications. It covers system configurations for Linux, FreeBSD, and Windows. Each section details the necessary memory and device setups for these operating systems.
> +
> +Navigate to the section that corresponds to your operating system to begin the setup process.
> +
> +.. contents:: Table of Contents
> +   :local:
> +
> +System Setup for Linux
> +----------------------
> +
> +Memory Setup: Reserving Hugepages
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +For Linux, DPDK requires hugepages be reserved for its use on the system. To check if hugepages are are on your system, you can run the following command::

"are are" probably should be "are reserved".

> +
> +        grep HugePages_Total /proc/meminfo
> +
> +If hugepages are not reserved, you will need to reserve them by following these steps:
> +
> +1. Determine the number of hugepages you want to allocate. For example, to allocate 1024 hugepages of 2MB each, you can use the following command::
> +
> +        echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
> +
> +2. To make the hugepages configuration persistent across reboots, add the following line to your `/etc/sysctl.conf` file, adjusting the number of hugepages as needed::
> +
> +        vm.nr_hugepages = 1024
> +
> +3. Most distributions make hugepages available via `/dev/hugepages`, so this step may not be necessary. If you need to manually mount the hugepages filesystem, add the following line to your `/etc/fstab` file::

Starting a bullet point with a sentence saying "this step may not be
necessary" seems a little strange - at least to me. Can we reword this perhaps?

> +
> +        nodev /mnt/huge hugetlbfs defaults 0 0
> +
> +   Then, create the mount directory and mount the filesystem::
> +
> +        mkdir -p /mnt/huge
> +        mount -a
> +

We need a section somewhere in the docs about other page sizes - both 1G on
x86, and the various sizes on Arm and other archs. Appendix would be a good
place for it, with a reference here. For the large page sizes we need to
talk about boot-time reservation.

> +Device Setup: VFIO
> +^^^^^^^^^^^^^^^^^^
> +
> +VFIO is a robust and secure driver that relies on IOMMU protection.
> +To make use of VFIO on Linux, the ``vfio-pci`` module must be loaded:
> +
> +.. code-block:: console
> +
> +    sudo modprobe vfio-pci
> +
> +VFIO kernel is usually present by default in all distributions,
> +however please consult your distribution's documentation to make sure that is the case.
> +
> +To make use of full VFIO functionality,
> +both kernel and BIOS must support and be configured
> +to use IO virtualization (such as Intel\ |reg| VT-d).
> +
> +.. note::
> +
> +   In most cases, specifying "iommu=on" as kernel parameter should be enough to
> +   configure the Linux kernel to use IOMMU.
> +
> +For proper operation of VFIO when running DPDK applications as a non-privileged user,
> +correct permissions should also be set up.
> +For more information, refer to :ref:`running_dpdk_apps_without_root`.
> +
> +Refer to :ref:`vfio_no_iommu_mode` when there is no IOMMU available on the system.
> +
> +Binding and Unbinding Network Ports to/from VFIO-PCI Module
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To bind or unbind network ports to/from the `vfio-pci` module on Linux, follow these steps:
> +
> +Replace ``<module_id>`` with the appropriate module identifier.

On initial reading I thought module_id was referring to kernel module, i.e.
vfio-pci. However, it instead is refering to the PCI device id or BDF
address. Let's clarify this by using a better term. I'd suggest "<pci_id>".
Also give an example:

Replace <pci_id> with the appropriate device identifier, e.g. 01:00.0,
a8:00.0.

> +
> +**Unbind from current module**:
> +   If a device is bound to a kernel driver, unbind it:
> +
> +   .. code-block:: bash
> +
> +      sudo dpdk-devbind.py -u <module_id>
> +

Actually, this step is not necessary. The devbind script is smart enough to
know that to bind to a new driver, it needs to unbind the device first, so
for binding to vfio-pci, it does unbind+bind with the one command.

> +**Bind to vfio-pci module**:
> +   Bind the device to the `vfio-pci` module:
> +
> +   .. code-block:: bash
> +
> +      sudo dpdk-devbind.py -b vfio-pci <module_id>
> +
> +System Setup for FreeBSD
> +------------------------
> +
> +.. _loading_contigmem_module:
> +
> +Memory Setup: Loading the DPDK contigmem Module
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To run a DPDK application on FreeBSD, physically contiguous memory is required. In the absence of non-transparent superpages, the included sources for the `contigmem` kernel module provides the ability to present contiguous blocks of memory for the DPDK to use. 
> +The ``contigmem`` module must be loaded into the running kernel before any DPDK is run.

"any DPDK" -> "any DPDK application"

> +Once DPDK is installed on the system, the module can be found in the ``/boot/modules``
> +directory.
> +
> +The amount of physically contiguous memory along with the number of physically
> +contiguous blocks to be reserved by the module can be set at runtime prior to module
> +loading using::
> +
> +    kenv hw.contigmem.num_buffers=n
> +    kenv hw.contigmem.buffer_size=m
> +
> +The kernel environment variables can also be specified during boot by placing the
> +following in ``/boot/loader.conf``::
> +
> +    hw.contigmem.num_buffers=n
> +    hw.contigmem.buffer_size=m
> +
> +The variables can be inspected using the following command::
> +
> +    sysctl -a hw.contigmem
> +
> +The module can then be loaded using ``kldload``::
> +
> +    cd /boot/modules
> +    kldload contigmem
> +
> +Device Setup: Loading the DPDK nic_uio Module
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +After :ref:`loading_contigmem_module` on FreeBSD, the ``nic_uio`` module must also be loaded into the running kernel prior to running any DPDK application, e.g. using::
> +
> +    cd /boot/modules
> +    kldload nic_uio
> +
> +By default, the ``nic_uio`` module will take ownership of network ports if they are
> +recognized DPDK devices and are not owned by another module. 
> +However, since the FreeBSD kernel includes support, either built-in, 
> +or via a separate driver module, for most network card devices,
> +it is likely that the ports to be used are already bound to a driver other than
> +``nic_uio``.
> +
> +To re-bind the ports to the `nic_uio` module upon loading, use the following command::
> +
> +    kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..."
> +
> +Where a comma-separated list of selectors is set, the list must not contain any
> +whitespace.
> +
> +The variable can also be specified during boot by placing the following into
> +``/boot/loader.conf``, before the previously-described ``nic_uio_load`` line::

Not previously-described!

> +
> +    hw.nic_uio.bdfs="2:0:0,2:0:1"
> +    nic_uio_load="YES"
> +
> +Binding and Unbinding Network Ports to/from nic_uio Module
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If the original driver for a network port has been compiled into the kernel, 
> +it is necessary to reboot FreeBSD to restore the original device binding. 
> +Before doing so, update or remove the ``hw.nic_uio.bdfs`` in ``/boot/loader.conf``.
> +
> +If rebinding to a driver that is a loadable module, the network port binding can be
> +reset without rebooting. To do so, unload both the target kernel module and the
> +``nic_uio`` module, modify or clear the ``hw.nic_uio.bdfs`` kernel environment
> +(``kenv``) value, and reload the two drivers - first the original kernel driver,
> +and then the ``nic_uio`` driver.
> +
> +Example commands to perform these steps are shown below::
> +
> +    kldunload nic_uio
> +    kldunload <original_driver>
> +    kenv -u hw.nic_uio.bdfs
> +    kldload <original_driver>
> +    kldload nic_uio  # optional
> +
> +System Setup for Windows
> +------------------------
> +
> +Memory Setup: Installing Windows Modules
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Before running DPDK applications on Windows, certain kernel-mode drivers must be installed. Note that these drivers are not signed, so you'll need to disable signature enforcement. However, be cautious as this can weaken your OS security and is generally not recommended in production environments.
> +
> +Device Setup: Install Drivers
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To run DPDK applications on Windows, you'll need to install specific kernel-mode drivers:
> +
> +- **virt2phys**: This driver is essential for providing access to physical addresses and is mandatory for allocating physically-contiguous memory, which is required by hardware PMDs. Once loaded successfully, this driver will appear in the Device Manager as ``Virtual to physical address translator device`` under the Kernel bypass category. If DPDK cannot communicate with the driver, a warning will be printed during initialization.
> +
> +- **NetUIO**: This driver provides access to device hardware resources and is mandatory for all hardware PMDs, except for the mlx5 PMD. Devices supported by NetUIO are listed in ``netuio.inf``. You can extend this list to try running DPDK with new devices.
> \ No newline at end of file
> -- 
> 2.41.0.windows.1
> 

[PATCH v3 4/7] Section 4: Running Applications

[David Young]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 5052 bytes --]

---
 .../getting_started_guide/run_apps/index.rst  |  10 ++
 .../run_apps/run_apps.rst                     | 118 ++++++++++++++++++
 2 files changed, 128 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst

diff --git a/doc/guides/getting_started_guide/run_apps/index.rst b/doc/guides/getting_started_guide/run_apps/index.rst
new file mode 100644
index 0000000000..f033cac5f0
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps/index.rst
@@ -0,0 +1,10 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+Running Applications
+====================
+
+.. toctree::
+    :maxdepth: 2
+
+    run_apps
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/run_apps/run_apps.rst b/doc/guides/getting_started_guide/run_apps/run_apps.rst
new file mode 100644
index 0000000000..339d4c0a68
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps/run_apps.rst
@@ -0,0 +1,118 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _run_apps:
+
+Running Applications
+====================
+
+The following instructions apply to Linux, FreeBSD, and Windows.
+
+.. contents:: Table of Contents
+   :local:
+
+Running Applications on Linux and FreeBSD
+-----------------------------------------
+
+Compiling and Running Sample Applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To compile a sample application:
+
+1. Navigate to the application's directory in the DPDK distribution.
+2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD.
+
+For instance, to compile the ``helloworld`` application:
+
+::
+
+    cd examples/helloworld
+    make    # On Linux
+    gmake   # On FreeBSD
+
+To run the application, use:
+
+::
+
+    ./build/helloworld -l 0-2
+
+The ``-l`` option indicates the cores on which the application should run.
+
+Sample Applications Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Hello World**: A basic application that prints a "hello world" message.
+2. **Basic Forwarding**: A skeleton example of a forwarding application.
+3. **Command Line**: Demonstrates the command line interface in DPDK.
+4. **Ethtool**: Showcases the Ethtool API in DPDK.
+
+For a comprehensive list of sample applications and their guides, 
+refer to the `DPDK Sample Applications User Guides <https://doc.dpdk.org/guides/sample_app_ug/index.html>`_.
+
+EAL Parameters
+^^^^^^^^^^^^^^
+
+Every DPDK application is linked with the DPDK target environment’s 
+Environmental Abstraction Layer (EAL) library, which provides generic options. 
+Some of these options include:
+
+- ``-c COREMASK`` or ``-l CORELIST``: Specifies the cores to run on.
+- ``-n NUM``: Number of memory channels per processor socket.
+- ``--socket-mem``: Memory allocation from hugepages on specific sockets.
+
+For a detailed list of EAL options, 
+refer to the `EAL parameters section <eal_parameters>`.
+
+Running Without Root Privileges
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Refer to :ref:`running_dpdk_apps_without_root`.
+
+Running Applications on Windows
+-------------------------------
+
+Running DPDK applications on Windows involves a few different steps. 
+This guide provides detailed instructions on how to run the helloworld example
+application, which can be used as a reference for running other DPDK applications.
+
+Grant Lock Pages in Memory Privilege
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use of hugepages ("large pages" in Windows terminology) requires
+``SeLockMemoryPrivilege`` for the user running an application. 
+This privilege allows the DPDK application to keep data in physical memory, 
+preventing the system from paging the data to virtual memory. 
+This can significantly improve the performance of your DPDK applications.
+
+To grant this privilege:
+
+1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter.
+2. Open Local Policies / User Rights Assignment / Lock pages in memory.
+3. Add desired users or groups to the list of grantees.
+
+The privilege is applied upon the next logon. If the privilege has been granted to the
+current user, a logoff is required before it is available. 
+More details can be found in the `Large-Page Support in MSDN <https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support>`_.
+
+Running the helloworld Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After setting up the drivers, you can run the helloworld example to verify your setup.
+Here are the steps:
+
+1. Navigate to the examples in the build directory::
+
+        cd C:\\Users\\me\\dpdk\\build\\examples
+
+2. Run the helloworld application::
+
+        dpdk-helloworld.exe -l 0-3
+
+The output should display a hello message from each core, like this:
+
+::
+
+    hello from core 1
+    hello from core 3
+    hello from core 0
+    hello from core 2
-- 
2.41.0.windows.1

Re: [PATCH v3 4/7] Section 4: Running Applications

[Bruce Richardson]

On Fri, Nov 03, 2023 at 12:01:50AM -0400, David Young wrote:
> ---
>  .../getting_started_guide/run_apps/index.rst  |  10 ++
>  .../run_apps/run_apps.rst                     | 118 ++++++++++++++++++
>  2 files changed, 128 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
>  create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst
> 
> diff --git a/doc/guides/getting_started_guide/run_apps/index.rst b/doc/guides/getting_started_guide/run_apps/index.rst
> new file mode 100644
> index 0000000000..f033cac5f0
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/run_apps/index.rst
> @@ -0,0 +1,10 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +Running Applications
> +====================
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    run_apps
> \ No newline at end of file

There seems to be only a single run_apps file, so we don't need a whole
subdir for it.

> diff --git a/doc/guides/getting_started_guide/run_apps/run_apps.rst b/doc/guides/getting_started_guide/run_apps/run_apps.rst
> new file mode 100644
> index 0000000000..339d4c0a68
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/run_apps/run_apps.rst
> @@ -0,0 +1,118 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _run_apps:
> +
> +Running Applications
> +====================
> +
> +The following instructions apply to Linux, FreeBSD, and Windows.
> +

Do they apply for windows? <self-update :-)> I see windows at the end, so yes,
we have instructions but they are split. I'd drop this opening line.

> +.. contents:: Table of Contents
> +   :local:
> +
> +Running Applications on Linux and FreeBSD
> +-----------------------------------------
> +
> +Compiling and Running Sample Applications
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To compile a sample application:
> +
> +1. Navigate to the application's directory in the DPDK distribution.
> +2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD.
> +
> +For instance, to compile the ``helloworld`` application:
> +
> +::
> +
> +    cd examples/helloworld
> +    make    # On Linux
> +    gmake   # On FreeBSD
> +

There is an assumption here (maybe all through this doc) that DPDK is
installed system-wide.
If not, maybe we tell the user they can compile the examples as part of a
DPDK build itself using meson option "-Dexamples=...".

> +To run the application, use:
> +
> +::
> +
> +    ./build/helloworld -l 0-2
> +
> +The ``-l`` option indicates the cores on which the application should run.
> +
> +Sample Applications Overview
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +1. **Hello World**: A basic application that prints a "hello world" message.
> +2. **Basic Forwarding**: A skeleton example of a forwarding application.
> +3. **Command Line**: Demonstrates the command line interface in DPDK.
> +4. **Ethtool**: Showcases the Ethtool API in DPDK.
> +

I'd drop this list. The reference below for the sample app guide is best.

> +For a comprehensive list of sample applications and their guides, 
> +refer to the `DPDK Sample Applications User Guides <https://doc.dpdk.org/guides/sample_app_ug/index.html>`_.
> +
> +EAL Parameters
> +^^^^^^^^^^^^^^
> +
> +Every DPDK application is linked with the DPDK target environment’s 
> +Environmental Abstraction Layer (EAL) library, which provides generic options. 
> +Some of these options include:
> +
> +- ``-c COREMASK`` or ``-l CORELIST``: Specifies the cores to run on.

Unrelated to your work, there has been some discussion on the DPDK mailing
list around moving away from coremasks in DPDK, since they are unwieldy to
use. Therefore, for simplicity, just document the -l option, and give a
couple of examples e.g.

	'-l 1-3' to run on 3 cores, 1, 2 and 3
	'-l 8,16' to run on 2 cores, 8 and 16
	'-l 1-7,9-15' to run on 14 cores, using 1 through 7 and then 9
		through 15

> +- ``-n NUM``: Number of memory channels per processor socket.
> +- ``--socket-mem``: Memory allocation from hugepages on specific sockets.
> +

I would drop these last two options, they are very much for advanced users.
So in the opening paragraph, instead of saying "some of these options
include", we can just talk about the "most important option" or similar to
that. Again, we have a refence link to get more info.

> +For a detailed list of EAL options, 
> +refer to the `EAL parameters section <eal_parameters>`.
> +
> +Running Without Root Privileges
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Refer to :ref:`running_dpdk_apps_without_root`.
> +
> +Running Applications on Windows
> +-------------------------------
> +
> +Running DPDK applications on Windows involves a few different steps. 
> +This guide provides detailed instructions on how to run the helloworld example
> +application, which can be used as a reference for running other DPDK applications.
> +
> +Grant Lock Pages in Memory Privilege
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Use of hugepages ("large pages" in Windows terminology) requires
> +``SeLockMemoryPrivilege`` for the user running an application. 
> +This privilege allows the DPDK application to keep data in physical memory, 
> +preventing the system from paging the data to virtual memory. 
> +This can significantly improve the performance of your DPDK applications.
> +
> +To grant this privilege:
> +
> +1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter.
> +2. Open Local Policies / User Rights Assignment / Lock pages in memory.
> +3. Add desired users or groups to the list of grantees.
> +
> +The privilege is applied upon the next logon. If the privilege has been granted to the
> +current user, a logoff is required before it is available. 
> +More details can be found in the `Large-Page Support in MSDN <https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support>`_.
> +
> +Running the helloworld Example
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +After setting up the drivers, you can run the helloworld example to verify your setup.
> +Here are the steps:
> +
> +1. Navigate to the examples in the build directory::
> +
> +        cd C:\\Users\\me\\dpdk\\build\\examples
> +
> +2. Run the helloworld application::
> +
> +        dpdk-helloworld.exe -l 0-3
> +
> +The output should display a hello message from each core, like this:
> +
> +::
> +
> +    hello from core 1
> +    hello from core 3
> +    hello from core 0
> +    hello from core 2
> -- 
> 2.41.0.windows.1
> 

[PATCH v3 5/7] Section 5: Appendix

[David Young]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 18486 bytes --]

---
 .../appendix/cross_compile_dpdk.rst           |  37 +++
 .../appendix/dpdk_meson_build_options.rst     |  57 ++++
 .../getting_started_guide/appendix/index.rst  |  17 +
 .../running_dpdk_apps_without_root.rst        |  36 +++
 .../appendix/vfio_advanced.rst                | 295 ++++++++++++++++++
 5 files changed, 442 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst

diff --git a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
new file mode 100644
index 0000000000..3e4efe23a4
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
@@ -0,0 +1,37 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _cross_compile_dpdk:
+
+Cross-compiling DPDK for Different Architectures on Linux
+=========================================================
+
+Cross-compiling DPDK for different architectures follows a similar process. Here are the general steps:
+
+1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain and any required libraries specific to the target architecture.
+
+2. **Build Using Cross-File**: Use Meson to set up the build with a cross-file specific to the target architecture, and then build with Ninja.
+
+Prerequisites
+-------------
+
+- NUMA Library (if required)
+- Meson and Ninja
+- pkg-config for the target architecture
+- Specific GNU or LLVM/Clang toolchain for the target architecture
+
+Cross-Compiling DPDK
+--------------------
+
+1. **Set Up the Cross Toolchain**: Download and extract the toolchain for the target architecture. Add it to the PATH.
+
+2. **Compile Any Required Libraries**: Compile libraries like NUMA if required.
+
+3. **Cross-Compile DPDK with Meson**:
+
+   .. code-block:: bash
+
+      meson setup cross-build --cross-file <target_machine_configuration>
+      ninja -C cross-build
+
+Refer to the specific sections for ARM64, LoongArch, and RISC-V for detailed instructions and architecture-specific considerations.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
new file mode 100644
index 0000000000..6669f98371
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
@@ -0,0 +1,57 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _dpdk_meson_build_options:
+
+DPDK Meson Build Configuration Options
+======================================
+
+DPDK provides a number of build configuration options that can be adjusted using the Meson build system. These options can be listed by running ``meson configure`` inside a configured build
+folder.
+
+Changing the Build Type
+-----------------------
+
+To change the build type from the default "release" to a regular "debug" build,
+you can either:
+
+- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially.
+- Run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
+
+Platform Options
+----------------
+
+The "platform" option specifies a set of configuration parameters that will be used. 
+The valid values are:
+
+- ``-Dplatform=native`` will tailor the configuration to the build machine.
+- ``-Dplatform=generic`` will use configuration that works on all machines of the same architecture as the build machine.
+- ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC.
+
+Consult the "socs" dictionary in ``config/arm/meson.build`` to see which SoCs are supported.
+
+Overriding Platform Parameters
+------------------------------
+
+The values determined by the platform parameter may be overwritten. For example,
+to set the ``max_lcores`` value to 256, you can either:
+
+- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially.
+- Run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Building Sample Applications
+----------------------------
+
+Some of the DPDK sample applications in the examples directory can be automatically built as
+part of a meson build. To do so, pass a comma-separated list of the examples to build to the
+``-Dexamples`` meson option as below::
+
+    meson setup -Dexamples=l2fwd,l3fwd build
+
+There is also a special value "all" to request that all example applications whose dependencies
+are met on the current system are built. When ``-Dexamples=all`` is set as a meson option,
+meson will check each example application to see if it can be built, and add all which can be
+built to the list of tasks in the ninja build configuration file.
+
+For a complete list of options, run ``meson configure`` inside your configured build
+folder.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/index.rst b/doc/guides/getting_started_guide/appendix/index.rst
new file mode 100644
index 0000000000..23bb1fcf78
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/index.rst
@@ -0,0 +1,17 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _appendix:
+
+Appendix
+========
+
+This section covers specific guides related to DPDK.
+
+.. toctree::
+    :maxdepth: 2
+
+    dpdk_meson_build_options
+    running_dpdk_apps_without_root
+    vfio_advanced
+    cross_compile_dpdk
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
new file mode 100644
index 0000000000..9f214bbdc8
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
@@ -0,0 +1,36 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _running_dpdk_apps_without_root:
+
+Running DPDK Applications Without Root Privileges
+=================================================
+
+Although applications using the DPDK use network ports and other hardware resources
+directly, with a number of small permission adjustments, 
+it is possible to run these applications as a user other than “root”. 
+To do so, the ownership, or permissions, on the following file system objects should be
+adjusted so the user account being used to run the DPDK application has
+access to them:
+
+Linux
+-----
+
+1. **Create a DPDK User Group**: Create a new user group for DPDK and add the desired user to this group.
+
+2. **Set Up Hugepages**: Configure hugepages for the user.
+
+3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool ``dpdk-devbind.py`` to bind the NIC to a user-space driver like ``vfio-pci`` or ``igb_uio``.
+
+4. **Set Permissions for UIO/VFIO Devices**: Change the ownership and permissions of the UIO or VFIO devices to allow access by the DPDK user group.
+
+5. **Run the DPDK Application**: Run the desired DPDK application as the user who has been added to the DPDK group.
+
+FreeBSD
+-------
+
+- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
+- The userspace contiguous memory device: ``/dev/contigmem``
+
+
+Refer to the `DPDK Release Notes <https://doc.dpdk.org/guides/rel_notes/index.html>`_ for supported applications.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/vfio_advanced.rst b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst
new file mode 100644
index 0000000000..1cdb138eb7
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst
@@ -0,0 +1,295 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _vfio_advanced:
+
+.. |reg| unicode:: U+000AE
+
+VFIO Advanced
+=============
+
+
+.. contents:: Table of Contents
+   :local:
+
+.. _vfio_no_iommu_mode:
+
+VFIO no-IOMMU mode
+------------------
+
+If there is no IOMMU available on the system, VFIO can still be used,
+but it has to be loaded with an additional module parameter:
+
+.. code-block:: console
+
+   modprobe vfio enable_unsafe_noiommu_mode=1
+
+Alternatively, one can also enable this option in an already loaded kernel module:
+
+.. code-block:: console
+
+   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
+
+After that, VFIO can be used with hardware devices as usual.
+
+.. note::
+
+   It may be required to unload all VFIO related-modules before probing
+   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
+
+.. warning::
+
+   Since no-IOMMU mode    forgoes IOMMU protection, it is inherently unsafe.
+   That said, it does make it possible for the user
+   to keep the degree of device access and programming that VFIO has,
+   in situations where IOMMU is not available.
+
+VFIO Memory Mapping Limits
+--------------------------
+
+For DMA mapping of either external memory or hugepages, VFIO interface is used.
+VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is
+mapped in hugepage granularity or system page granularity. Number of DMA
+mappings is limited by kernel with user locked memory limit of a process (rlimit)
+for system/hugepage memory. Another per-container overall limit applicable both
+for external memory and system memory was added in kernel 5.1 defined by
+VFIO module parameter ``dma_entry_limit`` with a default value of 64K.
+When application is out of DMA entries, these limits need to be adjusted to
+increase the allowed limit.
+
+Creating Virtual Functions using vfio-pci
+-----------------------------------------
+
+Since Linux version 5.7,
+the ``vfio-pci`` module supports the creation of virtual functions.
+After the PF is bound to ``vfio-pci`` module,
+the user can create the VFs using the ``sysfs`` interface,
+and these VFs will be bound to ``vfio-pci`` module automatically.
+
+When the PF is bound to ``vfio-pci``,
+by default it will have a randomly generated VF token.
+For security reasons, this token is write only,
+so the user cannot read it from the kernel directly.
+To access the VFs, the user needs to create a new token,
+and use it to initialize both VF and PF devices.
+The tokens are in UUID format,
+so any UUID generation tool can be used to create a new token.
+
+This VF token can be passed to DPDK by using EAL parameter ``--vfio-vf-token``.
+The token will be used for all PF and VF ports within the application.
+
+#. Generate the VF token by uuid command
+
+   .. code-block:: console
+
+      14d63f20-8445-11ea-8900-1f9ce7d5650d
+
+#. Load the ``vfio-pci`` module with ``enable_sriov`` parameter set
+
+   .. code-block:: console
+
+      sudo modprobe vfio-pci enable_sriov=1
+
+   Alternatively, pass the ``enable_sriov`` parameter through the ``sysfs`` if the    module is already loaded or is built-in:
+
+   .. code-block:: console
+
+      echo 1 | sudo tee /sys/module/vfio_pci/parameters/enable_sriov
+
+#. Bind the PCI devices to ``vfio-pci`` driver
+
+   .. code-block:: console
+
+      ./usertools/dpdk-devbind.py -b vfio-pci 0000:86:00.0
+
+#. Create the desired number of VF devices
+
+   .. code-block:: console
+
+      echo 2 > /sys/bus/pci/devices/0000:86:00.0/sriov_numvfs
+
+#. Start the DPDK application that will manage the PF device
+
+   .. code-block:: console
+
+      <build_dir>/app/dpdk-testpmd -l 22-25 -n 4 -a 86:00.0 \
+      --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=pf -- -i
+
+#. Start the DPDK application that will manage the VF device
+
+   .. code-block:: console
+
+      <build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \
+      --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i
+
+.. note::
+
+   Linux versions earlier than version 5.7 do not support the creation of
+   virtual functions within the VFIO framework.
+
+Troubleshooting VFIO
+--------------------
+
+In certain situations, using ``dpdk-devbind.py`` script
+to bind a device to VFIO driver may fail.
+The first place to check is the kernel messages:
+
+.. code-block:: console
+
+   dmesg | tail
+   ...
+   [ 1297.875090] vfio-pci: probe of 0000:31:00.0 failed with error -22
+   ...
+
+In most cases, the ``error -22`` indicates that the VFIO subsystem
+could not be enabled because there is no IOMMU support.
+
+To check whether the kernel has been booted with correct parameters,
+one can check the kernel command-line:
+
+.. code-block:: console
+
+   cat /proc/cmdline
+
+Please refer to earlier sections on how to configure kernel parameters
+correctly for your system.
+
+If the kernel is configured correctly, one also has to make sure that
+the BIOS configuration has virtualization features (such as Intel\ |reg| VT-d).
+There is no standard way to check if the platform is configured correctly,
+so please check with your platform documentation to see if it has such features,
+and how to enable them.
+
+In certain distributions, default kernel configuration is such that
+the no-IOMMU mode is disabled altogether at compile time.
+This can be checked in the boot configuration of your system:
+
+.. code-block:: console
+
+   cat /boot/config-$(uname -r) | grep NOIOMMU
+   # CONFIG_VFIO_NOIOMMU is not set
+
+If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
+VFIO driver will not support the no-IOMMU mode,
+and other alternatives (such as UIO drivers) will have to be used.
+
+VFIO Platform
+-------------
+
+VFIO Platform is a kernel driver that extends capabilities of VFIO
+by adding support for platform devices that reside behind an IOMMU.
+Linux usually learns about platform devices directly from device tree
+during boot-up phase,
+unlike for example, PCI devices which have necessary information built-in.
+
+To make use of VFIO platform, the ``vfio-platform`` module must be loaded first:
+
+.. code-block:: console
+
+   sudo modprobe vfio-platform
+
+.. note::
+
+   By default ``vfio-platform`` assumes that platform device has dedicated reset driver.
+   If such driver is missing or device does not require one,
+   this option can be turned off by setting ``reset_required=0`` module parameter.
+
+Afterwards platform device needs to be bound to ``vfio-platform``.
+This is standard procedure requiring two steps.
+First ``driver_override``, which is available inside platform device directory,
+needs to be set to ``vfio-platform``:
+
+.. code-block:: console
+
+   sudo echo vfio-platform > /sys/bus/platform/devices/DEV/driver_override
+
+Next ``DEV`` device must be bound to ``vfio-platform`` driver:
+
+.. code-block:: console
+
+   sudo echo DEV > /sys/bus/platform/drivers/vfio-platform/bind
+
+On application startup, DPDK platform bus driver scans ``/sys/bus/platform/devices``
+searching for devices that have ``driver`` symbolic link
+pointing to ``vfio-platform`` driver.
+Finally, scanned devices are matched against available PMDs.
+Matching is    successful if either PMD name or PMD alias matches kernel driver name
+or PMD name matches platform device name, all in that order.
+
+VFIO Platform depends on ARM/ARM64 and is usually enabled on distributions
+running on these systems.
+Consult your distributions documentation to make sure that is the case.
+
+Bifurcated Driver
+-----------------
+
+PMDs which use the bifurcated driver co-exists with the device kernel driver.
+On such model the NIC is controlled by the kernel, while the data
+path is performed by the PMD directly on top of the device.
+
+Such model has the following benefits:
+
+ - It is secure and robust, as the memory management and isolation
+   is done by the kernel.
+ - It enables the user to use legacy linux tools such as ``ethtool`` or
+   ``ifconfig`` while running DPDK application on the same network ports.
+ - It enables the DPDK application to filter only part of the traffic,
+   while the rest will be directed and handled by the kernel driver.
+   The flow bifurcation is performed by the NIC hardware.
+   As an example, using :ref:`flow_isolated_mode` allows to choose
+   strictly what is received in DPDK.
+
+More about the bifurcated driver can be found in
+NVIDIA `bifurcated PMD
+<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`_ presentation.
+
+UIO
+---
+
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
+In situations where using VFIO is not an option, there are alternative drivers one can
+use.
+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
+can be used as a substitute for VFIO. This module can be loaded using the command:
+
+.. code-block:: console
+
+   sudo modprobe uio_pci_generic
+
+.. note::
+
+   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
+
+As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
+which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
+It can be loaded as shown below:
+
+.. code-block:: console
+
+   sudo modprobe uio
+   sudo insmod igb_uio.ko
+
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
+.. 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 any UIO-based module.
+   For more details see :ref:`linux_gsg_binding_kernel` below.
+
+.. note::
+
+   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,
+   or add ``iommu.passthrough=1`` on aarch64 systems.
\ No newline at end of file
-- 
2.41.0.windows.1

Re: [PATCH v3 5/7] Section 5: Appendix

[Bruce Richardson]

I haven't reviewed this whole file in detail, as I assume most content is
copy-pasted from existing docs and so is correct. One comment inline below,
though.

/Bruce

On Fri, Nov 03, 2023 at 12:01:51AM -0400, David Young wrote:
> ---
>  .../appendix/cross_compile_dpdk.rst           |  37 +++
>  .../appendix/dpdk_meson_build_options.rst     |  57 ++++
>  .../getting_started_guide/appendix/index.rst  |  17 +
>  .../running_dpdk_apps_without_root.rst        |  36 +++
>  .../appendix/vfio_advanced.rst                | 295 ++++++++++++++++++
>  5 files changed, 442 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
>  create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
>  create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
>  create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
>  create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst
> 
> diff --git a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> new file mode 100644
> index 0000000000..3e4efe23a4
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> @@ -0,0 +1,37 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _cross_compile_dpdk:
> +
> +Cross-compiling DPDK for Different Architectures on Linux
> +=========================================================
> +
> +Cross-compiling DPDK for different architectures follows a similar process. Here are the general steps:
> +
> +1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain and any required libraries specific to the target architecture.
> +
> +2. **Build Using Cross-File**: Use Meson to set up the build with a cross-file specific to the target architecture, and then build with Ninja.
> +
> +Prerequisites
> +-------------
> +
> +- NUMA Library (if required)
> +- Meson and Ninja
> +- pkg-config for the target architecture
> +- Specific GNU or LLVM/Clang toolchain for the target architecture
> +
> +Cross-Compiling DPDK
> +--------------------
> +
> +1. **Set Up the Cross Toolchain**: Download and extract the toolchain for the target architecture. Add it to the PATH.
> +
> +2. **Compile Any Required Libraries**: Compile libraries like NUMA if required.
> +
> +3. **Cross-Compile DPDK with Meson**:
> +
> +   .. code-block:: bash
> +
> +      meson setup cross-build --cross-file <target_machine_configuration>
> +      ninja -C cross-build
> +
> +Refer to the specific sections for ARM64, LoongArch, and RISC-V for detailed instructions and architecture-specific considerations.
> \ No newline at end of file
> diff --git a/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> new file mode 100644
> index 0000000000..6669f98371
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> @@ -0,0 +1,57 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _dpdk_meson_build_options:
> +
> +DPDK Meson Build Configuration Options
> +======================================
> +
> +DPDK provides a number of build configuration options that can be adjusted using the Meson build system. These options can be listed by running ``meson configure`` inside a configured build
> +folder.
> +
> +Changing the Build Type
> +-----------------------
> +
> +To change the build type from the default "release" to a regular "debug" build,
> +you can either:
> +
> +- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially.
> +- Run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
> +
> +Platform Options
> +----------------
> +
> +The "platform" option specifies a set of configuration parameters that will be used. 
> +The valid values are:
> +
> +- ``-Dplatform=native`` will tailor the configuration to the build machine.
> +- ``-Dplatform=generic`` will use configuration that works on all machines of the same architecture as the build machine.
> +- ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC.
> +
> +Consult the "socs" dictionary in ``config/arm/meson.build`` to see which SoCs are supported.
> +
> +Overriding Platform Parameters
> +------------------------------
> +
> +The values determined by the platform parameter may be overwritten. For example,
> +to set the ``max_lcores`` value to 256, you can either:
> +
> +- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially.
> +- Run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
> +
> +Building Sample Applications
> +----------------------------
> +
> +Some of the DPDK sample applications in the examples directory can be automatically built as
> +part of a meson build. To do so, pass a comma-separated list of the examples to build to the
> +``-Dexamples`` meson option as below::
> +
> +    meson setup -Dexamples=l2fwd,l3fwd build
> +
> +There is also a special value "all" to request that all example applications whose dependencies
> +are met on the current system are built. When ``-Dexamples=all`` is set as a meson option,
> +meson will check each example application to see if it can be built, and add all which can be
> +built to the list of tasks in the ninja build configuration file.
> +
> +For a complete list of options, run ``meson configure`` inside your configured build
> +folder.
> \ No newline at end of file
> diff --git a/doc/guides/getting_started_guide/appendix/index.rst b/doc/guides/getting_started_guide/appendix/index.rst
> new file mode 100644
> index 0000000000..23bb1fcf78
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/appendix/index.rst
> @@ -0,0 +1,17 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _appendix:
> +
> +Appendix
> +========
> +
> +This section covers specific guides related to DPDK.
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    dpdk_meson_build_options
> +    running_dpdk_apps_without_root
> +    vfio_advanced
> +    cross_compile_dpdk
> \ No newline at end of file
> diff --git a/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> new file mode 100644
> index 0000000000..9f214bbdc8
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> @@ -0,0 +1,36 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +.. _running_dpdk_apps_without_root:
> +
> +Running DPDK Applications Without Root Privileges
> +=================================================
> +
> +Although applications using the DPDK use network ports and other hardware resources
> +directly, with a number of small permission adjustments, 
> +it is possible to run these applications as a user other than “root”. 
> +To do so, the ownership, or permissions, on the following file system objects should be
> +adjusted so the user account being used to run the DPDK application has
> +access to them:
> +

The text above implies that we would just be listing a set of files to
change. For FreeBSD that is the case, but for Linux, not so much! :-)

I'd change the linux section to be a similar list of files to FreeBSD:

* VFIO entries in /dev, /dev/vfio/<id>, where id is the VFIO group to which
  a device used by DPDK belongs.
* the hugepage mount directory: /dev/hugepages on many distributions, or
  any alternative mount point configured by the user, e.g. /mnt/huge,
  /mnt/huge_1G

We also need to note that to run as non-root on linux, you need to use DPDK
with iommu support through vfio.

> +Linux
> +-----
> +
> +1. **Create a DPDK User Group**: Create a new user group for DPDK and add the desired user to this group.
> +
> +2. **Set Up Hugepages**: Configure hugepages for the user.
> +
> +3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool ``dpdk-devbind.py`` to bind the NIC to a user-space driver like ``vfio-pci`` or ``igb_uio``.
> +
> +4. **Set Permissions for UIO/VFIO Devices**: Change the ownership and permissions of the UIO or VFIO devices to allow access by the DPDK user group.
> +
> +5. **Run the DPDK Application**: Run the desired DPDK application as the user who has been added to the DPDK group.
> +
> +FreeBSD
> +-------
> +
> +- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
> +- The userspace contiguous memory device: ``/dev/contigmem``
> +
> +
> +Refer to the `DPDK Release Notes <https://doc.dpdk.org/guides/rel_notes/index.html>`_ for supported applications.

<snip for brevity>

Re: [PATCH v3 5/7] Section 5: Appendix

[Dave Young]

[-- Attachment #1: Type: text/plain, Size: 11394 bytes --]

Bruce,

Is the following Linux update correct per your feedback?

Linux
-----

To run DPDK applications without root privileges on Linux, perform the
following steps:

1. **Create a DPDK User Group**: Create a new user group for DPDK and add
the desired user to this group.

2. **Set Up Hugepages**: Configure hugepages for the user.

3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool
``dpdk-devbind.py`` to bind the NIC to a user-space driver like
``vfio-pci`` or ``igb_uio``.

4. **Adjust Permissions for Specific Files and Directories**:

   - VFIO entries in ``/dev``, such as ``/dev/vfio/<id>``, where <id> is
the VFIO group to which a device used by DPDK belongs.
   - The hugepage mount directory, typically ``/dev/hugepages`` on many
distributions, or any alternative mount point configured by the user, e.g.,
``/mnt/huge``, ``/mnt/huge_1G``.

   Note: Running DPDK as non-root on Linux requires IOMMU support through
vfio.

5. **Run the DPDK Application**: Run the desired DPDK application as the
user who has been added to the DPDK group.

FreeBSD
-------

- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``,
``/dev/uio1``, and so on
- The userspace contiguous memory device: ``/dev/contigmem``

Refer to the `DPDK Release Notes <
https://doc.dpdk.org/guides/rel_notes/index.html>`_ for supported
applications.

Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com


On Fri, Nov 3, 2023 at 11:24 AM Bruce Richardson <bruce.richardson@intel.com>
wrote:

> I haven't reviewed this whole file in detail, as I assume most content is
> copy-pasted from existing docs and so is correct. One comment inline below,
> though.
>
> /Bruce
>
> On Fri, Nov 03, 2023 at 12:01:51AM -0400, David Young wrote:
> > ---
> >  .../appendix/cross_compile_dpdk.rst           |  37 +++
> >  .../appendix/dpdk_meson_build_options.rst     |  57 ++++
> >  .../getting_started_guide/appendix/index.rst  |  17 +
> >  .../running_dpdk_apps_without_root.rst        |  36 +++
> >  .../appendix/vfio_advanced.rst                | 295 ++++++++++++++++++
> >  5 files changed, 442 insertions(+)
> >  create mode 100644
> doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> >  create mode 100644
> doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> >  create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
> >  create mode 100644
> doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> >  create mode 100644
> doc/guides/getting_started_guide/appendix/vfio_advanced.rst
> >
> > diff --git
> a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> > new file mode 100644
> > index 0000000000..3e4efe23a4
> > --- /dev/null
> > +++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
> > @@ -0,0 +1,37 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright(c) 2010-2025 Intel Corporation.
> > +
> > +.. _cross_compile_dpdk:
> > +
> > +Cross-compiling DPDK for Different Architectures on Linux
> > +=========================================================
> > +
> > +Cross-compiling DPDK for different architectures follows a similar
> process. Here are the general steps:
> > +
> > +1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain
> and any required libraries specific to the target architecture.
> > +
> > +2. **Build Using Cross-File**: Use Meson to set up the build with a
> cross-file specific to the target architecture, and then build with Ninja.
> > +
> > +Prerequisites
> > +-------------
> > +
> > +- NUMA Library (if required)
> > +- Meson and Ninja
> > +- pkg-config for the target architecture
> > +- Specific GNU or LLVM/Clang toolchain for the target architecture
> > +
> > +Cross-Compiling DPDK
> > +--------------------
> > +
> > +1. **Set Up the Cross Toolchain**: Download and extract the toolchain
> for the target architecture. Add it to the PATH.
> > +
> > +2. **Compile Any Required Libraries**: Compile libraries like NUMA if
> required.
> > +
> > +3. **Cross-Compile DPDK with Meson**:
> > +
> > +   .. code-block:: bash
> > +
> > +      meson setup cross-build --cross-file
> <target_machine_configuration>
> > +      ninja -C cross-build
> > +
> > +Refer to the specific sections for ARM64, LoongArch, and RISC-V for
> detailed instructions and architecture-specific considerations.
> > \ No newline at end of file
> > diff --git
> a/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> > new file mode 100644
> > index 0000000000..6669f98371
> > --- /dev/null
> > +++
> b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
> > @@ -0,0 +1,57 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright(c) 2010-2025 Intel Corporation.
> > +
> > +.. _dpdk_meson_build_options:
> > +
> > +DPDK Meson Build Configuration Options
> > +======================================
> > +
> > +DPDK provides a number of build configuration options that can be
> adjusted using the Meson build system. These options can be listed by
> running ``meson configure`` inside a configured build
> > +folder.
> > +
> > +Changing the Build Type
> > +-----------------------
> > +
> > +To change the build type from the default "release" to a regular
> "debug" build,
> > +you can either:
> > +
> > +- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when
> configuring the build folder initially.
> > +- Run ``meson configure -Dbuildtype=debug`` inside the build folder
> after the initial meson run.
> > +
> > +Platform Options
> > +----------------
> > +
> > +The "platform" option specifies a set of configuration parameters that
> will be used.
> > +The valid values are:
> > +
> > +- ``-Dplatform=native`` will tailor the configuration to the build
> machine.
> > +- ``-Dplatform=generic`` will use configuration that works on all
> machines of the same architecture as the build machine.
> > +- ``-Dplatform=<SoC>`` will use configuration optimized for a
> particular SoC.
> > +
> > +Consult the "socs" dictionary in ``config/arm/meson.build`` to see
> which SoCs are supported.
> > +
> > +Overriding Platform Parameters
> > +------------------------------
> > +
> > +The values determined by the platform parameter may be overwritten. For
> example,
> > +to set the ``max_lcores`` value to 256, you can either:
> > +
> > +- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder
> initially.
> > +- Run ``meson configure -Dmax_lcores=256`` inside the build folder
> after the initial meson run.
> > +
> > +Building Sample Applications
> > +----------------------------
> > +
> > +Some of the DPDK sample applications in the examples directory can be
> automatically built as
> > +part of a meson build. To do so, pass a comma-separated list of the
> examples to build to the
> > +``-Dexamples`` meson option as below::
> > +
> > +    meson setup -Dexamples=l2fwd,l3fwd build
> > +
> > +There is also a special value "all" to request that all example
> applications whose dependencies
> > +are met on the current system are built. When ``-Dexamples=all`` is set
> as a meson option,
> > +meson will check each example application to see if it can be built,
> and add all which can be
> > +built to the list of tasks in the ninja build configuration file.
> > +
> > +For a complete list of options, run ``meson configure`` inside your
> configured build
> > +folder.
> > \ No newline at end of file
> > diff --git a/doc/guides/getting_started_guide/appendix/index.rst
> b/doc/guides/getting_started_guide/appendix/index.rst
> > new file mode 100644
> > index 0000000000..23bb1fcf78
> > --- /dev/null
> > +++ b/doc/guides/getting_started_guide/appendix/index.rst
> > @@ -0,0 +1,17 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright(c) 2010-2025 Intel Corporation.
> > +
> > +.. _appendix:
> > +
> > +Appendix
> > +========
> > +
> > +This section covers specific guides related to DPDK.
> > +
> > +.. toctree::
> > +    :maxdepth: 2
> > +
> > +    dpdk_meson_build_options
> > +    running_dpdk_apps_without_root
> > +    vfio_advanced
> > +    cross_compile_dpdk
> > \ No newline at end of file
> > diff --git
> a/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> > new file mode 100644
> > index 0000000000..9f214bbdc8
> > --- /dev/null
> > +++
> b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
> > @@ -0,0 +1,36 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright(c) 2010-2025 Intel Corporation.
> > +
> > +.. _running_dpdk_apps_without_root:
> > +
> > +Running DPDK Applications Without Root Privileges
> > +=================================================
> > +
> > +Although applications using the DPDK use network ports and other
> hardware resources
> > +directly, with a number of small permission adjustments,
> > +it is possible to run these applications as a user other than “root”.
> > +To do so, the ownership, or permissions, on the following file system
> objects should be
> > +adjusted so the user account being used to run the DPDK application has
> > +access to them:
> > +
>
> The text above implies that we would just be listing a set of files to
> change. For FreeBSD that is the case, but for Linux, not so much! :-)
>
> I'd change the linux section to be a similar list of files to FreeBSD:
>
> * VFIO entries in /dev, /dev/vfio/<id>, where id is the VFIO group to which
>   a device used by DPDK belongs.
> * the hugepage mount directory: /dev/hugepages on many distributions, or
>   any alternative mount point configured by the user, e.g. /mnt/huge,
>   /mnt/huge_1G
>
> We also need to note that to run as non-root on linux, you need to use DPDK
> with iommu support through vfio.
>
> > +Linux
> > +-----
> > +
> > +1. **Create a DPDK User Group**: Create a new user group for DPDK and
> add the desired user to this group.
> > +
> > +2. **Set Up Hugepages**: Configure hugepages for the user.
> > +
> > +3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool
> ``dpdk-devbind.py`` to bind the NIC to a user-space driver like
> ``vfio-pci`` or ``igb_uio``.
> > +
> > +4. **Set Permissions for UIO/VFIO Devices**: Change the ownership and
> permissions of the UIO or VFIO devices to allow access by the DPDK user
> group.
> > +
> > +5. **Run the DPDK Application**: Run the desired DPDK application as
> the user who has been added to the DPDK group.
> > +
> > +FreeBSD
> > +-------
> > +
> > +- The userspace-io device files in ``/dev``, for example,
> ``/dev/uio0``, ``/dev/uio1``, and so on
> > +- The userspace contiguous memory device: ``/dev/contigmem``
> > +
> > +
> > +Refer to the `DPDK Release Notes <
> https://doc.dpdk.org/guides/rel_notes/index.html>`_ for supported
> applications.
>
> <snip for brevity>
>

[-- Attachment #2: Type: text/html, Size: 13209 bytes --]

Re: [PATCH v3 5/7] Section 5: Appendix

[Bruce Richardson]

On Wed, Nov 15, 2023 at 08:28:55PM -0500, Dave Young wrote:
>    Bruce,
>    Is the following Linux update correct per your feedback?
>    Linux
>    -----
>    To run DPDK applications without root privileges on Linux, perform the
>    following steps:
>    1. **Create a DPDK User Group**: Create a new user group for DPDK and
>    add the desired user to this group.
>    2. **Set Up Hugepages**: Configure hugepages for the user.
>    3. **Bind the NIC to a User-Space Driver**: Use the DPDK tool
>    ``dpdk-devbind.py`` to bind the NIC to a user-space driver like
>    ``vfio-pci`` or ``igb_uio``

These three steps don't need to be covered in the docs. We already
described elsewhere about configuring hugepages and binding the device.
Also, to run as non-root, I would expect there to be a user a/c already
available on the system that the deployer of the app wants to use.

>    4. **Adjust Permissions for Specific Files and Directories**:
> 
>       - VFIO entries in ``/dev``, such as ``/dev/vfio/<id>``, where <id>
>    is the VFIO group to which a device used by DPDK belongs.
>       - The hugepage mount directory, typically ``/dev/hugepages`` on many
>    distributions, or any alternative mount point configured by the user,
>    e.g., ``/mnt/huge``, ``/mnt/huge_1G``.
>       Note: Running DPDK as non-root on Linux requires IOMMU support
>    through vfio.

This note needs to be explicitly called out to the top of the instructions.

The list of files to change the permissions on is key. The action -
changing permissions - is common between Linux and BSD, but the specific
files to adjust will be different.

>    5. **Run the DPDK Application**: Run the desired DPDK application as
>    the user who has been added to the DPDK group.
>    FreeBSD
>    -------
>    - The userspace-io device files in ``/dev``, for example,
>    ``/dev/uio0``, ``/dev/uio1``, and so on
>    - The userspace contiguous memory device: ``/dev/contigmem``

Regards,
/Bruce

[PATCH v3 6/7] Added link to Getting Started Guide in index.rst

[David Young]

---
 doc/guides/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index 244b99624c..51a47d3a51 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -7,6 +7,7 @@ DPDK documentation
 .. toctree::
    :maxdepth: 1
 
+   getting_started_guide/index
    linux_gsg/index
    freebsd_gsg/index
    windows_gsg/index
-- 
2.41.0.windows.1

Re: [PATCH v3 6/7] Added link to Getting Started Guide in index.rst

[Bruce Richardson]

On Fri, Nov 03, 2023 at 12:01:52AM -0400, David Young wrote:
> ---
>  doc/guides/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/guides/index.rst b/doc/guides/index.rst
> index 244b99624c..51a47d3a51 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/index.rst
> @@ -7,6 +7,7 @@ DPDK documentation
>  .. toctree::
>     :maxdepth: 1
>  
> +   getting_started_guide/index
>     linux_gsg/index
>     freebsd_gsg/index
>     windows_gsg/index

Rather than having this as a separte patch, just include this change in
patch 1 of the set, so the GSG doc is getting built from the start. It
allows us to build-check each patch for issues as we apply it.

Re: [PATCH v3 6/7] Added link to Getting Started Guide in index.rst

[Bruce Richardson]

On Fri, Nov 03, 2023 at 12:01:52AM -0400, David Young wrote:
> ---
>  doc/guides/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/guides/index.rst b/doc/guides/index.rst
> index 244b99624c..51a47d3a51 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/index.rst
> @@ -7,6 +7,7 @@ DPDK documentation
>  .. toctree::
>     :maxdepth: 1
>  
> +   getting_started_guide/index

Maybe I am missing something, but what patch is getting_started_guide/index
added in? Ideally it should be added with just the intro entry in patch 1,
and then each subsequent patch adds lines to the file as we add sections.

/Bruce

Re: [PATCH v3 6/7] Added link to Getting Started Guide in index.rst

[Dave Young]

[-- Attachment #1: Type: text/plain, Size: 1037 bytes --]

I can have it added in patch 1. In the v3 patchset it's added in
0006-Added-link-to-Getting-Started-Guide-in-index.rst.patch

Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com


On Fri, Nov 3, 2023 at 10:22 AM Bruce Richardson <bruce.richardson@intel.com>
wrote:

> On Fri, Nov 03, 2023 at 12:01:52AM -0400, David Young wrote:
> > ---
> >  doc/guides/index.rst | 1 +
> >  1 file changed, 1 insertion(+)
> >
> > diff --git a/doc/guides/index.rst b/doc/guides/index.rst
> > index 244b99624c..51a47d3a51 100644
> > --- a/doc/guides/index.rst
> > +++ b/doc/guides/index.rst
> > @@ -7,6 +7,7 @@ DPDK documentation
> >  .. toctree::
> >     :maxdepth: 1
> >
> > +   getting_started_guide/index
>
> Maybe I am missing something, but what patch is getting_started_guide/index
> added in? Ideally it should be added with just the intro entry in patch 1,
> and then each subsequent patch adds lines to the file as we add sections.
>
> /Bruce
>

[-- Attachment #2: Type: text/html, Size: 1691 bytes --]

Re: [PATCH v3 6/7] Added link to Getting Started Guide in index.rst

[Dave Young]

[-- Attachment #1: Type: text/plain, Size: 1423 bytes --]

Hi Bruce,

Disregard my previous email. It looks like getting_started_guide/index was
somehow deleted but I've added it back.

Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com


On Tue, Nov 7, 2023 at 8:47 PM Dave Young <dave@youngcopy.com> wrote:

> I can have it added in patch 1. In the v3 patchset it's added in
> 0006-Added-link-to-Getting-Started-Guide-in-index.rst.patch
>
> Thanks!
> David Young
> Professional Copywriter/Technical Writer
> Young Copy
> +1 (678) 500-9550
> https://www.youngcopy.com
>
>
> On Fri, Nov 3, 2023 at 10:22 AM Bruce Richardson <
> bruce.richardson@intel.com> wrote:
>
>> On Fri, Nov 03, 2023 at 12:01:52AM -0400, David Young wrote:
>> > ---
>> >  doc/guides/index.rst | 1 +
>> >  1 file changed, 1 insertion(+)
>> >
>> > diff --git a/doc/guides/index.rst b/doc/guides/index.rst
>> > index 244b99624c..51a47d3a51 100644
>> > --- a/doc/guides/index.rst
>> > +++ b/doc/guides/index.rst
>> > @@ -7,6 +7,7 @@ DPDK documentation
>> >  .. toctree::
>> >     :maxdepth: 1
>> >
>> > +   getting_started_guide/index
>>
>> Maybe I am missing something, but what patch is
>> getting_started_guide/index
>> added in? Ideally it should be added with just the intro entry in patch 1,
>> and then each subsequent patch adds lines to the file as we add sections.
>>
>> /Bruce
>>
>

[-- Attachment #2: Type: text/html, Size: 2588 bytes --]

[PATCH v3 7/7] Section 6: Glossary

[David Young]

---
 doc/guides/getting_started_guide/glossary.rst | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/glossary.rst

diff --git a/doc/guides/getting_started_guide/glossary.rst b/doc/guides/getting_started_guide/glossary.rst
new file mode 100644
index 0000000000..7fcfe16f38
--- /dev/null
+++ b/doc/guides/getting_started_guide/glossary.rst
@@ -0,0 +1,75 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+Glossary
+========
+
+This glossary provides definitions for key terms and concepts used within DPDK. Understanding these terms will help in comprehending the functionality and architecture of DPDK.
+
+**BIOS (Basic Input/Output System)**
+
+The firmware used to perform hardware initialization during the booting process and to provide runtime services for operating systems and programs.
+
+**Bifurcated Driver**
+
+A driver model that splits functionality between kernel and userspace, often used in high-performance networking.
+
+**Clang-LLVM**
+
+A compiler toolchain that includes the Clang C compiler and LLVM linker, used for building DPDK on Windows.
+
+**contigmem Module**
+
+A module in FreeBSD that provides physically contiguous memory allocation used by DPDK.
+
+**DMA (Direct Memory Access)**
+
+A feature that allows hardware devices to access the main system memory directly, without involving the CPU.
+
+**EAL (Environment Abstraction Layer)**
+
+The layer within DPDK that abstracts environmental specifics and provides a standard programming interface.
+
+**hugepages**
+
+Large memory pages used by the operating system to manage memory more efficiently, especially in high-performance applications like DPDK.
+
+**IOMMU (Input-Output Memory Management Unit)**
+
+A hardware component that translates device-visible virtual addresses to physical addresses, providing memory protection and isolation.
+
+**MinGW-w64 Toolchain**
+
+A development environment for creating Windows applications, used as an option for compiling DPDK on Windows.
+
+**NIC (Network Interface Card)**
+
+A hardware component that connects a computer to a network.
+
+**nic_uio Module**
+
+A UIO driver for network devices in FreeBSD, used by DPDK.
+
+**NUMA (Non-Uniform Memory Access)**
+
+A computer memory design used in multiprocessing where the memory access time depends on the memory location relative to the processor.
+
+**PMD (POLL Mode Driver)**
+
+A type of driver in DPDK that continuously polls for events rather than relying on interrupts, often used for high-performance networking.
+
+**SoC (System on a Chip)**
+
+An integrated circuit that integrates all components of a computer or other electronic system into a single chip.
+
+**UIO (Userspace I/O)**
+
+A Linux kernel module that enables user-space applications to access hardware devices directly.
+
+**VFIO (Virtual Function I/O)**
+
+A kernel driver that allows a virtual machine to access physical devices directly, used in DPDK for device assignment.
+
+**VFIO Platform**
+
+A framework in Linux that allows exposing direct device access to userspace, in a secure, IOMMU-protected way.
\ No newline at end of file
-- 
2.41.0.windows.1

Re: [PATCH v3 7/7] Section 6: Glossary

[Bruce Richardson]

On Fri, Nov 03, 2023 at 12:01:53AM -0400, David Young wrote:
> ---
>  doc/guides/getting_started_guide/glossary.rst | 75 +++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/glossary.rst
> 
> diff --git a/doc/guides/getting_started_guide/glossary.rst b/doc/guides/getting_started_guide/glossary.rst
> new file mode 100644
> index 0000000000..7fcfe16f38
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/glossary.rst
> @@ -0,0 +1,75 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2025 Intel Corporation.
> +
> +Glossary
> +========

One small general comment here. For a number of these DPDK-specific terms
we should provide a cross-reference to locations in the docs for more
information. For example EAL should link to the programmers guide doc
chapter. The kernel modules for DPDK on FreeBSD should link to the GSG
chapter where we explain about their use, etc.

/Bruce

[PATCH v4 0/6] docs: getting started guide consolidation

[David Young]

This patch series introduces significant updates to the DPDK Getting Started
Guide, enhancing user accessibility and content clarity:

1-Structural Improvements:
Integrated links to the Getting Started Guide in the main index.
Relocated run_apps.rst to the GSG index and removed run_apps/index.rst.

2-Refined Introduction:
Revised the introduction for improved clarity.
Highlighted step-by-step instructions adaptable for various operating systems.

3-Installation and Build Process Updates:
Redesigned installation instructions, categorizing tools under specific Linux
distributions and FreeBSD.
Updated Windows section with intuitive navigation and refreshed DPDK building
instructions in line with the latest Meson build system.

4-Technical Enhancements:
Updated unicode representations with isonum.txt.
Refined the hugepages section with corrected information and additional guidance.
Streamlined VFIO section instructions for network port binding using dpdk-devbind.py.

5-New Additions and Content Streamlining:
Introduced a guide on hugepages for various architectures.
Focused on IOMMU support for VFIO on Linux, along with simplified FreeBSD content.
Introduced reference tags (.. _vfio_platform:, .. _bifurcated_driver:,
.. _uio:) for improved document navigation.

6-Glossary and Navigation Enhancement:
Enhanced glossary formatting for readability.
Employed structured term definitions with .. glossary:: directive.
Expanded term definitions with links to content pages and integrated hyperlinks.

David Young (6):
  Section 1: Introduction
  Section 2: Install and Build DPDK
  Section 3: Setting up a System to Run DPDK Applications
  Section 4: Running Applications
  Section 5: Appendix
  Section 6: Glossary

 .../appendix/cross_compile_dpdk.rst           |  37 +++
 .../appendix/dpdk_meson_build_options.rst     |  57 ++++
 .../hugepages_different_architectures.rst     |  56 ++++
 .../getting_started_guide/appendix/index.rst  |  18 ++
 .../running_dpdk_apps_without_root.rst        |  24 ++
 .../appendix/vfio_advanced.rst                | 301 ++++++++++++++++++
 doc/guides/getting_started_guide/glossary.rst |  78 +++++
 doc/guides/getting_started_guide/index.rst    |  18 ++
 .../building_from_sources.rst                 | 180 +++++++++++
 .../install_and_build/index.rst               |  14 +
 .../installing_prebuilt_packages.rst          |  54 ++++
 doc/guides/getting_started_guide/intro.rst    |  13 +
 doc/guides/getting_started_guide/run_apps.rst | 114 +++++++
 .../getting_started_guide/run_apps/index.rst  |  10 +
 .../run_apps/run_apps.rst                     | 118 +++++++
 .../getting_started_guide/system_setup.rst    | 197 ++++++++++++
 doc/guides/index.rst                          |   1 +
 17 files changed, 1290 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst
 create mode 100644 doc/guides/getting_started_guide/glossary.rst
 create mode 100644 doc/guides/getting_started_guide/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
 create mode 100644 doc/guides/getting_started_guide/intro.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst
 create mode 100644 doc/guides/getting_started_guide/system_setup.rst

-- 
2.41.0.windows.1

[PATCH v4 1/6] Section 1: Introduction

[David Young]

Added link to Getting Started Guide in index.rst

Moved run_apps.rst to GSG index

Removed run_apps/index.rst - no longer needed

Added run_apps.rst to index

-Reformatted the introduction paragraph for better readability.
-Clarified that the guide provides basic step-by-step instructions with OS-specific instructions
included only where necessary for each operating system.
-Emphasized that by the end of this guide, the user should have a solid understanding of how to
implement and use DPDK in their networking projects, regardless of the operating system they are using.

Moved run_apps into GSG root directory
---
 doc/guides/getting_started_guide/index.rst    |  18 +++
 doc/guides/getting_started_guide/intro.rst    |  13 ++
 doc/guides/getting_started_guide/run_apps.rst | 114 ++++++++++++++++++
 doc/guides/index.rst                          |   1 +
 4 files changed, 146 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/index.rst
 create mode 100644 doc/guides/getting_started_guide/intro.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps.rst

diff --git a/doc/guides/getting_started_guide/index.rst b/doc/guides/getting_started_guide/index.rst
new file mode 100644
index 0000000000..3d7c0eb6ee
--- /dev/null
+++ b/doc/guides/getting_started_guide/index.rst
@@ -0,0 +1,18 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _getting_started_guide:
+
+Getting Started Guide
+=====================
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    intro
+    install_and_build/index
+    system_setup
+    run_apps
+    appendix/index
+    glossary
diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst
new file mode 100644
index 0000000000..3560d705d0
--- /dev/null
+++ b/doc/guides/getting_started_guide/intro.rst
@@ -0,0 +1,13 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2014 Intel Corporation.
+
+Introduction
+============
+
+Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, 
+FreeBSD, and Windows. DPDK is a set of libraries and drivers that accelerate packet processing 
+and allow the user to create high-performance networking applications.
+
+The guide is structured to provide basic step-by-step instructions with OS-specific instructions included only where necessary for each operating system. 
+By the end of this guide, you should have a solid understanding of how to implement
+and use DPDK in your networking projects, regardless of the operating system you are using.
diff --git a/doc/guides/getting_started_guide/run_apps.rst b/doc/guides/getting_started_guide/run_apps.rst
new file mode 100644
index 0000000000..d9ef1a6f96
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps.rst
@@ -0,0 +1,114 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _run_apps:
+
+Running Applications
+====================
+
+Running Applications on Linux and FreeBSD
+-----------------------------------------
+
+Compiling and Running Sample Applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To compile a sample application:
+
+1. Navigate to the application's directory in the DPDK distribution.
+2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD.
+
+For instance, to compile the ``helloworld`` application:
+
+::
+
+    cd examples/helloworld
+    make    # On Linux
+    gmake   # On FreeBSD
+
+.. note::
+   If DPDK is not installed system-wide, 
+   you can compile the examples as part of the DPDK build itself. 
+   If DPDK is not installed system-wide, you can compile the examples as part of the DPDK build 
+   itself. Use the meson build option ``-Dexamples=helloworld`` to compile specific examples 
+   or ``-Dexamples=all`` to compile all examples.
+
+To run the application, use:
+
+::
+
+    ./build/helloworld -l 0-2
+
+The ``-l`` option indicates the cores on which the application should run.
+This command runs the `helloworld` application on cores 0, 1, and 2.
+
+Sample Applications Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For a comprehensive list of sample applications and their guides, 
+refer to the `DPDK Sample Applications User Guides <https://doc.dpdk.org/guides/sample_app_ug/index.html>`_.
+
+EAL Parameters
+--------------
+
+Every DPDK application is linked with the DPDK target environment’s 
+Environmental Abstraction Layer (EAL) library. The most essential EAL option is ``-l CORELIST``, which specifies the cores the application should run on. For example:
+
+- ``-l 1-3`` to run on 3 cores: 1, 2, and 3.
+- ``-l 8,16`` to run on 2 cores: 8 and 16.
+- ``-l 1-7,9-15`` to run on 14 cores: 1 through 7 and 9 through 15.
+
+Please refer to the `EAL parameters section <eal_parameters>` section for a more comprehensive list of options.
+
+Running Without Root Privileges
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Refer to :ref:`running_dpdk_apps_without_root`.
+
+Running Applications on Windows
+-------------------------------
+
+Running DPDK applications on Windows involves a few different steps. 
+This guide provides detailed instructions on how to run the helloworld example
+application, which can be used as a reference for running other DPDK applications.
+
+Grant Lock Pages in Memory Privilege
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use of hugepages ("large pages" in Windows terminology) requires
+``SeLockMemoryPrivilege`` for the user running an application. 
+This privilege allows the DPDK application to keep data in physical memory, 
+preventing the system from paging the data to virtual memory. 
+This can significantly improve the performance of your DPDK applications.
+
+To grant this privilege:
+
+1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter.
+2. Open Local Policies / User Rights Assignment / Lock pages in memory.
+3. Add desired users or groups to the list of grantees.
+
+The privilege is applied upon the next logon. If the privilege has been granted to the
+current user, a logoff is required before it is available. 
+More details can be found in the `Large-Page Support in MSDN <https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support>`_.
+
+Running the helloworld Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After setting up the drivers, you can run the helloworld example to verify your setup.
+Here are the steps:
+
+1. Navigate to the examples in the build directory::
+
+        cd C:\\Users\\me\\dpdk\\build\\examples
+
+2. Run the helloworld application::
+
+        dpdk-helloworld.exe -l 0-3
+
+The output should display a hello message from each core, like this:
+
+::
+
+    hello from core 1
+    hello from core 3
+    hello from core 0
+    hello from core 2
diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index 244b99624c..51a47d3a51 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -7,6 +7,7 @@ DPDK documentation
 .. toctree::
    :maxdepth: 1
 
+   getting_started_guide/index
    linux_gsg/index
    freebsd_gsg/index
    windows_gsg/index
-- 
2.41.0.windows.1

[PATCH v4 2/6] Section 2: Install and Build DPDK

[David Young]

-Common Tools for All Distributions: The common tools installation instructions for
all Linux distributions and FreeBSD have been removed. Instead,
the tools are now listed under each specific distribution.
-Linux Distributions: The Linux distributions have been restructured to include
Alpine, Debian, Ubuntu, Fedora, RedHat Enterprise Linux (RHEL), and openSUSE.
Each distribution now has its own section with specific installation commands.
-Windows: The Windows section remains largely unchanged, but the instructions for
navigating to the directory where the DPDK source code is located have been updated.
-Building DPDK: The commands for setting up and compiling with the Meson build system
have been updated for both Linux, FreeBSD, and Windows.
-Cross-Compilation Instructions: The cross-compilation instructions for
different architectures were left unchanged.
-Formatting Changes: There are several formatting changes throughout the document,
including the addition of notes and changes to the headers for better readability and organization.
---
 .../building_from_sources.rst                 | 180 ++++++++++++++++++
 .../install_and_build/index.rst               |  14 ++
 .../installing_prebuilt_packages.rst          |  54 ++++++
 3 files changed, 248 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst

diff --git a/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
new file mode 100644
index 0000000000..ab54521ac5
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
@@ -0,0 +1,180 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _building_from_sources:
+
+Building and Installing DPDK from Sources
+=========================================
+
+This chapter provides a comprehensive guide for building DPDK from sources.
+It covers the necessary steps, prerequisites, and considerations for different architectures and compilers.
+
+Required Tools
+--------------
+
+To build DPDK, you'll need the following tools:
+
+- A C compiler like ``gcc`` (version 5+) or ``clang`` (version 3.6+)
+- ``pkg-config`` or ``pkgconf``
+- Python 3.6 or later
+- ``meson`` (version 0.57.0) and ``ninja``
+- ``pyelftools`` (version 0.22+)
+
+Platform-Specific Tool Installation
+-----------------------------------
+
+Linux
+^^^^^
+
+Alpine
+""""""
+
+.. code-block:: bash
+
+   sudo apk add alpine-sdk bsd-compat-headers gcc pkg-config python3 meson ninja pyelftools numactl-dev
+
+Debian, Ubuntu, and derivatives
+"""""""""""""""""""""""""""""""
+
+.. code-block:: bash
+
+   sudo apt install build-essential gcc pkg-config python3 meson ninja pyelftools libnuma-dev
+
+Fedora and RedHat Enterprise Linux (RHEL)
+"""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: bash
+
+   sudo dnf groupinstall "Development Tools"
+   sudo dnf install gcc pkg-config python3 meson ninja python3-pyelftools numactl-devel
+
+openSUSE
+""""""""
+
+.. code-block:: bash
+
+   sudo zypper install -t pattern devel_basis
+   sudo zypper install gcc pkg-config python3 meson ninja python3-pyelftools libnuma-devel
+
+FreeBSD
+^^^^^^^
+
+.. code-block:: bash
+
+   pkg install pkgconf python3 meson ninja pyelftools
+
+.. note::
+
+   If you're using FreeBSD, make sure kernel sources are included during the FreeBSD installation.
+
+Windows System Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Building the DPDK and its applications on Windows requires one of the following
+environments:
+
+- The Clang-LLVM C compiler and Microsoft MSVC linker.
+- The MinGW-w64 toolchain (either native or cross).
+
+The Meson Build system is used to prepare the sources for compilation with the Ninja backend.
+
+.. _clang_llvm:
+
+Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+1. Install the Compiler: Download and install the Clang compiler from the 
+   `LLVM website <http://releases.llvm.org/>`_.
+
+2. Install the Linker: Download and install the Build Tools for Visual Studio from the
+   `Microsoft website <https://visualstudio.microsoft.com/downloads/>`_.
+   When installing build tools, select the “Visual C++ build tools” option and make sure
+   the Windows SDK is selected.
+
+.. _mingw_w64_toolchain:
+
+Option 2: MinGW-w64 Toolchain
+""""""""""""""""""""""""""""""
+
+1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. 
+   Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug.
+
+2. On Windows: Obtain the latest version installer from the
+   `MinGW-w64 repository <https://mingw-w64.org/doku.php>`_. 
+   Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it. 
+   Install to a folder without spaces in its name, like ``C:\MinGW``. 
+   This path is assumed for the rest of this guide.
+
+Install the Build System
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download and install the build system from the
+`Meson website <http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer>`_.
+A good option to choose is the MSI installer for both meson and ninja together.
+Required version is Meson 0.57.x (baseline).
+
+Getting the DPDK Source
+-----------------------
+
+Linux and FreeBSD
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   wget https://fast.dpdk.org/rel/dpdk-20.11.tar.xz
+   tar -xJf dpdk-20.11.tar.xz
+   cd dpdk-20.11
+
+Windows
+^^^^^^^
+
+Download the DPDK source code from `DPDK's official website <https://www.dpdk.org/>`_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory.
+
+Navigate to the directory where the DPDK source code is located:
+
+.. code-block:: bash
+
+   cd C:\path\to\dpdk-20.11
+
+Building DPDK
+-------------
+
+.. note::
+
+   In all examples below, "build" is used as the name of the build directory. It is not part of the command itself.
+
+Linux and FreeBSD
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   meson setup build
+   meson compile -C build
+
+Windows
+^^^^^^^
+
+**Option 1: Using Clang-LLVM**
+
+.. code-block:: bash
+
+   set CC=clang
+   meson setup -Dexamples=helloworld build
+   meson compile -C build
+
+**Option 2: Using MinGW-w64**
+
+.. code-block:: bash
+
+   set PATH=C:\MinGW\mingw64\bin;%PATH%
+   meson setup -Dexamples=helloworld build
+   meson compile -C build
+
+.. note::
+
+   For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`.
+
+Cross-Compilation Instructions for Different Architectures
+----------------------------------------------------------
+
+For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`.
diff --git a/doc/guides/getting_started_guide/install_and_build/index.rst b/doc/guides/getting_started_guide/install_and_build/index.rst
new file mode 100644
index 0000000000..48e438282f
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/index.rst
@@ -0,0 +1,14 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _install_and_build:
+
+Install and Build DPDK
+======================
+
+.. toctree::
+    :maxdepth: 2
+
+    
+    installing_prebuilt_packages
+    building_from_sources
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
new file mode 100644
index 0000000000..3e395d65f1
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
@@ -0,0 +1,54 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _installing_prebuilt_packages:
+
+Installing Pre-built Packages
+=============================
+
+Pre-built packages provide a convenient way to install DPDK without the need to compile
+the source code manually. These packages are created and maintained by the DPDK
+community or OS vendors and are available for various operating systems and
+distributions.
+
+Available Distributions
+-----------------------
+
+Linux
+^^^^^
+
+Pre-built DPDK packages are available for several popular Linux distributions,
+including but not limited to:
+
+Alpine
+
+.. code-block:: bash
+
+   sudo apk add dpdk
+
+Debian and Ubuntu and derivatives
+
+.. code-block:: bash
+
+   sudo apt-get install dpdk
+
+Fedora and RedHat Enterprise Linux RHEL
+
+.. code-block:: bash
+
+   sudo dnf install dpdk
+
+openSUSE
+
+.. code-block:: bash
+
+   sudo zypper install dpdk
+
+FreeBSD
+^^^^^^^
+
+To install DPDK on FreeBSD, use the following command:
+
+.. code-block:: bash
+
+   sudo pkg install dpdk
\ No newline at end of file
-- 
2.41.0.windows.1

[PATCH v4 3/6] Section 3: Setting up a System to Run DPDK Applications

[David Young]

Replaced .. |reg| unicode:: U+000AE with .. include:: <isonum.txt>
Added a reference to the section memory_setup_reserving_hugepages
-Corrected the sentence “To check if hugepages are are on your system” to
“To check if hugepages are reserved on your system”
-Updated the instructions for checking if your distribution already provides access to
hugepages via /dev/hugepages and how to manually mount the hugepages filesystem if it doesn’t
-Added a note about configuring different hugepage sizes, including 1G pages on x86
and various sizes on ARM and other architectures
-Added a reference to the section device_setup_vfio
-Simplified the instructions for binding network ports to the vfio-pci module on Linux.
The new instructions use the dpdk-devbind.py script to automatically unbind the device
from its current driver, if necessary, before binding it to vfio-pci.
---
 .../getting_started_guide/system_setup.rst    | 197 ++++++++++++++++++
 1 file changed, 197 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/system_setup.rst

diff --git a/doc/guides/getting_started_guide/system_setup.rst b/doc/guides/getting_started_guide/system_setup.rst
new file mode 100644
index 0000000000..d798ad985b
--- /dev/null
+++ b/doc/guides/getting_started_guide/system_setup.rst
@@ -0,0 +1,197 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _memory_setup:
+
+.. include:: <isonum.txt>
+
+Setting up a System to Run DPDK Applications
+============================================
+
+This section provides step-by-step instructions for setting up your system to run DPDK applications. It covers system configurations for Linux, FreeBSD, and Windows. Each section details the necessary memory and device setups for these operating systems.
+
+Navigate to the section that corresponds to your operating system to begin the setup process.
+
+.. contents:: Table of Contents
+   :local:
+
+System Setup for Linux
+----------------------
+
+.. _memory_setup_reserving_hugepages:
+
+Memory Setup: Reserving Hugepages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For Linux, DPDK requires hugepages be reserved for its use on the system. To check if hugepages are reserved on your system, you can run the following command::
+
+        grep HugePages_Total /proc/meminfo
+
+If hugepages are not reserved, you will need to reserve them by following these steps:
+
+1. Determine the number of hugepages you want to allocate. For example, to allocate 1024 hugepages of 2MB each, you can use the following command::
+
+        echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+2. To make the hugepages configuration persistent across reboots, add the following line to your `/etc/sysctl.conf` file, adjusting the number of hugepages as needed::
+
+        vm.nr_hugepages = 1024
+
+3. Check if your distribution already provides access to hugepages via /dev/hugepages. If it doesn't, you will need to manually mount the hugepages filesystem. To do this, add the following line to your /etc/fstab file::
+
+        nodev /mnt/huge hugetlbfs defaults 0 0
+
+   Then, create the mount directory and mount the filesystem::
+
+        mkdir -p /mnt/huge
+        mount -a
+
+.. note::
+   For information on configuring different hugepage sizes, including 1G pages on x86 and various sizes on ARM and other architectures, refer to :ref:`Hugepages Configuration for Multiple Architectures <hugepages_different_architectures>`.
+
+.. _device_setup_vfio:
+
+Device Setup: VFIO
+^^^^^^^^^^^^^^^^^^
+
+VFIO is a robust and secure driver that relies on IOMMU protection.
+To make use of VFIO on Linux, the ``vfio-pci`` module must be loaded:
+
+.. code-block:: console
+
+    sudo modprobe vfio-pci
+
+VFIO kernel is usually present by default in all distributions,
+however please consult your distribution's documentation to make sure that is the case.
+
+To make use of full VFIO functionality,
+both kernel and BIOS must support and be configured
+to use IO virtualization (such as Intel\ |reg| VT-d).
+
+.. note::
+
+   In most cases, specifying "iommu=on" as kernel parameter should be enough to
+   configure the Linux kernel to use IOMMU.
+
+For proper operation of VFIO when running DPDK applications as a non-privileged user,
+correct permissions should also be set up.
+For more information, refer to :ref:`running_dpdk_apps_without_root`.
+
+Refer to :ref:`vfio_no_iommu_mode` when there is no IOMMU available on the system.
+
+Binding Network Ports to VFIO-PCI Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To bind network ports to the `vfio-pci` module on Linux, use the `dpdk-devbind.py` script with the following command. This script will automatically unbind the device from its current driver, if necessary, before binding it to `vfio-pci`.
+
+.. code-block:: bash
+
+    sudo dpdk-devbind.py -b vfio-pci <pci_id>
+
+Replace ``<pci_id>`` with the PCI device identifier of the network port. For example:
+
+.. code-block:: bash
+
+    # Example for a network port with PCI ID 01:00.0
+    sudo dpdk-devbind.py -b vfio-pci 01:00.0
+
+System Setup for FreeBSD
+------------------------
+
+.. _loading_contigmem_module:
+
+Memory Setup: Loading the DPDK contigmem Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run a DPDK application on FreeBSD, physically contiguous memory is required. In the absence of non-transparent superpages, the included sources for the `contigmem` kernel module provides the ability to present contiguous blocks of memory for the DPDK to use. 
+The ``contigmem`` module must be loaded into the running kernel before any DPDK application is run.
+Once DPDK is installed on the system, the module can be found in the ``/boot/modules``
+directory.
+
+The amount of physically contiguous memory along with the number of physically
+contiguous blocks to be reserved by the module can be set at runtime prior to module
+loading using::
+
+    kenv hw.contigmem.num_buffers=n
+    kenv hw.contigmem.buffer_size=m
+
+The kernel environment variables can also be specified during boot by placing the
+following in ``/boot/loader.conf``::
+
+    hw.contigmem.num_buffers=n
+    hw.contigmem.buffer_size=m
+
+The variables can be inspected using the following command::
+
+    sysctl -a hw.contigmem
+
+The module can then be loaded using ``kldload``::
+
+    cd /boot/modules
+    kldload contigmem
+
+.. _nic_uio_module:
+
+Device Setup: Loading the DPDK nic_uio Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After :ref:`loading_contigmem_module` on FreeBSD, the ``nic_uio`` module must be loaded into the running kernel before running any DPDK application.
+
+**Manual Loading:**
+   To load the module manually, execute the following command:
+
+   .. code-block:: bash
+
+       cd /boot/modules
+       kldload nic_uio
+
+**Automatic Loading at System Startup:**
+   For the module to be automatically loaded at system startup, add this line to `/boot/loader.conf`:
+
+   .. code-block:: text
+
+       nic_uio_load="YES"
+
+This configuration step allows the system to automatically load the `nic_uio` module during the boot process. Additionally, to bind specific network ports to the `nic_uio` module, set the `hw.nic_uio.bdfs` variable in the `/boot/loader.conf` file. Use a comma-separated list of PCI device identifiers for the network ports without any whitespace. For example:
+
+.. code-block:: text
+
+    hw.nic_uio.bdfs="2:0:0,2:0:1"
+
+Binding and Unbinding Network Ports to/from nic_uio Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the original driver for a network port has been compiled into the kernel, 
+it is necessary to reboot FreeBSD to restore the original device binding. 
+Before doing so, update or remove the ``hw.nic_uio.bdfs`` in ``/boot/loader.conf``.
+
+If rebinding to a driver that is a loadable module, the network port binding can be
+reset without rebooting. To do so, unload both the target kernel module and the
+``nic_uio`` module, modify or clear the ``hw.nic_uio.bdfs`` kernel environment
+(``kenv``) value, and reload the two drivers - first the original kernel driver,
+and then the ``nic_uio`` driver.
+
+Example commands to perform these steps are shown below::
+
+    kldunload nic_uio
+    kldunload <original_driver>
+    kenv -u hw.nic_uio.bdfs
+    kldload <original_driver>
+    kldload nic_uio  # optional
+
+System Setup for Windows
+------------------------
+
+Memory Setup: Installing Windows Modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before running DPDK applications on Windows, certain kernel-mode drivers must be installed. Note that these drivers are not signed, so you'll need to disable signature enforcement. However, be cautious as this can weaken your OS security and is generally not recommended in production environments.
+
+Device Setup: Install Drivers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To run DPDK applications on Windows, you'll need to install specific kernel-mode drivers:
+
+- **virt2phys**: This driver is essential for providing access to physical addresses and is mandatory for allocating physically-contiguous memory, which is required by hardware PMDs. Once loaded successfully, this driver will appear in the Device Manager as ``Virtual to physical address translator device`` under the Kernel bypass category. If DPDK cannot communicate with the driver, a warning will be printed during initialization.
+
+- **NetUIO**: This driver provides access to device hardware resources and is mandatory for all hardware PMDs, except for the mlx5 PMD. Devices supported by NetUIO are listed in ``netuio.inf``. You can extend this list to try running DPDK with new devices.
-- 
2.41.0.windows.1

[PATCH v4 4/6] Section 4: Running Applications

[David Young]

---
 .../getting_started_guide/run_apps/index.rst  |  10 ++
 .../run_apps/run_apps.rst                     | 118 ++++++++++++++++++
 2 files changed, 128 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst

diff --git a/doc/guides/getting_started_guide/run_apps/index.rst b/doc/guides/getting_started_guide/run_apps/index.rst
new file mode 100644
index 0000000000..f033cac5f0
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps/index.rst
@@ -0,0 +1,10 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+Running Applications
+====================
+
+.. toctree::
+    :maxdepth: 2
+
+    run_apps
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/run_apps/run_apps.rst b/doc/guides/getting_started_guide/run_apps/run_apps.rst
new file mode 100644
index 0000000000..339d4c0a68
--- /dev/null
+++ b/doc/guides/getting_started_guide/run_apps/run_apps.rst
@@ -0,0 +1,118 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _run_apps:
+
+Running Applications
+====================
+
+The following instructions apply to Linux, FreeBSD, and Windows.
+
+.. contents:: Table of Contents
+   :local:
+
+Running Applications on Linux and FreeBSD
+-----------------------------------------
+
+Compiling and Running Sample Applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To compile a sample application:
+
+1. Navigate to the application's directory in the DPDK distribution.
+2. Execute the ``make`` command on Linux or ``gmake`` on FreeBSD.
+
+For instance, to compile the ``helloworld`` application:
+
+::
+
+    cd examples/helloworld
+    make    # On Linux
+    gmake   # On FreeBSD
+
+To run the application, use:
+
+::
+
+    ./build/helloworld -l 0-2
+
+The ``-l`` option indicates the cores on which the application should run.
+
+Sample Applications Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Hello World**: A basic application that prints a "hello world" message.
+2. **Basic Forwarding**: A skeleton example of a forwarding application.
+3. **Command Line**: Demonstrates the command line interface in DPDK.
+4. **Ethtool**: Showcases the Ethtool API in DPDK.
+
+For a comprehensive list of sample applications and their guides, 
+refer to the `DPDK Sample Applications User Guides <https://doc.dpdk.org/guides/sample_app_ug/index.html>`_.
+
+EAL Parameters
+^^^^^^^^^^^^^^
+
+Every DPDK application is linked with the DPDK target environment’s 
+Environmental Abstraction Layer (EAL) library, which provides generic options. 
+Some of these options include:
+
+- ``-c COREMASK`` or ``-l CORELIST``: Specifies the cores to run on.
+- ``-n NUM``: Number of memory channels per processor socket.
+- ``--socket-mem``: Memory allocation from hugepages on specific sockets.
+
+For a detailed list of EAL options, 
+refer to the `EAL parameters section <eal_parameters>`.
+
+Running Without Root Privileges
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Refer to :ref:`running_dpdk_apps_without_root`.
+
+Running Applications on Windows
+-------------------------------
+
+Running DPDK applications on Windows involves a few different steps. 
+This guide provides detailed instructions on how to run the helloworld example
+application, which can be used as a reference for running other DPDK applications.
+
+Grant Lock Pages in Memory Privilege
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use of hugepages ("large pages" in Windows terminology) requires
+``SeLockMemoryPrivilege`` for the user running an application. 
+This privilege allows the DPDK application to keep data in physical memory, 
+preventing the system from paging the data to virtual memory. 
+This can significantly improve the performance of your DPDK applications.
+
+To grant this privilege:
+
+1. Open Local Security Policy snap-in, either through Control Panel / Computer Management / Local Security Policy, or by pressing Win+R, typing ``secpol``, and pressing Enter.
+2. Open Local Policies / User Rights Assignment / Lock pages in memory.
+3. Add desired users or groups to the list of grantees.
+
+The privilege is applied upon the next logon. If the privilege has been granted to the
+current user, a logoff is required before it is available. 
+More details can be found in the `Large-Page Support in MSDN <https://docs.microsoft.com/en-us/windows/win32/memory/large-page-support>`_.
+
+Running the helloworld Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After setting up the drivers, you can run the helloworld example to verify your setup.
+Here are the steps:
+
+1. Navigate to the examples in the build directory::
+
+        cd C:\\Users\\me\\dpdk\\build\\examples
+
+2. Run the helloworld application::
+
+        dpdk-helloworld.exe -l 0-3
+
+The output should display a hello message from each core, like this:
+
+::
+
+    hello from core 1
+    hello from core 3
+    hello from core 0
+    hello from core 2
-- 
2.41.0.windows.1

[PATCH v4 5/6] Section 5: Appendix

[David Young]

Added new guide on hugepages for different architectures

Added hugepages_different_architectures to index

-Content Streamlining: Removed initial detailed instructions on setting up DPDK
for non-root users.
Emphasized that running DPDK as non-root on Linux requires IOMMU support through vfio.
-Linux Section Updates: Simplified the section to focus on:
Adjusting permissions for VFIO entries in /dev and hugepage mount directories.
Running DPDK applications as a user in the DPDK group.
-FreeBSD Section Updates:
Streamlined content to specify adjusting permissions for:
Userspace-io device files in /dev, such as /dev/uio0, /dev/uio1, etc.
The userspace contiguous memory device: /dev/contigmem.
-Removed Sections: Detailed steps for creating user groups, binding NICs,
and setting up hugepages were removed.
-Overall Impact: The page now focuses more on the prerequisites for
running DPDK applications without root privileges, specifically for Linux and FreeBSD,
with less emphasis on detailed procedural steps.

-Added a reference tag `.. _vfio_platform:` at the start of the VFIO Platform section.
-Inserted a reference tag `.. _bifurcated_driver:` at the beginning of the Bifurcated Driver section.
-Appended a reference tag `.. _uio:` to the UIO section.
---
 .../appendix/cross_compile_dpdk.rst           |  37 +++
 .../appendix/dpdk_meson_build_options.rst     |  57 ++++
 .../hugepages_different_architectures.rst     |  56 ++++
 .../getting_started_guide/appendix/index.rst  |  18 ++
 .../running_dpdk_apps_without_root.rst        |  24 ++
 .../appendix/vfio_advanced.rst                | 301 ++++++++++++++++++
 6 files changed, 493 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst

diff --git a/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
new file mode 100644
index 0000000000..3e4efe23a4
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
@@ -0,0 +1,37 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _cross_compile_dpdk:
+
+Cross-compiling DPDK for Different Architectures on Linux
+=========================================================
+
+Cross-compiling DPDK for different architectures follows a similar process. Here are the general steps:
+
+1. **Get Compiler and Libraries**: Obtain the cross-compiler toolchain and any required libraries specific to the target architecture.
+
+2. **Build Using Cross-File**: Use Meson to set up the build with a cross-file specific to the target architecture, and then build with Ninja.
+
+Prerequisites
+-------------
+
+- NUMA Library (if required)
+- Meson and Ninja
+- pkg-config for the target architecture
+- Specific GNU or LLVM/Clang toolchain for the target architecture
+
+Cross-Compiling DPDK
+--------------------
+
+1. **Set Up the Cross Toolchain**: Download and extract the toolchain for the target architecture. Add it to the PATH.
+
+2. **Compile Any Required Libraries**: Compile libraries like NUMA if required.
+
+3. **Cross-Compile DPDK with Meson**:
+
+   .. code-block:: bash
+
+      meson setup cross-build --cross-file <target_machine_configuration>
+      ninja -C cross-build
+
+Refer to the specific sections for ARM64, LoongArch, and RISC-V for detailed instructions and architecture-specific considerations.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
new file mode 100644
index 0000000000..6669f98371
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
@@ -0,0 +1,57 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _dpdk_meson_build_options:
+
+DPDK Meson Build Configuration Options
+======================================
+
+DPDK provides a number of build configuration options that can be adjusted using the Meson build system. These options can be listed by running ``meson configure`` inside a configured build
+folder.
+
+Changing the Build Type
+-----------------------
+
+To change the build type from the default "release" to a regular "debug" build,
+you can either:
+
+- Pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially.
+- Run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
+
+Platform Options
+----------------
+
+The "platform" option specifies a set of configuration parameters that will be used. 
+The valid values are:
+
+- ``-Dplatform=native`` will tailor the configuration to the build machine.
+- ``-Dplatform=generic`` will use configuration that works on all machines of the same architecture as the build machine.
+- ``-Dplatform=<SoC>`` will use configuration optimized for a particular SoC.
+
+Consult the "socs" dictionary in ``config/arm/meson.build`` to see which SoCs are supported.
+
+Overriding Platform Parameters
+------------------------------
+
+The values determined by the platform parameter may be overwritten. For example,
+to set the ``max_lcores`` value to 256, you can either:
+
+- Pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially.
+- Run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
+
+Building Sample Applications
+----------------------------
+
+Some of the DPDK sample applications in the examples directory can be automatically built as
+part of a meson build. To do so, pass a comma-separated list of the examples to build to the
+``-Dexamples`` meson option as below::
+
+    meson setup -Dexamples=l2fwd,l3fwd build
+
+There is also a special value "all" to request that all example applications whose dependencies
+are met on the current system are built. When ``-Dexamples=all`` is set as a meson option,
+meson will check each example application to see if it can be built, and add all which can be
+built to the list of tasks in the ninja build configuration file.
+
+For a complete list of options, run ``meson configure`` inside your configured build
+folder.
\ No newline at end of file
diff --git a/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst
new file mode 100644
index 0000000000..a93904fc49
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/hugepages_different_architectures.rst
@@ -0,0 +1,56 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _hugepages_different_architectures:
+
+Hugepages Configuration for Multiple Architectures
+==================================================
+
+This section outlines the steps for configuring hugepages of various sizes on different architectures, an important aspect for optimizing DPDK performance.
+
+Hugepages on x86 Architecture
+-----------------------------
+
+**2MB and 1G Hugepages**
+
+- *2MB hugepages* are commonly used on x86.
+- *1G hugepages* can improve performance for large-memory applications.
+
+**Configuring 1G Hugepages**
+
+.. code-block:: bash
+
+    # Example GRUB configuration for 1G hugepages
+    GRUB_CMDLINE_LINUX="default_hugepagesz=1G hugepagesz=1G hugepages=4"
+
+Update GRUB and reboot after making these changes.
+
+Hugepages on ARM Architecture
+-----------------------------
+
+ARM supports a range of hugepage sizes, such as 64KB, 512KB, and 2MB.
+
+**Example Configuration**
+
+.. code-block:: bash
+
+    # Setting 2MB hugepages on ARM
+    echo N > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+Replace 'N' with the number of pages needed.
+
+Other Architectures
+-------------------
+
+Refer to architecture-specific documentation for hugepage configurations on platforms like PowerPC or MIPS.
+
+Boot-Time Reservation of Hugepages
+----------------------------------
+
+Boot-time reservation is essential for large hugepage sizes. Modify the boot loader, such as GRUB, for this purpose:
+
+.. code-block:: bash
+
+    GRUB_CMDLINE_LINUX="hugepagesz=2M hugepages=512"
+
+Regenerate the GRUB config and reboot your system.
diff --git a/doc/guides/getting_started_guide/appendix/index.rst b/doc/guides/getting_started_guide/appendix/index.rst
new file mode 100644
index 0000000000..b92e3afb5a
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/index.rst
@@ -0,0 +1,18 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _appendix:
+
+Appendix
+========
+
+This section covers specific guides related to DPDK.
+
+.. toctree::
+    :maxdepth: 2
+
+    dpdk_meson_build_options
+    hugepages_different_architectures
+    running_dpdk_apps_without_root
+    vfio_advanced
+    cross_compile_dpdk
diff --git a/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
new file mode 100644
index 0000000000..50cead324e
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
@@ -0,0 +1,24 @@
+.. _running_dpdk_apps_without_root:
+
+Running DPDK Applications Without Root Privileges
+=================================================
+
+It's important to note that running DPDK as non-root on Linux requires IOMMU support through vfio.
+
+Linux
+-----
+To run DPDK applications without root privileges on Linux, follow these steps:
+
+1. **Adjust Permissions for Specific Files and Directories**:
+
+   - VFIO entries in ``/dev``, such as ``/dev/vfio/<id>``, where ``<id>`` is the VFIO group to which a device used by DPDK belongs.
+   - The hugepage mount directory, typically ``/dev/hugepages``, or any alternative mount point configured by the user, e.g., ``/mnt/huge``, ``/mnt/huge_1G``.
+
+2. **Run the DPDK Application**: Execute the desired DPDK application as the user who has been added to the DPDK group.
+
+FreeBSD
+-------
+Adjust the permissions of the following files to run DPDK applications as a non-root user:
+
+- The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on.
+- The userspace contiguous memory device: ``/dev/contigmem``.
diff --git a/doc/guides/getting_started_guide/appendix/vfio_advanced.rst b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst
new file mode 100644
index 0000000000..35d9e783bf
--- /dev/null
+++ b/doc/guides/getting_started_guide/appendix/vfio_advanced.rst
@@ -0,0 +1,301 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+.. _vfio_advanced:
+
+.. |reg| unicode:: U+000AE
+
+VFIO Advanced
+=============
+
+
+.. contents:: Table of Contents
+   :local:
+
+.. _vfio_no_iommu_mode:
+
+VFIO no-IOMMU mode
+------------------
+
+If there is no IOMMU available on the system, VFIO can still be used,
+but it has to be loaded with an additional module parameter:
+
+.. code-block:: console
+
+   modprobe vfio enable_unsafe_noiommu_mode=1
+
+Alternatively, one can also enable this option in an already loaded kernel module:
+
+.. code-block:: console
+
+   echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
+
+After that, VFIO can be used with hardware devices as usual.
+
+.. note::
+
+   It may be required to unload all VFIO related-modules before probing
+   the module again with ``enable_unsafe_noiommu_mode=1`` parameter.
+
+.. warning::
+
+   Since no-IOMMU mode    forgoes IOMMU protection, it is inherently unsafe.
+   That said, it does make it possible for the user
+   to keep the degree of device access and programming that VFIO has,
+   in situations where IOMMU is not available.
+
+VFIO Memory Mapping Limits
+--------------------------
+
+For DMA mapping of either external memory or hugepages, VFIO interface is used.
+VFIO does not support partial unmap of once mapped memory. Hence DPDK's memory is
+mapped in hugepage granularity or system page granularity. Number of DMA
+mappings is limited by kernel with user locked memory limit of a process (rlimit)
+for system/hugepage memory. Another per-container overall limit applicable both
+for external memory and system memory was added in kernel 5.1 defined by
+VFIO module parameter ``dma_entry_limit`` with a default value of 64K.
+When application is out of DMA entries, these limits need to be adjusted to
+increase the allowed limit.
+
+Creating Virtual Functions using vfio-pci
+-----------------------------------------
+
+Since Linux version 5.7,
+the ``vfio-pci`` module supports the creation of virtual functions.
+After the PF is bound to ``vfio-pci`` module,
+the user can create the VFs using the ``sysfs`` interface,
+and these VFs will be bound to ``vfio-pci`` module automatically.
+
+When the PF is bound to ``vfio-pci``,
+by default it will have a randomly generated VF token.
+For security reasons, this token is write only,
+so the user cannot read it from the kernel directly.
+To access the VFs, the user needs to create a new token,
+and use it to initialize both VF and PF devices.
+The tokens are in UUID format,
+so any UUID generation tool can be used to create a new token.
+
+This VF token can be passed to DPDK by using EAL parameter ``--vfio-vf-token``.
+The token will be used for all PF and VF ports within the application.
+
+#. Generate the VF token by uuid command
+
+   .. code-block:: console
+
+      14d63f20-8445-11ea-8900-1f9ce7d5650d
+
+#. Load the ``vfio-pci`` module with ``enable_sriov`` parameter set
+
+   .. code-block:: console
+
+      sudo modprobe vfio-pci enable_sriov=1
+
+   Alternatively, pass the ``enable_sriov`` parameter through the ``sysfs`` if the    module is already loaded or is built-in:
+
+   .. code-block:: console
+
+      echo 1 | sudo tee /sys/module/vfio_pci/parameters/enable_sriov
+
+#. Bind the PCI devices to ``vfio-pci`` driver
+
+   .. code-block:: console
+
+      ./usertools/dpdk-devbind.py -b vfio-pci 0000:86:00.0
+
+#. Create the desired number of VF devices
+
+   .. code-block:: console
+
+      echo 2 > /sys/bus/pci/devices/0000:86:00.0/sriov_numvfs
+
+#. Start the DPDK application that will manage the PF device
+
+   .. code-block:: console
+
+      <build_dir>/app/dpdk-testpmd -l 22-25 -n 4 -a 86:00.0 \
+      --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=pf -- -i
+
+#. Start the DPDK application that will manage the VF device
+
+   .. code-block:: console
+
+      <build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -a 86:02.0 \
+      --vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i
+
+.. note::
+
+   Linux versions earlier than version 5.7 do not support the creation of
+   virtual functions within the VFIO framework.
+
+Troubleshooting VFIO
+--------------------
+
+In certain situations, using ``dpdk-devbind.py`` script
+to bind a device to VFIO driver may fail.
+The first place to check is the kernel messages:
+
+.. code-block:: console
+
+   dmesg | tail
+   ...
+   [ 1297.875090] vfio-pci: probe of 0000:31:00.0 failed with error -22
+   ...
+
+In most cases, the ``error -22`` indicates that the VFIO subsystem
+could not be enabled because there is no IOMMU support.
+
+To check whether the kernel has been booted with correct parameters,
+one can check the kernel command-line:
+
+.. code-block:: console
+
+   cat /proc/cmdline
+
+Please refer to earlier sections on how to configure kernel parameters
+correctly for your system.
+
+If the kernel is configured correctly, one also has to make sure that
+the BIOS configuration has virtualization features (such as Intel\ |reg| VT-d).
+There is no standard way to check if the platform is configured correctly,
+so please check with your platform documentation to see if it has such features,
+and how to enable them.
+
+In certain distributions, default kernel configuration is such that
+the no-IOMMU mode is disabled altogether at compile time.
+This can be checked in the boot configuration of your system:
+
+.. code-block:: console
+
+   cat /boot/config-$(uname -r) | grep NOIOMMU
+   # CONFIG_VFIO_NOIOMMU is not set
+
+If ``CONFIG_VFIO_NOIOMMU`` is not enabled in the kernel configuration,
+VFIO driver will not support the no-IOMMU mode,
+and other alternatives (such as UIO drivers) will have to be used.
+
+.. _vfio_platform:
+
+VFIO Platform
+-------------
+
+VFIO Platform is a kernel driver that extends capabilities of VFIO
+by adding support for platform devices that reside behind an IOMMU.
+Linux usually learns about platform devices directly from device tree
+during boot-up phase,
+unlike for example, PCI devices which have necessary information built-in.
+
+To make use of VFIO platform, the ``vfio-platform`` module must be loaded first:
+
+.. code-block:: console
+
+   sudo modprobe vfio-platform
+
+.. note::
+
+   By default ``vfio-platform`` assumes that platform device has dedicated reset driver.
+   If such driver is missing or device does not require one,
+   this option can be turned off by setting ``reset_required=0`` module parameter.
+
+Afterwards platform device needs to be bound to ``vfio-platform``.
+This is standard procedure requiring two steps.
+First ``driver_override``, which is available inside platform device directory,
+needs to be set to ``vfio-platform``:
+
+.. code-block:: console
+
+   sudo echo vfio-platform > /sys/bus/platform/devices/DEV/driver_override
+
+Next ``DEV`` device must be bound to ``vfio-platform`` driver:
+
+.. code-block:: console
+
+   sudo echo DEV > /sys/bus/platform/drivers/vfio-platform/bind
+
+On application startup, DPDK platform bus driver scans ``/sys/bus/platform/devices``
+searching for devices that have ``driver`` symbolic link
+pointing to ``vfio-platform`` driver.
+Finally, scanned devices are matched against available PMDs.
+Matching is    successful if either PMD name or PMD alias matches kernel driver name
+or PMD name matches platform device name, all in that order.
+
+VFIO Platform depends on ARM/ARM64 and is usually enabled on distributions
+running on these systems.
+Consult your distributions documentation to make sure that is the case.
+
+.. _bifurcated_driver:
+
+Bifurcated Driver
+-----------------
+
+PMDs which use the bifurcated driver co-exists with the device kernel driver.
+On such model the NIC is controlled by the kernel, while the data
+path is performed by the PMD directly on top of the device.
+
+Such model has the following benefits:
+
+ - It is secure and robust, as the memory management and isolation
+   is done by the kernel.
+ - It enables the user to use legacy linux tools such as ``ethtool`` or
+   ``ifconfig`` while running DPDK application on the same network ports.
+ - It enables the DPDK application to filter only part of the traffic,
+   while the rest will be directed and handled by the kernel driver.
+   The flow bifurcation is performed by the NIC hardware.
+   As an example, using :ref:`flow_isolated_mode` allows to choose
+   strictly what is received in DPDK.
+
+More about the bifurcated driver can be found in
+NVIDIA `bifurcated PMD
+<https://www.dpdk.org/wp-content/uploads/sites/35/2016/10/Day02-Session04-RonyEfraim-Userspace2016.pdf>`_ presentation.
+
+.. _uio:
+
+UIO
+---
+
+.. warning::
+
+   Using UIO drivers is inherently unsafe due to this method lacking IOMMU protection,
+   and can only be done by root user.
+
+In situations where using VFIO is not an option, there are alternative drivers one can
+use.
+In many cases, the standard ``uio_pci_generic`` module included in the Linux kernel
+can be used as a substitute for VFIO. This module can be loaded using the command:
+
+.. code-block:: console
+
+   sudo modprobe uio_pci_generic
+
+.. note::
+
+   ``uio_pci_generic`` module doesn't support the creation of virtual functions.
+
+As an alternative to the ``uio_pci_generic``, there is the ``igb_uio`` module
+which can be found in the repository `dpdk-kmods <http://git.dpdk.org/dpdk-kmods>`_.
+It can be loaded as shown below:
+
+.. code-block:: console
+
+   sudo modprobe uio
+   sudo insmod igb_uio.ko
+
+.. note::
+
+    For some devices which lack support for legacy interrupts, e.g. virtual function
+    (VF) devices, the ``igb_uio`` module may be needed in place of ``uio_pci_generic``.
+
+.. 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 any UIO-based module.
+   For more details see :ref:`linux_gsg_binding_kernel` below.
+
+.. note::
+
+   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,
+   or add ``iommu.passthrough=1`` on aarch64 systems.
-- 
2.41.0.windows.1

[PATCH v4 6/6] Section 6: Glossary

[David Young]

-Glossary Introduction Formatting: Refined the introduction's formatting for clarity.
-Directive Implementation: Used .. glossary:: directive for structured term definitions.
-Term Definitions and Linking: Expanded definitions for terms like BIOS,
Bifurcated Driver, Clang-LLVM, etc., with reference tags and links to their respective
content pages.
Enhanced Navigation: Integrated hyperlinks for each term, directing to detailed information 
on content pages.
---
 doc/guides/getting_started_guide/glossary.rst | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/glossary.rst

diff --git a/doc/guides/getting_started_guide/glossary.rst b/doc/guides/getting_started_guide/glossary.rst
new file mode 100644
index 0000000000..29e3f041ba
--- /dev/null
+++ b/doc/guides/getting_started_guide/glossary.rst
@@ -0,0 +1,78 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2025 Intel Corporation.
+
+Glossary
+========
+
+This glossary provides definitions for key terms and concepts used within DPDK. Understanding 
+these terms will help in comprehending the functionality and architecture of DPDK.
+
+.. glossary::
+
+    BIOS (Basic Input/Output System)
+
+        The firmware used to perform hardware initialization during the booting process and to provide runtime services for operating systems and programs.
+
+    :ref:`Bifurcated Driver <bifurcated_driver>`
+
+        A driver model that splits functionality between kernel and userspace, often used in high-performance networking.
+
+    :ref:`Clang-LLVM <clang_llvm>`
+
+        A compiler toolchain that includes the Clang C compiler and LLVM linker, used for building DPDK on Windows.
+
+    :ref:`contigmem Module <loading_contigmem_module>`
+
+        A module in FreeBSD that provides physically contiguous memory allocation used by DPDK.
+
+    :ref:`DMA (Direct Memory Access) <direct_memory_access_dma>`
+
+        A feature that allows hardware devices to access the main system memory directly, without involving the CPU.
+
+    :ref:`EAL (Environment Abstraction Layer) <Environment_Abstraction_Layer>`
+
+        The layer within DPDK that abstracts environmental specifics and provides a standard programming interface.
+
+    :ref:`hugepages <memory_setup_reserving_hugepages>`
+
+        Large memory pages used by the operating system to manage memory more efficiently, especially in high-performance applications like DPDK.
+
+    IOMMU (Input-Output Memory Management Unit)
+
+        A hardware component that translates device-visible virtual addresses to physical addresses, providing memory protection and isolation.
+
+    :ref:`MinGW-w64 Toolchain <mingw_w64_toolchain>`
+
+        A development environment for creating Windows applications, used as an option for compiling DPDK on Windows.
+
+    NIC (Network Interface Card)
+
+        A hardware component that connects a computer to a network.
+
+    :ref:`nic_uio Module <nic_uio_module>`
+
+        A UIO driver for network devices in FreeBSD, used by DPDK.
+
+    NUMA (Non-Uniform Memory Access)
+
+        A computer memory design used in multiprocessing where the memory access time depends on the memory location relative to the processor.
+
+    PMD (POLL Mode Driver)
+
+        A type of driver in DPDK that continuously polls for events rather than relying on interrupts, often used for high-performance networking.
+
+    SoC (System on a Chip)
+
+        An integrated circuit that integrates all components of a computer or other electronic system into a single chip.
+
+    :ref:`UIO (Userspace I/O) <uio>`
+
+        A Linux kernel module that enables user-space applications to access hardware devices directly.
+
+    :ref:`VFIO (Virtual Function I/O) <device_setup_vfio>`
+
+        A kernel driver that allows a virtual machine to access physical devices directly, used in DPDK for device assignment.
+
+    :ref:`VFIO Platform <vfio_platform>`
+
+        A framework in Linux that allows exposing direct device access to userspace, in a secure, IOMMU-protected way.
-- 
2.41.0.windows.1

Re: [PATCH v4 0/6] docs: getting started guide consolidation

[Thomas Monjalon]

23/11/2023 02:26, David Young:
>  .../appendix/cross_compile_dpdk.rst           |  37 +++
>  .../appendix/dpdk_meson_build_options.rst     |  57 ++++
>  .../hugepages_different_architectures.rst     |  56 ++++
>  .../getting_started_guide/appendix/index.rst  |  18 ++
>  .../running_dpdk_apps_without_root.rst        |  24 ++
>  .../appendix/vfio_advanced.rst                | 301 ++++++++++++++++++
>  doc/guides/getting_started_guide/glossary.rst |  78 +++++
>  doc/guides/getting_started_guide/index.rst    |  18 ++
>  .../building_from_sources.rst                 | 180 +++++++++++
>  .../install_and_build/index.rst               |  14 +
>  .../installing_prebuilt_packages.rst          |  54 ++++
>  doc/guides/getting_started_guide/intro.rst    |  13 +
>  doc/guides/getting_started_guide/run_apps.rst | 114 +++++++
>  .../getting_started_guide/run_apps/index.rst  |  10 +
>  .../run_apps/run_apps.rst                     | 118 +++++++
>  .../getting_started_guide/system_setup.rst    | 197 ++++++++++++
>  doc/guides/index.rst                          |   1 +
>  17 files changed, 1290 insertions(+)

I suppose we should also remove the old guide at the same time, isn't it?