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