llvm.org GIT mirror llvm / 51bcf5f
[docs][ARM] Add HowTo for cross compiling and testing compiler-rt builtins This document contains information on how to cross-compile the compiler-rt builtins library for several flavours of Arm target and how to test the libraries using qemu. Differential Revision: https://reviews.llvm.org/D39600 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@317554 91177308-0d34-0410-b5e6-96231b3b80d8 Peter Smith 1 year, 9 months ago
2 changed file(s) with 205 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ===================================================================
1 How to Cross Compile Compiler-rt Builtins For Arm
2 ===================================================================
3
4 Introduction
5 ============
6
7 This document contains information about building and testing the builtins part
8 of compiler-rt for an Arm target, from an x86_64 Linux machine.
9
10 While this document concentrates on Arm and Linux the general principles should
11 apply to other targets supported by compiler-rt. Further contributions for other
12 targets are welcome.
13
14 The instructions in this document depend on libraries and programs external to
15 LLVM, there are many ways to install and configure these dependencies so you
16 may need to adapt the instructions here to fit your own local situation.
17
18 Prerequisites
19 =============
20
21 In this use case we'll be using CMake on a Debian-based Linux system,
22 cross-compiling from an x86_64 host to a hard-float Armv7-A target. We'll be
23 using as many of the LLVM tools as we can, but it is possible to use GNU
24 equivalents.
25
26 * ``A build of LLVM/clang for the llvm-tools and llvm-config``
27 * ``The qemu-arm user mode emulator``
28 * ``An arm-linux-gnueabihf sysroot``
29
30 See https://compiler-rt.llvm.org/ for more information about the dependencies
31 on clang and LLVM.
32
33 ``qemu-arm`` should be available as a package for your Linux distribution.
34
35 The most complicated of the prequisites to satisfy is the arm-linux-gnueabihf
36 sysroot. The :doc:`HowToCrossCompileLLVM` has information about how to use the
37 Linux distributions multiarch support to fulfill the dependencies for building
38 LLVM. Alternatively, as building and testing just the compiler-rt builtins
39 requires fewer dependencies than LLVM, it is possible to use the Linaro
40 arm-linux-gnueabihf gcc installation as our sysroot.
41
42 Building compiler-rt builtins for Arm
43 =====================================
44 We will be doing a standalone build of compiler-rt using the following cmake
45 options.
46
47 * ``path/to/llvm/projects/compiler-rt``
48 * ``-DCOMPILER_RT_BUILD_BUILTINS=ON``
49 * ``-DCOMPILER_RT_BUILD_SANITIZERS=OFF``
50 * ``-DCOMPILER_RT_BUILD_XRAY=OFF``
51 * ``-DCOMPILER_RT_BUILD_LIBFUZZER=OFF``
52 * ``-DCOMPILER_RT_BUILD_PROFILE=OFF``
53 * ``-DCMAKE_C_COMPILER=/path/to/clang``
54 * ``-DCMAKE_AR=/path/to/llvm-ar``
55 * ``-DCMAKE_NM=/path/to/llvm-nm``
56 * ``-DCMAKE_RANLIB=/path/to/llvm-ranlib``
57 * ``-DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"``
58 * ``-DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"``
59 * ``-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON``
60 * ``-DLLVM_CONFIG_PATH=/path/to/llvm-config``
61 * ``-DCMAKE_C_FLAGS="build-c-flags"``
62
63 The build-c-flags need to be sufficient to pass the C-make compiler check and
64 to compile compiler-rt. When using a GCC 7 Linaro arm-linux-gnueabihf
65 installation the following flags are needed:
66
67 * ``--target=arm-linux-gnueabihf``
68 * ``--march=armv7a``
69 * ``--gcc-toolchain=/path/to/dir/toolchain``
70 * ``--sysroot=/path/to/toolchain/arm-linux-gnueabihf/libc``
71
72 Depending on how your sysroot is laid out, you may not need ``--gcc-toolchain``.
73 For example if you have added armhf as an architecture using your Linux
74 distributions multiarch support then you should be able to use ``--sysroot=/``.
75
76 Once cmake has completed the builtins can be built with ``ninja builtins``
77
78 Testing compiler-rt builtins using qemu-arm
79 ===========================================
80 To test the builtins library we need to add a few more cmake flags to enable
81 testing and set up the compiler and flags for test case. We must also tell
82 cmake that we wish to run the tests on ``qemu-arm``.
83
84 * ``-DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armhf/sysroot``
85 * ``-DCOMPILER_RT_INCLUDE_TESTS=ON``
86 * ``-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"``
87 * ``-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"``
88
89 The ``/path/to/armhf/sysroot`` should be the same as the one passed to
90 ``--sysroot`` in the "build-c-flags".
91
92 The "test-c-flags" can be the same as the "build-c-flags", with the addition
93 of ``"-fuse-ld=lld`` if you wish to use lld to link the tests.
94
95 Once cmake has completed the tests can be built and run using
96 ``ninja check-builtins``
97
98 Modifications for other Targets
99 ===============================
100
101 Arm Soft-Float Target
102 ---------------------
103 The instructions for the Arm hard-float target can be used for the soft-float
104 target by substituting soft-float equivalents for the sysroot and target. The
105 target to use is:
106
107 * ``-DCMAKE_C_COMPILER_TARGET=arm-linux-gnueabi``
108
109 Depending on whether you want to use floating point instructions or not you
110 may need extra c-flags such as ``-mfloat-abi=softfp`` for use of floating-point
111 instructions, and ``-mfloat-abi=soft -mfpu=none`` for software floating-point
112 emulation.
113
114 AArch64 Target
115 --------------
116 The instructions for Arm can be used for AArch64 by substituting AArch64
117 equivalents for the sysroot, emulator and target.
118
119 * ``-DCMAKE_C_COMPILER_TARGET=aarch64-linux-gnu``
120 * ``-DCOMPILER_RT_EMULATOR="qemu-aarch64 -L /path/to/aarch64/sysroot``
121
122 The CMAKE_C_FLAGS and COMPILER_RT_TEST_COMPILER_CFLAGS may also need:
123 ``"--sysroot=/path/to/aarch64/sysroot --gcc-toolchain=/path/to/gcc-toolchain"``
124
125 Armv6-m, Armv7-m and Armv7E-M targets
126 -------------------------------------
127 If you wish to build, but not test compiler-rt for Armv6-M, Armv7-M or Armv7E-M
128 then the easiest way is to use the BaremetalARM.cmake recipe in
129 clang/cmake/caches.
130
131 You will need a bare metal sysroot such as that provided by the GNU ARM
132 Embedded toolchain.
133
134 The libraries can be built with the cmake options:
135
136 * ``-DBAREMETAL_ARMV6M_SYSROOT=/path/to/bare/metal/sysroot``
137 * ``-DBAREMETAL_ARMV7M_SYSROOT=/path/to/bare/metal/sysroot``
138 * ``-DBAREMETAL_ARMV7EM_SYSROOT=/path/to/bare/metal/sysroot``
139 * ``-C /path/to/llvm/source/tools/clang/cmake/caches/BaremetalARM.cmake``
140
141 **Note** that for the recipe to work the compiler-rt source must be checked out
142 into the directory llvm/runtimes and not llvm/projects.
143
144 To build and test the libraries using a similar method to Armv7-A is possible
145 but more difficult. The main problems are:
146
147 * There isn't a ``qemu-arm`` user-mode emulator for bare-metal systems. The ``qemu-system-arm`` can be used but this is significantly more difficult to setup.
148 * The target to compile compiler-rt have the suffix -none-eabi. This uses the BareMetal driver in clang and by default won't find the libraries needed to pass the cmake compiler check.
149
150 As the Armv6-M, Armv7-M and Armv7E-M builds of compiler-rt only use instructions
151 that are supported on Armv7-A we can still get most of the value of running the
152 tests using the same ``qemu-arm`` that we used for Armv7-A by building and
153 running the test cases for Armv7-A but using the builtins compiled for
154 Armv6-M, Armv7-M or Armv7E-M. This will not catch instructions that are
155 supported on Armv7-A but not Armv6-M, Armv7-M and Armv7E-M.
156
157 To get the cmake compile test to pass the libraries needed to successfully link
158 the test application will need to be manually added to ``CMAKE_CFLAGS``.
159 Alternatively if you are using version 3.6 or above of cmake you can use
160 ``CMAKE_TRY_COMPILE_TARGET=STATIC_LIBRARY`` to skip the link step.
161
162 * ``-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY``
163 * ``-DCOMPILER_RT_OS_DIR="baremetal"``
164 * ``-DCOMPILER_RT_BUILD_BUILTINS=ON``
165 * ``-DCOMPILER_RT_BUILD_SANITIZERS=OFF``
166 * ``-DCOMPILER_RT_BUILD_XRAY=OFF``
167 * ``-DCOMPILER_RT_BUILD_LIBFUZZER=OFF``
168 * ``-DCOMPILER_RT_BUILD_PROFILE=OFF``
169 * ``-DCMAKE_C_COMPILER=${host_install_dir}/bin/clang``
170 * ``-DCMAKE_C_COMPILER_TARGET="your *-none-eabi target"``
171 * ``-DCMAKE_AR=/path/to/llvm-ar``
172 * ``-DCMAKE_NM=/path/to/llvm-nm``
173 * ``-DCMAKE_RANLIB=/path/to/llvm-ranlib``
174 * ``-DCOMPILER_RT_BAREMETAL_BUILD=ON``
175 * ``-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON``
176 * ``-DLLVM_CONFIG_PATH=/path/to/llvm-config``
177 * ``-DCMAKE_C_FLAGS="build-c-flags"``
178 * ``-DCMAKE_ASM_FLAGS="${arm_cflags}"``
179 * ``-DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armv7-A/sysroot"``
180 * ``-DCOMPILER_RT_INCLUDE_TESTS=ON``
181 * ``-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"``
182 * ``-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"``
183
184 The Armv6-M builtins will use the soft-float ABI. When compiling the tests for
185 Armv7-A we must include ``"-mthumb -mfloat-abi=soft -mfpu=none"`` in the
186 test-c-flags. We must use an Armv7-A soft-float abi sysroot for ``qemu-arm``.
187
188 Unfortunately at time of writing the Armv7-M and Armv7E-M builds of
189 compiler-rt will always include assembler files including floating point
190 instructions. This means that building for a cpu without a floating point unit
191 requires something like removing the arm_Thumb1_VFPv2_SOURCES from the
192 arm_Thumb1_SOURCES in builtins/CMakeLists.txt. The float-abi of the compiler-rt
193 library must be matched by the float abi of the Armv7-A sysroot used by
194 qemu-arm.
195
196 Depending on the linker used for the test cases you may encounter BuildAttribute
197 mismatches between the M-profile objects from compiler-rt and the A-profile
198 objects from the test. The lld linker does not check the BuildAttributes so it
199 can be used to link the tests by adding -fuse-ld=lld to the
200 ``COMPILER_RT_TEST_COMPILER_CFLAGS``.
6767 CMakePrimer
6868 AdvancedBuilds
6969 HowToBuildOnARM
70 HowToCrossCompileBuiltinsOnArm
7071 HowToCrossCompileLLVM
7172 CommandGuide/index
7273 GettingStarted
103104
104105 :doc:`HowToBuildOnARM`
105106 Notes on building and testing LLVM/Clang on ARM.
107
108 :doc:`HowToCrossCompileBuiltinsOnArm`
109 Notes on cross-building and testing the compiler-rt builtins for Arm.
106110
107111 :doc:`HowToCrossCompileLLVM`
108112 Notes on cross-building and testing LLVM/Clang.