doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst

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