X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Flinux_gsg%2Fsys_reqs.rst;h=4a401210de7e2f3b2ccc16995e7c3206f9773420;hb=de34aaa96be969bb919b98891af18ed0c435625d;hp=eb8442c622260e9889923302ffdc7bc5e83ba9ef;hpb=ccf5fd6045862d0abd02e42842b41c8550a9f114;p=dpdk.git diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst index eb8442c622..4a401210de 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -1,32 +1,5 @@ -.. 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 =================== @@ -61,39 +34,40 @@ Compilation of the DPDK .. 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 DPDK Release Notes. + 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. -* GNU ``make``. +* General development tools including a supported C compiler such as gcc (version 4.9+) or clang (version 3.4+). -* coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc. + * For RHEL/Fedora systems these can be installed using ``dnf groupinstall "Development Tools"`` -* gcc: versions 4.9 or later is recommended for all platforms. - 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``. + * For Ubuntu/Debian systems these can be installed using ``apt install build-essential`` -* libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``; - ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture; - ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;) +* Python 3.5 or later. -* Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64; - kernel - devel.ppc64) +* Meson (version 0.47.1+) and ninja -* Additional packages required for 32-bit compilation on 64-bit systems are: + * ``meson`` & ``ninja-build`` packages in most Linux distributions - * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64; + * If the packaged version is below the minimum version, the latest versions + can be installed from Python's "pip" repository: ``pip3 install meson ninja`` - * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64; +* ``pyelftools`` (version 0.22+) - .. note:: + * For RHEL/Fedora systems it can be installed using ``dnf install python-pyelftools`` - x86_x32 ABI is currently supported with distribution packages only on Ubuntu - higher than 13.10 or recent Debian distribution. The only supported compiler is gcc 4.9+. + * For Ubuntu/Debian it can be installed using ``apt install python3-pyelftools`` -* libnuma-devel - library for handling NUMA (Non Uniform Memory Access). +* Library for handling NUMA (Non Uniform Memory Access). -* Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package. + * ``numactl-devel`` in RHEL/Fedora; + + * ``libnuma-dev`` in Debian/Ubuntu; + +.. note:: + + Please ensure that the latest patches are applied to third party libraries + and software to avoid any known vulnerabilities. **Optional Tools:** @@ -105,23 +79,53 @@ Compilation of the DPDK 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. -* 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. +**Additional Libraries** + +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. + +In each case, the relevant library development package (``-devel`` or ``-dev``) is needed to build the DPDK components. + +For libraries the additional dependencies include: + +* libarchive: for some unit tests using tar to get their resources. + +* libelf: to compile and use the bpf library. -* libarchive headers and library are needed for some unit tests using tar to get their resources. +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` + + +Building DPDK Applications +-------------------------- + +The tool pkg-config or pkgconf, integrated in most build systems, +must be used to parse options and dependencies from libdpdk.pc. + +.. note:: + + 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. Running DPDK Applications ------------------------- -To run an DPDK application, some customization may be required on the target machine. +To run a DPDK application, some customization may be required on the target machine. System Software ~~~~~~~~~~~~~~~ **Required:** -* Kernel version >= 2.6.34 +* Kernel version >= 3.16 + + 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. The kernel version in use can be checked using the command:: @@ -160,8 +164,38 @@ Without hugepages, high TLB miss rates would occur with the standard 4k page siz Reserving Hugepages for DPDK Use ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. +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):: + + echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages + +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:: + + echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages + echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages + +The tool ``dpdk-hugepages.py`` can be used to manage hugepages. + +.. note:: + + 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. + +**Alternative:** + +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. + To reserve hugepages at boot time, a parameter is passed to the Linux kernel on the kernel command line. For 2 MB pages, just pass the hugepages option to the kernel. For example, to reserve 1024 pages of 2 MB, use:: @@ -188,96 +222,31 @@ 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). -See the Documentation/kernel-parameters.txt file in your Linux source tree for further details of these and other kernel options. - -**Alternative:** - -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):: - - echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages - -On a NUMA machine, pages should be allocated explicitly on separate nodes:: - - echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages - echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages - -.. note:: - - For 1G pages, it is not possible to reserve the hugepage memory after the system has booted. - - On IBM POWER system, the nr_overcommit_hugepages should be set to the same value as nr_hugepages. - For example, if the required page number is 128, the following commands are used:: - - echo 128 > /sys/kernel/mm/hugepages/hugepages-16384kB/nr_hugepages - echo 128 > /sys/kernel/mm/hugepages/hugepages-16384kB/nr_overcommit_hugepages +See the Documentation/admin-guide/kernel-parameters.txt file in your Linux source tree for further details of these and other kernel options. Using Hugepages with the DPDK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Once the hugepage memory is reserved, to make the memory available for DPDK use, perform the following steps:: - - mkdir /mnt/huge - mount -t hugetlbfs nodev /mnt/huge - -The mount point can be made permanent across reboots, by adding the following line to the ``/etc/fstab`` file:: - - nodev /mnt/huge hugetlbfs defaults 0 0 - -For 1GB pages, the page size must be specified as a mount option:: - - nodev /mnt/huge_1GB hugetlbfs pagesize=1GB 0 0 +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. -Xen Domain0 Support in the Linux Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. -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 DPDK applications work as normal for guests. +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). -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). +To make the hugepages of size 1GB available for DPDK use, +following steps must be performed:: -Enabling Xen Dom0 Mode in the DPDK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, Xen Dom0 mode is disabled in the 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. - -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. - -Loading the DPDK rte_dom0_mm Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To run any 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 DPDK target directory. -This module should be loaded using the insmod command as shown below (assuming that the current directory is the DPDK target directory):: - - sudo insmod kmod/rte_dom0_mm.ko rsv_memsize=X - -The value X cannot be greater than 4096(MB). - -Configuring Memory for DPDK Use -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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):: - - echo 2048 > /sys/kernel/mm/dom0-mm/memsize-mB/memsize - -The user can also check how much memory has already been used:: - - cat /sys/kernel/mm/dom0-mm/memsize-mB/memsize_rsvd - -Xen Domain0 does not support NUMA configuration, as a result the ``--socket-mem`` command line option is invalid for Xen Domain0. - -.. note:: - - The memsize value cannot be greater than the rsv_memsize value. + mkdir /mnt/huge + mount -t hugetlbfs pagesize=1GB /mnt/huge -Running the 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 DPDK application on Xen Domain0, an extra command line option ``--xen-dom0`` is required. + nodev /mnt/huge hugetlbfs pagesize=1GB 0 0