diff --git a/doc/develop/toolchains/arm_toolchain_for_embedded.rst b/doc/develop/toolchains/arm_toolchain_for_embedded.rst new file mode 100644 index 00000000000..f5a0d40f7b3 --- /dev/null +++ b/doc/develop/toolchains/arm_toolchain_for_embedded.rst @@ -0,0 +1,86 @@ +.. _toolchain_atfe: + +Arm Toolchain for Embedded (ATfE) +################################# + +#. LLVM toolchain by ARM + + #. Arm Toolchain for Embedded (ATfE) is a C and C++ toolchain from Arm based + on the free and open-source LLVM Compiler Infrastructure and the Picolib C + library for baremetal targets. + + #. ATfE is fined-tuned with a particular focus on performance for newer + ARM products (post 2024) like 64-bit Arm Architectures (AArch64), + or the M-Profile Vector Extension (MVE, a 32-bit Armv8.1-M extension). + +#. Installation + + #. Download and install a `Arm toolchain for embedded`_ build for your operating system + and extract it on your file system. + + #. :ref:`Set these environment variables `: + + - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``llvm``. + - Set :envvar:`LLVM_TOOLCHAIN_PATH` to the toolchain installation directory. + + #. To check that you have set these variables correctly in your current + environment, follow these example shell sessions (the + :envvar:`LLVM_TOOLCHAIN_PATH` values may be different on your system): + + .. tabs:: + + .. group-tab:: Ubuntu + + .. code-block:: bash + + echo $ZEPHYR_TOOLCHAIN_VARIANT + llvm + echo $LLVM_TOOLCHAIN_PATH + /home/you/Downloads/ATfE + + .. group-tab:: macOS + + .. code-block:: bash + + echo $ZEPHYR_TOOLCHAIN_VARIANT + llvm + echo $LLVM_TOOLCHAIN_PATH + /home/you/Downloads/ATfE + + .. group-tab:: Windows + + .. code-block:: powershell + + > echo %ZEPHYR_TOOLCHAIN_VARIANT% + llvm + > echo %LLVM_TOOLCHAIN_PATH% + C:\ATfE + + .. _toolchain_env_var: + + #. You can also set ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``LLVM_TOOLCHAIN_PATH`` as CMake + variables when generating a build system for a Zephyr application, like so: + + .. code-block:: console + + west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=... + +#. Toolchain settings + + #. Because LLVM is widely compatible with GNU tools, When builiding with any + LLVM toolchain, you have to specify some settings to let the compiler + know what tools to use: + + #. Linker: + Set :envvar:`CONFIG_LLVM_USE_LLD=y` to use LLVM linker. + set :envvar:`CONFIG_LLVM_USE_LD=y` to use the GNU LD linker. + + #. Runtime library: + Set :envvar:`CONFIG_COMPILER_RT_RTLIB=y` to use LLVM runtime library. + Set :envvar:`CONFIG_LIBGCC_RTLIB=y` to use LibGCC runtime library. + + .. code-block:: console + + west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=... -DCONFIG_LLVM_USE_LLD=y -DCONFIG_COMPILER_RT_RTLIB=y + +.. _Arm Toolchain for Embedded: https://developer.arm.com/Tools%20and%20Software/Arm%20Toolchain%20for%20Embedded diff --git a/doc/develop/toolchains/index.rst b/doc/develop/toolchains/index.rst index fabfaf0b016..a1710314e51 100644 --- a/doc/develop/toolchains/index.rst +++ b/doc/develop/toolchains/index.rst @@ -11,6 +11,7 @@ Guides on how to set up toolchains for Zephyr development. zephyr_sdk.rst arm_compiler_6.rst + arm_toolchain_for_embedded.rst cadence_xcc.rst designware_arc_mwdt.rst gnu_arm_embedded.rst