-.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-Compiling the Intel® DPDK Target from Source
-============================================
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2015 Intel Corporation.
-.. note::
-
- Parts of this process can also be done using the setup script described in Chapter 6 of this document.
-
-Install the Intel® DPDK and Browse Sources
-------------------------------------------
-
-First, uncompress the archive and move to the uncompressed Intel® DPDK source directory:
-
-.. code-block:: console
-
- user@host:~$ unzip DPDK-<version>.zip
- user@host:~$ cd DPDK-<version>
- user@host:~/DPDK-<version>$ ls
- app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile mk/ scripts/ tools/
-
-The Intel® DPDK is composed of several directories:
-
-* lib: Source code of Intel® DPDK libraries
-
-* app: Source code of Intel® DPDK applications (automatic tests)
-
-* examples: Source code of Intel® DPDK application examples
-
-* config, tools, scripts, mk: Framework-related makefiles, scripts and configuration
-
-Installation of Intel® DPDK Target Environments
------------------------------------------------
+.. _linux_gsg_compiling_dpdk:
-The format of a Intel® DPDK target is:
-
- ARCH-MACHINE-EXECENV-TOOLCHAIN
-
-where:
-
-* ARCH can be: i686, x86_64
-
-* MACHINE can be: native, ivshmem
-
-* EXECENV can be: linuxapp, bsdapp
-
-* TOOLCHAIN can be: gcc, icc
-
-The targets to be installed depend on the 32-bit and/or 64-bit packages and compilers installed on the host.
-Available targets can be found in the DPDK/config directory.
-The defconfig\_ prefix should not be used.
+Compiling the DPDK Target from Source
+=====================================
.. note::
- Configuration files are provided with the RTE_MACHINE optimization level set.
- 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.
- For more information on this setting, and its possible values, see the *Intel® DPDK Programmers Guide*.
-
-When using the Intel® C++ Compiler (icc), one of the following commands should be invoked for 64-bit or 32-bit use respectively.
-Notice that the shell scripts update the $PATH variable and therefore should not be performed in the same session.
-Also, verify the compiler's installation directory since the path may be different:
-
-.. code-block:: console
-
- source /opt/intel/bin/iccvars.sh intel64
- source /opt/intel/bin/iccvars.sh ia32
-
-To install and make targets, use the make install T=<target> command in the top-level Intel® DPDK directory.
-
-For example, to compile a 64-bit target using icc, run:
+ Parts of this process can also be done using the setup script described in
+ the :ref:`linux_setup_script` section of this document.
-.. code-block:: console
-
- make install T=x86_64-native-linuxapp-icc
+Uncompress DPDK and Browse Sources
+----------------------------------
-To compile a 32-bit build using gcc, the make command should be:
+First, uncompress the archive and move to the uncompressed DPDK source directory:
.. code-block:: console
- make install T=i686-native-linuxapp-gcc
-
-To compile all 64-bit targets using gcc, use:
-
-.. code-block:: console
-
- make install T=x86_64*gcc
-
-To compile all 64-bit targets using both gcc and icc, use:
-
-.. code-block:: console
-
- make install T=x86_64-*
-
-.. note::
-
- The wildcard operator (*) can be used to create multiple targets at the same time.
+ tar xJf dpdk-<version>.tar.xz
+ cd dpdk-<version>
-To prepare a target without building it, for example, if the configuration changes need to be made before compilation,
-use the make config T=<target> command:
+The DPDK is composed of several directories:
-.. code-block:: console
+* lib: Source code of DPDK libraries
- make config T=x86_64-native-linuxapp-gcc
+* drivers: Source code of DPDK poll-mode drivers
-.. warning::
+* app: Source code of DPDK applications (automatic tests)
- The igb_uio module must be compiled with the same kernel as the one running on the target.
- If the Intel® 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.
+* examples: Source code of DPDK application examples
-Once the target environment is created, the user may move to the target environment directory and continue to make code changes and re-compile.
-The user may also make modifications to the compile-time Intel® DPDK configuration by editing the .config file in the build directory.
-(This is a build-local copy of the defconfig file from the top- level config directory).
+* config, buildtools: Framework-related scripts and configuration
-.. code-block:: console
+Compiling and Installing DPDK System-wide
+-----------------------------------------
- cd x86_64-native-linuxapp-gcc
- vi .config
- make
+DPDK can be configured, built and installed on your system using the tools
+``meson`` and ``ninja``.
-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 Intel® DPDK Environment Target
------------------------------------------------------
+DPDK Configuration
+~~~~~~~~~~~~~~~~~~
-Once a target is created it contains all libraries and header files for the Intel® DPDK environment that are required to build customer applications.
-In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing.
-In the case of Linux, a kmod directory is also present that contains a module to install:
+To configure a DPDK build use:
.. code-block:: console
- $ ls x86_64-native-linuxapp-gcc
- app build hostapp include kmod lib Makefile
+ meson <options> build
-Loading the Intel® DPDK igb_uio Module
---------------------------------------
+where "build" is the desired output build directory, and "<options>" can be
+empty or one of a number of meson or DPDK-specific build options, described
+later in this section. The configuration process will finish with a summary
+of what DPDK libraries and drivers are to be built and installed, and for
+each item disabled, a reason why that is the case. This information can be
+used, for example, to identify any missing required packages for a driver.
-To run any Intel® DPDK application, the igb_uio module can be loaded into the running kernel.
-The module is found in the kmod sub-directory of the Intel® DPDK target directory.
-This module should be loaded using the insmod command as shown below (assuming that the current directory is the Intel® DPDK target directory).
-In many cases, the uio support in the Linux* kernel is compiled as a module rather than as part of the kernel,
-so it is often necessary to load the uio module first:
+Once configured, to build and then install DPDK system-wide use:
.. code-block:: console
- sudo modprobe uio
- sudo insmod kmod/igb_uio.ko
-
-Since Intel® DPDK release 1.7 provides VFIO support, compilation and use of igb_uio module has become optional for platforms that support using VFIO.
-
-Loading VFIO Module
--------------------
-
-To run an Intel® DPDK application and make use of VFIO, the vfio-pci module must be loaded:
-
-.. code-block:: console
+ cd build
+ ninja
+ ninja install
+ ldconfig
- sudo modprobe vfio-pci
+The last two commands above generally need to be run as root,
+with the `ninja install` step copying the built objects to their final system-wide locations,
+and the last step causing the dynamic loader `ld.so` to update its cache to take account of the new objects.
-Note that in order to use VFIO, your kernel must support it.
-VFIO kernel modules have been included in the Linux kernel since version 3.6.0 and are usually present by default,
-however please consult your distributions documentation to make sure that is the case.
+.. note::
-Also, to use VFIO, both kernel and BIOS must support and be configured to use IO virtualization (such as Intel® VT-d).
+ On some linux distributions, such as Fedora or Redhat, paths in `/usr/local` are
+ not in the default paths for the loader. Therefore, on these
+ distributions, `/usr/local/lib` and `/usr/local/lib64` should be added
+ to a file in `/etc/ld.so.conf.d/` before running `ldconfig`.
-For proper operation of VFIO when running Intel® DPDK applications as a non-privileged user, correct permissions should also be set up.
-This can be done by using the Intel® DPDK setup script (called setup.sh and located in the tools directory).
+.. _adjusting_build_options:
-Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules
-----------------------------------------------------------------------
+Adjusting Build Options
+~~~~~~~~~~~~~~~~~~~~~~~
-As of release 1.4, Intel® DPDK applications no longer automatically unbind all supported network ports from the kernel driver in use.
-Instead, all ports that are to be used by an Intel® DPDK application must be bound to the igb_uio or vfio-pci module before the application is run.
-Any network ports under Linux* control will be ignored by the Intel® DPDK poll-mode drivers and cannot be used by the application.
+DPDK has a number of options that can be adjusted as part of the build configuration process.
+These options can be listed by running ``meson configure`` inside a configured build folder.
+Many of these options come from the "meson" tool itself and can be seen documented on the
+`Meson Website <https://mesonbuild.com/Builtin-options.html>`_.
-.. warning::
+For example, to change the build-type from the default, "debugoptimized",
+to a regular "debug" build, you can either:
- The Intel® DPDK will, by default, no longer automatically unbind network ports from the kernel driver at startup.
- Any ports to be used by an Intel® DPDK application must be unbound from Linux* control and bound to the igb_uio or vfio-pci module before the application is run.
+* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially
-To bind ports to the igb_uio or vfio-pci module for Intel® DPDK use, and then subsequently return ports to Linux* control,
-a utility script called dpdk_nic _bind.py is provided in the tools subdirectory.
-This utility can be used to provide a view of the current state of the network ports on the system,
-and to bind and unbind those ports from the different kernel modules, including igb_uio and vfio-pci.
-The following are some examples of how the script can be used.
-A full description of the script and its parameters can be obtained by calling the script with the --help or --usage options.
+* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run.
-.. warning::
+Other options are specific to the DPDK project but can be adjusted similarly.
+To set the "max_lcores" value to 256, for example, you can either:
- Due to the way VFIO works, there are certain limitations to which devices can be used with VFIO.
- Mainly it comes down to how IOMMU groups work.
- Any Virtual Function device can be used with VFIO on its own, but physical devices will require either all ports bound to VFIO,
- or some of them bound to VFIO while others not being bound to anything at all.
+* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially
- If your device is behind a PCI-to-PCI bridge, the bridge will then be part of the IOMMU group in which your device is in.
- Therefore, the bridge driver should also be unbound from the bridge PCI device for VFIO to work with devices behind the bridge.
+* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run.
-.. warning::
+Some of the DPDK sample applications in the `examples` directory can be
+automatically built as part of a meson build too.
+To do so, pass a comma-separated list of the examples to build to the
+`-Dexamples` meson option as below::
- While any user can run the dpdk_nic_bind.py script to view the status of the network ports,
- binding or unbinding network ports requires root privileges.
+ meson -Dexamples=l2fwd,l3fwd build
-To see the status of all network ports on the system:
+As with other meson options, this can also be set post-initial-config using `meson configure` in the build directory.
+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.
-.. code-block:: console
+.. _building_app_using_installed_dpdk:
- root@host:DPDK# ./tools/dpdk_nic_bind.py --status
+Building Applications Using Installed DPDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Network devices using IGB_UIO driver
- ====================================
- 0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=igb_uio unused=ixgbe
- 0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=igb_uio unused=ixgbe
+When installed system-wide, DPDK provides a pkg-config file ``libdpdk.pc`` for applications to query as part of their build.
+It's recommended that the pkg-config file be used, rather than hard-coding the parameters (cflags/ldflags)
+for DPDK into the application build process.
- Network devices using kernel driver
- ===================================
- 0000:04:00.0 'I350 Gigabit Network Connection' if=em0 drv=igb unused=igb_uio *Active*
- 0000:04:00.1 'I350 Gigabit Network Connection' if=eth1 drv=igb unused=igb_uio
- 0000:04:00.2 'I350 Gigabit Network Connection' if=eth2 drv=igb unused=igb_uio
- 0000:04:00.3 'I350 Gigabit Network Connection' if=eth3 drv=igb unused=igb_uio
+An example of how to query and use the pkg-config file can be found in the ``Makefile`` of each of the example applications included with DPDK.
+A simplified example snippet is shown below, where the target binary name has been stored in the variable ``$(APP)``
+and the sources for that build are stored in ``$(SRCS-y)``.
- Other network devices
- =====================
- <none>
+.. code-block:: makefile
-To bind device eth1, 04:00.1, to the igb_uio driver:
+ PKGCONF = pkg-config
-.. code-block:: console
+ CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk)
+ LDFLAGS += $(shell $(PKGCONF) --libs libdpdk)
- root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio 04:00.1
+ $(APP): $(SRCS-y) Makefile
+ $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS)
-or, alternatively,
+.. note::
-.. code-block:: console
+ Unlike with the make build system present 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`).
- root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio eth1
+an equivalent build recipe for a simple DPDK application using meson as a
+build system is shown below:
-To restore device 82:00.0 to its original kernel binding:
+.. code-block:: python
-.. code-block:: console
+ project('dpdk-app', 'c')
- root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=ixgbe 82:00.0
+ dpdk = dependency('libdpdk')
+ sources = files('main.c')
+ executable('dpdk-app', sources, dependencies: dpdk)