toolchain: doc: Custom toolchain doc updated for other.h requirement

Added missing toolchain name to path for generic.cmake and target.cmake.

Added section explaining the need for, and the use of, the
toolchain/other.h header file.

Signed-off-by: Danny Oerndrup <[email protected]>

Author: daor-oti

doc/getting_started/toolchain_custom_cmake.rst

@@ -13,12 +13,16 @@ environment variables <env_vars>`:
 Zephyr will then include the toolchain cmake files located in the
 :file:`TOOLCHAIN_ROOT` directory:
 
-- :file:`cmake/toolchain/generic.cmake`: configures the toolchain for "generic"
-  use, which mostly means running the C preprocessor on :ref:`devicetree
-  input files <dt-input-files>`.
-- :file:`cmake/toolchain/target.cmake`: configures the toolchain for "target"
-  use, i.e. building Zephyr and your application's source code.
+- :file:`cmake/toolchain/<toolchain name>/generic.cmake`: configures the
+  toolchain for "generic" use, which mostly means running the C preprocessor
+  on the generated
+  :ref:`devicetree` file.
+- :file:`cmake/toolchain/<toolchain name>/target.cmake`: configures the
+  toolchain for "target" use, i.e. building Zephyr and your application's
+  source code.
 
+Here <toolchain name> is the same as the name provided in
+:envvar:`ZEPHYR_TOOLCHAIN_VARIANT`
 See the zephyr files :zephyr_file:`cmake/generic_toolchain.cmake` and
 :zephyr_file:`cmake/target_toolchain.cmake` for more details on what your
 :file:`generic.cmake` and :file:`target.cmake` files should contain.
@@ -39,5 +43,30 @@ your :makevar:`ZEPHYR_TOOLCHAIN_VARIANT`, :makevar:`TOOLCHAIN_ROOT`, and other
 settings in a file named :file:`my-toolchain.cmake`, you can then invoke cmake
 as ``cmake -C my-toolchain.cmake ...`` to save typing.
 
+Zephyr includes :file:`include/toolchain.h` which again includes a toolchain
+specific header based on the compiler identifier, such as ``__llvm__`` or
+``__GNUC__``.
+Some custom compilers identify themselves as the compiler on which they are
+based, for example ``llvm`` which then gets the :file:`toolchain/llvm.h` included.
+This included file may though not be right for the custom toolchain. In order
+to solve this, and thus to get the :file:`include/other.h` included instead,
+add the set(TOOLCHAIN_USE_CUSTOM 1) cmake line to the generic.cmake and/or
+target.cmake files located under
+:file:`<TOOLCHAIN_ROOT>/cmake/toolchain/<toolchain name>/`.
+
+When :makevar:`TOOLCHAIN_USE_CUSTOM` is set, the :file:`other.h` must be
+available out-of-tree and it must include the correct header for the custom
+toolchain.
+A good location for the :file:`other.h` header file, would be a
+directory under the directory specified in :envvar:`TOOLCHAIN_ROOT` as
+:file:`include/toolchain`.
+To get the toolchain header included in zephyr's build, the
+:makevar:`USERINCLUDE` can be set to point to the include directory, as shown
+here:
+
+.. code-block:: console
+
+   west build -- -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=... -DUSERINCLUDE=...
+
 .. _cmake option:
    https://cmake.org/cmake/help/latest/manual/cmake.1.html#options