This enhancement issue describes the Clang/LLVM toolchain support plan in the Zephyr SDK.

Goals

• Provide LLVM Binary Utilities as part of the SDK
• Provide Clang C/C++ Compiler as part of the SDK
• Support SDK Clang/LLVM toolchain in Zephyr

Specifications

• LLVM Binary Utilities

  • LLVM Binary Utilities shall be an optional component of the SDK that is available separately from the SDK GNU Binutils.
  • The following LLVM Binary Utilities binaries shall be provided ^[1]:
    • dsymutil
    • lld
    • llvm-ar
    • llvm-cov
    • llvm-cxxfilt
    • llvm-dwarfdump
    • llvm-nm
    • llvm-objcopy
    • llvm-objdump
    • llvm-profdata
    • llvm-ranlib (-> llvm-ar)
    • llvm-readelf (-> llvm-readobj)
    • llvm-readobj
    • llvm-size
    • llvm-strip (-> llvm-objcopy)
    • llvm-symbolizer
    • wasm-ld (-> lld)

• Clang Compiler

  • Clang Compiler shall be an optional component of the SDK that is available separately from the SDK GCC.
  • Clang Compiler shall be configured to C and C++ languages.
  • The following Clang compiler binaries shall be provided:
    • clang
    • clang++ (-> clang)
    • clang-cpp (->clang)

• Pre-built Libraries

  • The following pre-built libraries shall be provided:
    • compiler-rt
    • picolibc
    • libunwind
    • libc++abi
    • libc++
  • The pre-built libraries shall be provided for the following Arm targets ^[2]:
    • armv6m_soft_nofp
    • armv7em_hard_fpv4_sp_d16
    • armv7em_hard_fpv5_d16
    • armv7em_soft_nofp
    • armv7m_soft_fpv4_sp_d16
    • armv7m_soft_nofp
    • armv8.1m.main_hard_fp_nomve
    • armv8.1m.main_hard_fpdp_nomve
    • armv8.1m.main_hard_nofp_mve
    • armv8.1m.main_hard_nofp_nomve
    • armv8.1m.main_hard_fp
    • armv8.1m.main_soft_nofp
  • The pre-built libraries shall be provided for the following RISC-V targets ^[3]:
    • rv32e_zicsr_zifencei/ilp32e
    • rv32em_zicsr_zifencei/ilp32e
    • rv32emc_zicsr/ilp32e
    • rv32emc_zicsr_zba_zbb_zbc_zbs/ilp32e
    • rv32emc_zicsr_zifencei/ilp32e
    • rv32emc_zicsr_zifencei_zba_zbb_zbc_zbs/ilp32e
    • rv32i_zicsr_zifencei/ilp32
    • rv32if_zicsr_zifencei/ilp32
    • rv32im_zicsr_zifencei/ilp32
    • rv32im_zicsr_zifencei_zba_zbb_zbc_zbs/ilp32
    • rv32imac_zicsr_zifencei/ilp32
    • rv32imafc_zicsr_zifencei/ilp32
    • rv32imafd_zicsr_zifencei/ilp32
    • rv32imfc_zicsr_zifencei/ilp32

• Zephyr Build System Integration

  • The SDK Clang/LLVM toolchain shall be selectable by setting ZEPHYR_TOOLCHAIN_VARIANT=zephyr-llvm.
    • The existing ZEPHYR_TOOLCHAIN_VARIANT=zephyr (aka. GCC) shall be renamed to ZEPHYR_TOOLCHAIN_VARIANT=zephyr-gnu.
    • ZEPHYR_TOOLCHAIN_VARIANT=zephyr shall map to ZEPHYR_TOOLCHAIN_VARIANT=zephyr-gnu for the foreseeable in order to ensure compatibility.
  • The zephyr-llvm toolchain shall invoke Clang compiler with LLVM Linker ^[4]:
    • Build system configuration: COMPILER=clang, BINTOOLS=llvm, LINKER=lld

• SDK Distribution

  • Distribution Archive
    • The existing "GNU toolchain distribution archive" (toolchain_HOST-TARGET) shall be split into "GNU Binutils distribution archive" (toolchain_gnu-binutils_OS-TARGET) and "GCC distribution archive" (toolchain_gcc_HOST-TARGET) ^[5]. Binutils and GCC will be kept in the same "GNU" archive since Zephyr SDK LLVM support will default to using LLVM lld, not GNU ld.
    • A new distribution archive for LLVM Binary Utilities (toolchain_llvm-binutils_HOST) shall be added.
    • A new distribution archive for Clang Compiler (toolchain_clang-base_HOST) shall be added.
    • A new distribution archive for Clang Pre-built Libraries (toolchain_clang-lib_HOST-TARGET) shall be added.
  • Distribution Bundle
    • The existing "GNU toolchain distribution bundle" (zephyr-sdk-VER_HOST) shall be renamed to zephyr-sdk-VER-gcc_HOST.
    • A new distribution bundle consisting of Clang/LLVM toolchain (zephyr-sdk-VER-clang_HOST) shall be added.
    • The distribution bundle installation script shall be updated to support installation of individual GNU Binutils, LLVM Binutils, GCC, Clang components for the minimal distribution bundle.

• Clang/LLVM Toolchain Build Process

  • A custom build script shall be implemented for building Clang/LLVM toolchain ^[6].

^[1] Based on the "LLVM Binary Utilities" included in LLVM Embedded Toolchain for Arm.
^[2] Based on the pre-built multi-libs included in LLVM Embedded Toolchain for Arm.
^[3] Based on the pre-built 32-bit RISC-V multi-libs currently included in the SDK GCC.
^[4] LLVM Linker (lld) support is currently very limited and it is desirable to use GNU Linker (ld) for maximum compatibility. Note that GNU Linker is used by default for ZEPHYR_TOOLCHAIN_VARIANT=llvm as well. lld support seems to be sufficiently mature now.
^[5] This ensures that GNU Linker, which is part of GNU Binutils, can be installed alongside Clang/LLVM toolchain without installing GCC.
^[6] Ideally, we would implement Clang/LLVM toolchain support in crosstool-ng and upstream it; but, doing so will likely delay this task too much for our liking -- we will see.

Tasks

Phase 1

Inclusion of Clang/LLVM toolchain binaries and pre-built compiler-rt library for Arm-M-profile cores and RISC-V RV32I and RV32E cores in the SDK

• Implement LLVM binary utilities build process
• Implement Clang compiler build process
• Implement compiler-rt multi-lib build process for Arm
• Implement compiler-rt multi-lib build process for RISC-V
• Rework the distribution archive build process as per the "SDK Distribution" specifications above
• Rework the distribution bundle build process as per the "SDK Distribution" specifications above

Phase 2

Addition of pre-built C/C++ libraries for Arm M-profile cores and RISC-V RV32I and RV32E cores to the SDK

• Implement Picolibc multi-lib build process
• Implement libunwind multi-lib build process
• Implement libc++abi multi-lib build process
• Implement libc++ multi-lib build process

Future

(Nothing concrete about these ...)

• Implement Clang/LLVM toolchain support in crosstool-ng and refactor the SDK build process to use it
• Add pre-built libraries for other architectures (i.e. other than Arm and RISC-V)

Resources

• LLVM source tree
• LLVM Embedded Toolchain for Arm
• Zephyr Clang/LLVM toolchain support for RISC-V