2 Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Intel Corporation nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 Quick Start Setup Script
32 ========================
34 The setup.sh script, found in the tools subdirectory, allows the user to perform the following tasks:
36 * Build the DPDK libraries
38 * Insert and remove the DPDK IGB_UIO kernel module
40 * Insert and remove VFIO kernel modules
42 * Insert and remove the DPDK KNI kernel module
44 * Create and delete hugepages for NUMA and non-NUMA cases
46 * View network port status and reserve ports for DPDK application use
48 * Set up permissions for using VFIO as a non-privileged user
50 * Run the test and testpmd applications
52 * Look at hugepages in the meminfo
54 * List hugepages in /mnt/huge
56 * Remove built DPDK libraries
58 Once these steps have been completed for one of the EAL targets,
59 the user may compile their own application that links in the EAL libraries to create the DPDK image.
64 The setup.sh script is logically organized into a series of steps that a user performs in sequence.
65 Each step provides a number of options that guide the user to completing the desired task.
66 The following is a brief synopsis of each step.
68 **Step 1: Build DPDK Libraries**
70 Initially, the user must select a DPDK target to choose the correct target type and compiler options to use when building the libraries.
72 The user must have all libraries, modules, updates and compilers installed in the system prior to this,
73 as described in the earlier chapters in this Getting Started Guide.
75 **Step 2: Setup Environment**
77 The user configures the Linux* environment to support the running of DPDK applications.
78 Hugepages can be set up for NUMA or non-NUMA systems. Any existing hugepages will be removed.
79 The DPDK kernel module that is needed can also be inserted in this step,
80 and network ports may be bound to this module for DPDK application use.
82 **Step 3: Run an Application**
84 The user may run the test application once the other steps have been performed.
85 The test application allows the user to run a series of functional tests for the DPDK.
86 The testpmd application, which supports the receiving and sending of packets, can also be run.
88 **Step 4: Examining the System**
90 This step provides some tools for examining the status of hugepage mappings.
92 **Step 5: System Cleanup**
94 The final step has options for restoring the system to its original state.
99 The following are some example of how to use the setup.sh script.
100 The script should be run using the source command.
101 Some options in the script prompt the user for further data before proceeding.
105 The setup.sh script should be run with root privileges.
107 .. code-block:: console
109 user@host:~/rte$ source tools/setup.sh
111 ------------------------------------------------------------------------
113 RTE_SDK exported as /home/user/rte
115 ------------------------------------------------------------------------
117 Step 1: Select the DPDK environment to build
119 ------------------------------------------------------------------------
121 [1] i686-native-linuxapp-gcc
123 [2] i686-native-linuxapp-icc
125 [3] ppc_64-power8-linuxapp-gcc
127 [4] x86_64-ivshmem-linuxapp-gcc
129 [5] x86_64-ivshmem-linuxapp-icc
131 [6] x86_64-native-bsdapp-clang
133 [7] x86_64-native-bsdapp-gcc
135 [8] x86_64-native-linuxapp-clang
137 [9] x86_64-native-linuxapp-gcc
139 [10] x86_64-native-linuxapp-icc
141 ------------------------------------------------------------------------
143 Step 2: Setup linuxapp environment
145 ------------------------------------------------------------------------
147 [11] Insert IGB UIO module
149 [12] Insert VFIO module
151 [13] Insert KNI module
153 [14] Setup hugepage mappings for non-NUMA systems
155 [15] Setup hugepage mappings for NUMA systems
157 [16] Display current Ethernet device settings
159 [17] Bind Ethernet device to IGB UIO module
161 [18] Bind Ethernet device to VFIO module
163 [19] Setup VFIO permissions
165 ------------------------------------------------------------------------
167 Step 3: Run test application for linuxapp environment
169 ------------------------------------------------------------------------
171 [20] Run test application ($RTE_TARGET/app/test)
173 [21] Run testpmd application in interactive mode ($RTE_TARGET/app/testpmd)
175 ------------------------------------------------------------------------
179 ------------------------------------------------------------------------
181 [22] List hugepage info from /proc/meminfo
183 ------------------------------------------------------------------------
185 Step 5: Uninstall and system cleanup
187 ------------------------------------------------------------------------
189 [23] Uninstall all targets
191 [24] Unbind NICs from IGB UIO driver
193 [25] Remove IGB UIO module
195 [26] Remove VFIO module
197 [27] Remove KNI module
199 [28] Remove hugepage mappings
205 The following selection demonstrates the creation of the x86_64-native-linuxapp-gcc DPDK library.
207 .. code-block:: console
211 ================== Installing x86_64-native-linuxapp-gcc
217 RTE_TARGET exported as x86_64-native -linuxapp-gcc
219 The following selection demonstrates the starting of the DPDK UIO driver.
221 .. code-block:: console
225 Unloading any existing DPDK UIO module
226 Loading DPDK UIO module
228 The following selection demonstrates the creation of hugepages in a NUMA system.
229 1024 2 MByte pages are assigned to each node.
230 The result is that the application should use -m 4096 for starting the application to access both memory areas
231 (this is done automatically if the -m option is not provided).
235 If prompts are displayed to remove temporary files, type 'y'.
237 .. code-block:: console
241 Removing currently reserved hugepages
242 mounting /mnt/huge and removing directory
243 Input the number of 2MB pages for each node
244 Example: to have 128MB of hugepages available per node,
245 enter '64' to reserve 64 * 2MB pages on each node
246 Number of pages for node0: 1024
247 Number of pages for node1: 1024
249 Creating /mnt/huge and mounting as hugetlbfs
251 The following selection demonstrates the launch of the test application to run on a single core.
253 .. code-block:: console
257 Enter hex bitmask of cores to execute test app on
258 Example: to execute app on cores 0 to 7, enter 0xff
261 EAL: coremask set to 1
262 EAL: Detected lcore 0 on socket 0
264 EAL: Master core 0 is ready (tid=1b2ad720)
270 Once the user has run the setup.sh script, built one of the EAL targets and set up hugepages (if using one of the Linux EAL targets),
271 the user can then move on to building and running their application or one of the examples provided.
273 The examples in the /examples directory provide a good starting point to gain an understanding of the operation of the DPDK.
274 The following command sequence shows how the helloworld sample application is built and run.
275 As recommended in Section 4.2.1 , "Logical Core Use by Applications",
276 the logical core layout of the platform should be determined when selecting a core mask to use for an application.
278 .. code-block:: console
280 rte@rte-desktop:~/rte/examples$ cd helloworld/
281 rte@rte-desktop:~/rte/examples/helloworld$ make
284 INSTALL-APP helloworld
285 INSTALL-MAP helloworld.map
287 rte@rte-desktop:~/rte/examples/helloworld$ sudo ./build/app/helloworld -c 0xf -n 3
288 [sudo] password for rte:
289 EAL: coremask set to f
290 EAL: Detected lcore 0 as core 0 on socket 0
291 EAL: Detected lcore 1 as core 0 on socket 1
292 EAL: Detected lcore 2 as core 1 on socket 0
293 EAL: Detected lcore 3 as core 1 on socket 1
294 EAL: Setting up hugepage memory...
295 EAL: Ask a virtual area of 0x200000 bytes
296 EAL: Virtual area found at 0x7f0add800000 (size = 0x200000)
297 EAL: Ask a virtual area of 0x3d400000 bytes
298 EAL: Virtual area found at 0x7f0aa0200000 (size = 0x3d400000)
299 EAL: Ask a virtual area of 0x400000 bytes
300 EAL: Virtual area found at 0x7f0a9fc00000 (size = 0x400000)
301 EAL: Ask a virtual area of 0x400000 bytes
302 EAL: Virtual area found at 0x7f0a9f600000 (size = 0x400000)
303 EAL: Ask a virtual area of 0x400000 bytes
304 EAL: Virtual area found at 0x7f0a9f000000 (size = 0x400000)
305 EAL: Ask a virtual area of 0x800000 bytes
306 EAL: Virtual area found at 0x7f0a9e600000 (size = 0x800000)
307 EAL: Ask a virtual area of 0x800000 bytes
308 EAL: Virtual area found at 0x7f0a9dc00000 (size = 0x800000)
309 EAL: Ask a virtual area of 0x400000 bytes
310 EAL: Virtual area found at 0x7f0a9d600000 (size = 0x400000)
311 EAL: Ask a virtual area of 0x400000 bytes
312 EAL: Virtual area found at 0x7f0a9d000000 (size = 0x400000)
313 EAL: Ask a virtual area of 0x400000 bytes
314 EAL: Virtual area found at 0x7f0a9ca00000 (size = 0x400000)
315 EAL: Ask a virtual area of 0x200000 bytes
316 EAL: Virtual area found at 0x7f0a9c600000 (size = 0x200000)
317 EAL: Ask a virtual area of 0x200000 bytes
318 EAL: Virtual area found at 0x7f0a9c200000 (size = 0x200000)
319 EAL: Ask a virtual area of 0x3fc00000 bytes
320 EAL: Virtual area found at 0x7f0a5c400000 (size = 0x3fc00000)
321 EAL: Ask a virtual area of 0x200000 bytes
322 EAL: Virtual area found at 0x7f0a5c000000 (size = 0x200000)
323 EAL: Requesting 1024 pages of size 2MB from socket 0
324 EAL: Requesting 1024 pages of size 2MB from socket 1
325 EAL: Master core 0 is ready (tid=de25b700)
326 EAL: Core 1 is ready (tid=5b7fe700)
327 EAL: Core 3 is ready (tid=5a7fc700)
328 EAL: Core 2 is ready (tid=5affd700)