doc/guides/linux_gsg/quick_start.rst

   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 Quick Start Setup Script
  32 ========================
  33
  34 The setup.sh script, found in the tools subdirectory, allows the user to perform the following tasks:
  35
  36 *   Build the DPDK libraries
  37
  38 *   Insert and remove the DPDK IGB_UIO kernel module
  39
  40 *   Insert and remove VFIO kernel modules
  41
  42 *   Insert and remove the DPDK KNI kernel module
  43
  44 *   Create and delete hugepages for NUMA and non-NUMA cases
  45
  46 *   View network port status and reserve ports for DPDK application use
  47
  48 *   Set up permissions for using VFIO as a non-privileged user
  49
  50 *   Run the test and testpmd applications
  51
  52 *   Look at hugepages in the meminfo
  53
  54 *   List hugepages in /mnt/huge
  55
  56 *   Remove built DPDK libraries
  57
  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.
  60
  61 Script Organization
  62 -------------------
  63
  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.
  67
  68 **Step 1: Build DPDK Libraries**
  69
  70 Initially, the user must select a DPDK target to choose the correct target type and compiler options to use when building the libraries.
  71
  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.
  74
  75 **Step 2: Setup Environment**
  76
  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.
  81
  82 **Step 3: Run an Application**
  83
  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.
  87
  88 **Step 4: Examining the System**
  89
  90 This step provides some tools for examining the status of hugepage mappings.
  91
  92 **Step 5: System Cleanup**
  93
  94 The final step has options for restoring the system to its original state.
  95
  96 Use Cases
  97 ---------
  98
  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.
 102
 103 .. warning::
 104
 105     The setup.sh script should be run with root privileges.
 106
 107 .. code-block:: console
 108
 109     user@host:~/rte$ source tools/setup.sh
 110
 111     ------------------------------------------------------------------------
 112
 113     RTE_SDK exported as /home/user/rte
 114
 115     ------------------------------------------------------------------------
 116
 117     Step 1: Select the DPDK environment to build
 118
 119     ------------------------------------------------------------------------
 120
 121     [1] i686-native-linuxapp-gcc
 122
 123     [2] i686-native-linuxapp-icc
 124
 125     [3] ppc_64-power8-linuxapp-gcc
 126
 127     [4] x86_64-ivshmem-linuxapp-gcc
 128
 129     [5] x86_64-ivshmem-linuxapp-icc
 130
 131     [6] x86_64-native-bsdapp-clang
 132
 133     [7] x86_64-native-bsdapp-gcc
 134
 135     [8] x86_64-native-linuxapp-clang
 136
 137     [9] x86_64-native-linuxapp-gcc
 138
 139     [10] x86_64-native-linuxapp-icc
 140
 141     ------------------------------------------------------------------------
 142
 143     Step 2: Setup linuxapp environment
 144
 145     ------------------------------------------------------------------------
 146
 147     [11] Insert IGB UIO module
 148
 149     [12] Insert VFIO module
 150
 151     [13] Insert KNI module
 152
 153     [14] Setup hugepage mappings for non-NUMA systems
 154
 155     [15] Setup hugepage mappings for NUMA systems
 156
 157     [16] Display current Ethernet device settings
 158
 159     [17] Bind Ethernet device to IGB UIO module
 160
 161     [18] Bind Ethernet device to VFIO module
 162
 163     [19] Setup VFIO permissions
 164
 165     ------------------------------------------------------------------------
 166
 167     Step 3: Run test application for linuxapp environment
 168
 169     ------------------------------------------------------------------------
 170
 171     [20] Run test application ($RTE_TARGET/app/test)
 172
 173     [21] Run testpmd application in interactive mode ($RTE_TARGET/app/testpmd)
 174
 175     ------------------------------------------------------------------------
 176
 177     Step 4: Other tools
 178
 179     ------------------------------------------------------------------------
 180
 181     [22] List hugepage info from /proc/meminfo
 182
 183     ------------------------------------------------------------------------
 184
 185     Step 5: Uninstall and system cleanup
 186
 187     ------------------------------------------------------------------------
 188
 189     [23] Uninstall all targets
 190
 191     [24] Unbind NICs from IGB UIO driver
 192
 193     [25] Remove IGB UIO module
 194
 195     [26] Remove VFIO module
 196
 197     [27] Remove KNI module
 198
 199     [28] Remove hugepage mappings
 200
 201     [29] Exit Script
 202
 203 Option:
 204
 205 The following selection demonstrates the creation of the x86_64-native-linuxapp-gcc DPDK library.
 206
 207 .. code-block:: console
 208
 209     Option: 9
 210
 211     ================== Installing x86_64-native-linuxapp-gcc
 212
 213     Configuration done
 214     == Build scripts
 215     == Build scripts/testhost
 216     HOSTCC testhost.o
 217     ...
 218     Build complete
 219     RTE_TARGET exported as x86_64-native -linuxapp-gcc
 220
 221 The 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
 230 The following selection demonstrates the creation of hugepages in a NUMA system.
 231 1024 2 Mbyte pages are assigned to each node.
 232 The 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     nmounting /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
 253 The 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
 269 Applications
 270 ------------
 271
 272 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),
 273 the user can then move on to building and running their application or one of the examples provided.
 274
 275 The examples in the /examples directory provide a good starting point to gain an understanding of the operation of the DPDK.
 276 The following command sequence shows how the helloworld sample application is built and run.
 277 As recommended in Section 4.2.1 , "Logical Core Use by Applications",
 278 the 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     rte@rte-desktop:~/rte/examples$ cd helloworld/
 283     rte@rte-desktop:~/rte/examples/helloworld$ make
 284     CC main.o
 285     LD helloworld
 286     INSTALL-APP helloworld
 287     INSTALL-MAP helloworld.map
 288
 289     rte@rte-desktop:~/rte/examples/helloworld$ sudo ./build/app/helloworld -c 0xf -n 3
 290     [sudo] password for rte:
 291     EAL: coremask set to f
 292     EAL: Detected lcore 0 as core 0 on socket 0
 293     EAL: Detected lcore 1 as core 0 on socket 1
 294     EAL: Detected lcore 2 as core 1 on socket 0
 295     EAL: Detected lcore 3 as core 1 on socket 1
 296     EAL: Setting up hugepage memory...
 297     EAL: Ask a virtual area of 0x200000 bytes
 298     EAL: Virtual area found at 0x7f0add800000 (size = 0x200000)
 299     EAL: Ask a virtual area of 0x3d400000 bytes
 300     EAL: Virtual area found at 0x7f0aa0200000 (size = 0x3d400000)
 301     EAL: Ask a virtual area of 0x400000 bytes
 302     EAL: Virtual area found at 0x7f0a9fc00000 (size = 0x400000)
 303     EAL: Ask a virtual area of 0x400000 bytes
 304     EAL: Virtual area found at 0x7f0a9f600000 (size = 0x400000)
 305     EAL: Ask a virtual area of 0x400000 bytes
 306     EAL: Virtual area found at 0x7f0a9f000000 (size = 0x400000)
 307     EAL: Ask a virtual area of 0x800000 bytes
 308     EAL: Virtual area found at 0x7f0a9e600000 (size = 0x800000)
 309     EAL: Ask a virtual area of 0x800000 bytes
 310     EAL: Virtual area found at 0x7f0a9dc00000 (size = 0x800000)
 311     EAL: Ask a virtual area of 0x400000 bytes
 312     EAL: Virtual area found at 0x7f0a9d600000 (size = 0x400000)
 313     EAL: Ask a virtual area of 0x400000 bytes
 314     EAL: Virtual area found at 0x7f0a9d000000 (size = 0x400000)
 315     EAL: Ask a virtual area of 0x400000 bytes
 316     EAL: Virtual area found at 0x7f0a9ca00000 (size = 0x400000)
 317     EAL: Ask a virtual area of 0x200000 bytes
 318     EAL: Virtual area found at 0x7f0a9c600000 (size = 0x200000)
 319     EAL: Ask a virtual area of 0x200000 bytes
 320     EAL: Virtual area found at 0x7f0a9c200000 (size = 0x200000)
 321     EAL: Ask a virtual area of 0x3fc00000 bytes
 322     EAL: Virtual area found at 0x7f0a5c400000 (size = 0x3fc00000)
 323     EAL: Ask a virtual area of 0x200000 bytes
 324     EAL: Virtual area found at 0x7f0a5c000000 (size = 0x200000)
 325     EAL: Requesting 1024 pages of size 2MB from socket 0
 326     EAL: Requesting 1024 pages of size 2MB from socket 1
 327     EAL: Master core 0 is ready (tid=de25b700)
 328     EAL: Core 1 is ready (tid=5b7fe700)
 329     EAL: Core 3 is ready (tid=5a7fc700)
 330     EAL: Core 2 is ready (tid=5affd700)
 331     hello from core 1
 332     hello from core 2
 333     hello from core 3
 334     hello from core 0