doc/guides/freebsd_gsg/build_dpdk.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 Compiling the Intel® DPDK Target from Source
  32 ============================================
  33
  34 Install the Intel® DPDK and Browse Sources
  35 ------------------------------------------
  36
  37 First, uncompress the archive and move to the Intel® DPDK source directory:
  38
  39 .. code-block:: console
  40
  41     user@host:~ # unzip DPDK-<version>zip
  42     user@host:~ # cd DPDK-<version>
  43     user@host:~/DPDK # ls
  44     app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile mk/ scripts/ tools/
  45
  46 The Intel® DPDK is composed of several directories:
  47
  48 *   lib: Source code of Intel® DPDK libraries
  49
  50 *   app: Source code of Intel® DPDK applications (automatic tests)
  51
  52 *   examples: Source code of Intel® DPDK applications
  53
  54 *   config, tools, scripts, mk: Framework-related makefiles, scripts and configuration
  55
  56 Installation of the Intel® DPDK Target Environments
  57 ---------------------------------------------------
  58
  59 The format of an Intel® DPDK target is:
  60
  61 ARCH-MACHINE-EXECENV-TOOLCHAIN
  62
  63 Where:
  64
  65 *   ARCH is:   x86_64
  66
  67 *   MACHINE is: native
  68
  69 *   EXECENV is: bsdapp
  70
  71 *   TOOLCHAIN is: gcc
  72
  73 The configuration files for the Intel® DPDK targets can be found in the DPDK/config
  74 directory in the form of:
  75
  76 ::
  77
  78     defconfig_ARCH-MACHINE-EXECENV-TOOLCHAIN
  79
  80 .. note::
  81
  82     Configuration files are provided with the RTE_MACHINE optimization level set.
  83     Within the configuration files, the RTE_MACHINE configuration value is set
  84     to native, which means that the compiled software is tuned for the platform
  85     on which it is built.  For more information on this setting, and its
  86     possible values, see the *Intel® DPDK Programmers Guide*.
  87
  88 To install and make the target, use gmake install T=<target> CC=gcc48.
  89
  90 For example to compile for FreeBSD* use:
  91
  92 .. code-block:: console
  93
  94     gmake install T=x86_64-native-bsdapp-gcc CC=gcc48
  95
  96 To prepare a target without building it, for example, if the configuration
  97 changes need to be made before compilation, use the gmake config T=<target> command:
  98
  99 .. code-block:: console
 100
 101     gmake config T=x86_64-native-bsdapp-gcc CC=gcc48
 102
 103 To build after configuration, change directory to ./x86_64-native-bsdapp-gcc and use:
 104
 105 .. code-block:: console
 106
 107     gmake CC=gcc48
 108
 109 Browsing the Installed Intel® DPDK Environment Target
 110 -----------------------------------------------------
 111
 112 Once a target is created, it contains all the libraries and header files for the
 113 Intel® DPDK environment that are required to build customer applications.
 114 In addition, the test and testpmd applications are built under the build/app
 115 directory, which may be used for testing.  A kmod directory is also present that
 116 contains the kernel modules to install:
 117
 118 .. code-block:: console
 119
 120     user@host:~/DPDK # ls x86_64-native-bsdapp-gcc
 121     app   build    hostapp    include    kmod    lib    Makefile
 122
 123 Loading the Intel® DPDK contigmem Module
 124 ----------------------------------------
 125
 126 To run any Intel® DPDK application, the contigmem module must be loaded into the
 127 running kernel. The module is found in the kmod sub-directory of the Intel® DPDK
 128 target directory. The module can be loaded using kldload (assuming that the
 129 current directory is the Intel® DPDK target directory):
 130
 131 .. code-block:: console
 132
 133     kldload ./kmod/contigmem.ko
 134
 135 It is advisable to include the loading of the contigmem module during the boot
 136 process to avoid issues with potential memory fragmentation during later system
 137 up time.  This can be achieved by copying the module to the /boot/kernel/
 138 directory and placing the following into /boot/loader.conf:
 139
 140 ::
 141
 142     contigmem_load="YES"
 143
 144 .. note::
 145
 146     The contigmem_load directive should be placed after any definitions of
 147     hw.contigmem.num_buffers and hw.contigmem.buffer_size if the default values
 148     are not to be used.
 149
 150 An error such as kldload: can't load ./x86_64-native-bsdapp-gcc/kmod/contigmem.ko:
 151 Exec format error, is generally attributed to not having enough contiguous memory
 152 available and can be verified via dmesg or /var/log/messages:
 153
 154 .. code-block:: console
 155
 156     kernel: contigmalloc failed for buffer <n>
 157
 158 To avoid this error, reduce the number of buffers or the buffer size.
 159
 160 Loading the Intel® DPDK nic_uio Module
 161 --------------------------------------
 162
 163 After loading the contigmem module, the nic_uio must also be loaded into the
 164 running kernel prior to running any Intel® DPDK application.  This module must
 165 be loaded using the kldload command as shown below (assuming that the current
 166 directory is the Intel® DPDK target directory).
 167
 168 .. code-block:: console
 169
 170     kldload ./kmod/nic_uio.ko
 171
 172 .. note::
 173
 174     Currently loaded modules can be seen by using the kldstat command.  A module
 175     can be removed from the running kernel by using kldunload <module_name>.
 176     While the nic_uio module can be loaded during boot, the module load order
 177     cannot be guaranteed and in the case where only some ports are bound to
 178     nic_uio and others remain in use by the original driver, it is necessary to
 179     load nic_uio after booting into the kernel, specifically after the original
 180     driver has been loaded.
 181
 182 To load the module during boot, copy the nic_uio module to /boot/kernel and place the following into /boot/loader.conf:
 183
 184 ::
 185
 186     nic_uio_load="YES"
 187
 188 .. note::
 189
 190     nic_uio_load="YES" must appear after the contigmem_load directive, if it exists.
 191
 192 Binding Network Ports to the nic_uio Module
 193 -------------------------------------------
 194
 195 By default, the nic_uio module will take ownership of network ports if they are
 196 recognized Intel® DPDK devices and are not owned by another module.
 197
 198 Device ownership can be viewed using the pciconf -l command.
 199
 200 The example below shows four Intel® 82599 network ports under if_ixgbe module ownership.
 201
 202 .. code-block:: console
 203
 204     user@host:~ # pciconf -l
 205     ix0@pci0:1:0:0: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 206     ix1@pci0:1:0:1: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 207     ix2@pci0:2:0:0: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 208     ix3@pci0:2:0:1: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 209
 210 The first column constitutes three components:
 211
 212 #.  Device name: ixN
 213
 214 #.  Unit name:  pci0
 215
 216 #.  Selector (Bus:Device:Function):   1:0:0
 217
 218 Where no driver is associated with a device, the device name will be none.
 219
 220 By default, the FreeBSD* kernel will include built-in drivers for the most common
 221 devices; a kernel rebuild would normally be required to either remove the drivers
 222 or configure them as loadable modules.
 223
 224 To avoid building a custom kernel, the nic_uio module can detach a network port
 225 from its current device driver.  This is achieved by setting the hw.nic_uio.bdfs
 226 kernel environment variable prior to loading nic_uio, as follows:
 227
 228 ::
 229
 230     hw.nic_uio.bdfs="b:d:f,b:d:f,..."
 231
 232 Where a comma separated list of selectors is set, the list must not contain any
 233 whitespace.
 234
 235 For example to re-bind ix2@pci0:2:0:0 and ix3@pci0:2:0: to the nic_uio module
 236 upon loading, use the following command:
 237
 238 .. code-block:: console
 239
 240     kenv hw.nic_uio.bdfs="2:0:0,2:0:1"
 241
 242 The variable can also be specified during boot by placing the following into
 243 /boot/loader.conf:
 244
 245 ::
 246
 247     hw.nic_uio.bdfs="2:0:0,2:0:1"
 248
 249 To restore the original device binding, it is necessary to reboot FreeBSD* if the
 250 original driver has been compiled into the kernel.
 251
 252 For example to rebind some or all ports to the original driver:
 253
 254 Update or remove the hw.nic_uio.bdfs entry in /boot/loader.conf if specified there
 255 for persistency, then;
 256
 257 .. code-block:: console
 258
 259     reboot
 260
 261 If rebinding to a driver that is a loadable module, the network port binding can
 262 be reset without rebooting.  This requires the unloading of the nic_uio module
 263 and the original driver.
 264
 265 Update or remove the hw.nic_uio.bdfs entry from /boot/loader.conf if specified
 266 there for persistency.
 267
 268 .. code-block:: console
 269
 270     kldunload nic_uio
 271
 272 kldunload <original_driver>
 273
 274 .. code-block:: console
 275
 276     kenv -u hw.nic_uio.bdfs
 277
 278 to remove all network ports from nic_uio and undefined this system variable OR
 279
 280 .. code-block:: console
 281
 282     kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..."
 283
 284 (to update nic_uio ports)
 285
 286 .. code-block:: console
 287
 288     kldload <original_driver>
 289     kldload nic_uio
 290
 291 (if updating the list of associated network ports)