-.. 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.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
System Requirements
===================
-This chapter describes the packages required to compile the Intel® DPDK.
+This chapter describes the packages required to compile the DPDK.
.. note::
- If the Intel® DPDK is being used on an Intel® Communications Chipset 89xx Series platform,
- please consult the *Intel® Communications Chipset 89xx Series Software for Linux* Getting Started Guide*.
+ If the DPDK is being used on an Intel® Communications Chipset 89xx Series platform,
+ please consult the *Intel® Communications Chipset 89xx Series Software for Linux Getting Started Guide*.
-BIOS Setting Prerequisite
--------------------------
+BIOS Setting Prerequisite on x86
+--------------------------------
-For the majority of platforms, no special BIOS settings are needed to use basic Intel® DPDK functionality.
+For the majority of platforms, no special BIOS settings are needed to use basic DPDK functionality.
However, for additional HPET timer and power management functionality,
-and high performance of small packets on 40G NIC, BIOS setting changes may be needed.
-Consult :ref:`Chapter 5. Enabling Additional Functionality <Enabling_Additional_Functionality>`
+and high performance of small packets, BIOS setting changes may be needed.
+Consult the section on :ref:`Enabling Additional Functionality <Enabling_Additional_Functionality>`
for more information on the required changes.
-Compilation of the Intel® DPDK
-------------------------------
-
-**Required Tools:**
-
.. note::
- Testing has been performed using Fedora* 18. The setup commands and installed packages needed on other systems may be different.
- For details on other Linux distributions and the versions tested, please consult the Intel® DPDK Release Notes.
+ If UEFI secure boot is enabled, the Linux kernel may disallow the use of
+ UIO on the system. Therefore, devices for use by DPDK should be bound to the
+ ``vfio-pci`` kernel module rather than ``igb_uio`` or ``uio_pci_generic``.
+ For more details see :ref:`linux_gsg_binding_kernel`.
-* GNU make
+Compilation of the DPDK
+-----------------------
-* coreutils: cmp, sed, grep, arch
+**Required Tools and Libraries:**
-* gcc: versions 4.5.x or later is recommended.
- On some distributions, some specific compiler flags and linker flags are enabled by default and
- affect performance (- fstack-protector, for example).
- Please refer to the documentation of your distribution and to gcc -dumpspecs.
+.. note::
-* libc headers (glibc-devel.i686 / libc6-dev-i386; glibc-devel.x86_64 for 64-bit compilation)
+ 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.
-* Linux kernel headers or sources required to build kernel modules. (kernel- devel.x86_64)
+* General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+).
-* Additional packages required for 32-bit compilation on 64-bit systems are:
+ * For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"``
- glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686
+ * For Ubuntu/Debian systems these can be installed using ``apt install build-essential``
-* Python, version 2.6 or 2.7, to use various helper scripts included in the Intel® DPDK package
+* Python 3.5 or later.
+* Meson (version 0.47.1+) and ninja
-**Optional Tools:**
+ * ``meson`` & ``ninja-build`` packages in most Linux distributions
-* Intel® C++ Compiler (icc). For installation, additional libraries may be required.
- See the icc Installation Guide found in the Documentation directory under the compiler installation.
- This release has been tested using version 12.1.
+ * If the packaged version is below the minimum version, the latest versions
+ can be installed from Python's "pip" repository: ``pip3 install meson ninja``
-* libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver.
- This driver is disabled by default and can be enabled by setting CONFIG_RTE_LIBRTE_PMD_PCAP=y in the build time config file.
+* ``pyelftools`` (version 0.22+)
-Running Intel® DPDK Applications
---------------------------------
+ * For Fedora systems it can be installed using ``dnf install python-pyelftools``
-To run an Intel® DPDK application, some customization may be required on the target machine.
+ * For RHEL/CentOS systems it can be installed using ``pip3 install pyelftools``
-System Software
-~~~~~~~~~~~~~~~
+ * For Ubuntu/Debian it can be installed using ``apt install python3-pyelftools``
-**Required:**
+* Library for handling NUMA (Non Uniform Memory Access).
-* Kernel version >= 2.6.33
+ * ``numactl-devel`` in RHEL/Fedora;
- The kernel version in use can be checked using the command:
+ * ``libnuma-dev`` in Debian/Ubuntu;
- .. code-block:: console
-
- uname -r
-
-For details of the patches needed to use the Intel® DPDK with earlier kernel versions,
-see the Intel® DPDK FAQ included in the *Intel® DPDK Release Notes*.
-Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32 kernel that already has all the necessary patches applied.
-
-* glibc >= 2.7 (for features related to cpuset)
-
- The version can be checked using the ldd --version command. A sample output is shown below:
-
- .. code-block:: console
-
- # ldd --version
+.. note::
- ldd (GNU libc) 2.14.90
- Copyright (C) 2011 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO
- warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- Written by Roland McGrath and Ulrich Drepper.
+ Please ensure that the latest patches are applied to third party libraries
+ and software to avoid any known vulnerabilities.
-* Kernel configuration
- In the Fedora* OS and other common distributions, such as Ubuntu*, or RedHat Enterprise Linux*,
- the vendor supplied kernel configurations can be used to run most Intel® DPDK applications.
+**Optional Tools:**
- For other kernel builds, options which should be enabled for Intel® DPDK include:
+* Intel® C++ Compiler (icc). For installation, additional libraries may be required.
+ See the icc Installation Guide found in the Documentation directory under the compiler installation.
- * UIO support
+* IBM® Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries
+ which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install
+ it, see the IBM official installation document.
- * HUGETLBFS
+**Additional Libraries**
- * PROC_PAGE_MONITOR support
+A number of DPDK components, such as libraries and poll-mode drivers (PMDs) have additional dependencies.
+For DPDK builds, the presence or absence of these dependencies will be automatically detected
+enabling or disabling the relevant components appropriately.
- * HPET and HPET_MMAP configuration options should also be enabled if HPET support is required.
- See :ref:`Section 5.1 High Precision Event Timer (HPET) Functionality <High_Precision_Event_Timer>` for more details.
+In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components.
-Use of Hugepages in the Linux* Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For libraries the additional dependencies include:
-Hugepage support is required for the large memory pool allocation used for packet buffers
-(the HUGETLBFS option must be enabled in the running kernel as indicated in Section 2.3).
-By using hugepage allocations, performance is increased since fewer pages are needed,
-and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches),
-which reduce the time it takes to translate a virtual page address to a physical page address.
-Without hugepages, high TLB miss rates would occur with the standard 4k page size, slowing performance.
+* libarchive: for some unit tests using tar to get their resources.
-Reserving Hugepages for Intel® DPDK Use
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* libelf: to compile and use the bpf library.
-The allocation of hugepages should be done at boot time or as soon as possible after system boot
-to prevent memory from being fragmented in physical memory.
-To reserve hugepages at boot time, a parameter is passed to the Linux* kernel on the kernel command line.
+For poll-mode drivers, the additional dependencies for each driver can be
+found in that driver's documentation in the relevant DPDK guide document,
+e.g. :doc:`../nics/index`
-For 2 MB pages, just pass the hugepages option to the kernel. For example, to reserve 1024 pages of 2 MB, use:
-.. code-block:: console
+Building DPDK Applications
+--------------------------
- hugepages=1024
+The tool pkg-config or pkgconf, integrated in most build systems,
+must be used to parse options and dependencies from libdpdk.pc.
-For other hugepage sizes, for example 1G pages, the size must be specified explicitly and
-can also be optionally set as the default hugepage size for the system.
-For example, to reserve 4G of hugepage memory in the form of four 1G pages, the following options should be passed to the kernel:
+.. note::
-.. code-block:: console
+ pkg-config 0.27, supplied with RHEL-7,
+ does not process the Libs.private section correctly,
+ resulting in statically linked applications not being linked properly.
- default_hugepagesz=1G hugepagesz=1G hugepages=4
-.. note::
+Running DPDK Applications
+-------------------------
- The hugepage sizes that a CPU supports can be determined from the CPU flags.
- If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages are supported.
+To run a DPDK application, some customization may be required on the target machine.
-.. note::
+System Software
+~~~~~~~~~~~~~~~
- For 64-bit applications, it is recommended to use 1 GB hugepages if the platform supports them.
+**Required:**
-In the case of a dual-socket NUMA system,
-the number of hugepages reserved at boot time is generally divided equally between the two sockets
-(on the assumption that sufficient memory is present on both sockets).
+* Kernel version >= 3.16
-See the Documentation/kernel-parameters.txt file in your Linux* source tree for further details of these and other kernel options.
+ The kernel version required is based on the oldest long term stable kernel available
+ at kernel.org when the DPDK version is in development.
+ Compatibility for recent distribution kernels will be kept, notably RHEL/CentOS 7.
-**Alternative:**
+ The kernel version in use can be checked using the command::
-For 2 MB pages, there is also the option of allocating hugepages after the system has booted.
-This is done by echoing the number of hugepages required to a nr_hugepages file in the /sys/devices/ directory.
-For a single-node system, the command to use is as follows (assuming that 1024 pages are required):
+ uname -r
-.. code-block:: console
+* glibc >= 2.7 (for features related to cpuset)
- echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+ The version can be checked using the ``ldd --version`` command.
-On a NUMA machine, pages should be allocated explicitly on separate nodes:
+* Kernel configuration
-.. code-block:: console
+ In the Fedora OS and other common distributions, such as Ubuntu, or Red Hat Enterprise Linux,
+ the vendor supplied kernel configurations can be used to run most DPDK applications.
- echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
- echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
+ For other kernel builds, options which should be enabled for DPDK include:
-.. note::
+ * HUGETLBFS
- For 1G pages, it is not possible to reserve the hugepage memory after the system has booted.
+ * PROC_PAGE_MONITOR support
-Using Hugepages with the Intel® DPDK
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * HPET and HPET_MMAP configuration options should also be enabled if HPET support is required.
+ See the section on :ref:`High Precision Event Timer (HPET) Functionality <High_Precision_Event_Timer>` for more details.
-Once the hugepage memory is reserved, to make the memory available for Intel® DPDK use, perform the following steps:
+.. _linux_gsg_hugepages:
-.. code-block:: console
+Use of Hugepages in the Linux Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- mkdir /mnt/huge
- mount -t hugetlbfs nodev /mnt/huge
+Hugepage support is required for the large memory pool allocation used for packet buffers
+(the HUGETLBFS option must be enabled in the running kernel as indicated the previous section).
+By using hugepage allocations, performance is increased since fewer pages are needed,
+and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches),
+which reduce the time it takes to translate a virtual page address to a physical page address.
+Without hugepages, high TLB miss rates would occur with the standard 4k page size, slowing performance.
-The mount point can be made permanent across reboots, by adding the following line to the /etc/fstab file:
+Reserving Hugepages for DPDK Use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: console
+The reservation of hugepages can be performed at run time.
+This is done by echoing the number of hugepages required
+to a ``nr_hugepages`` file in the ``/sys/kernel/`` directory
+corresponding to a specific page size (in Kilobytes).
+For a single-node system, the command to use is as follows
+(assuming that 1024 of 2MB pages are required)::
- nodev /mnt/huge hugetlbfs defaults 0 0
+ echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
-For 1GB pages, the page size must be specified as a mount option:
+On a NUMA machine, the above command will usually divide the number of hugepages
+equally across all NUMA nodes (assuming there is enough memory on all NUMA nodes).
+However, pages can also be reserved explicitly on individual NUMA nodes
+using a ``nr_hugepages`` file in the ``/sys/devices/`` directory::
-.. code-block:: console
+ echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
+ echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
- nodev /mnt/huge_1GB hugetlbfs pagesize=1GB 0 0
+The tool ``dpdk-hugepages.py`` can be used to manage hugepages.
-Xen Domain0 Support in the Linux* Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
-The existing memory management implementation is based on the Linux* kernel hugepage mechanism.
-On the Xen hypervisor, hugepage support for DomainU (DomU) Guests means that Intel® DPDK applications work as normal for guests.
+ Some kernel versions may not allow reserving 1 GB hugepages at run time,
+ so reserving them at boot time may be the only option.
+ Please see below for instructions.
-However, Domain0 (Dom0) does not support hugepages.
-To work around this limitation, a new kernel module rte_dom0_mm is added to facilitate the allocation and mapping of memory via
-**IOCTL** (allocation) and **MMAP** (mapping).
+**Alternative:**
-Enabling Xen Dom0 Mode in the Intel® DPDK
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In the general case, reserving hugepages at run time is perfectly fine,
+but in use cases where having lots of physically contiguous memory is required,
+it is preferable to reserve hugepages at boot time,
+as that will help in preventing physical memory from becoming heavily fragmented.
-By default, Xen Dom0 mode is disabled in the Intel® DPDK build configuration files.
-To support Xen Dom0, the CONFIG_RTE_LIBRTE_XEN_DOM0 setting should be changed to “y”, which enables the Xen Dom0 mode at compile time.
+To reserve hugepages at boot time, a parameter is passed to the Linux kernel on the kernel command line.
-Furthermore, the CONFIG_RTE_EAL_ALLOW_INV_SOCKET_ID setting should also be changed to “y” in the case of the wrong socket ID being received.
+For 2 MB pages, just pass the hugepages option to the kernel. For example, to reserve 1024 pages of 2 MB, use::
-Loading the Intel® DPDK rte_dom0_mm Module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ hugepages=1024
-To run any Intel® DPDK application on Xen Dom0, the rte_dom0_mm module must be loaded into the running kernel with rsv_memsize option.
-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):
+For other hugepage sizes, for example 1G pages, the size must be specified explicitly and
+can also be optionally set as the default hugepage size for the system.
+For example, to reserve 4G of hugepage memory in the form of four 1G pages, the following options should be passed to the kernel::
-.. code-block:: console
+ default_hugepagesz=1G hugepagesz=1G hugepages=4
- sudo insmod kmod/rte_dom0_mm.ko rsv_memsize=X
+.. note::
-The value X cannot be greater than 4096(MB).
+ The hugepage sizes that a CPU supports can be determined from the CPU flags on Intel architecture.
+ If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages are supported.
+ On IBM Power architecture, the supported hugepage sizes are 16MB and 16GB.
-Configuring Memory for Intel® DPDK Use
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
-After the rte_dom0_mm.ko kernel module has been loaded, the user must configure the memory size for DPDK usage.
-This is done by echoing the memory size to a memsize file in the /sys/devices/ directory.
-Use the following command (assuming that 2048 MB is required):
+ For 64-bit applications, it is recommended to use 1 GB hugepages if the platform supports them.
-.. code-block:: console
+In the case of a dual-socket NUMA system,
+the number of hugepages reserved at boot time is generally divided equally between the two sockets
+(on the assumption that sufficient memory is present on both sockets).
- echo 2048 > /sys/kernel/mm/dom0-mm/memsize-mB/memsize
+See the Documentation/admin-guide/kernel-parameters.txt file in your Linux source tree for further details of these and other kernel options.
-The user can also check how much memory has already been used:
+Using Hugepages with the DPDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: console
+If secondary process support is not required, DPDK is able to use hugepages
+without any configuration by using "in-memory" mode.
+Please see :doc:`linux_eal_parameters` for more details.
- cat /sys/kernel/mm/dom0-mm/memsize-mB/memsize_rsvd
+If secondary process support is required,
+mount points for hugepages need to be created.
+On modern Linux distributions, a default mount point for hugepages
+is provided by the system and is located at ``/dev/hugepages``.
+This mount point will use the default hugepage size
+set by the kernel parameters as described above.
-Xen Domain0 does not support NUMA configuration, as a result the --socket-mem command line option is invalid for Xen Domain0.
+However, in order to use hugepage sizes other than the default, it is necessary
+to manually create mount points for those hugepage sizes (e.g. 1GB pages).
-.. note::
+To make the hugepages of size 1GB available for DPDK use,
+following steps must be performed::
- The memsize value cannot be greater than the rsv_memsize value.
+ mkdir /mnt/huge
+ mount -t hugetlbfs pagesize=1GB /mnt/huge
-Running the Intel® DPDK Application on Xen Domain0
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The mount point can be made permanent across reboots, by adding the following line to the ``/etc/fstab`` file::
-To run the Intel® DPDK application on Xen Domain0, an extra command line option --xen-dom0 is required.
+ nodev /mnt/huge hugetlbfs pagesize=1GB 0 0
git.droids-corp.org / dpdk.git / blobdiff