@@ -31,7 +31,7 @@ The DPDK is composed of several directories:
* examples: Source code of DPDK application examples
-* config, buildtools, mk: Framework-related makefiles, scripts and configuration
+* config, buildtools: Framework-related scripts and configuration
Compiling and Installing DPDK System-wide
-----------------------------------------
@@ -39,11 +39,6 @@ Compiling and Installing DPDK System-wide
DPDK can be configured, built and installed on your system using the tools
``meson`` and ``ninja``.
-.. note::
-
- The older makefile-based build system used in older DPDK releases is
- still present and its use is described in section
- `Installation of DPDK Target Environment using Make`_.
DPDK Configuration
~~~~~~~~~~~~~~~~~~
@@ -81,6 +76,8 @@ and the last step causing the dynamic loader `ld.so` to update its cache to take
distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
+.. _adjusting_build_options:
+
Adjusting Build Options
~~~~~~~~~~~~~~~~~~~~~~~
@@ -117,6 +114,9 @@ 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.
+.. _building_app_using_installed_dpdk:
+
+
Building Applications Using Installed DPDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -140,11 +140,12 @@ and the sources for that build are stored in ``$(SRCS-y)``.
.. note::
- Unlike with the older make build system, the meson system is not
- designed to be used directly from a build directory. Instead it is
- recommended that it be installed either system-wide or to a known
- location in the user's home directory. The install location can be set
- using the `--prefix` meson option (default: `/usr/local`).
+ Unlike with the make build system present used in older DPDK releases,
+ the meson system is not designed to be used directly from a build
+ directory. Instead it is recommended that it be installed either
+ system-wide or to a known location in the user's home directory.
+ The install location can be set using the `--prefix` meson option
+ (default: `/usr/local`).
an equivalent build recipe for a simple DPDK application using meson as a
build system is shown below:
@@ -156,64 +157,3 @@ build system is shown below:
dpdk = dependency('libdpdk')
sources = files('main.c')
executable('dpdk-app', sources, dependencies: dpdk)
-
-
-Installation of DPDK Target Environment using Make
---------------------------------------------------
-
-.. note::
-
- The building of DPDK using make will be deprecated in a future release. It
- is therefore recommended that DPDK installation is done using meson and
- ninja as described above.
-
-Get a native target environment automatically::
-
- make defconfig O=mybuild
-
-.. note::
-
- Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
- which means that the compiled software is tuned for the platform on which it is built.
-
-Or get a specific target environment::
-
- make config T=x86_64-native-linux-gcc O=mybuild
-
-The format of a DPDK target is "ARCH-MACHINE-EXECENV-TOOLCHAIN".
-Available targets can be found with::
-
- make help
-
-Customize the target configuration in the generated ``.config`` file.
-Example for enabling the pcap PMD::
-
- sed -ri 's,(PMD_PCAP=).*,\1y,' mybuild/.config
-
-Compile the target::
-
- make -j4 O=mybuild
-
-.. warning::
-
- Any kernel modules to be used, e.g. ``igb_uio``, ``kni``, must be compiled with the
- same kernel as the one running on the target.
- If the DPDK is not being built on the target machine,
- the ``RTE_KERNELDIR`` environment variable should be used to point the compilation at a copy of the kernel version to be used on the target machine.
-
-Install the target in a separate directory::
-
- make install O=mybuild DESTDIR=myinstall prefix=
-
-The environment is ready to build a DPDK application::
-
- RTE_SDK=$(pwd)/myinstall/share/dpdk RTE_TARGET=x86_64-native-linux-gcc make -C myapp
-
-In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
-
-Browsing the Installed DPDK Environment Target
-----------------------------------------------
-
-Once a target is created it contains all libraries, including poll-mode drivers, and header files for the DPDK environment that are required to build customer applications.
-In addition, the test applications are built under the app directory, which may be used for testing.
-A kmod directory is also present that contains kernel modules which may be loaded if needed.
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2010-2014 Intel Corporation.
-Compiling and Running Sample Applications
+Running Sample Applications
=========================================
The chapter describes how to compile and run applications in an DPDK environment.
@@ -15,56 +15,7 @@ It also provides a pointer to where sample applications are stored.
Compiling a Sample Application
------------------------------
-Once an DPDK target environment directory has been created (such as ``x86_64-native-linux-gcc``),
-it contains all libraries and header files required to build an application.
-
-When compiling an application in the Linux* environment on the DPDK, the following variables must be exported:
-
-* ``RTE_SDK`` - Points to the DPDK installation directory.
-
-* ``RTE_TARGET`` - Points to the DPDK target environment directory.
-
-The following is an example of creating the ``helloworld`` application, which runs in the DPDK Linux environment.
-This example may be found in the ``${RTE_SDK}/examples`` directory.
-
-The directory contains the ``main.c`` file. This file, when combined with the libraries in the DPDK target environment,
-calls the various functions to initialize the DPDK environment,
-then launches an entry point (dispatch application) for each core to be utilized.
-By default, the binary is generated in the build directory.
-
-.. code-block:: console
-
- cd examples/helloworld/
- export RTE_SDK=$HOME/DPDK
- export RTE_TARGET=x86_64-native-linux-gcc
-
- make
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
-
- ls build/app
- helloworld helloworld.map
-
-.. note::
-
- In the above example, ``helloworld`` was in the directory structure of the DPDK.
- However, it could have been located outside the directory structure to keep the DPDK structure intact.
- In the following case, the ``helloworld`` application is copied to a new directory as a new starting point.
-
- .. code-block:: console
-
- export RTE_SDK=/home/user/DPDK
- cp -r $(RTE_SDK)/examples/helloworld my_rte_app
- cd my_rte_app/
- export RTE_TARGET=x86_64-native-linux-gcc
-
- make
- CC main.o
- LD helloworld
- INSTALL-APP helloworld
- INSTALL-MAP helloworld.map
+Please refer to :ref:`building_app_using_installed_dpdk` for detail on compiling sample apps.
Running a Sample Application
----------------------------
@@ -168,7 +119,7 @@ Copy the DPDK application binary to your target, then run the application as fol
(assuming the platform has four memory channels per processor socket,
and that cores 0-3 are present and are to be used for running the application)::
- ./helloworld -l 0-3 -n 4
+ ./dpdk-helloworld -l 0-3 -n 4
.. note::
@@ -232,19 +183,7 @@ If the DPDK cannot allocate enough memory on each socket, the EAL initialization
Additional Sample Applications
------------------------------
-Additional sample applications are included in the ${RTE_SDK}/examples directory.
+Additional sample applications are included in the DPDK examples directory.
These sample applications may be built and run in a manner similar to that described in earlier sections in this manual.
In addition, see the *DPDK Sample Applications User Guide* for a description of the application,
specific instructions on compilation and execution and some explanation of the code.
-
-Additional Test Applications
-----------------------------
-
-In addition, there are two other applications that are built when the libraries are created.
-The source files for these are in the DPDK/app directory and are called test and testpmd.
-Once the libraries are created, they can be found in the build/app directory.
-
-* The test application provides a variety of specific tests for the various functions in the DPDK.
-
-* The testpmd application provides a number of different packet throughput tests and
- examples of features such as how to use the Flow Director found in the Intel® 82599 10 Gigabit Ethernet Controller.
@@ -67,7 +67,7 @@ Augment the cross toolchain with NUMA support
.. note::
- This way is optional, an alternative is to use extra CFLAGS and LDFLAGS, depicted in :ref:`configure_and_cross_compile_dpdk_build` below.
+ This way is optional, an alternative is to use extra CFLAGS and LDFLAGS.
Copy the NUMA header files and lib to the cross compiler's directories:
@@ -79,8 +79,8 @@ Copy the NUMA header files and lib to the cross compiler's directories:
.. _configure_and_cross_compile_dpdk_build:
-Cross Compiling DPDK using Meson
---------------------------------
+Cross Compiling DPDK
+--------------------
Meson depends on pkgconfig to find the dependencies.
The package ``pkg-config-aarch64-linux-gnu`` is required for aarch64.
@@ -99,45 +99,3 @@ command::
meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
ninja -C arm64-build
-
-Configure and Cross Compile DPDK using Make
--------------------------------------------
-To configure a build, choose one of the target configurations, like arm64-dpaa-linux-gcc and arm64-thunderx-linux-gcc.
-
-.. code-block:: console
-
- make config T=arm64-armv8a-linux-gcc
-
-To cross-compile, without compiling the kernel modules, use the following command:
-
-.. code-block:: console
-
- make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n
-
-To cross-compile, including the kernel modules, the kernel source tree needs to be specified by setting
-RTE_KERNELDIR:
-
-.. code-block:: console
-
- make -j CROSS=aarch64-linux-gnu- RTE_KERNELDIR=<kernel_src_rootdir> CROSS_COMPILE=aarch64-linux-gnu-
-
-To compile for non-NUMA targets, without compiling the kernel modules, use the following command:
-
-.. code-block:: console
-
- make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n CONFIG_RTE_LIBRTE_VHOST_NUMA=n CONFIG_RTE_EAL_NUMA_AWARE_HUGEPAGES=n
-
-.. note::
-
- 1. EXTRA_CFLAGS and EXTRA_LDFLAGS should be added to include the NUMA headers and link the library respectively,
- if the above step :ref:`augment_the_cross_toolchain_with_numa_support` was skipped therefore the toolchain was not
- augmented with NUMA support.
-
- 2. "-isystem <numa_install_dir>/include" should be add to EXTRA_CFLAGS, otherwise the numa.h file will get a lot of compiling
- errors of Werror=cast-qual, Werror=strict-prototypes and Werror=old-style-definition.
-
- An example is given below:
-
- .. code-block:: console
-
- make -j CROSS=aarch64-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n EXTRA_CFLAGS="-isystem <numa_install_dir>/include" EXTRA_LDFLAGS="-L<numa_install_dir>/lib -lnuma"
@@ -41,7 +41,9 @@ Enabling HPET in the DPDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, HPET support is disabled in the DPDK build configuration files.
-To use HPET, the ``CONFIG_RTE_LIBEAL_USE_HPET`` setting should be changed to ``y``, which will enable the HPET settings at compile time.
+To use HPET, use the following meson build option which will enable the HPET settings at compile time::
+
+ meson configure -Duse_hpet=true
For an application to use the ``rte_get_hpet_cycles()`` and ``rte_get_hpet_hz()`` API calls,
and optionally to make the HPET the default time source for the rte_timer library,
@@ -128,13 +130,8 @@ Loading the DPDK KNI Kernel Module
----------------------------------
To run the DPDK Kernel NIC Interface (KNI) sample application, an extra kernel module (the kni module) must be loaded into the running kernel.
-The module is found in the kmod sub-directory of the DPDK target directory.
-Similar to the loading of the ``igb_uio`` module, this module should be loaded using the insmod command as shown below
-(assuming that the current directory is the DPDK target directory):
-
-.. code-block:: console
-
- insmod kmod/rte_kni.ko
+The module is found in the kernel/linux sub-directory of the DPDK build directory.
+This can be enabled in the same way as the ``igb_uio`` module, please see :ref:`load_uio` for details.
.. note::
@@ -23,7 +23,7 @@ The following is a list of DPDK documents in the suggested reading order:
* The software architecture and how to use it (through examples), specifically in a Linux application (linux) environment
- * The content of the DPDK, the build system (including the commands that can be used in the root DPDK Makefile to build the development kit and
+ * The content of the DPDK, the build system (including the commands that can be used to build the development kit and
an application) and guidelines for porting an application
* Optimizations used in the software and those that should be considered for new development
@@ -12,6 +12,9 @@ Different PMDs may require different kernel drivers in order to work properly.
Depends on the PMD being used, a corresponding kernel driver should be load
and bind to the network ports.
+.. _load_uio:
+
+
UIO
---
@@ -28,19 +31,20 @@ can provide the uio capability. This module can be loaded using the command:
``uio_pci_generic`` module doesn't support the creation of virtual functions.
As an alternative to the ``uio_pci_generic``, the DPDK also includes the igb_uio
-module which can be found in the kmod subdirectory referred to above. It can
+module which can be found in the kernel/linux subdirectory referred to above. It can
be loaded as shown below:
.. code-block:: console
sudo modprobe uio
- sudo insmod kmod/igb_uio.ko
+ sudo insmod <build_dir>/kernel/linux/igb_uio/igb_uio.ko
.. note::
- ``igb_uio`` module is disabled by default starting from ``DPDK v20.02``.
- To build it, the config option ``CONFIG_RTE_EAL_IGB_UIO`` should be enabled.
- It is planned to move ``igb_uio`` module to a different git repository.
+ Building DPDK Linux kernel modules is disabled by default starting from DPDK v20.02.
+ To enable them again, the config option "enable_kmods" needs to be set in the meson
+ build configuration. See :ref:`adjusting_build_options` for details on how to set/clear
+ build options. It is planned to move ``igb_uio`` module to a different git repository.
.. note::
@@ -104,11 +108,11 @@ parameter ``--vfio-vf-token``.
3. echo 2 > /sys/bus/pci/devices/0000:86:00.0/sriov_numvfs
4. Start the PF:
- ./x86_64-native-linux-gcc/app/testpmd -l 22-25 -n 4 -w 86:00.0 \
+ ./<build_dir>/app/dpdk-testpmd -l 22-25 -n 4 -w 86:00.0 \
--vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=pf -- -i
5. Start the VF:
- ./x86_64-native-linux-gcc/app/testpmd -l 26-29 -n 4 -w 86:02.0 \
+ ./<build_dir>/app/dpdk-testpmd -l 26-29 -n 4 -w 86:02.0 \
--vfio-vf-token=14d63f20-8445-11ea-8900-1f9ce7d5650d --file-prefix=vf0 -- -i
Also, to use VFIO, both kernel and BIOS must support and be configured to use IO virtualization (such as Intel® VT-d).
@@ -37,17 +37,13 @@ Compilation of the DPDK
The setup commands and installed packages needed on various systems may be different.
For details on Linux distributions and the versions tested, please consult the DPDK Release Notes.
-* General development tools including ``make``, and a supported C compiler such as ``gcc`` (version 4.9+) or ``clang`` (version 3.4+).
+* General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+).
* For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
* For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
-* Python, recommended version 3.5+.
-
- * Python v3.5+ is needed to build DPDK using meson and ninja
-
- * Python 2.7+ or 3.2+, to use various helper scripts included in the DPDK package.
+* Python, v3.5 or later.
* Meson (version 0.47.1+) and ninja
@@ -82,12 +78,8 @@ Compilation of the DPDK
**Additional Libraries**
A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
-For DPDK builds using meson, the presence or absence of these dependencies will be
-automatically detected enabling or disabling the relevant components appropriately.
-
-For builds using make, these components are disabled in the default configuration and
-need to be enabled manually by changing the relevant setting to "y" in the build configuration file
-i.e. the ``.config`` file in the build folder.
+For DPDK builds, the presence or absence of these dependencies will be automatically detected
+enabling or disabling the relevant components appropriately.
In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.