quick_start.rst revision 7b53c036
1..  BSD LICENSE
2    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
3    All rights reserved.
4
5    Redistribution and use in source and binary forms, with or without
6    modification, are permitted provided that the following conditions
7    are met:
8
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
14    distribution.
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.
18
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.
30
31.. _linux_setup_script:
32
33Quick Start Setup Script
34========================
35
36The dpdk-setup.sh script, found in the tools subdirectory, allows the user to perform the following tasks:
37
38*   Build the DPDK libraries
39
40*   Insert and remove the DPDK IGB_UIO kernel module
41
42*   Insert and remove VFIO kernel modules
43
44*   Insert and remove the DPDK KNI kernel module
45
46*   Create and delete hugepages for NUMA and non-NUMA cases
47
48*   View network port status and reserve ports for DPDK application use
49
50*   Set up permissions for using VFIO as a non-privileged user
51
52*   Run the test and testpmd applications
53
54*   Look at hugepages in the meminfo
55
56*   List hugepages in ``/mnt/huge``
57
58*   Remove built DPDK libraries
59
60Once these steps have been completed for one of the EAL targets,
61the user may compile their own application that links in the EAL libraries to create the DPDK image.
62
63Script Organization
64-------------------
65
66The dpdk-setup.sh script is logically organized into a series of steps that a user performs in sequence.
67Each step provides a number of options that guide the user to completing the desired task.
68The following is a brief synopsis of each step.
69
70**Step 1: Build DPDK Libraries**
71
72Initially, the user must select a DPDK target to choose the correct target type and compiler options to use when building the libraries.
73
74The user must have all libraries, modules, updates and compilers installed in the system prior to this,
75as described in the earlier chapters in this Getting Started Guide.
76
77**Step 2: Setup Environment**
78
79The user configures the Linux* environment to support the running of DPDK applications.
80Hugepages can be set up for NUMA or non-NUMA systems. Any existing hugepages will be removed.
81The DPDK kernel module that is needed can also be inserted in this step,
82and network ports may be bound to this module for DPDK application use.
83
84**Step 3: Run an Application**
85
86The user may run the test application once the other steps have been performed.
87The test application allows the user to run a series of functional tests for the DPDK.
88The testpmd application, which supports the receiving and sending of packets, can also be run.
89
90**Step 4: Examining the System**
91
92This step provides some tools for examining the status of hugepage mappings.
93
94**Step 5: System Cleanup**
95
96The final step has options for restoring the system to its original state.
97
98Use Cases
99---------
100
101The following are some example of how to use the dpdk-setup.sh script.
102The script should be run using the source command.
103Some options in the script prompt the user for further data before proceeding.
104
105.. warning::
106
107    The dpdk-setup.sh script should be run with root privileges.
108
109.. code-block:: console
110
111    source tools/dpdk-setup.sh
112
113    ------------------------------------------------------------------------
114
115    RTE_SDK exported as /home/user/rte
116
117    ------------------------------------------------------------------------
118
119    Step 1: Select the DPDK environment to build
120
121    ------------------------------------------------------------------------
122
123    [1] i686-native-linuxapp-gcc
124
125    [2] i686-native-linuxapp-icc
126
127    [3] ppc_64-power8-linuxapp-gcc
128
129    [4] x86_64-ivshmem-linuxapp-gcc
130
131    [5] x86_64-ivshmem-linuxapp-icc
132
133    [6] x86_64-native-bsdapp-clang
134
135    [7] x86_64-native-bsdapp-gcc
136
137    [8] x86_64-native-linuxapp-clang
138
139    [9] x86_64-native-linuxapp-gcc
140
141    [10] x86_64-native-linuxapp-icc
142
143    ------------------------------------------------------------------------
144
145    Step 2: Setup linuxapp environment
146
147    ------------------------------------------------------------------------
148
149    [11] Insert IGB UIO module
150
151    [12] Insert VFIO module
152
153    [13] Insert KNI module
154
155    [14] Setup hugepage mappings for non-NUMA systems
156
157    [15] Setup hugepage mappings for NUMA systems
158
159    [16] Display current Ethernet device settings
160
161    [17] Bind Ethernet device to IGB UIO module
162
163    [18] Bind Ethernet device to VFIO module
164
165    [19] Setup VFIO permissions
166
167    ------------------------------------------------------------------------
168
169    Step 3: Run test application for linuxapp environment
170
171    ------------------------------------------------------------------------
172
173    [20] Run test application ($RTE_TARGET/app/test)
174
175    [21] Run testpmd application in interactive mode ($RTE_TARGET/app/testpmd)
176
177    ------------------------------------------------------------------------
178
179    Step 4: Other tools
180
181    ------------------------------------------------------------------------
182
183    [22] List hugepage info from /proc/meminfo
184
185    ------------------------------------------------------------------------
186
187    Step 5: Uninstall and system cleanup
188
189    ------------------------------------------------------------------------
190
191    [23] Uninstall all targets
192
193    [24] Unbind NICs from IGB UIO driver
194
195    [25] Remove IGB UIO module
196
197    [26] Remove VFIO module
198
199    [27] Remove KNI module
200
201    [28] Remove hugepage mappings
202
203    [29] Exit Script
204
205Option:
206
207The following selection demonstrates the creation of the ``x86_64-native-linuxapp-gcc`` DPDK library.
208
209.. code-block:: console
210
211    Option: 9
212
213    ================== Installing x86_64-native-linuxapp-gcc
214
215    Configuration done
216    == Build lib
217    ...
218    Build complete
219    RTE_TARGET exported as x86_64-native-linuxapp-gcc
220
221The following selection demonstrates the starting of the DPDK UIO driver.
222
223.. code-block:: console
224
225    Option: 25
226
227    Unloading any existing DPDK UIO module
228    Loading DPDK UIO module
229
230The following selection demonstrates the creation of hugepages in a NUMA system.
2311024 2 MByte pages are assigned to each node.
232The result is that the application should use -m 4096 for starting the application to access both memory areas
233(this is done automatically if the -m option is not provided).
234
235.. note::
236
237    If prompts are displayed to remove temporary files, type 'y'.
238
239.. code-block:: console
240
241    Option: 15
242
243    Removing currently reserved hugepages
244    mounting /mnt/huge and removing directory
245    Input the number of 2MB pages for each node
246    Example: to have 128MB of hugepages available per node,
247    enter '64' to reserve 64 * 2MB pages on each node
248    Number of pages for node0: 1024
249    Number of pages for node1: 1024
250    Reserving hugepages
251    Creating /mnt/huge and mounting as hugetlbfs
252
253The following selection demonstrates the launch of the test application to run on a single core.
254
255.. code-block:: console
256
257    Option: 20
258
259    Enter hex bitmask of cores to execute test app on
260    Example: to execute app on cores 0 to 7, enter 0xff
261    bitmask: 0x01
262    Launching app
263    EAL: coremask set to 1
264    EAL: Detected lcore 0 on socket 0
265    ...
266    EAL: Master core 0 is ready (tid=1b2ad720)
267    RTE>>
268
269Applications
270------------
271
272Once the user has run the dpdk-setup.sh script, built one of the EAL targets and set up hugepages (if using one of the Linux EAL targets),
273the user can then move on to building and running their application or one of the examples provided.
274
275The examples in the /examples directory provide a good starting point to gain an understanding of the operation of the DPDK.
276The following command sequence shows how the helloworld sample application is built and run.
277As recommended in Section 4.2.1 , "Logical Core Use by Applications",
278the logical core layout of the platform should be determined when selecting a core mask to use for an application.
279
280.. code-block:: console
281
282    cd helloworld/
283    make
284      CC main.o
285      LD helloworld
286      INSTALL-APP helloworld
287      INSTALL-MAP helloworld.map
288
289    sudo ./build/app/helloworld -c 0xf -n 3
290    [sudo] password for rte:
291
292    EAL: coremask set to f
293    EAL: Detected lcore 0 as core 0 on socket 0
294    EAL: Detected lcore 1 as core 0 on socket 1
295    EAL: Detected lcore 2 as core 1 on socket 0
296    EAL: Detected lcore 3 as core 1 on socket 1
297    EAL: Setting up hugepage memory...
298    EAL: Ask a virtual area of 0x200000 bytes
299    EAL: Virtual area found at 0x7f0add800000 (size = 0x200000)
300    EAL: Ask a virtual area of 0x3d400000 bytes
301    EAL: Virtual area found at 0x7f0aa0200000 (size = 0x3d400000)
302    EAL: Ask a virtual area of 0x400000 bytes
303    EAL: Virtual area found at 0x7f0a9fc00000 (size = 0x400000)
304    EAL: Ask a virtual area of 0x400000 bytes
305    EAL: Virtual area found at 0x7f0a9f600000 (size = 0x400000)
306    EAL: Ask a virtual area of 0x400000 bytes
307    EAL: Virtual area found at 0x7f0a9f000000 (size = 0x400000)
308    EAL: Ask a virtual area of 0x800000 bytes
309    EAL: Virtual area found at 0x7f0a9e600000 (size = 0x800000)
310    EAL: Ask a virtual area of 0x800000 bytes
311    EAL: Virtual area found at 0x7f0a9dc00000 (size = 0x800000)
312    EAL: Ask a virtual area of 0x400000 bytes
313    EAL: Virtual area found at 0x7f0a9d600000 (size = 0x400000)
314    EAL: Ask a virtual area of 0x400000 bytes
315    EAL: Virtual area found at 0x7f0a9d000000 (size = 0x400000)
316    EAL: Ask a virtual area of 0x400000 bytes
317    EAL: Virtual area found at 0x7f0a9ca00000 (size = 0x400000)
318    EAL: Ask a virtual area of 0x200000 bytes
319    EAL: Virtual area found at 0x7f0a9c600000 (size = 0x200000)
320    EAL: Ask a virtual area of 0x200000 bytes
321    EAL: Virtual area found at 0x7f0a9c200000 (size = 0x200000)
322    EAL: Ask a virtual area of 0x3fc00000 bytes
323    EAL: Virtual area found at 0x7f0a5c400000 (size = 0x3fc00000)
324    EAL: Ask a virtual area of 0x200000 bytes
325    EAL: Virtual area found at 0x7f0a5c000000 (size = 0x200000)
326    EAL: Requesting 1024 pages of size 2MB from socket 0
327    EAL: Requesting 1024 pages of size 2MB from socket 1
328    EAL: Master core 0 is ready (tid=de25b700)
329    EAL: Core 1 is ready (tid=5b7fe700)
330    EAL: Core 3 is ready (tid=5a7fc700)
331    EAL: Core 2 is ready (tid=5affd700)
332    hello from core 1
333    hello from core 2
334    hello from core 3
335    hello from core 0
336