docs/getting_started/tfm_build_instruction.rst

##################
Build instructions
##################
Please make sure you have all required software installed as explained in the
:doc:`software requirements <tfm_sw_requirement>`.

The external dependecies are briefly listed in the
:ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.

The configuration-table
:ref:`docs/getting_started/tfm_build_instruction:Configuring the build` section
explains all the supported build parameters:

****************
TF-M build steps
****************
TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
build environment. The instructions are below.

.. Note::

    It is recommended to build each different build configurations in separate
    directories.

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

    cd <base folder>
    git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
    git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.23.0
    git clone https://git.trustedfirmware.org/TF-M/tf-m-tests.git
    git clone https://github.com/JuulLabs-OSS/mcuboot.git -b v1.6.0

.. Note::
   For building with Armclang compiler version 6.10.0, please follow the note
   in :ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.

.. Note::
   For building with the IAR toolchain, please see the notes in
   :doc:`software requirements <tfm_build_instruction_iar>`

Build steps for the AN521 target platform:
==========================================
.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    mkdir cmake_build
    cd cmake_build
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
    cmake --build ./ -- install

Regression Tests for the AN521 target platform
==============================================
*TF-M build regression tests on Linux*

.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    mkdir cmake_test
    cd cmake_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

*TF-M build regression tests on Windows*

.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    mkdir cmake_test
    cd cmake_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Build for PSA Developer API compliance tests
============================================
The build system provides the support for linking with prebuilt PSA Developer
API compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``,
``ConfigPsaApiTestIPC.cmake`` or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config
file. The build system assumes that the PSA API compliance test suite is checked
out at the same level of the TF-M root folder and the default name for the build
folder has been used when compiling the PSA API compliance tests. Each set of
tests for the Internal Trusted Storage, Protected Storage, Crypto and Attestation
services needs to be enabled at the build configuration step by defining::

    -DPSA_API_TEST_INTERNAL_TRUSTED_STORAGE=ON
    -DPSA_API_TEST_PROTECTED_STORAGE=ON
    -DPSA_API_TEST_STORAGE=ON
    -DPSA_API_TEST_CRYPTO=ON
    -DPSA_API_TEST_INITIAL_ATTESTATION=ON

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

.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    mkdir cmake_psa_test
    cd cmake_psa_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Build for PSA FF (IPC) compliance tests
=======================================

The build system assumes that the PSA FF compliance test suite is checked out
at the same level of the TF-M root folder and the default name for the build
folder has been used when compiling the PSA FF compliance tests.

Parse the PSA FF compliance tests partition manifests using a tool script named
as ``tfm_parse_manifest_list.py``. This tool updates the TFM partitions data
structure with PSA test suite partitions detail and creates the manifest output
files that are required for the PSA test suite build. Using these manifest
output files, build the PSA FF compliance tests as per the instructions
given in the PSA FF compliance tests README.

.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    python tools/tfm_parse_manifest_list.py -m tools/tfm_psa_ff_test_manifest_list.yaml append

The build system provides the support for linking with prebuilt PSA FF
compliance NS and S test libraries when using the ``ConfigPsaApiTestIPC.cmake``
or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config file.  The PSA FF compliance
tests need to be enabled at the build configuration step by defining::

    -DPSA_API_TEST_IPC=ON.

For example, to enable the PSA FF tests for ConfigPsaApiTestIPCTfmLevel2.cmake
config :

.. code-block:: bash

    cd <base folder>
    cd trusted-firmware-m
    mkdir cmake_psa_test
    cd cmake_psa_test
    cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTestIPCTfmLevel2.cmake` -DPSA_API_TEST_IPC=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
    cmake --build ./ -- install

Location of build artifacts
===========================
The build system defines an API which allow easy usage of build
artifacts. The ``install`` build target copies all files which might be needed
as a dependency by external tools or build systems to the
``<build_dir>/install/outputs``
directory, with the following directory hierarchy:

::

    <build_dir>/install/outputs/fvp/
    <build_dir>/install/outputs/<target_platform>/

There is one folder for FVP testing, with more elaborate naming and
there is an other for testing on target hardware platform (AN521, etc.), where
naming convention is aligned with 8.3 format. The dependency tree of
``install`` build target ensures a proper update (i.e. build) of all output
files before the actual installation step takes place. As such it is suggested
to use this build target to build TF-M.

Export dependency files for NS applications
-------------------------------------------
An NS application requires a number of files to interface with TF-M.
The build system exports these files as part of the ``install`` target and
places them in to a single directory::

    <build_dir>/install/export/tfm

Further details on how to integrate a new NS app with TF-M are available in the
:doc:`integration guide <tfm_integration_guide>`.

Building the documentation
==========================
Please ensure the dependencies for building the documentation are installed
as explained in the :doc:`software requirements <tfm_sw_requirement>`. The
requirements to build the firmware, are only required when using the CMAKE
method

There are currently two ways of building the documentation:
- Using the CMake build system as custom targets
- Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)

Using the CMake build-system
----------------------------

Building PDF output is optional and can be disabled by removing LaTex from the
PATH.

.. Note::
   For building the documentation all tools needed to build the firmware must
   be available.

Building the Reference Manual
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_doc
    cd cmake_doc
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
    cmake --build ./ -- install_doc

The documentation files will be available under the directory::

    cmake_doc/install/doc/reference_manual

Building the User Guide
^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash

    cd <TF-M base folder>
    mkdir cmake_doc
    cd cmake_doc
    cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
    cmake --build ./ -- install_userguide

The documentation files will be available under the directory::

    cmake_doc/install/doc/user_guide

Manually using documentation generation tools
---------------------------------------------

Invoking Sphinx-build will build both user_guide and reference_manual
targets.

.. code-block:: bash

    # Build the documentation from build_docs directory
    cd <TF-M base folder>/ build_docs/
    sphinx-build ./ user_guide

    # Build the documentation from a custom location
    # setting the build_docs as input

    # Note that using this method will still generate the reference manual
    # to the  <TF-M base folder>/build_docs/reference_manual
    cd <TF-M base folder>/OTHER_DIR/OTHER_DIR2
    sphinx-build  <TF-M base folder>/build_docs/ DESIRED_OUTPUT_DIR

*********************
Configuring the build
*********************
The build configuration for TF-M is provided to the build system using command
line arguments:

.. list-table::
   :widths: 20 80

   * - -DPROJ_CONFIG=<file>
     - Specifies the way the application is built.

       | <file> is the absolute path to configurations file
         named as ``Config<APP_NAME>.cmake``.
       | i.e. On Linux:
         ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```

   * - -DTARGET_PLATFORM=<target platform name>
     - Specifies the target platform.
       Supported platforms:

          - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
            ``-DTARGET_PLATFORM=AN521``
          - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
            ``-DTARGET_PLATFORM=AN519``
          - Arm SSE-123 Example Subsystem for MPS2+ (AN539)
            ``-DTARGET_PLATFORM=AN539``
          - Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
            ``-DTARGET_PLATFORM=FVP_SSE300_MPS2``
          - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_A``
          - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_B1``
          - Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
            ``-DTARGET_PLATFORM=MUSCA_S1``
          - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
            ``-DTARGET_PLATFORM=AN524``
          - Cypress CYS0644ABZI-S2D44 board (PSoC64 platform)
            ``-DTARGET_PLATFORM=psoc64``
            See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc64_spec>`
          - DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS platform)
            ``-DTARGET_PLATFORM=SSE-200_AWS``
          - DISCO_L562QE board (Cortex-M33 STM32L562)
            ``-DTARGET_PLATFORM=STM_DISCO_L562QE``
            See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
          - NUCLEO_L552ZE_Q (Cortex-M33 STM32L552)
            ``-DTARGET_PLATFORM=STM_NUCLEO_L552ZE_Q``
            See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`

   * - -DCOMPILER=<compiler name>
     - Specifies the compiler toolchain
       The possible values are:

         - ``ARMCLANG``
         - ``GNUARM``
   * - -DCMAKE_BUILD_TYPE=<build type>
     - Configures debugging support.
       The possible values are:

         - ``Debug``
         - ``Release``
         - ``Relwithdebinfo``
         - ``Minsizerel``
   * - -DMBEDCRYPTO_DEBUG=<ON|OFF>
     - Enables debug symbols for Mbed Crypto(MbedTLS) library. If a
       cryptographic accelerator is enabled then this will also enable
       debug symbols and logging for any accelerator libraries.
   * - -DBUILD_DWARF_VERSION=<dwarf version>
     - Configures DWARF version.
       The possible values are:

         - 2
         - 3
         - 4

.. Note::
    Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
    without BL2 bootloader.

**************
Configurations
**************
Configurations files under `configs` are TF-M provided configurations for building.
They are used by the `-DPROJ_CONFIG` argument for the build command line.
The following table describes the differences between the configurations:

+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
|     Configuration      | Model [1]_ | TF-M LVL [2]_ | Regression [3]_ | Core Test [4]_ | IPC Test [5]_ | PSA API Test [6]_ |        Comment          |
+========================+============+===============+=================+================+===============+===================+=========================+
| Default                | Library    | 1             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| Regression             | Library    | 1             | Yes             | Yes            | No            | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| CoreIPC                | IPC        | 1             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| CoreIPCTfmLevel2       | IPC        | 2             | No              | No             | No            | No                | TF-M, no tests          |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionIPC          | IPC        | 1             | Yes             | Yes            | Yes           | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionIPCTfmLevel2 | IPC        | 2             | Yes             | Yes            | Yes           | No                | TF-M & Regression tests |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTest             | Library    | 1             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTestIPC          | IPC        | 1             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| PsaApiTestIPCTfmLevel2 | IPC        | 2             | No              | No             | No            | Yes               | TF-M & PSA API tests    |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| DefaultProfileS        | Library    | 1             | No              | No             | No            | No                | TF-M Profile Small,     |
|                        |            |               |                 |                |               |                   | no tests [7]_           |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
| RegressionProfileS     | Library    | 1             | Yes             | Yes            | No            | No                | TF-M Profile Small &    |
|                        |            |               |                 |                |               |                   | Regression tests [7]_   |
+------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+

.. [1] Which TF-M Model is set: `CORE_IPC`. If `CORE_IPC` is set to true then the model is IPC model, otherwise it's library model.

.. [2] The TF-M isolation level `TFM_LVL`. Currently Library model supports level 1. IPC model supports level 1 and 2.

.. [3] Build regression tests or not: `REGRESSION`.

.. [4] Build core tests or not: `CORE_TEST`.

.. [5] Build IPC tests or not: `IPC_TEST`. It can be only enabled in IPC model

.. [6] Build for PSA API compliance tests or not: `PSA_API_TEST`.

.. [7] Profile Small config doesn't cover all the platforms. Please check
       Profile Small config files to find out the supported platforms.

.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _Doxygen: https://www.doxygen.nl

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

*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*