doc/guides/linux_gsg/quick_start.rst

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