docs/building/tfm_build_instruction.rst

##################
Build instructions
##################

.. warning::
    The build process was changed a lot in Q3 2023 and included into the release after v1.9.
    For building instructions for early versions please refer to the documentation of respective
    versions.

As you know from the :doc:`introduction </introduction/readme>` TF-M implements
:term:`SPE` with a set of secure services.
TF-M application as :term:`NSPE` client uses those services through isolation boundary via
:term:`PSA-FF-M` API.
Both SPE and NSPE are separate binaries and built independently.
This document describes the process of building both of them and the interface between.
SPE and NSPE binaries are combined and signed making the final image for downloading onto targets.

TF-M uses `CMake <https://cmake.org/overview/>`__ **v3.15** or higher.
Before starting please make sure you have all required software installed and
configured as explained in the
:doc:`TF-M getting started </getting_started/tfm_getting_started>`.

.. contents:: Contents
    :depth: 2
    :local:

The additional building materials you can find in the following links:TF-M source folder

.. toctree::
    :maxdepth: 1

    Run TF-M tests and applications <run_tfm_examples_on_arm_platforms>
    Building the documentation <documentation_generation>
    IAR toolchain <tfm_build_instruction_iar>

.. _Building SPE:

*******************
Building TF-M (SPE)
*******************
This build generates the SPE binary and artifacts, necessary for :ref:`Building NSPE`.

.. _Getting the source-code:

Getting the source code
=======================
.. code-block:: bash

    cd <base folder>
    git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git

In this documentation, the cloned ``trusted-firmware-m`` repository will be referenced as
``<TF-M source dir>``.
Additionally, TF-M depends on several external projects, handled by CMake automatically but
you can alter that behaviour using :ref:`Dependency management`.

.. Note::

 - For building with Armclang compiler version 6.10.0+, please follow the note
   in :doc:`TF-M getting started </getting_started/tfm_getting_started>`.
 - For building with the IAR toolchain, please see the notes in
   :doc:`IAR software requirements <tfm_build_instruction_iar>`

Configuring
===========
TF-M has many config options for configuring and fine-tuning. Please check the
:ref:`tf-m_configuration` section for the details. The **base** (default) configuration
contains only essential components such as SPM and HW platform support hence the
only mandatory argument to TF-M build is a platform name, provided via
CMake command-line option ``-DTFM_PLATFORM=<platform name>``, it can be:

- A relative path under ``<TF-M source dir>/platform/ext/target``, for example ``arm/mps2/an521``.
- An absolute path of target platform, mainly used for out-of-tree platform build.
- A basename of the target platform folder, for example ``an521``.

Essential Directories
---------------------
There are 3 essential directories used by CMake for building TF-M:

- Source code directory ``<TF-M source dir>``
- Build directory ``<Build Dir>`` - the location of all intermediate files required to produce
  a build target.
- Install directory ``<Artifact Dir>`` - the location of the build output files.

Note::
    It's recommended to use absolute paths for all directories. Relative paths may not fully work.

.. _Toolchains:

Toolchains
----------
TF-M supports 3 toolchains for cross-compiling and building the project binaries:

- GNU - **default**
- ArmClang
- IAR

Each toolchain has a configuration file for the compiler and linker.
Use ``TFM_TOOLCHAIN_FILE`` option to provide a path to a preferred toolchain file or the toolchain
file name.
The default **toolchain_GNUARM.cmake** is selected by `config_base.cmake`
file if the option is omitted.

.. _Build type:

Build type
----------
By default, a MinSizeRel configuration is built. Alternate build types can be
specified with the ``CMAKE_BUILD_TYPE`` variable. The possible
types are:

- Debug
- RelWithDebInfo
- Release
- MinSizeRel - **default**

Debug symbols are added by default to all builds, but can be removed from
*Release* and *MinSizeRel* builds by setting ``TFM_DEBUG_SYMBOLS`` to `OFF`.

*RelWithDebInfo*, *Release* and *MinSizeRel* all have different
optimizations turned on and hence will produce smaller, faster code than
*Debug*. *MinSizeRel* will produce the smallest code and hence is often
a good idea on RAM or flash-constrained systems.

.. _Output files:

Output files
------------
In a successful build, a set of files will be created in the ``<Artifact Dir>``.
By default, it is ``<Build Dir>\api_ns`` subfolder but you can redirect the
output to any location using ``CMAKE_INSTALL_PREFIX`` option. It can be an
absolute path or relative to your current directory. For the contents of the
artifact directory please refer to :ref:`Artifacts structure`.

Other build parameters
----------------------
The full list of default options is in ``config/config_base.cmake`` and
explained in :ref:`tfm_cmake_configuration`. Several important options
are listed below.

+----------------------------+------------------------------------------+---------------+
| Parameter                  | Description                              | Default value |
+============================+==========================================+===============+
| BL2                        | Build level 2 secure bootloader.         | ON            |
+----------------------------+------------------------------------------+---------------+
| PROJECT_CONFIG_HEADER_FILE | User defined header file for TF-M config |               |
+----------------------------+------------------------------------------+---------------+
| TFM_ISOLATION_LEVEL        | Set TFM isolation level.                 | 1             |
+----------------------------+------------------------------------------+---------------+
| TFM_PROFILE                | See :ref:`tf-m_profiles`.                |               |
+----------------------------+------------------------------------------+---------------+

Project Config Header File
--------------------------
CMake variable ``PROJECT_CONFIG_HEADER_FILE`` can be set by a user the full path to a
configuration header file, which is used to fine-tune component options. The detailed reference
for the project config header file is in :ref:`Header_configuration`.

Building binaries
=================

The command below shows a general template for building TF-M as a typical CMake project:

.. code-block:: bash

    cmake -S <TF-M source dir> -B <Build Dir> -DTFM_PLATFORM=<platform>
    cmake --build <Build Dir> -- install

.. Note::
    It is recommended to clean up the build directory before re-build if the config
    header file is updated. CMake is unable to automatically recognize the
    dependency when the header file is defined as a macro.

Building default configuration for an521
----------------------------------------

.. code-block:: bash

    cd <TF-M source dir>
    cmake -S . -B build -DTFM_PLATFORM=arm/mps2/an521
    cmake --build build -- install

The command above is intended to do:
  - take TF-M sources in the current ``.`` folder
  - build SPE in the ``build`` folder
  - for **an521** platform
  - using GNU toolchain *by default*. Use ``-DTFM_TOOLCHAIN_FILE=<toolchain file>``
    for alternatives as described in :ref:`Toolchains`
  - install output files in ``build/api_ns`` folder *by default*. You can specify
    a different directory using ``-DCMAKE_INSTALL_PREFIX=<Artifact dir>``
    as described in :ref:`Output files`

.. Note::
    It is recommended to build each different build configuration in a separate
    build directory.

CMake can generate code for many native build systems. TF-M is tested with
``Unix Makefiles`` (default) and ``Ninja``. The ``-G`` option can specify
alternative generators. For example for building with Ninja in the Debug
:ref:`Build type` using ArmClang :ref:`Toolchains` you can use the following:

.. code-block:: bash

    cd <TF-M source dir>
    cmake -S . -B build -DTFM_PLATFORM=arm/mps2/an521 -GNinja -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DCMAKE_BUILD_TYPE=Debug
    cmake --build build -- install

.. _Dependency management:

Dependency management
=====================

The TF-M build system will fetch all dependencies by default with appropriate
versions and store them inside the build tree. In this case, the build tree
location is ``<build_dir>/lib/ext``.

If you have local copies already and wish to avoid having the libraries
downloaded every time the build directory is deleted, then the following
variables can be set to the paths to the root directories of the local repos.
This will disable the automatic downloading for that dependencies and speed up
development iterations or allow usage of a dependency version different from the
current one.
Additionally, these path variables can be set in ``localrepos.cmake``
file which will be included in a build if it exists.
This file is ignored in TF-M git settings.

The following table lists the commonly used repos. For others, you can refer to ``lib/ext``.

+----------------+---------------------+-----------------------------------------------------+
| Dependency     | Cmake variable      | Git repo URL                                        |
+================+=====================+=====================================================+
| Mbed Crypto    | MBEDCRYPTO_PATH     | https://github.com/ARMmbed/mbedtls                  |
+----------------+---------------------+-----------------------------------------------------+
| MCUboot        | MCUBOOT_PATH        | https://github.com/mcu-tools/mcuboot                |
+----------------+---------------------+-----------------------------------------------------+
| QCBOR          | QCBOR_PATH          | https://github.com/laurencelundblade/QCBOR.git      |
+----------------+---------------------+-----------------------------------------------------+

The recommended versions of the dependencies are listed in ``config/config_base.cmake``.

.. Note::

 - Some repositories might need patches to allow building it as a part of TF-M.
   While these patches are being upstreamed they are stored in a
   dependency folder under ``lib/ext/``.
   In order to use local repositories those patches shall be applied to original source.
   An alternative is to copy out the auto-downloaded repos under the ``<build_dir>/lib/ext``.
   They have been applied with patches and can be used directly.

 - **tf-m-tests** is a special dependency used for testing purpose only as described in
   :ref:`Building Tests`

Example: building TF-M with local Mbed Crypto repo
--------------------------------------------------

Preparing a local repository consists of 2 steps: cloning and patching.
This is only required to be done once. For dependencies without ``.patch``
files in their ``lib/ext`` directory the only required step is
cloning the repo and checking out the correct branch.

.. code-block:: bash

    cd <Mbed Crypto base folder>
    git clone https://github.com/ARMmbed/mbedtls
    cd mbedtls
    git checkout <MBEDCRYPTO_VERSION from <TF-M source dir>/config_base.cmake>
    git apply <TF-M source dir>/lib/ext/mbedcrypo/*.patch

.. Note::

   ``<Mbed Crypto base folder>`` does not need to have any fixed position related
   to the TF-M repo so alternative method to get prepared dependency repos is to
   let TF-M download it once and then copy them out of the ``build/lib/ext`` folder.

Now build TF-M binaries

.. code-block:: bash

    cd <TF-M source dir>
    cmake -S . -B build -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
    cmake --build build -- install

.. _Building NSPE:

***************************
Building Application (NSPE)
***************************

As a result of :ref:`Building SPE` you will get a set of :ref:`Output files` in
``<Artifact Dir>`` required for building TF-M application. Essentially, SPE
exports a binary and a set of C source files for PSA interface and platform.
Please note that NSPE and SPE are independent projects and can be built using
different toolchains and toolchain options.

.. _Artifacts structure:

SPE artifacts structure
=======================

SPE components prepared and installed for NSPE usage in ``<Artifact Dir>``
will have the following structure:

.. code-block:: none

    <Artifact Dir>
    ├── bin
    ├── cmake
    ├── config
    ├── image_signing
    ├── interface
    ├── platform
    └── CMakeLists.txt

With certain configurations, additional folders may also be installed.
These folders have the following content:

- **bin** - binary images of SPE, Bootloader(optional) and combined.
- **cmake** - CMake scripts like SPE configuration and :ref:`NSPE toolchains`.
- **config** - Configuration files
- **image_signing** - binary image signing tool and keys.
- **interface** - PSA interface exposed by SPE.
- **platform** - source code for a selected hardware platform.
- **CMakeLists.txt** - CMake script for the artifacts integration in NSPE.

The content of ``<Artifact Dir>`` is a prepared directory for integration with
CMake project as shown in the :ref:`NSPE CmakeLists.txt` below.

.. _NSPE toolchains:

NSPE toolchains
===============

SPE prepares and exports CMake toolchain files for building NSPE in all
supported :ref:`Toolchains` in ``<Artifact Dir>/cmake`` folder.
Toolchain used to build NSPE can be different from what is used to build SPE.

.. _NSPE CmakeLists.txt:

Basic SPE integration
=====================
Refer to the example of TF-M applications in **tf-m-extras** repository.

.. _Building Tests:

**************
Building Tests
**************
The tests is a TF-M application which verifies TF-M functionality on both SPE and NSPE sides.
Conceptually, it builds the same way as described above in 2 consequent steps (SPE then NSPE).

However, tests require an extension of SPE side with test code and extra functionality
for some Non-Secure test cases. To inject that test code into SPE the
``CONFIG_TFM_TEST_DIR`` option is used. When SPE build system sees this option
it adds the corresponding folder via ``add_subdirectory(${CONFIG_TFM_TEST_DIR} tf-m-test)``
and includes it to SPE binary.
Also, test configurations should be passed to SPE build to include building Secure Tests.

To hide these complexities to developers, TF-M implements a wrapper CMake in **tf-m-tests**
repository to build the SPE for testing.

The recommended tf-m-tests repo commit to verify TF-M can be found at
``<TF-M source dir>/lib/ext/tf-m-tests/version.txt``.
It does not support auto-downloading as builds start from it.
You need to download it manually before building any tests.

Regression Tests
================
For instructions on configuring, building and executing the regression tests
please refer to the documentation in **tf-m-tests** repository (to be added).
The regression test application is located under **/tests_reg** folder.
It is recommended to build both SPE and NSPE from that folder.

The basic commands for building the regression tests will be:

.. code-block:: bash

    cd </tf-m-tests/tests_reg>
    cmake -S spe -B build_spe -DTFM_PLATFORM=arm/mps2/an521 -DCONFIG_TFM_SOURCE_PATH=<TF-M source dir>
          -DTEST_S=ON -DTEST_NS=ON
    cmake --build build_spe -- install

    cmake -S . -B build_test -DCONFIG_SPE_PATH=<Absolute path to>/build_spe/api_ns
    cmake --build build_test

Instead of enable all the supported Secure (``TEST_S``) and NS (``TEST_NS`` tests, you can also
enable individual test suites by using ``-DTEST_S_<SUITE>=ON`` or ``-DTEST_NS_<SUITE>=ON``.
For the available test suites, refer to the ``default_s_test_config.cmake`` and
``default_ns_test_config.cmake`` files in tf-m-tests repo.

PSA API tests
=============
PSA API tests from https://github.com/ARM-software/psa-arch-tests use the same
mechanism for SPE extension as the regression tests above utilising ``CONFIG_TFM_TEST_DIR`` option.
PSA API tests are selected by the TEST_PSA_API variable. Enabling both regression tests and
PSA API tests simultaneously is **not** supported.

TF-M implements a wrapper CMake for PSA API tests as well.

For instructions on building and executing the regression tests
please refer to the documentation in **tf-m-tests** repository (to be added).
The PSA API test codes are located under **/tests_psa_arch** folder.

Here is a brief description of the basic flow:
There are 5 different TEST_PSA_API test suites to be run.

.. code-block:: bash

    -DTEST_PSA_API=INTERNAL_TRUSTED_STORAGE
    -DTEST_PSA_API=PROTECTED_STORAGE
    -DTEST_PSA_API=STORAGE
    -DTEST_PSA_API=CRYPTO
    -DTEST_PSA_API=INITIAL_ATTESTATION

Respectively for the corresponding service. For example, to enable the PSA API
tests for the Crypto service:

.. code-block:: bash

    cd </tf-m-tests/tests_psa_arch folder>
    cmake -S spe -B build_spe -DTFM_PLATFORM=arm/mps2/an521 -DCONFIG_TFM_SOURCE_PATH=<TF-M source dir>
          -DTEST_PSA_API=CRYPTO
    cmake --build build_spe -- install

    cmake -S . -B build_test -DCONFIG_SPE_PATH=<Absolute path to>/build_spe/api_ns
    cmake --build build_test

--------------

*Copyright (c) 2017-2023, Arm Limited. All rights reserved.*
*Copyright (c) 2022, Cypress Semiconductor Corporation. All rights reserved.*