1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2021 ARM Corporation.
4 Cross compiling DPDK for aarch64 and aarch32
5 ============================================
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.
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.
24 NUMA is required by most modern machines, not needed for non-NUMA architectures.
28 For compiling the NUMA lib, run libtool --version to ensure the libtool version >= 2.2,
29 otherwise the compilation will fail with errors.
31 .. code-block:: console
33 git clone https://github.com/numactl/numactl.git
35 git checkout v2.0.13 -b v2.0.13
38 ./configure --host=aarch64-linux-gnu CC=aarch64-none-linux-gnu-gcc --prefix=<numa install dir>
43 The compiler is ``aarch64-none-linux-gnu-gcc`` if you download GCC
44 using the below guide. If you're using a different compiler,
45 make sure you're using the proper executable name.
47 The numa header files and lib file is generated in the include and lib folder
48 respectively under ``<numa install dir>``.
53 Meson depends on pkgconfig to find the dependencies.
54 The package ``pkg-config-aarch64-linux-gnu`` is required for aarch64.
55 To install it in Ubuntu::
57 sudo apt install pkg-config-aarch64-linux-gnu
59 For aarch32, install ``pkg-config-arm-linux-gnueabihf``::
61 sudo apt install pkg-config-arm-linux-gnueabihf
67 .. _obtain_GNU_toolchain:
69 Get the cross toolchain
70 ~~~~~~~~~~~~~~~~~~~~~~~
72 The latest GNU cross compiler toolchain can be downloaded from:
73 https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads.
75 It is always recommended to check and get the latest compiler tool
76 from the page and use it to generate better code.
77 As of this writing 9.2-2019.12 is the newest,
78 the following description is an example of this version.
82 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
83 tar -xvf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
84 export PATH=$PATH:<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin
88 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
89 tar -xvf gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz
90 export PATH=$PATH:<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf/bin
94 For the host requirements and other info, refer to the release note section:
95 https://releases.linaro.org/components/toolchain/binaries/
97 .. _augment_the_gnu_toolchain_with_numa_support:
99 Augment the GNU toolchain with NUMA support
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 Copy the NUMA header files and lib to the cross compiler's directories:
104 .. code-block:: console
106 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/
107 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/
108 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 Using LDFLAGS and CFLAGS is not a viable alternative to copying the files.
113 The Meson docs say it is not recommended, as there are many caveats
114 to their use with Meson, especially when rebuilding the project.
115 A viable alternative would be to use the ``c_args`` and ``c_link_args``
116 options with Meson 0.51.0 and higher:
118 .. code-block:: console
120 -Dc_args=-I<numa_install_dir>/include -Dc_link_args=-L<numa_install_dir>/lib
122 For Meson versions lower than 0.51.0, the ``c_args`` and ``c_link_args``
123 options do not apply to cross compilation.
124 However, the compiler/linker flags may be added to cross files under [properties]:
126 .. code-block:: console
128 c_args = ['-I<numa_install_dir>/include']
129 c_link_args = ['-L<numa_install_dir>/lib']
131 Cross Compiling DPDK with GNU toolchain using Meson
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136 The names of GCC binaries in cross files differ from the downloaded ones,
137 which have an extra ``-none-`` in their name.
138 Please modify the cross file binaries accordingly
139 when using the downloaded cross compilers.
141 An example cross file with modified names and added NUMA paths
142 would look like this:
144 .. code-block:: console
147 c = 'aarch64-none-linux-gnu-gcc'
148 cpp = 'aarch64-none-linux-gnu-cpp'
149 ar = 'aarch64-none-linux-gnu-gcc-ar'
150 strip = 'aarch64-none-linux-gnu-strip'
151 pkgconfig = 'aarch64-linux-gnu-pkg-config' # the downloaded binaries
152 # do not contain a pkgconfig binary, so it is not modified
157 cpu_family = 'aarch64'
162 # Generate binaries that are portable across all Armv8 machines
164 c_args = ['-I<numa_install_dir>/include'] # replace <numa_install_dir>
165 c_link_args = ['-L<numa_install_dir>/lib'] # with your path
167 To cross-compile DPDK on a desired target machine we can use the following
170 meson cross-build --cross-file <target_machine_configuration>
173 For example if the target machine is aarch64 we can use the following
174 command, provided the cross file has been modified accordingly::
176 meson aarch64-build-gcc --cross-file config/arm/arm64_armv8_linux_gcc
177 ninja -C aarch64-build-gcc
179 If the target machine is aarch32 we can use the following command,
180 provided the cross file has been modified accordingly::
182 meson aarch32-build --cross-file config/arm/arm32_armv8_linux_gcc
183 ninja -C aarch32-build
188 Obtain the cross tool chain
189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
191 The latest LLVM/Clang cross compiler toolchain can be downloaded from:
192 https://developer.arm.com/tools-and-software/open-source-software/developer-tools/llvm-toolchain.
194 .. code-block:: console
197 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
199 The LLVM/Clang toolchain does not implement the standard c library.
200 The GNU toolchain ships an implementation we can use.
201 Refer to obtain_GNU_toolchain_ to get the GNU toolchain.
203 Unzip and add into the PATH
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
206 .. code-block:: console
208 tar -xvf clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
209 export PATH=$PATH:<cross_install_dir>/clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04/bin
211 Cross Compiling DPDK with LLVM/Clang toolchain using Meson
212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
216 To use the NUMA library follow the same steps as for
217 augment_the_gnu_toolchain_with_numa_support_.
219 The paths to GNU stdlib must be specified in a cross file.
220 Augmenting the default cross-file's ``c_args`` and ``c_link_args``
221 ``config/arm/arm64_armv8_linux_clang_ubuntu1804`` would look like this:
223 .. code-block:: console
226 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']
227 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']
229 Assuming the file with augmented ``c_args`` and ``c_link_args``
230 is named ``arm64_armv8_linux_clang``,
231 use the following command to cross-compile DPDK for the target machine::
233 meson aarch64-build-clang --cross-file config/arm/arm64_armv8_linux_clang
234 ninja -C aarch64-build-clang
236 Cross Compiling DPDK with LLVM/Clang toolchain using Meson on Ubuntu 18.04
237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
239 On most popular Linux distribution it is not necessary to download
240 the toolchains, but rather use the packages provided by said distributions.
241 On Ubuntu 18.04, these packages are needed:
243 .. code-block:: console
245 sudo apt-get install pkg-config-aarch64-linux-gnu clang llvm llvm-dev lld
246 libc6-dev-arm64-cross libatomic1-arm64-cross libgcc-8-dev-arm64-cross
248 Use the following command to cross-compile DPDK for the target machine::
250 meson aarch64-build-clang --cross-file config/arm/arm64_armv8_linux_clang_ubuntu1804
251 ninja -C aarch64-build-clang
253 Building for an aarch64 SoC on an aarch64 build machine
254 -------------------------------------------------------
256 If you wish to build on an aarch64 build machine for a different aarch64 SoC,
257 you don't need a separate cross toolchain, just a different set of
258 configuration options. To build for an aarch64 SoC, use the -Dplatform meson
261 meson soc_build -Dplatform=<target_soc>
263 Substitute <target_soc> with one of the supported SoCs
265 .. literalinclude:: ../../../config/arm/meson.build
266 :start-after: Start of SoCs list
267 :end-before: End of SoCs list
269 These SoCs are also used in cross files, e.g.::
272 # Generate binaries that are portable across all Armv8 machines
275 Supported SoC configuration
276 ---------------------------
278 The SoC configuration is a combination of implementer and CPU part number
279 configuration and SoC-specific configuration::
282 'description': 'SoC Description', # mandatory
283 'implementer': <implementer_id>, # mandatory
284 'part_number': <part_number>, # mandatory
285 'numa': false, # optional, specify for non-NUMA SoCs
286 'enable_drivers': 'common/*,bus/*', # optional, comma-separated list of
287 # drivers to build, wildcards are accepted
288 'disable_drivers': 'crypto/*', # optional, comma-separated list of
289 # drivers to disable, wildcards are accepted
291 ['RTE_MAX_LCORE', '16'],
292 ['RTE_MAX_NUMA_NODES', '1']
293 ] # optional, list of DPDK options that will be added
297 Where <implementer_id> is a key defined in the implementers dictionary
298 in config/arm/meson.build (e.g. 0x41) and part_number is a key defined
299 in implementers[<implementer_id>]['part_number_config'] dictionary
300 (i.e. the part number must be defined for the implementer,
301 e.g. for 0x41, a valid value is 0xd49, which is the neoverse-n2 SoC).