X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Flinux_gsg%2Fbuild_dpdk.rst;h=1d867dedf68477bae193229cc60a1d9543cc344f;hb=08b1d50543dea1a9e817f67f4b97ea22347e2a09;hp=e32afd5f8af849b2c56321d0a5125f35dee0aa7a;hpb=0db52e6694bfcf2f0c1437ebdcb97b34864efba0;p=dpdk.git diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst index e32afd5f8a..1d867dedf6 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2010-2015 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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2015 Intel Corporation. .. _linux_gsg_compiling_dpdk: @@ -38,8 +11,8 @@ Compiling the DPDK Target from Source Parts of this process can also be done using the setup script described in the :ref:`linux_setup_script` section of this document. -Install the DPDK and Browse Sources ------------------------------------ +Uncompress DPDK and Browse Sources +---------------------------------- First, uncompress the archive and move to the uncompressed DPDK source directory: @@ -58,88 +31,127 @@ 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 -Installation of DPDK Target Environments ----------------------------------------- +Compiling and Installing DPDK System-wide +----------------------------------------- -The format of a DPDK target is:: +DPDK can be configured, built and installed on your system using the tools +``meson`` and ``ninja``. - ARCH-MACHINE-EXECENV-TOOLCHAIN -where: +DPDK Configuration +~~~~~~~~~~~~~~~~~~ -* ``ARCH`` can be: ``i686``, ``x86_64``, ``ppc_64`` +To configure a DPDK build use: -* ``MACHINE`` can be: ``native``, ``power8`` +.. code-block:: console + + meson build + +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. + +Once configured, to build and then install DPDK system-wide use: -* ``EXECENV`` can be: ``linuxapp``, ``bsdapp`` +.. code-block:: console -* ``TOOLCHAIN`` can be: ``gcc``, ``icc`` + cd build + ninja + ninja install + ldconfig -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. +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:: - 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 *DPDK Programmers Guide*. + 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`. -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: +.. _adjusting_build_options: -.. code-block:: console +Adjusting Build Options +~~~~~~~~~~~~~~~~~~~~~~~ - source /opt/intel/bin/iccvars.sh intel64 - source /opt/intel/bin/iccvars.sh ia32 +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 `_. -To install and make targets, use the ``make install T=`` command in the top-level DPDK directory. +For example, to change the build-type from the default, "debugoptimized", +to a regular "debug" build, you can either: -For example, to compile a 64-bit target using icc, run: +* pass ``-Dbuildtype=debug`` or ``--buildtype=debug`` to meson when configuring the build folder initially -.. code-block:: console +* run ``meson configure -Dbuildtype=debug`` inside the build folder after the initial meson run. - make install T=x86_64-native-linuxapp-icc +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: -To compile a 32-bit build using gcc, the make command should be: +* pass ``-Dmax_lcores=256`` to meson when configuring the build folder initially -.. code-block:: console +* run ``meson configure -Dmax_lcores=256`` inside the build folder after the initial meson run. - make install T=i686-native-linuxapp-gcc +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:: -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: + meson -Dexamples=l2fwd,l3fwd build -.. code-block:: console +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. - make config T=x86_64-native-linuxapp-gcc +.. _building_app_using_installed_dpdk: -.. warning:: +Building Applications Using Installed DPDK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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. +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. -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 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). +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)``. -.. code-block:: console +.. code-block:: makefile + + PKGCONF = pkg-config + + CFLAGS += -O3 $(shell $(PKGCONF) --cflags libdpdk) + LDFLAGS += $(shell $(PKGCONF) --libs libdpdk) + + $(APP): $(SRCS-y) Makefile + $(CC) $(CFLAGS) $(SRCS-y) -o $@ $(LDFLAGS) + +.. note:: + + 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`). - cd x86_64-native-linuxapp-gcc - vi .config - make +an equivalent build recipe for a simple DPDK application using meson as a +build system is shown below: -In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code. +.. code-block:: python -Browsing the Installed DPDK Environment Target ----------------------------------------------- + project('dpdk-app', 'c') -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 and testpmd applications are built under the build/app directory, which may be used for testing. -A kmod directory is also present that contains kernel modules which may be loaded if needed. + dpdk = dependency('libdpdk') + sources = files('main.c') + executable('dpdk-app', sources, dependencies: dpdk)