X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Flinux_gsg%2Fbuild_dpdk.rst;h=f78eef25174e9ae2badf138c5abfbceac83e04b7;hb=e50cb2233128d97a22c352c34e52af2925a702b9;hp=ee6cb69b33b276ec20014479f59acad7ae4894a8;hpb=aae5e11e847ec0b07b00c14564fdef787a0f3595;p=dpdk.git diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst index ee6cb69b33..f78eef2517 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -1,270 +1,181 @@ -.. 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:: +.. _linux_gsg_compiling_dpdk: - Parts of this process can also be done using the setup script described in Chapter 6 of this document. +Compiling the DPDK Target from Source +===================================== -Install the Intel® DPDK and Browse Sources ------------------------------------------- +Uncompress DPDK and Browse Sources +---------------------------------- -First, uncompress the archive and move to the uncompressed Intel® DPDK source directory: +First, uncompress the archive and move to the uncompressed DPDK source directory: .. code-block:: console - user@host:~$ unzip DPDK-.zip - user@host:~$ cd DPDK- - user@host:~/DPDK-$ 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 ------------------------------------------------ - -The format of a Intel® DPDK target is: - - ARCH-MACHINE-EXECENV-TOOLCHAIN - -where: - -* ARCH can be: i686, x86_64 + tar xJf dpdk-.tar.xz + cd dpdk- -* MACHINE can be: native, ivshmem +The DPDK is composed of several directories: -* EXECENV can be: linuxapp, bsdapp +* lib: Source code of DPDK libraries -* TOOLCHAIN can be: gcc, icc +* drivers: Source code of DPDK poll-mode drivers -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. +* app: Source code of DPDK applications (automatic tests) -.. note:: +* examples: Source code of DPDK application examples - 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*. +* config, buildtools: Framework-related scripts and configuration -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: +Compiling and Installing DPDK System-wide +----------------------------------------- -.. code-block:: console +DPDK can be configured, built and installed on your system using the tools +``meson`` and ``ninja``. - source /opt/intel/bin/iccvars.sh intel64 - source /opt/intel/bin/iccvars.sh ia32 -To install and make targets, use the make install T= command in the top-level Intel® DPDK directory. +DPDK Configuration +~~~~~~~~~~~~~~~~~~ -For example, to compile a 64-bit target using icc, run: +To configure a DPDK build use: .. code-block:: console - make install T=x86_64-native-linuxapp-icc - -To compile a 32-bit build using gcc, the make command should be: + meson build -.. code-block:: console - - make install T=i686-native-linuxapp-gcc +where "build" is the desired output build directory, and "" 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 compile all 64-bit targets using gcc, use: +Once configured, to build and then install DPDK system-wide use: .. code-block:: console - make install T=x86_64*gcc + cd build + ninja + ninja install + ldconfig -To compile all 64-bit targets using both gcc and icc, use: - -.. code-block:: console - - make install T=x86_64-* +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:: - The wildcard operator (*) can be used to create multiple targets at the same time. - -To prepare a target without building it, for example, if the configuration changes need to be made before compilation, -use the make config T= command: - -.. code-block:: console - - make config T=x86_64-native-linuxapp-gcc - -.. warning:: - - 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. - -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). - -.. code-block:: console - - cd x86_64-native-linuxapp-gcc - vi .config - make - -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 ------------------------------------------------------ - -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: - -.. code-block:: console - - $ ls x86_64-native-linuxapp-gcc - app build hostapp include kmod lib Makefile + 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`. -Loading the Intel® DPDK igb_uio Module --------------------------------------- +.. _adjusting_build_options: -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: +Adjusting Build Options +~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: console +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 `_. - sudo modprobe uio - sudo insmod kmod/igb_uio.ko +For example, to change the build-type from the default, "debugoptimized", +to a regular "debug" build, you can either: -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. +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially -Loading VFIO Module -------------------- +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run. -To run an Intel® DPDK application and make use of VFIO, the vfio-pci module must be loaded: +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: -.. code-block:: console +* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially - sudo modprobe vfio-pci +* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run. -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. +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:: -Also, to use VFIO, both kernel and BIOS must support and be configured to use IO virtualization (such as Intel® VT-d). + meson -Dexamples=l2fwd,l3fwd build -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). +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. -Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules ----------------------------------------------------------------------- -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. +Building 32-bit DPDK on 64-bit Systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. warning:: +To build a 32-bit copy of DPDK on a 64-bit OS, +the ``-m32`` flag should be passed to the compiler and linker +to force the generation of 32-bit objects and binaries. +This can be done either by setting ``CFLAGS`` and ``LDFLAGS`` in the environment, +or by passing the value to meson using ``-Dc_args=-m32`` and ``-Dc_link_args=-m32``. +For correctly identifying and using any dependency packages, +the ``pkg-config`` tool must also be configured +to look in the appropriate directory for .pc files for 32-bit libraries. +This is done by setting ``PKG_CONFIG_LIBDIR`` to the appropriate path. - 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. +The following meson command can be used on RHEL/Fedora systems to configure a 32-bit build, +assuming the relevant 32-bit development packages, such as a 32-bit libc, are installed:: -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. + PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig \ + meson -Dc_args='-m32' -Dc_link_args='-m32' build -.. warning:: +For Debian/Ubuntu systems, the equivalent command is:: - 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. + PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig \ + meson -Dc_args='-m32' -Dc_link_args='-m32' build - 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. +Once the build directory has been configured, +DPDK can be compiled using ``ninja`` as described above. -.. warning:: - 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. +.. _building_app_using_installed_dpdk: -To see the status of all network ports on the system: +Building Applications Using Installed DPDK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: console +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. - root@host:DPDK# ./tools/dpdk_nic_bind.py --status +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)``. - 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 +.. code-block:: makefile - 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 + PKGCONF = pkg-config - Other network devices - ===================== - + CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk) + LDFLAGS += $(shell $(PKGCONF) --libs libdpdk) -To bind device eth1, 04:00.1, to the igb_uio driver: + $(APP): $(SRCS-y) Makefile + $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) -.. code-block:: console - - root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio 04:00.1 +.. note:: -or, alternatively, + 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`). -.. code-block:: console +an equivalent build recipe for a simple DPDK application using meson as a +build system is shown below: - root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=igb_uio eth1 +.. code-block:: python -To restore device 82:00.0 to its original kernel binding: - -.. 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)