* [PATCH 1/6] Section 1: Introduction
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:30 ` Ferruh Yigit
2023-09-20 15:48 ` [PATCH 2/6] Section 2: Install and Build DPDK David Young
` (7 subsequent siblings)
8 siblings, 1 reply; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, David Young
---
doc/guides/getting_started_guide/intro.rst | 16 ++++++++++++++++
1 file changed, 16 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..88bdd48849
--- /dev/null
+++ b/doc/guides/getting_started_guide/intro.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
+
+Introduction
+============
+
+Welcome to the unified 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.
+
+We hope this guide serves as a valuable resource as you explore the powerful
+capabilities of DPDK.
\ No newline at end of file
--
2.41.0.windows.1
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 1/6] Section 1: Introduction
2023-09-20 15:48 ` [PATCH 1/6] Section 1: Introduction David Young
@ 2023-09-25 11:30 ` Ferruh Yigit
2023-10-11 18:26 ` Dave Young
0 siblings, 1 reply; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:30 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, David Young wrote:
> ---
> doc/guides/getting_started_guide/intro.rst | 16 ++++++++++++++++
> 1 file changed, 16 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..88bdd48849
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/intro.rst
> @@ -0,0 +1,16 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> + Copyright(c) 2010-2014 Intel Corporation.
> +
> +Introduction
> +============
> +
> +Welcome to the unified getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and
>
'unified' makes sense only with the context of this effort, for anyone
who is reading this for the first time it may not mean much, I suggest
just drop it: "Welcome to the getting started guide for ..."
> +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.
> +
> +We hope this guide serves as a valuable resource as you explore the powerful
> +capabilities of DPDK.
> \ No newline at end of file
Last paragraph feels like marketing text :), I would be OK without it,
but this is personal preference.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 1/6] Section 1: Introduction
2023-09-25 11:30 ` Ferruh Yigit
@ 2023-10-11 18:26 ` Dave Young
0 siblings, 0 replies; 28+ messages in thread
From: Dave Young @ 2023-10-11 18:26 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, Bruce Richardson
[-- Attachment #1: Type: text/plain, Size: 2298 bytes --]
Thank you for the feedback. I agree with the suggested changes to remove
"unified" and the last paragraph. These changes have been made locally. I
plan to send updated versions of all patches in this series at the same
time, so you can expect to see these adjustments in the next version.
Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com
On Mon, Sep 25, 2023 at 7:30 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:
> On 9/20/2023 4:48 PM, David Young wrote:
> > ---
> > doc/guides/getting_started_guide/intro.rst | 16 ++++++++++++++++
> > 1 file changed, 16 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..88bdd48849
> > --- /dev/null
> > +++ b/doc/guides/getting_started_guide/intro.rst
> > @@ -0,0 +1,16 @@
> > +.. SPDX-License-Identifier: BSD-3-Clause
> > + Copyright(c) 2010-2014 Intel Corporation.
> > +
> > +Introduction
> > +============
> > +
> > +Welcome to the unified getting started guide for the Data Plane
> Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set
> of libraries and
> >
>
> 'unified' makes sense only with the context of this effort, for anyone
> who is reading this for the first time it may not mean much, I suggest
> just drop it: "Welcome to the getting started guide for ..."
>
>
> > +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.
> > +
> > +We hope this guide serves as a valuable resource as you explore the
> powerful
> > +capabilities of DPDK.
> > \ No newline at end of file
>
> Last paragraph feels like marketing text :), I would be OK without it,
> but this is personal preference.
>
>
[-- Attachment #2: Type: text/html, Size: 3032 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 2/6] Section 2: Install and Build DPDK
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
2023-09-20 15:48 ` [PATCH 1/6] Section 1: Introduction David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:30 ` Ferruh Yigit
2023-09-25 16:05 ` Tyler Retzlaff
2023-09-20 15:48 ` [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications David Young
` (6 subsequent siblings)
8 siblings, 2 replies; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, David Young
---
.../building_from_sources.rst | 108 ++++++++++++++++++
.../install_and_build/index.rst | 15 +++
.../installing_prebuilt_packages.rst | 54 +++++++++
.../windows_install_build.rst | 93 +++++++++++++++
4 files changed, 270 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
create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
@@ -0,0 +1,108 @@
+.. 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 both
+Linux and FreeBSD platforms. 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.53.2+) and ``ninja``
+- ``pyelftools`` (version 0.22+)
+
+Here's how to install them:
+
+Linux
+^^^^^
+
+Alpine
+
+.. code-block:: bash
+
+ sudo apk add alpine-sdk bsd-compat-headers
+ pip install meson ninja
+
+Debian and Ubuntu and derivatives
+
+.. code-block:: bash
+
+ sudo apt install build-essential
+ pip install meson ninja
+
+Fedora and RedHat Enterprise Linux RHEL
+
+.. code-block:: bash
+
+ sudo dnf groupinstall "Development Tools"
+ pip install meson ninja
+
+openSUSE
+
+.. code-block:: bash
+
+ sudo zypper install -t pattern devel_basis python3-pyelftools
+ pip install meson ninja
+
+FreeBSD
+^^^^^^^
+
+FreeBSD (as root)
+
+.. code-block:: bash
+
+ pkg install meson pkgconf py38-pyelftools
+
+Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation.
+
+Getting the DPDK Source
+-----------------------
+
+Download the DPDK source code from the official repository
+``https://fast.dpdk.org/rel/``.
+
+Use ``wget`` to grab the DPDK version::
+
+ wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
+
+Extract the downloaded archive:
+
+.. code-block:: bash
+
+ tar -xvf dpdk-<version>.tar.gz
+
+Navigate to the DPDK directory:
+
+.. code-block:: bash
+
+ cd dpdk-<version>
+
+Building DPDK
+-------------
+
+Configure the build based on your needs, hardware, and environment.
+This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”.
+
+.. code-block:: bash
+
+ ninja -C build
+ cd build
+ sudo ninja install
+ ldconfig
+
+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..f4d8740fb6
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/index.rst
@@ -0,0 +1,15 @@
+.. 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
+ windows_install_build
\ 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
diff --git a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
new file mode 100644
index 0000000000..ea0e131766
--- /dev/null
+++ b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2015 Intel Corporation.
+
+.. _windows_install_build:
+
+Windows DPDK Build
+==================
+
+Before you begin the process of building DPDK on Windows,
+make sure your system meets all the necessary requirements as outlined below.
+
+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.
+Recommended version is either Meson 0.57.0 (baseline) or the latest release.
+
+Install the Backend
+-------------------
+
+If using Ninja, download and install the backend from the
+`Ninja website <https://ninja-build.org/>`_ or install along with the meson build
+system.
+
+Once you have verified that your system meets these requirements,
+you can proceed with the following steps to build DPDK.
+
+Build the Code
+--------------
+
+The build environment is setup to build the EAL and the helloworld example by default.
+To compile the examples, the flag -Dexamples is required.
+
+**Option 1. Native Build on Windows**
+
+When using Clang-LLVM, specifying the compiler might be required to complete the meson
+command::
+
+ set CC=clang
+
+When using MinGW-w64, it is sufficient to have toolchain executables in PATH::
+
+ set PATH=C:\MinGW\mingw64\bin;%PATH%
+
+To compile the examples::
+
+ cd C:\Users\me\dpdk
+ meson -Dexamples=helloworld build
+ ninja -C build
+
+**Option 2. Cross-Compile with MinGW-w64**
+
+The cross-file option must be specified for Meson.
+Depending on the distribution, paths in this file may need adjustments::
+
+ meson --cross-file config/x86/cross-mingw -Dexamples=helloworld build
+ ninja -C build
\ No newline at end of file
--
2.41.0.windows.1
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 2/6] Section 2: Install and Build DPDK
2023-09-20 15:48 ` [PATCH 2/6] Section 2: Install and Build DPDK David Young
@ 2023-09-25 11:30 ` Ferruh Yigit
2023-09-25 12:20 ` Bruce Richardson
2023-09-25 16:05 ` Tyler Retzlaff
1 sibling, 1 reply; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:30 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, David Young wrote:
> ---
> .../building_from_sources.rst | 108 ++++++++++++++++++
> .../install_and_build/index.rst | 15 +++
> .../installing_prebuilt_packages.rst | 54 +++++++++
> .../windows_install_build.rst | 93 +++++++++++++++
> 4 files changed, 270 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
> create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> @@ -0,0 +1,108 @@
> +.. 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 both
> +Linux and FreeBSD platforms. 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.53.2+) and ``ninja``
> +- ``pyelftools`` (version 0.22+)
> +
>
Is 'libnuma' also a dependency?
When I remove it in my platform and build DPDK again, getting following
in meson stage:
"
config/meson.build:419:4: ERROR: Problem encountered:
No NUMA library (development package) found, yet DPDK configured for
multiple NUMA nodes.
Please install libnuma, or set 'max_numa_nodes' option to '1' to build
without NUMA support.
"
> +Here's how to install them:
> +
> +Linux
> +^^^^^
> +
> +Alpine
> +
> +.. code-block:: bash
> +
> + sudo apk add alpine-sdk bsd-compat-headers
> + pip install meson ninja
> +
> +Debian and Ubuntu and derivatives
> +
> +.. code-block:: bash
> +
> + sudo apt install build-essential
> + pip install meson ninja
> +
> +Fedora and RedHat Enterprise Linux RHEL
> +
> +.. code-block:: bash
> +
> + sudo dnf groupinstall "Development Tools"
> + pip install meson ninja
> +
Above are missing some of the dependencies above, just to confirm if
they are installed by default?
And even if so, if we should provide explicit commands to install all,
to be sure?
> +openSUSE
> +
> +.. code-block:: bash
> +
> + sudo zypper install -t pattern devel_basis python3-pyelftools
> + pip install meson ninja
> +
> +FreeBSD
> +^^^^^^^
> +
> +FreeBSD (as root)
> +
> +.. code-block:: bash
> +
> + pkg install meson pkgconf py38-pyelftools
> +
> +Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation.
> +
> +Getting the DPDK Source
> +-----------------------
> +
> +Download the DPDK source code from the official repository
> +``https://fast.dpdk.org/rel/``.
> +
> +Use ``wget`` to grab the DPDK version::
> +
> + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> +
> +Extract the downloaded archive:
> +
> +.. code-block:: bash
> +
> + tar -xvf dpdk-<version>.tar.gz
> +
> +Navigate to the DPDK directory:
> +
> +.. code-block:: bash
> +
> + cd dpdk-<version>
> +
> +Building DPDK
> +-------------
> +
> +Configure the build based on your needs, hardware, and environment.
> +This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”.
> +
> +.. code-block:: bash
> +
> + ninja -C build
> + cd build
> + sudo ninja install>
Above mentions from "meson install", here using "ninja install", should
we unify it to one?
> + ldconfig
> +
> +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..f4d8740fb6
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/index.rst
> @@ -0,0 +1,15 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> + Copyright(c) 2010-2025 Intel Corporation.
> +
2025?
> +.. _install_and_build:
> +
> +Install and Build DPDK
> +======================
> +
> +.. toctree::
> + :maxdepth: 2
> +
> +
> + installing_prebuilt_packages
> + building_from_sources
> + windows_install_build
> \ 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
> diff --git a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> new file mode 100644
> index 0000000000..ea0e131766
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> @@ -0,0 +1,93 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> + Copyright(c) 2010-2015 Intel Corporation.
> +
> +.. _windows_install_build:
> +
> +Windows DPDK Build
> +==================
> +
> +Before you begin the process of building DPDK on Windows,
> +make sure your system meets all the necessary requirements as outlined below.
> +
> +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).
> +
>
What is the difference of both two, as a new DPDK user which one should
I select?
> +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.
> +Recommended version is either Meson 0.57.0 (baseline) or the latest release.
> +
> +Install the Backend
> +-------------------
> +
> +If using Ninja, download and install the backend from the
> +`Ninja website <https://ninja-build.org/>`_ or install along with the meson build
> +system.
> +
> +Once you have verified that your system meets these requirements,
> +you can proceed with the following steps to build DPDK.
> +
> +Build the Code
> +--------------
> +
> +The build environment is setup to build the EAL and the helloworld example by default.
> +To compile the examples, the flag -Dexamples is required.
> +
What do you think to emphasis 'helloworld' & '-Dexamples', with `` or *
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 2/6] Section 2: Install and Build DPDK
2023-09-25 11:30 ` Ferruh Yigit
@ 2023-09-25 12:20 ` Bruce Richardson
0 siblings, 0 replies; 28+ messages in thread
From: Bruce Richardson @ 2023-09-25 12:20 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: David Young, dev
On Mon, Sep 25, 2023 at 12:30:35PM +0100, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, David Young wrote:
> > ---
> > .../building_from_sources.rst | 108 ++++++++++++++++++
> > .../install_and_build/index.rst | 15 +++
> > .../installing_prebuilt_packages.rst | 54 +++++++++
> > .../windows_install_build.rst | 93 +++++++++++++++
> > 4 files changed, 270 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
> > create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
> > --- /dev/null
> > +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> > @@ -0,0 +1,108 @@
> > +.. 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 both
> > +Linux and FreeBSD platforms. 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.53.2+) and ``ninja``
> > +- ``pyelftools`` (version 0.22+)
> > +
> >
>
> Is 'libnuma' also a dependency?
>
> When I remove it in my platform and build DPDK again, getting following
> in meson stage:
>
> "
> config/meson.build:419:4: ERROR: Problem encountered:
> No NUMA library (development package) found, yet DPDK configured for
> multiple NUMA nodes.
> Please install libnuma, or set 'max_numa_nodes' option to '1' to build
> without NUMA support.
> "
>
Realistically, yes it is a dependency and we should include it here.
>
>
> > +Here's how to install them:
> > +
> > +Linux
> > +^^^^^
> > +
> > +Alpine
> > +
> > +.. code-block:: bash
> > +
> > + sudo apk add alpine-sdk bsd-compat-headers
> > + pip install meson ninja
> > +
> > +Debian and Ubuntu and derivatives
> > +
> > +.. code-block:: bash
> > +
> > + sudo apt install build-essential
> > + pip install meson ninja
> > +
> > +Fedora and RedHat Enterprise Linux RHEL
> > +
> > +.. code-block:: bash
> > +
> > + sudo dnf groupinstall "Development Tools"
> > + pip install meson ninja
> > +
>
> Above are missing some of the dependencies above, just to confirm if
> they are installed by default?
> And even if so, if we should provide explicit commands to install all,
> to be sure?
>
>
>
> > +openSUSE
> > +
> > +.. code-block:: bash
> > +
> > + sudo zypper install -t pattern devel_basis python3-pyelftools
> > + pip install meson ninja
> > +
> > +FreeBSD
> > +^^^^^^^
> > +
> > +FreeBSD (as root)
> > +
> > +.. code-block:: bash
> > +
> > + pkg install meson pkgconf py38-pyelftools
> > +
> > +Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation.
> > +
> > +Getting the DPDK Source
> > +-----------------------
> > +
> > +Download the DPDK source code from the official repository
> > +``https://fast.dpdk.org/rel/``.
> > +
> > +Use ``wget`` to grab the DPDK version::
> > +
> > + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> > +
> > +Extract the downloaded archive:
> > +
> > +.. code-block:: bash
> > +
> > + tar -xvf dpdk-<version>.tar.gz
> > +
> > +Navigate to the DPDK directory:
> > +
> > +.. code-block:: bash
> > +
> > + cd dpdk-<version>
> > +
> > +Building DPDK
> > +-------------
> > +
> > +Configure the build based on your needs, hardware, and environment.
> > +This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”.
> > +
> > +.. code-block:: bash
> > +
> > + ninja -C build
> > + cd build
> > + sudo ninja install>
>
> Above mentions from "meson install", here using "ninja install", should
> we unify it to one?
>
Yes, we should standardize on meson install.
>
<snip for brevity>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 2/6] Section 2: Install and Build DPDK
2023-09-20 15:48 ` [PATCH 2/6] Section 2: Install and Build DPDK David Young
2023-09-25 11:30 ` Ferruh Yigit
@ 2023-09-25 16:05 ` Tyler Retzlaff
2023-10-12 18:08 ` Dave Young
1 sibling, 1 reply; 28+ messages in thread
From: Tyler Retzlaff @ 2023-09-25 16:05 UTC (permalink / raw)
To: David Young; +Cc: dev, Bruce Richardson
On Wed, Sep 20, 2023 at 11:48:06AM -0400, David Young wrote:
> ---
> .../building_from_sources.rst | 108 ++++++++++++++++++
> .../install_and_build/index.rst | 15 +++
> .../installing_prebuilt_packages.rst | 54 +++++++++
> .../windows_install_build.rst | 93 +++++++++++++++
> 4 files changed, 270 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
> create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> @@ -0,0 +1,108 @@
> +.. 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 both
> +Linux and FreeBSD platforms. It covers the necessary steps, prerequisites,
> +and considerations for different architectures and compilers.
when the title of the section is general it shouldn't mention a specific
OS in the content. if the content is OS specific then the parent section
or the title of the section should identify to which OS it applies. in
general it would be nice to convey that windows is an equally supported
platform to the other operating systems.
i know it's a bit of a dance i hope you can help interpret what i'm
trying to convey.
> +
> +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.53.2+) and ``ninja``
> +- ``pyelftools`` (version 0.22+)
> +
> +Here's how to install them:
> +
> +Linux
> +^^^^^
> +
> +Alpine
> +
> +.. code-block:: bash
> +
> + sudo apk add alpine-sdk bsd-compat-headers
> + pip install meson ninja
> +
> +Debian and Ubuntu and derivatives
> +
> +.. code-block:: bash
> +
> + sudo apt install build-essential
> + pip install meson ninja
> +
> +Fedora and RedHat Enterprise Linux RHEL
> +
> +.. code-block:: bash
> +
> + sudo dnf groupinstall "Development Tools"
> + pip install meson ninja
> +
> +openSUSE
> +
> +.. code-block:: bash
> +
> + sudo zypper install -t pattern devel_basis python3-pyelftools
> + pip install meson ninja
> +
> +FreeBSD
> +^^^^^^^
> +
> +FreeBSD (as root)
> +
> +.. code-block:: bash
> +
> + pkg install meson pkgconf py38-pyelftools
> +
> +Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation.
> +
> +Getting the DPDK Source
> +-----------------------
> +
> +Download the DPDK source code from the official repository
> +``https://fast.dpdk.org/rel/``.
> +
> +Use ``wget`` to grab the DPDK version::
> +
> + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> +
> +Extract the downloaded archive:
> +
> +.. code-block:: bash
> +
> + tar -xvf dpdk-<version>.tar.gz
> +
> +Navigate to the DPDK directory:
> +
> +.. code-block:: bash
> +
> + cd dpdk-<version>
> +
> +Building DPDK
> +-------------
> +
> +Configure the build based on your needs, hardware, and environment.
> +This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”.
> +
> +.. code-block:: bash
> +
> + ninja -C build
> + cd build
> + sudo ninja install
> + ldconfig
> +
> +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..f4d8740fb6
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/index.rst
> @@ -0,0 +1,15 @@
> +.. 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
> + windows_install_build
> \ 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
> diff --git a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> new file mode 100644
> index 0000000000..ea0e131766
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> @@ -0,0 +1,93 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> + Copyright(c) 2010-2015 Intel Corporation.
> +
> +.. _windows_install_build:
> +
> +Windows DPDK Build
> +==================
> +
> +Before you begin the process of building DPDK on Windows,
> +make sure your system meets all the necessary requirements as outlined below.
> +
> +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.
would it be overly objectionable to state specific LLVM >= 16.0.x as
required?
> +- 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.
> +Recommended version is either Meson 0.57.0 (baseline) or the latest release.
s/Recommended/Required/ is 0.57.0 i do not believe their latest release
works?
> +
> +Install the Backend
> +-------------------
> +
> +If using Ninja, download and install the backend from the
> +`Ninja website <https://ninja-build.org/>`_ or install along with the meson build
> +system.
i'm not sure we need to mention the installation of the ninja backend
since you acquire it along with meson 0.57.0? anyone call me wrong on
this or does windows use any other backend that we are aware? if not i
think we can delete the 'install the backend' section entirely.
> +
> +Once you have verified that your system meets these requirements,
> +you can proceed with the following steps to build DPDK.
> +
> +Build the Code
> +--------------
> +
> +The build environment is setup to build the EAL and the helloworld example by default.
> +To compile the examples, the flag -Dexamples is required.
> +
> +**Option 1. Native Build on Windows**
> +
> +When using Clang-LLVM, specifying the compiler might be required to complete the meson
> +command::
> +
> + set CC=clang
> +
> +When using MinGW-w64, it is sufficient to have toolchain executables in PATH::
> +
> + set PATH=C:\MinGW\mingw64\bin;%PATH%
> +
> +To compile the examples::
> +
> + cd C:\Users\me\dpdk
> + meson -Dexamples=helloworld build
meson setup -Dexamples=helloworld build
> + ninja -C build
meson compile -C build
> +
> +**Option 2. Cross-Compile with MinGW-w64**
> +
> +The cross-file option must be specified for Meson.
> +Depending on the distribution, paths in this file may need adjustments::
> +
> + meson --cross-file config/x86/cross-mingw -Dexamples=helloworld build
> + ninja -C build
> \ No newline at end of file
> --
> 2.41.0.windows.1
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 2/6] Section 2: Install and Build DPDK
2023-09-25 16:05 ` Tyler Retzlaff
@ 2023-10-12 18:08 ` Dave Young
2023-10-17 13:37 ` Tyler Retzlaff
0 siblings, 1 reply; 28+ messages in thread
From: Dave Young @ 2023-10-12 18:08 UTC (permalink / raw)
To: Tyler Retzlaff; +Cc: dev, Bruce Richardson
[-- Attachment #1: Type: text/plain, Size: 13118 bytes --]
Tyler, can you provide an example of the OS specific section/title you're
thinking would make sense to use?
Can you confirm the following?
1. The Clang-LLVM C compiler (version >= 16.0.x)
2. Meson Build system (Required version: 0.57.0)
3. Updated commands:
# Previous Command
meson -Dexamples=helloworld build
# Updated Command
meson setup -Dexamples=helloworld build
# Previous Command
ninja -C build
# Updated Command
meson compile -C build
4. Since Ninja is bundled with Meson 0.57.0, a separate section for its
installation may not be necessary. Is this correct?
Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com
On Mon, Sep 25, 2023 at 12:05 PM Tyler Retzlaff <
roretzla@linux.microsoft.com> wrote:
> On Wed, Sep 20, 2023 at 11:48:06AM -0400, David Young wrote:
> > ---
> > .../building_from_sources.rst | 108 ++++++++++++++++++
> > .../install_and_build/index.rst | 15 +++
> > .../installing_prebuilt_packages.rst | 54 +++++++++
> > .../windows_install_build.rst | 93 +++++++++++++++
> > 4 files changed, 270 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
> > create mode 100644
> doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
> > --- /dev/null
> > +++
> b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> > @@ -0,0 +1,108 @@
> > +.. 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 both
> > +Linux and FreeBSD platforms. It covers the necessary steps,
> prerequisites,
> > +and considerations for different architectures and compilers.
>
> when the title of the section is general it shouldn't mention a specific
> OS in the content. if the content is OS specific then the parent section
> or the title of the section should identify to which OS it applies. in
> general it would be nice to convey that windows is an equally supported
> platform to the other operating systems.
>
> i know it's a bit of a dance i hope you can help interpret what i'm
> trying to convey.
>
> > +
> > +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.53.2+) and ``ninja``
> > +- ``pyelftools`` (version 0.22+)
> > +
> > +Here's how to install them:
> > +
> > +Linux
> > +^^^^^
> > +
> > +Alpine
> > +
> > +.. code-block:: bash
> > +
> > + sudo apk add alpine-sdk bsd-compat-headers
> > + pip install meson ninja
> > +
> > +Debian and Ubuntu and derivatives
> > +
> > +.. code-block:: bash
> > +
> > + sudo apt install build-essential
> > + pip install meson ninja
> > +
> > +Fedora and RedHat Enterprise Linux RHEL
> > +
> > +.. code-block:: bash
> > +
> > + sudo dnf groupinstall "Development Tools"
> > + pip install meson ninja
> > +
> > +openSUSE
> > +
> > +.. code-block:: bash
> > +
> > + sudo zypper install -t pattern devel_basis python3-pyelftools
> > + pip install meson ninja
> > +
> > +FreeBSD
> > +^^^^^^^
> > +
> > +FreeBSD (as root)
> > +
> > +.. code-block:: bash
> > +
> > + pkg install meson pkgconf py38-pyelftools
> > +
> > +Note: If you're using FreeBSD, you'll also need kernel sources. Make
> sure they're included during the FreeBSD installation.
> > +
> > +Getting the DPDK Source
> > +-----------------------
> > +
> > +Download the DPDK source code from the official repository
> > +``https://fast.dpdk.org/rel/`` <https://fast.dpdk.org/rel/>.
> > +
> > +Use ``wget`` to grab the DPDK version::
> > +
> > + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> > +
> > +Extract the downloaded archive:
> > +
> > +.. code-block:: bash
> > +
> > + tar -xvf dpdk-<version>.tar.gz
> > +
> > +Navigate to the DPDK directory:
> > +
> > +.. code-block:: bash
> > +
> > + cd dpdk-<version>
> > +
> > +Building DPDK
> > +-------------
> > +
> > +Configure the build based on your needs, hardware, and environment.
> > +This might include setting specific flags or options. For example:
> “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja”
> and install using “meson install”.
> > +
> > +.. code-block:: bash
> > +
> > + ninja -C build
> > + cd build
> > + sudo ninja install
> > + ldconfig
> > +
> > +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..f4d8740fb6
> > --- /dev/null
> > +++ b/doc/guides/getting_started_guide/install_and_build/index.rst
> > @@ -0,0 +1,15 @@
> > +.. 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
> > + windows_install_build
> > \ 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
> > diff --git
> a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> > new file mode 100644
> > index 0000000000..ea0e131766
> > --- /dev/null
> > +++
> b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> > @@ -0,0 +1,93 @@
> > +.. SPDX-License-Identifier: BSD-3-Clause
> > + Copyright(c) 2010-2015 Intel Corporation.
> > +
> > +.. _windows_install_build:
> > +
> > +Windows DPDK Build
> > +==================
> > +
> > +Before you begin the process of building DPDK on Windows,
> > +make sure your system meets all the necessary requirements as outlined
> below.
> > +
> > +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.
>
> would it be overly objectionable to state specific LLVM >= 16.0.x as
> required?
>
> > +- 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.
> > +Recommended version is either Meson 0.57.0 (baseline) or the latest
> release.
>
> s/Recommended/Required/ is 0.57.0 i do not believe their latest release
> works?
>
> > +
> > +Install the Backend
> > +-------------------
> > +
> > +If using Ninja, download and install the backend from the
> > +`Ninja website <https://ninja-build.org/>`_ or install along with the
> meson build
> > +system.
>
> i'm not sure we need to mention the installation of the ninja backend
> since you acquire it along with meson 0.57.0? anyone call me wrong on
> this or does windows use any other backend that we are aware? if not i
> think we can delete the 'install the backend' section entirely.
>
> > +
> > +Once you have verified that your system meets these requirements,
> > +you can proceed with the following steps to build DPDK.
> > +
> > +Build the Code
> > +--------------
> > +
> > +The build environment is setup to build the EAL and the helloworld
> example by default.
> > +To compile the examples, the flag -Dexamples is required.
> > +
> > +**Option 1. Native Build on Windows**
> > +
> > +When using Clang-LLVM, specifying the compiler might be required to
> complete the meson
> > +command::
> > +
> > + set CC=clang
> > +
> > +When using MinGW-w64, it is sufficient to have toolchain executables in
> PATH::
> > +
> > + set PATH=C:\MinGW\mingw64\bin;%PATH%
> > +
> > +To compile the examples::
> > +
> > + cd C:\Users\me\dpdk
> > + meson -Dexamples=helloworld build
>
> meson setup -Dexamples=helloworld build
>
> > + ninja -C build
>
> meson compile -C build
>
> > +
> > +**Option 2. Cross-Compile with MinGW-w64**
> > +
> > +The cross-file option must be specified for Meson.
> > +Depending on the distribution, paths in this file may need adjustments::
> > +
> > + meson --cross-file config/x86/cross-mingw -Dexamples=helloworld
> build
> > + ninja -C build
> > \ No newline at end of file
> > --
> > 2.41.0.windows.1
>
[-- Attachment #2: Type: text/html, Size: 16136 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 2/6] Section 2: Install and Build DPDK
2023-10-12 18:08 ` Dave Young
@ 2023-10-17 13:37 ` Tyler Retzlaff
0 siblings, 0 replies; 28+ messages in thread
From: Tyler Retzlaff @ 2023-10-17 13:37 UTC (permalink / raw)
To: Dave Young; +Cc: dev, Bruce Richardson
On Thu, Oct 12, 2023 at 02:08:46PM -0400, Dave Young wrote:
> Tyler, can you provide an example of the OS specific section/title you're
> thinking would make sense to use?
I think what is below is okay, but it probably just needs a Windows
section?
Right now there is, so just adding Windows into the list would be
enough? If I didn't understand the question ask again :)
Required Tools
--------------
Linux
Tools applicable to all distributions, maybe?
Distribution 1
Tools applicable to specific distribution 1.
Distribution 2
Tools applicable to specific distribution 2.
FreeBSD
Tools applicable for FreeBSD
.. Maybe there are per-release or per toolchain speicic things, maybe not?
Windows
Tools applicable to Windows
.. Probably per-toolchain specific things.
I might get a brick thrown at me but I might also suggest sorting by OS
name? I know Linux is important, regardless Windows ends up last either
way so it's just a suggestion.
Hope this is what you were asking.
>
> Can you confirm the following?
>
> 1. The Clang-LLVM C compiler (version >= 16.0.x)
> 2. Meson Build system (Required version: 0.57.0)
> 3. Updated commands:
Yes, this is what I use today. I wonder if we can provide links?
But also MinGW is also used as an alternative to LLVM.
>
> # Previous Command
> meson -Dexamples=helloworld build
> # Updated Command
> meson setup -Dexamples=helloworld build
Yes, updated command is what I use currently.
>
> # Previous Command
> ninja -C build
> # Updated Command
> meson compile -C build
Yes, updated command is what I use currently.
>
> 4. Since Ninja is bundled with Meson 0.57.0, a separate section for its
> installation may not be necessary. Is this correct?
Yes, I believe this is the case. I have never had to separately install
ninja or another backend.
Once all of your changes have settled I plan to add some additional
detail related to MSVC as well but for the moment it is *not* supported
usefully so we don't need to mention it yet.
>
> Thanks!
> David Young
> Professional Copywriter/Technical Writer
> Young Copy
> +1 (678) 500-9550
> https://www.youngcopy.com
>
>
> On Mon, Sep 25, 2023 at 12:05 PM Tyler Retzlaff <
> roretzla@linux.microsoft.com> wrote:
>
> > On Wed, Sep 20, 2023 at 11:48:06AM -0400, David Young wrote:
> > > ---
> > > .../building_from_sources.rst | 108 ++++++++++++++++++
> > > .../install_and_build/index.rst | 15 +++
> > > .../installing_prebuilt_packages.rst | 54 +++++++++
> > > .../windows_install_build.rst | 93 +++++++++++++++
> > > 4 files changed, 270 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
> > > create mode 100644
> > doc/guides/getting_started_guide/install_and_build/windows_install_build.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..e4ee8e436d
> > > --- /dev/null
> > > +++
> > b/doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
> > > @@ -0,0 +1,108 @@
> > > +.. 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 both
> > > +Linux and FreeBSD platforms. It covers the necessary steps,
> > prerequisites,
> > > +and considerations for different architectures and compilers.
> >
> > when the title of the section is general it shouldn't mention a specific
> > OS in the content. if the content is OS specific then the parent section
> > or the title of the section should identify to which OS it applies. in
> > general it would be nice to convey that windows is an equally supported
> > platform to the other operating systems.
> >
> > i know it's a bit of a dance i hope you can help interpret what i'm
> > trying to convey.
> >
> > > +
> > > +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.53.2+) and ``ninja``
> > > +- ``pyelftools`` (version 0.22+)
> > > +
> > > +Here's how to install them:
> > > +
> > > +Linux
> > > +^^^^^
> > > +
> > > +Alpine
> > > +
> > > +.. code-block:: bash
> > > +
> > > + sudo apk add alpine-sdk bsd-compat-headers
> > > + pip install meson ninja
> > > +
> > > +Debian and Ubuntu and derivatives
> > > +
> > > +.. code-block:: bash
> > > +
> > > + sudo apt install build-essential
> > > + pip install meson ninja
> > > +
> > > +Fedora and RedHat Enterprise Linux RHEL
> > > +
> > > +.. code-block:: bash
> > > +
> > > + sudo dnf groupinstall "Development Tools"
> > > + pip install meson ninja
> > > +
> > > +openSUSE
> > > +
> > > +.. code-block:: bash
> > > +
> > > + sudo zypper install -t pattern devel_basis python3-pyelftools
> > > + pip install meson ninja
> > > +
> > > +FreeBSD
> > > +^^^^^^^
> > > +
> > > +FreeBSD (as root)
> > > +
> > > +.. code-block:: bash
> > > +
> > > + pkg install meson pkgconf py38-pyelftools
> > > +
> > > +Note: If you're using FreeBSD, you'll also need kernel sources. Make
> > sure they're included during the FreeBSD installation.
> > > +
> > > +Getting the DPDK Source
> > > +-----------------------
> > > +
> > > +Download the DPDK source code from the official repository
> > > +``https://fast.dpdk.org/rel/`` <https://fast.dpdk.org/rel/>.
> > > +
> > > +Use ``wget`` to grab the DPDK version::
> > > +
> > > + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz
> > > +
> > > +Extract the downloaded archive:
> > > +
> > > +.. code-block:: bash
> > > +
> > > + tar -xvf dpdk-<version>.tar.gz
> > > +
> > > +Navigate to the DPDK directory:
> > > +
> > > +.. code-block:: bash
> > > +
> > > + cd dpdk-<version>
> > > +
> > > +Building DPDK
> > > +-------------
> > > +
> > > +Configure the build based on your needs, hardware, and environment.
> > > +This might include setting specific flags or options. For example:
> > “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja”
> > and install using “meson install”.
> > > +
> > > +.. code-block:: bash
> > > +
> > > + ninja -C build
> > > + cd build
> > > + sudo ninja install
> > > + ldconfig
> > > +
> > > +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..f4d8740fb6
> > > --- /dev/null
> > > +++ b/doc/guides/getting_started_guide/install_and_build/index.rst
> > > @@ -0,0 +1,15 @@
> > > +.. 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
> > > + windows_install_build
> > > \ 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
> > > diff --git
> > a/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> > b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> > > new file mode 100644
> > > index 0000000000..ea0e131766
> > > --- /dev/null
> > > +++
> > b/doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
> > > @@ -0,0 +1,93 @@
> > > +.. SPDX-License-Identifier: BSD-3-Clause
> > > + Copyright(c) 2010-2015 Intel Corporation.
> > > +
> > > +.. _windows_install_build:
> > > +
> > > +Windows DPDK Build
> > > +==================
> > > +
> > > +Before you begin the process of building DPDK on Windows,
> > > +make sure your system meets all the necessary requirements as outlined
> > below.
> > > +
> > > +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.
> >
> > would it be overly objectionable to state specific LLVM >= 16.0.x as
> > required?
> >
> > > +- 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.
> > > +Recommended version is either Meson 0.57.0 (baseline) or the latest
> > release.
> >
> > s/Recommended/Required/ is 0.57.0 i do not believe their latest release
> > works?
> >
> > > +
> > > +Install the Backend
> > > +-------------------
> > > +
> > > +If using Ninja, download and install the backend from the
> > > +`Ninja website <https://ninja-build.org/>`_ or install along with the
> > meson build
> > > +system.
> >
> > i'm not sure we need to mention the installation of the ninja backend
> > since you acquire it along with meson 0.57.0? anyone call me wrong on
> > this or does windows use any other backend that we are aware? if not i
> > think we can delete the 'install the backend' section entirely.
> >
> > > +
> > > +Once you have verified that your system meets these requirements,
> > > +you can proceed with the following steps to build DPDK.
> > > +
> > > +Build the Code
> > > +--------------
> > > +
> > > +The build environment is setup to build the EAL and the helloworld
> > example by default.
> > > +To compile the examples, the flag -Dexamples is required.
> > > +
> > > +**Option 1. Native Build on Windows**
> > > +
> > > +When using Clang-LLVM, specifying the compiler might be required to
> > complete the meson
> > > +command::
> > > +
> > > + set CC=clang
> > > +
> > > +When using MinGW-w64, it is sufficient to have toolchain executables in
> > PATH::
> > > +
> > > + set PATH=C:\MinGW\mingw64\bin;%PATH%
> > > +
> > > +To compile the examples::
> > > +
> > > + cd C:\Users\me\dpdk
> > > + meson -Dexamples=helloworld build
> >
> > meson setup -Dexamples=helloworld build
> >
> > > + ninja -C build
> >
> > meson compile -C build
> >
> > > +
> > > +**Option 2. Cross-Compile with MinGW-w64**
> > > +
> > > +The cross-file option must be specified for Meson.
> > > +Depending on the distribution, paths in this file may need adjustments::
> > > +
> > > + meson --cross-file config/x86/cross-mingw -Dexamples=helloworld
> > build
> > > + ninja -C build
> > > \ No newline at end of file
> > > --
> > > 2.41.0.windows.1
> >
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
2023-09-20 15:48 ` [PATCH 1/6] Section 1: Introduction David Young
2023-09-20 15:48 ` [PATCH 2/6] Section 2: Install and Build DPDK David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:31 ` Ferruh Yigit
2023-09-20 15:48 ` [PATCH 4/6] Section 4: Running Applications David Young
` (5 subsequent siblings)
8 siblings, 1 reply; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, 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
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications
2023-09-20 15:48 ` [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications David Young
@ 2023-09-25 11:31 ` Ferruh Yigit
2023-09-25 12:22 ` Bruce Richardson
0 siblings, 1 reply; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:31 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, 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
> +
> +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.
> +
Not sure above sentences adds value.
> +.. 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
> +
>
We have './usertools/dpdk-hugepages.py' script for this, which I am
using regularly.
Script is wrapper to what described above, so I think good to explain
basics, but also may worth mentioning from script, it is more user
friendly than above instructions.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications
2023-09-25 11:31 ` Ferruh Yigit
@ 2023-09-25 12:22 ` Bruce Richardson
2023-10-12 17:32 ` Dave Young
0 siblings, 1 reply; 28+ messages in thread
From: Bruce Richardson @ 2023-09-25 12:22 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: David Young, dev
On Mon, Sep 25, 2023 at 12:31:34PM +0100, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, 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
> > +
> > +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.
> > +
>
> Not sure above sentences adds value.
>
>
>
> > +.. 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
> > +
> >
>
>
> We have './usertools/dpdk-hugepages.py' script for this, which I am
> using regularly.
>
> Script is wrapper to what described above, so I think good to explain
> basics, but also may worth mentioning from script, it is more user
> friendly than above instructions.
>
Actually, if script can do all the basics - something I believe Stephen and
Thomas also pointed out on a slack review earlier - then we should just
drop the manual steps from here. If we think the script is sufficiently
robust, we can drop them from the doc entirely, or if not, move them to an
appendix which we reference here.
/Bruce
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications
2023-09-25 12:22 ` Bruce Richardson
@ 2023-10-12 17:32 ` Dave Young
0 siblings, 0 replies; 28+ messages in thread
From: Dave Young @ 2023-10-12 17:32 UTC (permalink / raw)
To: Bruce Richardson; +Cc: Ferruh Yigit, dev
[-- Attachment #1: Type: text/plain, Size: 4612 bytes --]
I asked the following in the Slack channel, responding to Stephen and
Thomas so asking in this thread as well to confirm:
To confirm, the three steps in 3.1.1 Memory Setup: Reservering Hugepages at
http://170.249.220.94/getting_started_guide/system_setup.html#system-setup-for-linux
can be replaced with the following:
Memory Setup: Reserving Hugepages
To simplify the hugepages setup, use the `dpdk-hugepages` script:
sudo dpdk-hugepages --setup
To confirm, the instructions in 3.1.2 Device Setup: VFIO at
http://170.249.220.94/getting_started_guide/system_setup.html#device-setup-vfio
can be replaced with the following:
Device Setup: VFIO
For VFIO setup, please refer to the `Kernel Documentation for VFIO <
https://www.kernel.org/doc/html/latest/driver-api/vfio.html>`_.
Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com
On Mon, Sep 25, 2023 at 8:22 AM Bruce Richardson <bruce.richardson@intel.com>
wrote:
> On Mon, Sep 25, 2023 at 12:31:34PM +0100, Ferruh Yigit wrote:
> > On 9/20/2023 4:48 PM, 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
> > > +
> > > +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.
> > > +
> >
> > Not sure above sentences adds value.
> >
> >
> >
> > > +.. 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
> > > +
> > >
> >
> >
> > We have './usertools/dpdk-hugepages.py' script for this, which I am
> > using regularly.
> >
> > Script is wrapper to what described above, so I think good to explain
> > basics, but also may worth mentioning from script, it is more user
> > friendly than above instructions.
> >
> Actually, if script can do all the basics - something I believe Stephen and
> Thomas also pointed out on a slack review earlier - then we should just
> drop the manual steps from here. If we think the script is sufficiently
> robust, we can drop them from the doc entirely, or if not, move them to an
> appendix which we reference here.
>
> /Bruce
>
[-- Attachment #2: Type: text/html, Size: 6490 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 4/6] Section 4: Running Applications
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (2 preceding siblings ...)
2023-09-20 15:48 ` [PATCH 3/6] Section 3: Setting up a System to Run DPDK Applications David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:32 ` Ferruh Yigit
2023-09-20 15:48 ` [PATCH 5/6] Section 5: Appendix David Young
` (4 subsequent siblings)
8 siblings, 1 reply; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, 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
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 4/6] Section 4: Running Applications
2023-09-20 15:48 ` [PATCH 4/6] Section 4: Running Applications David Young
@ 2023-09-25 11:32 ` Ferruh Yigit
0 siblings, 0 replies; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:32 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, 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
> 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.
>
This is not the 'examples' folder in the source code, and this is
already mentioned as 'in the DPDK distribution', but I wonder if this
requires a little more clarification.
Also this folder can be '<dpdk install dir>/share/dpdk/examples/' if
DPDK installed manually.
> +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:
> +
>
Should we mention here that running some applications requires root
privilege?
> +::
> +
> + ./build/helloworld -l 0-2
> +
> +The ``-l`` option indicates the cores on which the application should run.
> +
Should we provide a link to the eal argument documentation, which
describes '-l' and more...
> +Sample Applications Overview
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +1. **Hello World**: A basic application that prints a "hello world" message.
>
'helloworld' sample is about core management, it distributes the work
(printing "hello world") to the cores provided in the argument list,
does it worth to mention this, not sure.
Otherwise it is not clear what just printing "hello world" is good for,
and why we have a sample like this.
> +2. **Basic Forwarding**: A skeleton example of a forwarding application.
>
"packet forwarding" ??
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 5/6] Section 5: Appendix
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (3 preceding siblings ...)
2023-09-20 15:48 ` [PATCH 4/6] Section 4: Running Applications David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:33 ` Ferruh Yigit
2023-09-20 15:48 ` [PATCH 6/6] Section 6: Glossary David Young
` (3 subsequent siblings)
8 siblings, 1 reply; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, David Young
---
.../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
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 5/6] Section 5: Appendix
2023-09-20 15:48 ` [PATCH 5/6] Section 5: Appendix David Young
@ 2023-09-25 11:33 ` Ferruh Yigit
2023-09-25 11:52 ` Ferruh Yigit
2023-09-25 12:24 ` Bruce Richardson
0 siblings, 2 replies; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:33 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, 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
>
These files are put under 'appendix' folder,
and I can see these documents are linked from other 'getting started
guide' documentations, which I assume the reason to put these under
'appendix' folder.
But these are not limited to getting started, perhaps we can do a better
organization of them out of getting started appendix.
> 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.
> +
>
I think we need a sample commands, additional to description, on how to
run an application as a non-priviledged user.
> +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.
>
Applications that run without root privileges? Do we have that kind of
list in release notes?
> \ 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
> +------------------
> +
I guess this is the only documentation specific to "VFIO", (and title is
VFIO advanced), I think it can be better to start with describing VFIO,
instead of starting with no-iommu mode.
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 5/6] Section 5: Appendix
2023-09-25 11:33 ` Ferruh Yigit
@ 2023-09-25 11:52 ` Ferruh Yigit
2023-09-25 12:24 ` Bruce Richardson
1 sibling, 0 replies; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:52 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/25/2023 12:33 PM, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, 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
>>
>
> These files are put under 'appendix' folder,
> and I can see these documents are linked from other 'getting started
> guide' documentations, which I assume the reason to put these under
> 'appendix' folder.
> But these are not limited to getting started, perhaps we can do a better
> organization of them out of getting started appendix.
>
>
>
>> 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.
Mentioned sections are not in this document, so can be good to provide
link for them.
>> \ 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.
>> +
>>
>
> I think we need a sample commands, additional to description, on how to
> run an application as a non-priviledged user.
>
>
>> +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.
>>
>
> Applications that run without root privileges? Do we have that kind of
> list in release notes?
>
>
>
>> \ 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
>> +------------------
>> +
>
> I guess this is the only documentation specific to "VFIO", (and title is
> VFIO advanced), I think it can be better to start with describing VFIO,
> instead of starting with no-iommu mode.
>
>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 5/6] Section 5: Appendix
2023-09-25 11:33 ` Ferruh Yigit
2023-09-25 11:52 ` Ferruh Yigit
@ 2023-09-25 12:24 ` Bruce Richardson
1 sibling, 0 replies; 28+ messages in thread
From: Bruce Richardson @ 2023-09-25 12:24 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: David Young, dev
On Mon, Sep 25, 2023 at 12:33:52PM +0100, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, 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
> >
>
> These files are put under 'appendix' folder,
> and I can see these documents are linked from other 'getting started
> guide' documentations, which I assume the reason to put these under
> 'appendix' folder.
> But these are not limited to getting started, perhaps we can do a better
> organization of them out of getting started appendix.
>
The plan is to merge all three GSG docs into one, in which case the single
combined GSG should be the only thing referencing these. Therefore, I think
having them placed as here makes most sense.
/Bruce
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH 6/6] Section 6: Glossary
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (4 preceding siblings ...)
2023-09-20 15:48 ` [PATCH 5/6] Section 5: Appendix David Young
@ 2023-09-20 15:48 ` David Young
2023-09-25 11:43 ` Ferruh Yigit
2023-09-22 4:15 ` [PATCH 0/6] docs: Unify Getting Started Guides Tyler Retzlaff
` (2 subsequent siblings)
8 siblings, 1 reply; 28+ messages in thread
From: David Young @ 2023-09-20 15:48 UTC (permalink / raw)
To: dev; +Cc: Bruce Richardson, 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
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 6/6] Section 6: Glossary
2023-09-20 15:48 ` [PATCH 6/6] Section 6: Glossary David Young
@ 2023-09-25 11:43 ` Ferruh Yigit
0 siblings, 0 replies; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:43 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, 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
> +========
> +
> +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.
> +
BIOS seems a little too generic for DPDK context, not sure.
> +**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.
> +
"on Windows" vs "for 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.
> +
This is the only type of driver that DPDK has, and at this point term
kind of tied to DPDK, in case above can be read as this is one of the
driver types in DPDK.
> +**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.
> +
I am not sure if this is accurate, although it is not exactly wrong,
vfio.ko is a kernel module implementation for below 'vfio platform', and
allows "userspace applications (including virtual machine)" to access
physical device. Enables DPDK to directly access to the physical devices.
To prevent duplication, perhaps easier to first describe the "VFIO
Platform" and later describe vfio.ko as kernel module implementation for
"VFIO Platform" used by DPDK?
> +**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
What do you think to add 'RTE' too, it may confuse some newcomers?
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (5 preceding siblings ...)
2023-09-20 15:48 ` [PATCH 6/6] Section 6: Glossary David Young
@ 2023-09-22 4:15 ` Tyler Retzlaff
2023-09-22 14:47 ` David Marchand
2023-09-25 11:54 ` Ferruh Yigit
8 siblings, 0 replies; 28+ messages in thread
From: Tyler Retzlaff @ 2023-09-22 4:15 UTC (permalink / raw)
To: David Young; +Cc: dev, Bruce Richardson
On Wed, Sep 20, 2023 at 11:48:04AM -0400, David Young wrote:
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> consolidated into a single, streamlined guide to simplify the user experience
> and facilitate easier maintenance.
>
seems like a good idea to me. i'm assuming that the existing content is
just being re-organized. after the re-organization is complete i'll plan
to bring some of the windows specific content up to date.
thanks for doing this.
Series-acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (6 preceding siblings ...)
2023-09-22 4:15 ` [PATCH 0/6] docs: Unify Getting Started Guides Tyler Retzlaff
@ 2023-09-22 14:47 ` David Marchand
2023-09-22 15:54 ` Bruce Richardson
2023-09-25 11:54 ` Ferruh Yigit
8 siblings, 1 reply; 28+ messages in thread
From: David Marchand @ 2023-09-22 14:47 UTC (permalink / raw)
To: David Young, Bruce Richardson, Thomas Monjalon; +Cc: dev
Hello David,
On Wed, Sep 20, 2023 at 5:49 PM David Young <dave@youngcopy.com> wrote:
>
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> consolidated into a single, streamlined guide to simplify the user experience
> and facilitate easier maintenance.
>
> 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
From my understanding, existing copyright banners should be preserved
by this reorganisation work.
Yet I noticed a few Copyright banners dated 2025, please double check
and fix them.
Bruce, Thomas,
An open question, if new docs are created, who should this work be
attributed to? the dpdk contributors?
Thanks.
--
David Marchand
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-22 14:47 ` David Marchand
@ 2023-09-22 15:54 ` Bruce Richardson
0 siblings, 0 replies; 28+ messages in thread
From: Bruce Richardson @ 2023-09-22 15:54 UTC (permalink / raw)
To: David Marchand; +Cc: David Young, Thomas Monjalon, dev
On Fri, Sep 22, 2023 at 04:47:55PM +0200, David Marchand wrote:
> Hello David,
>
> On Wed, Sep 20, 2023 at 5:49 PM David Young <dave@youngcopy.com> wrote:
> >
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> > consolidated into a single, streamlined guide to simplify the user experience
> > and facilitate easier maintenance.
> >
> > 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
>
> From my understanding, existing copyright banners should be preserved
> by this reorganisation work.
> Yet I noticed a few Copyright banners dated 2025, please double check
> and fix them.
>
>
> Bruce, Thomas,
> An open question, if new docs are created, who should this work be
> attributed to? the dpdk contributors?
>
For this re-organisation, I expect the copyrights from the existing content
be preserved - merging if so necessary, e.g. a page merged from two
separate ones with differen copyright owners.
For brand new content, the way things look now, it's just likely to come from
existing DPDK experts, so they will apply their usual attributions AFAIK.
/Bruce
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-20 15:48 [PATCH 0/6] docs: Unify Getting Started Guides David Young
` (7 preceding siblings ...)
2023-09-22 14:47 ` David Marchand
@ 2023-09-25 11:54 ` Ferruh Yigit
2023-10-11 18:34 ` Dave Young
2023-10-13 16:28 ` Bruce Richardson
8 siblings, 2 replies; 28+ messages in thread
From: Ferruh Yigit @ 2023-09-25 11:54 UTC (permalink / raw)
To: David Young, dev; +Cc: Bruce Richardson
On 9/20/2023 4:48 PM, David Young wrote:
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> consolidated into a single, streamlined guide to simplify the user experience
> and facilitate easier maintenance.
>
> 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
>
Hi David,
New documentations are not in the toctree, so they are not accessible by
the links in the left column.
Sphinx generates warning for this:
WARNING: document isn't included in any toctree
Also existing per platform documentation is not removed yet.
I assume both above done intentionally for the development phase of this
documentation, but this is just a reminder in-case not.
And not all context seems moved from existing per platform getting
started guides, is there are plan to keep them around for a while as
reference, or move that context to other files?
Thanks,
ferruh
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-25 11:54 ` Ferruh Yigit
@ 2023-10-11 18:34 ` Dave Young
2023-10-13 16:28 ` Bruce Richardson
1 sibling, 0 replies; 28+ messages in thread
From: Dave Young @ 2023-10-11 18:34 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, Bruce Richardson
[-- Attachment #1: Type: text/plain, Size: 2342 bytes --]
Thank you for reviewing the patches and for your feedback.
1. Regarding the toctree, I've added the new Getting Started Guide so that
it's accessible via the links in the left column. I've tested this on my
local version, and the warning should disappear once the patch is submitted.
2. As for the existing per-platform documentation, it has not been removed
yet because I'm still in the process of developing the consolidated Getting
Started Guide. The existing documentation will remain in place for the time
being.
3. About the context not yet moved from the existing per-platform guides,
I'm considering how best to integrate this information into the new guide.
Bruce, do you have any thoughts on whether these should be kept around for
reference or moved to other files?
I plan to send updated versions of all patches in this series at the same
time, incorporating all the feedback received.
Thank you again for your time and input.
Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com
On Mon, Sep 25, 2023 at 7:54 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:
> On 9/20/2023 4:48 PM, David Young wrote:
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows have
> been
> > consolidated into a single, streamlined guide to simplify the user
> experience
> > and facilitate easier maintenance.
> >
> > 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
> >
>
> Hi David,
>
> New documentations are not in the toctree, so they are not accessible by
> the links in the left column.
> Sphinx generates warning for this:
> WARNING: document isn't included in any toctree
>
> Also existing per platform documentation is not removed yet.
>
> I assume both above done intentionally for the development phase of this
> documentation, but this is just a reminder in-case not.
>
>
> And not all context seems moved from existing per platform getting
> started guides, is there are plan to keep them around for a while as
> reference, or move that context to other files?
>
>
> Thanks,
> ferruh
>
>
[-- Attachment #2: Type: text/html, Size: 3044 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH 0/6] docs: Unify Getting Started Guides
2023-09-25 11:54 ` Ferruh Yigit
2023-10-11 18:34 ` Dave Young
@ 2023-10-13 16:28 ` Bruce Richardson
1 sibling, 0 replies; 28+ messages in thread
From: Bruce Richardson @ 2023-10-13 16:28 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: David Young, dev
On Mon, Sep 25, 2023 at 12:54:15PM +0100, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, David Young wrote:
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows
> > have been consolidated into a single, streamlined guide to simplify the
> > user experience and facilitate easier maintenance.
> >
> > 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
> >
>
> Hi David,
>
> New documentations are not in the toctree, so they are not accessible by
> the links in the left column. Sphinx generates warning for this:
> WARNING: document isn't included in any toctree
>
> Also existing per platform documentation is not removed yet.
>
> I assume both above done intentionally for the development phase of this
> documentation, but this is just a reminder in-case not.
>
>
> And not all context seems moved from existing per platform getting
> started guides, is there are plan to keep them around for a while as
> reference, or move that context to other files?
>
Part of the work in consolidating these docs is to remove any unnecessary
details. After all, these are Getting Started Guides, which should contain
only the minimal info for getting started and not much else. The more
content we have, the harder the docs become to follow. Some extra content
is moved to the appendicies, but I, for one, think we should keep these
docs as slim as possible. For example, we should document one way to do
things in the main doc. Any alternative methods should be documented via
links elsewhere.
For content that is not transferred over as part of this patchset, if there
are any concerns about omissions, I think we should discuss them on a case
by case basis. Just because something was in the original docs does not
mean it needs to go in the new one. :-)
/Bruce
^ permalink raw reply [flat|nested] 28+ messages in thread