Cosmic-Clang Toolchain

This is a LLVM and Clang compiler toolchain built for kernel development. Builds are always made from the latest LLVM sources rather than stable releases, so complete stability cannot be guaranteed.

This toolchain targets the AArch32 and AArch64 architectures.

Polly, LLVM's polyhedral loop optimizer, is also included for users who want to experiment with additional optimization. Note that this toolchain is not suitable for anything other than bare-metal development; it has not been built with support for any libc or userspace development in mind.

binutils is also included for convenience. Unlike LLVM, however, the latest stable version of binutils is always used to reduce the opportunity for breakage because this project is primarily focused on cutting-edge Clang, not binutils. This means that users do not need to download separate GCC toolchains to build the Linux kernel.

The build scripts (powered by tc-build) behind this can be found here.

Host compatibility

This toolchain is built on Ubuntu 20.04 focal, which uses glibc 2.37. Compatibility with older distributions cannot be guaranteed. Other libc implementations (such as musl) are not supported.

Building Linux

For an AArch64 cross-compilation setup, you must set the following variables. Some of them can be environment variables, but some must be passed directly to make as a command-line argument. It is recommended to pass all of them as make arguments to avoid confusing errors:

• CC=clang (must be passed directly to make)
• CROSS_COMPILE=aarch64-linux-gnu-
• If your kernel has a 32-bit vDSO: CROSS_COMPILE_ARM32=arm-linux-gnueabi-

Optionally, you can also choose to use as many LLVM tools as possible to reduce reliance on binutils. All of these must be passed directly to make:

• AS=llvm-as
• AR=llvm-ar
• NM=llvm-nm
• OBJCOPY=llvm-objcopy
• OBJDUMP=llvm-objdump
• OBJSIZE=llvm-size
• STRIP=llvm-strip

Note, however, that additional kernel patches may be required for these LLVM tools to work. It is also possible to replace the binutils linkers (lf.bfd and ld.gold) with lld and use Clang's integrated assembler for inline assembly in C code, but that will require many more kernel patches and it is currently impossible to use the integrated assembler for all assembly code in the kernel.

Android kernels older than 4.14 will require patches for compiling with any Clang toolchain to work; those patches are out of the scope of this project. See android-kernel-clang for more information.

Android kernels 4.19 and newer use the upstream variable CROSS_COMPILE_COMPAT. When building these kernels, replace CROSS_COMPILE_ARM32 in your commands and scripts with CROSS_COMPILE_COMPAT.

Differences from other toolchains

Proton Clang has been designed to be easy-to-use compared to other toolchains, such as AOSP Clang. The differences are as follows:

• CLANG_TRIPLE does not need to be set because we don't use AOSP binutils
• LD_LIBRARY_PATH does not need to be set because we set library load paths in the toolchain
• No separate GCC/binutils toolchains are necessary; all tools are bundled

Common problems

as: unrecognized option '-EL'

Usually, this means that CROSS_COMPILE is not set correctly. Check that variable as well as your PATH to make sure that the required tools are available for Clang to invoke. You can test it manually like tihs:

$ ${CROSS_COMPILE}ld -v
GNU ld (GNU Binutils) 2.37

If you see Command not found or any other error, one of the two variables mentioned above is most likely set incorrectly.

If you continue to encounter this error after verifying CROSS_COMPILE and PATH, you are probably running into a change in Clang 12's handling of cross-compiling. The fix is to either merge linux-stable (which already has the fix included) cherry-pick "Makefile: Fix GCC_TOOLCHAIN_DIR prefix for Clang cross compilation" manually.

If the error still continues to appear and you have an arm64 kernel that includes vdso32, you will also need to cherry-pick "arm64: vdso32: Fix '--prefix=' value for newer versions of clang" to fix the second vdso32 error. Merging linux-stable is also an option if you are on Linux 5.4 or newer.

Cannot use CONFIG_CC_STACKPROTECTOR_STRONG: -fstack-protector-strong not supported by compiler

This error is actually a result of stack protector checks in the Makefile that cause the real error to be masked. It indicates that one or more unsupported compiler flags have been passed to Clang. Disable CONFIG_CC_STACKPROTECTOR_STRONG in favor of CONFIG_CC_STACKPROTECTOR_NONE temporarily (make sure you don't keep this change permanently for security reasons) and Clang will output the flag that is causing the problem.

In downstream kernels, the cause is usually big.LITTLE CPU optimization flags that have been added to the Makefile unconditionally. The correct solution is to check cc-name for the current compiler and adjust the optimization flags accordingly — big.LITTLE for GCC and little-only for Clang. See "Makefile: Optimize for sm8150's Kryo 485 CPU setup" for an example implementation of this.

scripts/gcc-version.sh: line 25: aarch64-linux-gnu-gcc: command not found

This is caused by unconditional invocations of gcc-version.sh in CAF's camera_v2 driver. The recommended solution is to cherry-pick Google's fix from the Pixel 2 kernel, which simply removes the faulty invocations as they were never useful to begin with.

Note that these errors are harmless and don't necessarily need to be fixed, but nonetheless, ignoring them is not recommended.

undefined reference to 'stpcpy'

This is caused by a libcall optimization added in Clang 14 that optimizes certain basic sprintf calls into stpcpy calls. The correct fix for this is to cherry-pick "lib/string.c: implement stpcpy", which adds a simple implementation of stpcpy to the kernel so that Clang can use it.