]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2010-2014 Intel Corporation. | |
7c673cae FG |
3 | |
4 | System Requirements | |
5 | =================== | |
6 | ||
7 | This chapter describes the packages required to compile the DPDK. | |
8 | ||
9 | .. note:: | |
10 | ||
11 | If the DPDK is being used on an Intel® Communications Chipset 89xx Series platform, | |
12 | please consult the *Intel® Communications Chipset 89xx Series Software for Linux Getting Started Guide*. | |
13 | ||
14 | BIOS Setting Prerequisite on x86 | |
15 | -------------------------------- | |
16 | ||
17 | For the majority of platforms, no special BIOS settings are needed to use basic DPDK functionality. | |
18 | However, for additional HPET timer and power management functionality, | |
9f95a23c | 19 | and high performance of small packets, BIOS setting changes may be needed. |
7c673cae FG |
20 | Consult the section on :ref:`Enabling Additional Functionality <Enabling_Additional_Functionality>` |
21 | for more information on the required changes. | |
22 | ||
9f95a23c TL |
23 | .. note:: |
24 | ||
25 | If UEFI secure boot is enabled, the Linux kernel may disallow the use of | |
26 | UIO on the system. Therefore, devices for use by DPDK should be bound to the | |
27 | ``vfio-pci`` kernel module rather than ``igb_uio`` or ``uio_pci_generic``. | |
28 | For more details see :ref:`linux_gsg_binding_kernel`. | |
29 | ||
7c673cae FG |
30 | Compilation of the DPDK |
31 | ----------------------- | |
32 | ||
9f95a23c | 33 | **Required Tools and Libraries:** |
7c673cae FG |
34 | |
35 | .. note:: | |
36 | ||
9f95a23c TL |
37 | The setup commands and installed packages needed on various systems may be different. |
38 | For details on Linux distributions and the versions tested, please consult the DPDK Release Notes. | |
7c673cae FG |
39 | |
40 | * GNU ``make``. | |
41 | ||
42 | * coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc. | |
43 | ||
44 | * gcc: versions 4.9 or later is recommended for all platforms. | |
45 | On some distributions, some specific compiler flags and linker flags are enabled by | |
46 | default and affect performance (``-fstack-protector``, for example). Please refer to the documentation | |
47 | of your distribution and to ``gcc -dumpspecs``. | |
48 | ||
49 | * libc headers, often packaged as ``gcc-multilib`` (``glibc-devel.i686`` / ``libc6-dev-i386``; | |
50 | ``glibc-devel.x86_64`` / ``libc6-dev`` for 64-bit compilation on Intel architecture; | |
51 | ``glibc-devel.ppc64`` for 64 bit IBM Power architecture;) | |
52 | ||
53 | * Linux kernel headers or sources required to build kernel modules. (kernel - devel.x86_64; | |
54 | kernel - devel.ppc64) | |
55 | ||
56 | * Additional packages required for 32-bit compilation on 64-bit systems are: | |
57 | ||
58 | * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Intel i686/x86_64; | |
59 | ||
60 | * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for IBM ppc_64; | |
61 | ||
11fdf7f2 | 62 | .. note:: |
7c673cae | 63 | |
11fdf7f2 TL |
64 | x86_x32 ABI is currently supported with distribution packages only on Ubuntu |
65 | higher than 13.10 or recent Debian distribution. The only supported compiler is gcc 4.9+. | |
7c673cae | 66 | |
9f95a23c TL |
67 | * Library for handling NUMA (Non Uniform Memory Access). |
68 | ||
69 | * numactl-devel in Red Hat/Fedora; | |
70 | ||
71 | * libnuma-dev in Debian/Ubuntu; | |
72 | ||
73 | .. note:: | |
74 | ||
75 | On systems with NUMA support, `libnuma-dev` (aka `numactl-devel`) | |
76 | is a recommended dependency when `--legacy-mem` switch is used, | |
77 | and a *required* dependency if default memory mode is used. | |
78 | While DPDK will compile and run without `libnuma` | |
79 | even on NUMA-enabled systems, | |
80 | both usability and performance will be degraded. | |
81 | ||
11fdf7f2 | 82 | * Python, version 2.7+ or 3.2+, to use various helper scripts included in the DPDK package. |
7c673cae FG |
83 | |
84 | ||
85 | **Optional Tools:** | |
86 | ||
87 | * Intel® C++ Compiler (icc). For installation, additional libraries may be required. | |
88 | See the icc Installation Guide found in the Documentation directory under the compiler installation. | |
89 | ||
90 | * IBM® Advance ToolChain for Powerlinux. This is a set of open source development tools and runtime libraries | |
91 | which allows users to take leading edge advantage of IBM's latest POWER hardware features on Linux. To install | |
92 | it, see the IBM official installation document. | |
93 | ||
94 | * libpcap headers and libraries (libpcap-devel) to compile and use the libpcap-based poll-mode driver. | |
95 | This driver is disabled by default and can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_PCAP=y`` in the build time config file. | |
96 | ||
97 | * libarchive headers and library are needed for some unit tests using tar to get their resources. | |
98 | ||
99 | ||
100 | Running DPDK Applications | |
101 | ------------------------- | |
102 | ||
103 | To run an DPDK application, some customization may be required on the target machine. | |
104 | ||
105 | System Software | |
106 | ~~~~~~~~~~~~~~~ | |
107 | ||
108 | **Required:** | |
109 | ||
9f95a23c TL |
110 | * Kernel version >= 3.16 |
111 | ||
112 | The kernel version required is based on the oldest long term stable kernel available | |
113 | at kernel.org when the DPDK version is in development. | |
114 | Compatibility for recent distribution kernels will be kept, notably RHEL/CentOS 7. | |
7c673cae FG |
115 | |
116 | The kernel version in use can be checked using the command:: | |
117 | ||
118 | uname -r | |
119 | ||
120 | * glibc >= 2.7 (for features related to cpuset) | |
121 | ||
122 | The version can be checked using the ``ldd --version`` command. | |
123 | ||
124 | * Kernel configuration | |
125 | ||
126 | In the Fedora OS and other common distributions, such as Ubuntu, or Red Hat Enterprise Linux, | |
127 | the vendor supplied kernel configurations can be used to run most DPDK applications. | |
128 | ||
129 | For other kernel builds, options which should be enabled for DPDK include: | |
130 | ||
7c673cae FG |
131 | * HUGETLBFS |
132 | ||
133 | * PROC_PAGE_MONITOR support | |
134 | ||
135 | * HPET and HPET_MMAP configuration options should also be enabled if HPET support is required. | |
136 | See the section on :ref:`High Precision Event Timer (HPET) Functionality <High_Precision_Event_Timer>` for more details. | |
137 | ||
138 | .. _linux_gsg_hugepages: | |
139 | ||
140 | Use of Hugepages in the Linux Environment | |
141 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
142 | ||
143 | Hugepage support is required for the large memory pool allocation used for packet buffers | |
144 | (the HUGETLBFS option must be enabled in the running kernel as indicated the previous section). | |
145 | By using hugepage allocations, performance is increased since fewer pages are needed, | |
146 | and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches), | |
147 | which reduce the time it takes to translate a virtual page address to a physical page address. | |
148 | Without hugepages, high TLB miss rates would occur with the standard 4k page size, slowing performance. | |
149 | ||
150 | Reserving Hugepages for DPDK Use | |
151 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
152 | ||
153 | The allocation of hugepages should be done at boot time or as soon as possible after system boot | |
154 | to prevent memory from being fragmented in physical memory. | |
155 | To reserve hugepages at boot time, a parameter is passed to the Linux kernel on the kernel command line. | |
156 | ||
157 | For 2 MB pages, just pass the hugepages option to the kernel. For example, to reserve 1024 pages of 2 MB, use:: | |
158 | ||
159 | hugepages=1024 | |
160 | ||
161 | For other hugepage sizes, for example 1G pages, the size must be specified explicitly and | |
162 | can also be optionally set as the default hugepage size for the system. | |
163 | For example, to reserve 4G of hugepage memory in the form of four 1G pages, the following options should be passed to the kernel:: | |
164 | ||
165 | default_hugepagesz=1G hugepagesz=1G hugepages=4 | |
166 | ||
167 | .. note:: | |
168 | ||
169 | The hugepage sizes that a CPU supports can be determined from the CPU flags on Intel architecture. | |
170 | If pse exists, 2M hugepages are supported; if pdpe1gb exists, 1G hugepages are supported. | |
171 | On IBM Power architecture, the supported hugepage sizes are 16MB and 16GB. | |
172 | ||
173 | .. note:: | |
174 | ||
175 | For 64-bit applications, it is recommended to use 1 GB hugepages if the platform supports them. | |
176 | ||
177 | In the case of a dual-socket NUMA system, | |
178 | the number of hugepages reserved at boot time is generally divided equally between the two sockets | |
179 | (on the assumption that sufficient memory is present on both sockets). | |
180 | ||
9f95a23c | 181 | See the Documentation/admin-guide/kernel-parameters.txt file in your Linux source tree for further details of these and other kernel options. |
7c673cae FG |
182 | |
183 | **Alternative:** | |
184 | ||
185 | For 2 MB pages, there is also the option of allocating hugepages after the system has booted. | |
186 | This is done by echoing the number of hugepages required to a nr_hugepages file in the ``/sys/devices/`` directory. | |
187 | For a single-node system, the command to use is as follows (assuming that 1024 pages are required):: | |
188 | ||
189 | echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages | |
190 | ||
191 | On a NUMA machine, pages should be allocated explicitly on separate nodes:: | |
192 | ||
193 | echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages | |
194 | echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages | |
195 | ||
196 | .. note:: | |
197 | ||
198 | For 1G pages, it is not possible to reserve the hugepage memory after the system has booted. | |
199 | ||
200 | Using Hugepages with the DPDK | |
201 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
202 | ||
203 | Once the hugepage memory is reserved, to make the memory available for DPDK use, perform the following steps:: | |
204 | ||
205 | mkdir /mnt/huge | |
206 | mount -t hugetlbfs nodev /mnt/huge | |
207 | ||
208 | The mount point can be made permanent across reboots, by adding the following line to the ``/etc/fstab`` file:: | |
209 | ||
210 | nodev /mnt/huge hugetlbfs defaults 0 0 | |
211 | ||
212 | For 1GB pages, the page size must be specified as a mount option:: | |
213 | ||
214 | nodev /mnt/huge_1GB hugetlbfs pagesize=1GB 0 0 |