X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Flinux_gsg%2Fsys_reqs.rst;h=d7ea8520e558c226c3583bf364a3410a114cf179;hb=2e4859f3b362fa2960d71dc70b77a13a24f5c228;hp=c14411e7f202bc057a12efc276246b40fe287e75;hpb=e8d6f51ab3f7c3fbb84e64894e5005fff106330a;p=dpdk.git diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst old mode 100755 new mode 100644 index c14411e7f2..d7ea8520e5 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -1,287 +1,254 @@ -.. 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 ` +and high performance of small packets, BIOS setting changes may be needed. +Consult the section on :ref:`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 ` 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 ` 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