Repository files navigation

This repository contains build scripts and auxiliary material for building abare-metal LLVM based toolchain targeting Arm based on:

• clang + llvm
• lld
• libc++abi
• libc++
• compiler-rt
• picolibc, or optionally newlib or LLVM's libc

The goal is to provide an LLVM based bare-metal toolchain that can target theArm architecture family from Armv6-M and newer. The toolchain follows the ABIfor the Arm Architecture and attempts to provide typical features needed forembedded and realtime operating systems.

• Armv6-M
• Armv7-M
• Armv7E-M
• Armv8-M Mainline and Baseline
• Armv8.1-M Mainline and Baseline
• Armv4T (experimental)
• Armv5TE (experimental)
• Armv6 (experimental, using the Armv5TE library variant)
• Armv7-A
• Armv7-R
• AArch32 Armv8-A
• AArch32 Armv8-R
• AArch64 Armv8-A

C++ is partially supported with the use of libc++ and libc++abi from LLVM. Featuresthat are not supported include:

• Multithreading

LLVM Embedded Toolchain for Arm uses the unstable libc++ ABI version. This ABIuses all the latest libc++ improvements and bugfixes, but may result in linkerrors when linking against objects compiled against older versions of the ABI.For more information seehttps://libcxx.llvm.org/DesignDocs/ABIVersioning.html.

The LLVM Embedded Toolchain for Arm relies on the following upstream components

Content of this repository is licensed under Apache-2.0, seeLICENSE.txt. Individual patch files under thepatchesfolder may contain code under the upstream project license, if they arecherry-picks of upstream commits into the LLVM Embedded Toolchain for Armrelease branches, see corresponding pull requests for references.

The resulting binaries are covered under their respective open source licenses,see component links above.

Testing for some targets uses the freely-available but not open-source Arm FVPmodels, which have their own licenses. These are not used by default, seeBuilding from source for details.

LLVM Embedded Toolchain for Arm is built and tested on Ubuntu 18.04 LTS.

The Windows version is built on Windows Server 2019 and lightly tested on Windows 10.

Building on macOS is functional for x86_64 and Apple Silicon.

Binary packagesare provided for major LLVM releases for Linux and Windows.

Download a release of the toolchain for your platform fromGithubreleasesand extract the archive into an arbitrary directory.

Install appropriate latest supported Microsoft Visual C++ Redistributable package, such as fromMicrosoft Visual C++ Redistributable latest supported downloads.

Note: If you are using the toolchain in a shared environment with untrusted input,make sure it is sufficiently sandboxed.

To use the toolchain, on the command line you need to provide the following options:

• The target triple.
• The FPU to use.
• Disabling/enabling C++ exceptions and RTTI.
• The C runtime library: eithercrt0 orcrt0-semihost.crt0 will be linked automatically, but this can be suppressedwith the-nostartfiles option so thatcrt0-semihost can be used.
• The semihosting library, if usingcrt0-semihost.
• Alinker script specified with-T.Defaultpicolibcpp.ld andpicolibc.ld scripts are provided and can be useddirectly or included from acustom linker script.

For example:

$ PATH=<install-dir>/LLVMEmbeddedToolchainForArm-<revision>/bin:$PATH$ clang \--target=armv6m-none-eabi \-mfpu=none \-fno-exceptions \-fno-rtti \-nostartfiles \-lcrt0-semihost \-lsemihost \-T picolibc.ld \-o example example.c

clang's multilib system will automatically select an appropriate set oflibraries based on your compile flags.clang will emit a warning if noappropriate set of libraries can be found.

To display the directory selected by the multilib system, add the flag-print-multi-directory to yourclang command line options.

To display all available multilibs runclang with the flag-print-multi-liband a target triple like--target=aarch64-none-elf or--target=arm-none-eabi.

It's possible thatclang will choose a set of libraries that are not the onesyou want to use. In this case you can bypass the multilib system by providing a--sysroot option specifying the directory containing theinclude andlibdirectories of the libraries you want to use. For example:

$ clang \--sysroot=<install-dir>/LLVMEmbeddedToolchainForArm-<revision>/lib/clang-runtimes/arm-none-eabi/armv6m_soft_nofp \--target=armv6m-none-eabi \-mfpu=none \-fno-exceptions \-fno-rtti \-nostartfiles \-lcrt0-semihost \-lsemihost \-T picolibc.ld \-o example example.c

The FPU selection can be skipped, but it is not recommended to as the defaultsare different to GCC ones.

The builds of the toolchain come packaged with two config files, Omax.cfg and OmaxLTO.cfg.When used, these config files enable several build optimisation flags to achieve highest performance on typical embedded benchmarks. OmaxLTO.cfg enables link-time optimisation (LTO) specific flags.These configs can be optionally passed using the--config flag. For example:

$ clang \example.c \...--config=Omax.cfg \--config=OmaxLTO.cfg \-o example

Users should be warned that Omax.cfg enables-ffast-math which breaks IEEE compliance andenables maths optimisations which can affect code correctness. LTOs arekept separately in OmaxLTO.cfg as users may not want LTOs due to potential increase in link timeand/or increased memory usage during linking. Some of the options in the config files are undocumented internal LLVM options. For these undocumented options please see the source code of thecorresponding optimisation passes in theLLVM projectto find out more. Users are also encouraged to create their own configs and tune their ownflag parameters.Information on LLVM Embedded Toolchain for Arm specific optimization flags is available inOptimization Flags

Binary releases of the LLVM Embedded Toolchain for Arm are based on releasebranches of the upstream LLVM Project, thus can safely be used with all toolsprovided by LLVMreleasesof matching version.

SeeMigrating from Arm GNU ToolchainandExperimental newlib supportfor advice on using LLVM Embedded Toolchain for Arm with existing projectsrelying on the Arm GNU Toolchain.

Note:picolibc provides excellentsupport for Arm GNU Toolchain,so projects that require using both Arm GNU Toolchain and LLVM Embedded Toolchain for Armcan choose eitherpicolibc ornewlib.

LLVM Embedded Toolchain for Arm is an open source project and thus can be builtfrom source. Please see theBuilding from sourceguide for detailed instructions.

Please raise an issue viaGithub issues.

Please see theContribution Guide for details.