Reorganize and update the aarch64 cross guide with clang cross
compilation. Update the GNU toolchain version which clang also uses.
Reorganize into common part, GNU part and clang part.
Signed-off-by: Juraj Linkeš <juraj.lin...@pantheon.tech>
Acked-by: Ruifeng Wang <ruifeng.w...@arm.com>
---
.../linux_gsg/cross_build_dpdk_for_arm64.rst | 183 +++++++++++++-----
1 file changed, 132 insertions(+), 51 deletions(-)
diff --git a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
index d0d346c83..ed34cdb0f 100644
--- a/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
+++ b/doc/guides/linux_gsg/cross_build_dpdk_for_arm64.rst
@@ -1,104 +1,185 @@
.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2018 ARM Corporation.
+ Copyright(c) 2020 ARM Corporation.
-Cross compile DPDK for ARM64
-============================
+Cross compiling DPDK for ARM64
+==============================
This chapter describes how to cross compile DPDK for ARM64 from x86 build
hosts.
.. note::
Whilst it is recommended to natively build DPDK on ARM64 (just
- like with x86), it is also possible to cross-build DPDK for ARM64. An
- ARM64 cross compile GNU toolchain is used for this.
+ like with x86), it is also possible to cross compile DPDK for ARM64.
+ An ARM64 cross compiler GNU toolchain or an LLVM/clang toolchain
+ may be used for cross-compilation.
-Obtain the cross tool chain
----------------------------
-The latest cross compile tool chain can be downloaded from:
+
+Prerequisites
+-------------
+
+NUMA library
+~~~~~~~~~~~~
+
+NUMA is required by most modern machines, not needed for non-NUMA
architectures.
+
+.. note::
+
+ For compiling the NUMA lib, run libtool --version to ensure the libtool
version >= 2.2,
+ otherwise the compilation will fail with errors.
+
+.. code-block:: console
+
+ git clone https://github.com/numactl/numactl.git
+ cd numactl
+ git checkout v2.0.13 -b v2.0.13
+ ./autogen.sh
+ autoconf -i
+ ./configure --host=aarch64-linux-gnu CC=<compiler> --prefix=<numa install
dir>
+ make install
+
+.. note::
+
+ The compiler above can be either aarch64-linux-gnu-gcc or clang.
+ See below for information on how to get the compiler of your choice.
+
+The numa header files and lib file is generated in the include and lib folder
respectively under <numa install dir>.
+
+Meson prerequisites
+~~~~~~~~~~~~~~~~~~~
+
+Meson depends on pkgconfig to find the dependencies.
+The package ``pkg-config-aarch64-linux-gnu`` is required for aarch64.
+To install it in Ubuntu::
+
+ sudo apt install pkg-config-aarch64-linux-gnu
+
+
+GNU toolchain
+-------------
+
+.. _obtain_GNU_toolchain:
+
+Obtain the cross toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The latest GNU cross compiler toolchain can be downloaded from:
https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads.
It is always recommended to check and get the latest compiler tool from the
page and use
-it to generate better code. As of this writing 8.3-2019.03 is the newest, the
following
+it to generate better code. As of this writing 9.2-2019.12 is the newest, the
following
description is an example of this version.
.. code-block:: console
- wget
https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz
+ 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
Unzip and add into the PATH
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: console
- tar -xvf gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu.tar.xz
- export
PATH=$PATH:<cross_install_dir>/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/bin
+ tar -xvf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
+ export
PATH=$PATH:<cross_install_dir>/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu/bin
.. note::
For the host requirements and other info, refer to the release note
section: https://releases.linaro.org/components/toolchain/binaries/
-.. _arm_cross_build_getting_the_prerequisite_library:
+.. _augment_the_gnu_toolchain_with_numa_support:
-Getting the prerequisite library
---------------------------------
-
-NUMA is required by most modern machines, not needed for non-NUMA
architectures.
+Augment the GNU toolchain with NUMA support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
- For compiling the NUMA lib, run libtool --version to ensure the libtool
version >= 2.2,
- otherwise the compilation will fail with errors.
+ This way is optional, an alternative is to use extra CFLAGS and LDFLAGS.
+
+Copy the NUMA header files and lib to the cross compiler's directories:
.. code-block:: console
- git clone https://github.com/numactl/numactl.git
- cd numactl
- git checkout v2.0.13 -b v2.0.13
- ./autogen.sh
- autoconf -i
- ./configure --host=aarch64-linux-gnu CC=aarch64-linux-gnu-gcc
--prefix=<numa install dir>
- make install
+ 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/
+ 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/
+ 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/
-The numa header files and lib file is generated in the include and lib folder
respectively under <numa install dir>.
+Cross Compiling DPDK with GNU toolchain using Meson
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To cross-compile DPDK on a desired target machine we can use the following
+command::
+
+ meson cross-build --cross-file <target_machine_configuration>
+ ninja -C cross-build
+
+For example if the target machine is aarch64 we can use the following
+command::
-.. _augment_the_cross_toolchain_with_numa_support:
+ meson aarch64-build-gcc --cross-file config/arm/arm64_armv8_linux_gcc
+ ninja -C aarch64-build-gcc
-Augment the cross toolchain with NUMA support
----------------------------------------------
+
+LLVM/Clang toolchain
+--------------------
+
+Obtain the cross tool chain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The latest LLVM/Clang cross compiler toolchain can be downloaded from:
+https://developer.arm.com/tools-and-software/open-source-software/developer-tools/llvm-toolchain.
+
+.. code-block:: console
+
+ # Ubuntu binaries
+ 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
+
+The LLVM/Clang toolchain does not implement the standard c library. The GNU
toolchain
+ships an implementation we can use. Refer to obtain_GNU_toolchain_ to get the
+GNU toolchain.
+
+Unzip and add into the PATH
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ tar -xvf clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
+ export
PATH=$PATH:<cross_install_dir>/clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04/bin
+
+Cross Compiling DPDK with LLVM/Clang toolchain using Meson
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
- This way is optional, an alternative is to use extra CFLAGS and LDFLAGS.
+ To use the NUMA library follow the same steps as for
+ augment_the_gnu_toolchain_with_numa_support_.
-Copy the NUMA header files and lib to the cross compiler's directories:
+The paths to GNU stdlib must be specified in a cross file. Augmenting the
default
+cross-file's c_args and c_link_args
config/arm/arm64_armv8_linux_clang_ubuntu1804 would look like this:
.. code-block:: console
- cp <numa_install_dir>/include/numa*.h
<cross_install_dir>/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/aarch64-linux-gnu/libc/usr/include/
- cp <numa_install_dir>/lib/libnuma.a
<cross_install_dir>/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/lib/gcc/aarch64-linux-gnu/8.3.0/
- cp <numa_install_dir>/lib/libnuma.so
<cross_install_dir>/gcc-arm-8.3-2019.03-x86_64-aarch64-linux-gnu/lib/gcc/aarch64-linux-gnu/8.3.0/
+ ...
+ 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']
+ 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']
-.. _configure_and_cross_compile_dpdk_build:
+Assuming the file with augmented c_args and c_link_args is named
arm64_armv8_linux_clang,
+use the following command to cross-compile DPDK for your target machine::
-Cross Compiling DPDK
---------------------
+ meson aarch64-build-clang --cross-file config/arm/arm64_armv8_linux_clang
+ ninja -C aarch64-build-clang
-Meson depends on pkgconfig to find the dependencies.
-The package ``pkg-config-aarch64-linux-gnu`` is required for aarch64.
-To install it in Ubuntu::
+Cross Compiling DPDK with LLVM/Clang toolchain using Meson on Ubuntu 18.04
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- sudo apt-get install pkg-config-aarch64-linux-gnu
+On most popular Linux distribution it's not necessary to download
+the toolchains, but rather use the packages provided by said distributions.
+On Ubuntu 18.04, you'll need these packages:
-To cross-compile DPDK on a desired target machine we can use the following
-command::
+.. code-block:: console
- meson cross-build --cross-file <target_machine_configuration>
- ninja -C cross-build
+ sudo apt-get install pkg-config-aarch64-linux-gnu clang llvm llvm-dev lld
+ libc6-dev-arm64-cross libatomic1-arm64-cross libgcc-8-dev-arm64-cross
-For example if the target machine is arm64 we can use the following
-command::
+Use the following command to cross-compile DPDK for your target machine::
- meson arm64-build --cross-file config/arm/arm64_armv8_linux_gcc
- ninja -C arm64-build
+ meson aarch64-build-clang --cross-file
config/arm/arm64_armv8_linux_clang_ubuntu1804
+ ninja -C aarch64-build-clang
Supported cross-compilation targets
-----------------------------------
--
2.20.1
