From: Ferruh Yigit <ferruh.yigit@amd.com>
To: David Young <dave@youngcopy.com>, dev@dpdk.org
Cc: Bruce Richardson <bruce.richardson@intel.com>
Subject: Re: [PATCH 5/6] Section 5: Appendix
Date: Mon, 25 Sep 2023 12:33:52 +0100 [thread overview]
Message-ID: <2d67e056-8020-4153-9494-08c264496254@amd.com> (raw)
In-Reply-To: <20230920154817.617-6-dave@youngcopy.com>
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.
next prev parent reply other threads:[~2023-09-25 11:33 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
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-25 11:30 ` Ferruh Yigit
2023-10-11 18:26 ` Dave Young
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
2023-10-12 18:08 ` Dave Young
2023-10-17 13:37 ` Tyler Retzlaff
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
2023-10-12 17:32 ` Dave Young
2023-09-20 15:48 ` [PATCH 4/6] Section 4: Running Applications David Young
2023-09-25 11:32 ` Ferruh Yigit
2023-09-20 15:48 ` [PATCH 5/6] Section 5: Appendix David Young
2023-09-25 11:33 ` Ferruh Yigit [this message]
2023-09-25 11:52 ` Ferruh Yigit
2023-09-25 12:24 ` Bruce Richardson
2023-09-20 15:48 ` [PATCH 6/6] Section 6: Glossary David Young
2023-09-25 11:43 ` Ferruh Yigit
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
2023-10-11 18:34 ` Dave Young
2023-10-13 16:28 ` Bruce Richardson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=2d67e056-8020-4153-9494-08c264496254@amd.com \
--to=ferruh.yigit@amd.com \
--cc=bruce.richardson@intel.com \
--cc=dave@youngcopy.com \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).