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. > >
