doc: toolchain: atfe: arm toolchain for embedded documentation

Arm Toolchain for Embedded (ATfE) is the next-generation Arm embedded
C/C++ compilation toolchain.

Arm Toolchain for Embedded is 100% open source. Arm is investing in the
LLVM linker and minor tools, and in the Picolib C library, to create a
performant 100% open source compilation toolchain for embedded
development with Arm-based designs.

The proprietary components used in Arm Compiler for Embedded 6 (the
linker, C library, and binutils carried over from the legacy Arm
Compiler 5 toolchain) are retired in favour of their open source
(LLVM and Picolib) equivalents.

Product page: https://developer.arm.com/Tools%20and%20Software/Arm%20Toolchain%20for%20Embedded
Github repo: https://github.com/arm/arm-toolchain

Signed-off-by: Alex Fabre <alex.fabre@rtone.fr>

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 <env_vars>`:
+
+      - 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

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