doc/guides/freebsd_gsg/build_dpdk.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 .. _building_from_source:
   5
   6 Compiling the DPDK Target from Source
   7 =====================================
   8
   9 Prerequisites
  10 -------------
  11
  12 The following FreeBSD packages are required to build DPDK:
  13
  14 * meson
  15 * ninja
  16 * pkgconf
  17
  18 These can be installed using (as root)::
  19
  20   pkg install meson pkgconf
  21
  22 To compile the required kernel modules for memory management and working
  23 with physical NIC devices, the kernel sources for FreeBSD also
  24 need to be installed. If not already present on the system, these can be
  25 installed via commands like the following, for FreeBSD 12.1 on x86_64::
  26
  27   fetch http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.1-RELEASE/src.txz
  28   tar -C / -xJvf src.txz
  29
  30 To enable the telemetry library in DPDK, the jansson library also needs to
  31 be installed, and can be installed via::
  32
  33   pkg install jansson
  34
  35 Individual drivers may have additional requirements. Consult the relevant
  36 driver guide for any driver-specific requirements of interest.
  37
  38 Building DPDK
  39 -------------
  40
  41 The following commands can be used to build and install DPDK on a system.
  42 The final, install, step generally needs to be run as root::
  43
  44   meson build
  45   cd build
  46   ninja
  47   ninja install
  48
  49 This will install the DPDK libraries and drivers to `/usr/local/lib` with a
  50 pkg-config file `libdpdk.pc` installed to `/usr/local/lib/pkgconfig`. The
  51 DPDK test applications, such as `dpdk-testpmd` are installed to
  52 `/usr/local/bin`. To use these applications, it is recommended that the
  53 `contigmem` and `nic_uio` kernel modules be loaded first, as described in
  54 the next section.
  55
  56 .. note::
  57
  58         It is recommended that pkg-config be used to query information
  59         about the compiler and linker flags needed to build applications
  60         against DPDK.  In some cases, the path `/usr/local/lib/pkgconfig`
  61         may not be in the default search paths for `.pc` files, which means
  62         that queries for DPDK information may fail. This can be fixed by
  63         setting the appropriate path in `PKG_CONFIG_PATH` environment
  64         variable.
  65
  66
  67 .. _loading_contigmem:
  68
  69 Loading the DPDK contigmem Module
  70 ---------------------------------
  71
  72 To run a DPDK application, physically contiguous memory is required.
  73 In the absence of non-transparent superpages, the included sources for the
  74 contigmem kernel module provides the ability to present contiguous blocks of
  75 memory for the DPDK to use. The contigmem module must be loaded into the
  76 running kernel before any DPDK is run.  The module is found in the kmod
  77 sub-directory of the DPDK target directory.
  78
  79 The amount of physically contiguous memory along with the number of physically
  80 contiguous blocks to be reserved by the module can be set at runtime prior to
  81 module loading using:
  82
  83 .. code-block:: console
  84
  85     kenv hw.contigmem.num_buffers=n
  86     kenv hw.contigmem.buffer_size=m
  87
  88 The kernel environment variables can also be specified during boot by placing the
  89 following in ``/boot/loader.conf``::
  90
  91     hw.contigmem.num_buffers=n hw.contigmem.buffer_size=m
  92
  93 The variables can be inspected using the following command:
  94
  95 .. code-block:: console
  96
  97     sysctl -a hw.contigmem
  98
  99 Where n is the number of blocks and m is the size in bytes of each area of
 100 contiguous memory.  A default of two buffers of size 1073741824 bytes (1 Gigabyte)
 101 each is set during module load if they are not specified in the environment.
 102
 103 The module can then be loaded using kldload (assuming that the current directory
 104 is the DPDK target directory):
 105
 106 .. code-block:: console
 107
 108     kldload ./kmod/contigmem.ko
 109
 110 It is advisable to include the loading of the contigmem module during the boot
 111 process to avoid issues with potential memory fragmentation during later system
 112 up time.  This can be achieved by copying the module to the ``/boot/kernel/``
 113 directory and placing the following into ``/boot/loader.conf``::
 114
 115     contigmem_load="YES"
 116
 117 .. note::
 118
 119     The contigmem_load directive should be placed after any definitions of
 120     ``hw.contigmem.num_buffers`` and ``hw.contigmem.buffer_size`` if the default values
 121     are not to be used.
 122
 123 An error such as:
 124
 125 .. code-block:: console
 126
 127     kldload: can't load ./x86_64-native-freebsd-gcc/kmod/contigmem.ko:
 128              Exec format error
 129
 130 is generally attributed to not having enough contiguous memory
 131 available and can be verified via dmesg or ``/var/log/messages``:
 132
 133 .. code-block:: console
 134
 135     kernel: contigmalloc failed for buffer <n>
 136
 137 To avoid this error, reduce the number of buffers or the buffer size.
 138
 139 .. _loading_nic_uio:
 140
 141 Loading the DPDK nic_uio Module
 142 -------------------------------
 143
 144 After loading the contigmem module, the ``nic_uio`` module must also be loaded into the
 145 running kernel prior to running any DPDK application.  This module must
 146 be loaded using the kldload command as shown below (assuming that the current
 147 directory is the DPDK target directory).
 148
 149 .. code-block:: console
 150
 151     kldload ./kmod/nic_uio.ko
 152
 153 .. note::
 154
 155     If the ports to be used are currently bound to a existing kernel driver
 156     then the ``hw.nic_uio.bdfs sysctl`` value will need to be set before loading the
 157     module. Setting this value is described in the next section below.
 158
 159 Currently loaded modules can be seen by using the ``kldstat`` command and a module
 160 can be removed from the running kernel by using ``kldunload <module_name>``.
 161
 162 To load the module during boot, copy the ``nic_uio`` module to ``/boot/kernel``
 163 and place the following into ``/boot/loader.conf``::
 164
 165     nic_uio_load="YES"
 166
 167 .. note::
 168
 169     ``nic_uio_load="YES"`` must appear after the contigmem_load directive, if it exists.
 170
 171 By default, the ``nic_uio`` module will take ownership of network ports if they are
 172 recognized DPDK devices and are not owned by another module. However, since
 173 the FreeBSD kernel includes support, either built-in, or via a separate driver
 174 module, for most network card devices, it is likely that the ports to be used are
 175 already bound to a driver other than ``nic_uio``. The following sub-section describe
 176 how to query and modify the device ownership of the ports to be used by
 177 DPDK applications.
 178
 179 .. _binding_network_ports:
 180
 181 Binding Network Ports to the nic_uio Module
 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 Device ownership can be viewed using the pciconf -l command. The example below shows
 185 four Intel® 82599 network ports under ``if_ixgbe`` module ownership.
 186
 187 .. code-block:: console
 188
 189     pciconf -l
 190     ix0@pci0:1:0:0: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 191     ix1@pci0:1:0:1: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 192     ix2@pci0:2:0:0: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 193     ix3@pci0:2:0:1: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00
 194
 195 The first column constitutes three components:
 196
 197 #. Device name: ``ixN``
 198
 199 #. Unit name: ``pci0``
 200
 201 #. Selector (Bus:Device:Function): ``1:0:0``
 202
 203 Where no driver is associated with a device, the device name will be ``none``.
 204
 205 By default, the FreeBSD kernel will include built-in drivers for the most common
 206 devices; a kernel rebuild would normally be required to either remove the drivers
 207 or configure them as loadable modules.
 208
 209 To avoid building a custom kernel, the ``nic_uio`` module can detach a network port
 210 from its current device driver. This is achieved by setting the ``hw.nic_uio.bdfs``
 211 kernel environment variable prior to loading ``nic_uio``, as follows::
 212
 213     hw.nic_uio.bdfs="b:d:f,b:d:f,..."
 214
 215 Where a comma separated list of selectors is set, the list must not contain any
 216 whitespace.
 217
 218 For example to re-bind ``ix2@pci0:2:0:0`` and ``ix3@pci0:2:0:1`` to the ``nic_uio`` module
 219 upon loading, use the following command::
 220
 221     kenv hw.nic_uio.bdfs="2:0:0,2:0:1"
 222
 223 The variable can also be specified during boot by placing the following into
 224 ``/boot/loader.conf``, before the previously-described ``nic_uio_load`` line - as
 225 shown::
 226
 227     hw.nic_uio.bdfs="2:0:0,2:0:1"
 228     nic_uio_load="YES"
 229
 230 Binding Network Ports Back to their Original Kernel Driver
 231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 232
 233 If the original driver for a network port has been compiled into the kernel,
 234 it is necessary to reboot FreeBSD to restore the original device binding. Before
 235 doing so, update or remove the ``hw.nic_uio.bdfs`` in ``/boot/loader.conf``.
 236
 237 If rebinding to a driver that is a loadable module, the network port binding can
 238 be reset without rebooting. To do so, unload both the target kernel module and the
 239 ``nic_uio`` module, modify or clear the ``hw.nic_uio.bdfs`` kernel environment (kenv)
 240 value, and reload the two drivers - first the original kernel driver, and then
 241 the ``nic_uio driver``. Note: the latter does not need to be reloaded unless there are
 242 ports that are still to be bound to it.
 243
 244 Example commands to perform these steps are shown below:
 245
 246 .. code-block:: console
 247
 248     kldunload nic_uio
 249     kldunload <original_driver>
 250
 251     # To clear the value completely:
 252     kenv -u hw.nic_uio.bdfs
 253
 254     # To update the list of ports to bind:
 255     kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..."
 256
 257     kldload <original_driver>
 258
 259     kldload nic_uio  # optional