doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 ARM Corporation.
   3
   4 Cross compiling DPDK for aarch64 and aarch32
   5 ============================================
   6
   7 This chapter describes how to cross compile DPDK for aarch64 on x86 build
   8 machine and compile 32-bit aarch32 DPDK on aarch64 build machine.
   9
  10 .. note::
  11
  12    Whilst it is recommended to natively build DPDK on aarch64 (just
  13    like with x86), it is also possible to cross compile DPDK for aarch64.
  14    An aarch64 cross compiler GNU toolchain or an LLVM/clang toolchain
  15    may be used for cross-compilation.
  16
  17
  18 Prerequisites
  19 -------------
  20
  21 NUMA library
  22 ~~~~~~~~~~~~
  23
  24 NUMA is required by most modern machines, not needed for non-NUMA architectures.
  25
  26 .. note::
  27
  28    For compiling the NUMA lib, run libtool --version to ensure the libtool version >= 2.2,
  29    otherwise the compilation will fail with errors.
  30
  31 .. code-block:: console
  32
  33    git clone https://github.com/numactl/numactl.git
  34    cd numactl
  35    git checkout v2.0.13 -b v2.0.13
  36    ./autogen.sh
  37    autoconf -i
  38    ./configure --host=aarch64-linux-gnu CC=<compiler> --prefix=<numa install dir>
  39    make install
  40
  41 .. note::
  42
  43    The compiler above can be either aarch64-linux-gnu-gcc or clang.
  44    See below for information on how to get specific compilers.
  45
  46 The numa header files and lib file is generated in the include and lib folder
  47 respectively under ``<numa install dir>``.
  48
  49 Meson prerequisites
  50 ~~~~~~~~~~~~~~~~~~~
  51
  52 Meson depends on pkgconfig to find the dependencies.
  53 The package ``pkg-config-aarch64-linux-gnu`` is required for aarch64.
  54 To install it in Ubuntu::
  55
  56    sudo apt install pkg-config-aarch64-linux-gnu
  57
  58 For aarch32, install ``pkg-config-arm-linux-gnueabihf``::
  59
  60    sudo apt install pkg-config-arm-linux-gnueabihf
  61
  62
  63 GNU toolchain
  64 -------------
  65
  66 .. _obtain_GNU_toolchain:
  67
  68 Get the cross toolchain
  69 ~~~~~~~~~~~~~~~~~~~~~~~
  70
  71 The latest GNU cross compiler toolchain can be downloaded from:
  72 https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads.
  73
  74 It is always recommended to check and get the latest compiler tool
  75 from the page and use it to generate better code.
  76 As of this writing 9.2-2019.12 is the newest,
  77 the following description is an example of this version.
  78
  79 For aarch64::
  80
  81    wget https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
  82    tar -xvf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
  83    export PATH=$PATH:<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin
  84
  85 For aarch32::
  86
  87    wget https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz
  88    tar -xvf gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz
  89    export PATH=$PATH:<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf/bin
  90
  91 .. note::
  92
  93    For the host requirements and other info, refer to the release note section:
  94    https://releases.linaro.org/components/toolchain/binaries/
  95
  96 .. _augment_the_gnu_toolchain_with_numa_support:
  97
  98 Augment the GNU toolchain with NUMA support
  99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 100
 101 .. note::
 102
 103    This way is optional, an alternative is to use extra CFLAGS and LDFLAGS.
 104
 105 Copy the NUMA header files and lib to the cross compiler's directories:
 106
 107 .. code-block:: console
 108
 109    cp <numa_install_dir>/include/numa*.h <cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/aarch64-none-linux-gnu/libc/usr/include/
 110    cp <numa_install_dir>/lib/libnuma.a <cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/lib/gcc/aarch64-none-linux-gnu/9.2.1/
 111    cp <numa_install_dir>/lib/libnuma.so <cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/lib/gcc/aarch64-none-linux-gnu/9.2.1/
 112
 113 Cross Compiling DPDK with GNU toolchain using Meson
 114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 115
 116 To cross-compile DPDK on a desired target machine we can use the following
 117 command::
 118
 119    meson cross-build --cross-file <target_machine_configuration>
 120    ninja -C cross-build
 121
 122 For example if the target machine is aarch64 we can use the following
 123 command::
 124
 125    meson aarch64-build-gcc --cross-file config/arm/arm64_armv8_linux_gcc
 126    ninja -C aarch64-build-gcc
 127
 128 If the target machine is aarch32 we can use the following command::
 129
 130    meson aarch32-build --cross-file config/arm/arm32_armv8_linux_gcc
 131    ninja -C aarch32-build
 132
 133 LLVM/Clang toolchain
 134 --------------------
 135
 136 Obtain the cross tool chain
 137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 138
 139 The latest LLVM/Clang cross compiler toolchain can be downloaded from:
 140 https://developer.arm.com/tools-and-software/open-source-software/developer-tools/llvm-toolchain.
 141
 142 .. code-block:: console
 143
 144    # Ubuntu binaries
 145    wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
 146
 147 The LLVM/Clang toolchain does not implement the standard c library.
 148 The GNU toolchain ships an implementation we can use.
 149 Refer to obtain_GNU_toolchain_ to get the GNU toolchain.
 150
 151 Unzip and add into the PATH
 152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 .. code-block:: console
 155
 156    tar -xvf clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
 157    export PATH=$PATH:<cross_install_dir>/clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04/bin
 158
 159 Cross Compiling DPDK with LLVM/Clang toolchain using Meson
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 .. note::
 163
 164    To use the NUMA library follow the same steps as for
 165    augment_the_gnu_toolchain_with_numa_support_.
 166
 167 The paths to GNU stdlib must be specified in a cross file.
 168 Augmenting the default cross-file's ``c_args`` and ``c_link_args``
 169 ``config/arm/arm64_armv8_linux_clang_ubuntu1804`` would look like this:
 170
 171 .. code-block:: console
 172
 173    ...
 174    c_args = ['-target', 'aarch64-linux-gnu', '--sysroot', '<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/aarch64-none-linux-gnu/libc']
 175    c_link_args = ['-target', 'aarch64-linux-gnu', '-fuse-ld=lld', '--sysroot', '<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/aarch64-none-linux-gnu/libc', '--gcc-toolchain=<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu']
 176
 177 Assuming the file with augmented ``c_args`` and ``c_link_args``
 178 is named ``arm64_armv8_linux_clang``,
 179 use the following command to cross-compile DPDK for the target machine::
 180
 181    meson aarch64-build-clang --cross-file config/arm/arm64_armv8_linux_clang
 182    ninja -C aarch64-build-clang
 183
 184 Cross Compiling DPDK with LLVM/Clang toolchain using Meson on Ubuntu 18.04
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187 On most popular Linux distribution it is not necessary to download
 188 the toolchains, but rather use the packages provided by said distributions.
 189 On Ubuntu 18.04, these packages are needed:
 190
 191 .. code-block:: console
 192
 193    sudo apt-get install pkg-config-aarch64-linux-gnu clang llvm llvm-dev lld
 194    libc6-dev-arm64-cross libatomic1-arm64-cross libgcc-8-dev-arm64-cross
 195
 196 Use the following command to cross-compile DPDK for the target machine::
 197
 198    meson aarch64-build-clang --cross-file config/arm/arm64_armv8_linux_clang_ubuntu1804
 199    ninja -C aarch64-build-clang
 200
 201 Building for an aarch64 SoC on an aarch64 build machine
 202 -------------------------------------------------------
 203
 204 If you wish to build on an aarch64 build machine for a different aarch64 SoC,
 205 you don't need a separate cross toolchain, just a different set of
 206 configuration options. To build for an aarch64 SoC, use the -Dplatform meson
 207 option::
 208
 209    meson soc_build -Dplatform=<target_soc>
 210
 211 Substitute <target_soc> with one of the supported SoCs
 212
 213 .. literalinclude:: ../../../config/arm/meson.build
 214    :start-after: Start of SoCs list
 215    :end-before: End of SoCs list
 216
 217 These SoCs are also used in cross files, e.g.::
 218
 219    [properties]
 220    # Generate binaries that are portable across all Armv8 machines
 221    platform = 'generic'
 222
 223 Supported SoC configuration
 224 ---------------------------
 225
 226 The SoC configuration is a combination of implementer and CPU part number
 227 configuration and SoC-specific configuration::
 228
 229    soc_<name> = {
 230       'description': 'SoC Description',  # mandatory
 231       'implementer': <implementer_id>,   # mandatory
 232       'part_number': <part_number>,      # mandatory
 233       'numa': false,  # optional, specify for non-NUMA SoCs
 234       'enable_drivers': 'common/*,bus/*',  # optional, comma-separated list of
 235                               # drivers to build, wildcards are accepted
 236       'disable_drivers': 'crypto/*',       # optional, comma-separated list of
 237                               # drivers to disable, wildcards are accepted
 238       'flags': [
 239          ['RTE_MAX_LCORE', '16'],
 240          ['RTE_MAX_NUMA_NODES', '1']
 241       ]               # optional, list of DPDK options that will be added
 242                       # or overwritten
 243    }
 244
 245 Where <implementer_id> is a key defined in the implementers dictionary
 246 in config/arm/meson.build (e.g. 0x41) and part_number is a key defined
 247 in implementers[<implementer_id>]['part_number_config'] dictionary
 248 (i.e. the part number must be defined for the implementer,
 249 e.g. for 0x41, a valid value is 0xd49, which is the neoverse-n2 SoC).