Docs: Update documentation for split build
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Co-authored-by: Kevin Peng <kevin.peng@arm.com>
Change-Id: I090ce549d26501a83ecacc4c6d73ff955eeb1bd4
diff --git a/docs/building/run_tfm_examples_on_arm_platforms.rst b/docs/building/run_tfm_examples_on_arm_platforms.rst
index ea2c1f9..4676acf 100644
--- a/docs/building/run_tfm_examples_on_arm_platforms.rst
+++ b/docs/building/run_tfm_examples_on_arm_platforms.rst
@@ -1,15 +1,17 @@
-##################################
-Run TF-M examples on Arm platforms
-##################################
-Instructions for how to run TF-M and example test application on Arm platforms.
+################################################
+Run TF-M tests and applications on Arm platforms
+################################################
+Instructions for how to run TF-M tests and applications on Arm platforms.
Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
Follow :doc:`secure boot </design_docs/booting/tfm_secure_boot>` to build the
binaries with or without BL2 bootloader.
-****************************************************************
-Execute TF-M example and regression tests on MPS2 boards and FVP
-****************************************************************
+.. _tf-m_regression_tests:
+
+****************************************************
+Execute TF-M regression tests on MPS2 boards and FVP
+****************************************************
The BL2 bootloader and TF-M example application and tests have been verified
using the reference model for MPS2 (AN521), in `Keil MDK`_ ,
`Fixed Virtual Platforms`_ and `Arm Development Studio`_ .
@@ -215,9 +217,9 @@
Description: 'Read interface'
....
-*******************************************************************
-Execute TF-M example and regression tests on Musca test chip boards
-*******************************************************************
+*******************************************************
+Execute TF-M regression tests on Musca test chip boards
+*******************************************************
.. Note::
Before executing any images on Musca-B1 board, please check the
diff --git a/docs/building/tfm_build_instruction.rst b/docs/building/tfm_build_instruction.rst
index 9eef380..99c006c 100644
--- a/docs/building/tfm_build_instruction.rst
+++ b/docs/building/tfm_build_instruction.rst
@@ -2,39 +2,57 @@
Build instructions
##################
-Please make sure you have all required software installed as explained in the
+.. 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>`.
-The additional building materials you can find in the following links:
+
+.. 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 examples <run_tfm_examples_on_arm_platforms>
+ Run TF-M tests and applications <run_tfm_examples_on_arm_platforms>
Building the documentation <documentation_generation>
IAR toolchain <tfm_build_instruction_iar>
-****************
-TF-M build steps
-****************
-TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
-build environment. The instructions are below.
+.. _Building SPE:
-Cmake version ``3.15.0`` or higher is required.
+*******************
+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
+Getting the source code
=======================
.. code-block:: bash
cd <base folder>
git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
-To simplify documentation commands, the new created repository under
-``trusted-firmware-m`` would be referenced as ``<TF-M base folder>`` and
-its parent, the ``<base folder>``. Dependency management is now handled by
-cmake. If you wish to alter this behaviour, see
-:ref:`building/tfm_build_instruction:Manual dependency management`
+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::
@@ -43,45 +61,79 @@
- For building with the IAR toolchain, please see the notes in
:doc:`IAR software requirements <tfm_build_instruction_iar>`
-Basic configuration
-===================
+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:
-TF-M has many options for configuration and fine-tuning. Please check the
-:ref:`tf-m_configuration` section for details. The **base** configuration
-will be build by default with only essential modules SPM and platform hence
-a platform must be selected via ``TFM_PLATFORM`` options, 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``.
- - A relative path under ``<TF-M_root>/platform/ext/target``,
- for example ``arm/mps2/an521``.
- - An absolute path of target platform, mainly used for out-of-tree platform
- build.
- - A target platform name that is supported under
- <TF-M_root>/platform/ext/target, 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
+- 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``.
+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.
+*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.
-Other cmake parameters
+.. _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.
@@ -91,113 +143,265 @@
+============================+==========================================+===============+
| BL2 | Build level 2 secure bootloader. | ON |
+----------------------------+------------------------------------------+---------------+
-| NS | Build NS app. Required for test code. | ON |
-+----------------------------+------------------------------------------+---------------+
| PROJECT_CONFIG_HEADER_FILE | User defined header file for TF-M config | |
+----------------------------+------------------------------------------+---------------+
| TFM_ISOLATION_LEVEL | Set TFM isolation level. | 1 |
+----------------------------+------------------------------------------+---------------+
-| TFM_PROFILE | Set TFM profile. | |
-+----------------------------+------------------------------------------+---------------+
-| TEST_S | Build secure regression tests. | OFF |
-+----------------------------+------------------------------------------+---------------+
-| TEST_NS | Build non-secure regression tests. | OFF |
-+----------------------------+------------------------------------------+---------------+
-| TEST_PSA_API | Build PSA API TESTS for the given | |
-| | suite. Takes a PSA api ``SUITE`` as an | |
-| | argument (``CRYPTO`` etc). | |
+| TFM_PROFILE | See :ref:`tf-m_profiles`. | |
+----------------------------+------------------------------------------+---------------+
Project Config Header File
--------------------------
-
-CMake variable ``PROJECT_CONFIG_HEADER_FILE`` is set by users with the full path of the
+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 project config header file is in :ref:`Header_configuration`.
+for the project config header file is in :ref:`Header_configuration`.
-.. Note::
+Building binaries
+=================
- It is recommended to clean up build folder before re-build if config header file is updated.
- CMake is unable to automatically recognize the dependency when the header file is defined as a macro.
-
-TF-M Profiles
--------------
-
-TF-M Profiles are implemented as a single cmake configuration file, under the
-``config/profile`` directory. A good understanding can be gained quickly by
-looking at the Profile configuration files, but the ultimate reference for
-Profiles is in :ref:`tf-m_profiles`.
-
-*******************
-TF-M build examples
-*******************
-
-Example: building TF-M for AN521 platform using GCC:
-====================================================
-.. code-block:: bash
-
- cd <TF-M base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521
- cmake --build cmake_build -- install
-
-Alternately using traditional cmake syntax
+The command below shows a general template for building TF-M as a typical CMake project:
.. code-block:: bash
- cd <TF-M base folder>
- mkdir cmake_build
- cd cmake_build
- cmake .. -DTFM_PLATFORM=arm/mps2/an521
- make install
+ 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.
-The default build uses Unix Makefiles. The ``-G`` option can be used to change
-this. The default build uses the GNU ARM toolchain and creates a Release build.
-These options can be overridden using the ``TFM_TOOLCHAIN_FILE`` and
-``CMAKE_BUILD_TYPE`` parameters, as shown below
+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 base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -GNinja -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DCMAKE_BUILD_TYPE=Debug
- cmake --build cmake_build -- install
+ 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
-Regression Tests for the AN521 target platform
-==============================================
+.. _Dependency management:
-Regression tests can be build by using the TEST_S and TEST_NS settings. Either
-can be used in isolation or both can be used to enable both suites. All tests
-for all enabled partitions are run, along with IPC and Multicore tests if those
-features are enabled.
+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 <TF-M base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
- cmake --build cmake_build -- install
+ 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
-Alternately using traditional cmake syntax
+.. 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 base folder>
- mkdir cmake_build
- cd cmake_build
- cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_S=ON -DTEST_NS=ON
- make install
+ 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
-Build for PSA API tests
+.. _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
=======================
-The build system provides support for building and integrating the PSA API tests
-from https://github.com/ARM-software/psa-arch-tests. PSA API tests are
-controlled using the TEST_PSA_API variable. Enabling both regression tests and
+
+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.
-The value of the TEST_PSA_API variable is the suite to be run.
+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
@@ -212,134 +416,13 @@
.. code-block:: bash
- cd <TF-M base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
- cmake --build cmake_build -- install
+ 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
-Alternately using traditional cmake syntax
-
-.. code-block:: bash
-
- cd <TF-M base folder>
- mkdir cmake_build
- cd cmake_build
- cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
- make install
-
-Location of build artifacts
-===========================
-
-All build artifacts are provided in the ``<build_dir>/bin`` directory. It is
-**not** required to run ``make install`` to generate artifacts in this location.
-
-
-For the purposes of maintaining compatibility with the legacy cmake build
-system, they are also provided in
-``<build_dir>/install/outputs/<target_platform>/``. In order to generate the
-artifacts in this location ``make install`` must be run.
-
-****************************
-Manual dependency management
-****************************
-
-The TF-M build system will by default fetch all dependencies with appropriate
-versions and store them inside the build tree. In this case, the build tree
-location is ``<build_dir>/lib/ext``, and the extra libraries can be cleaned by
-deleting that directory.
-
-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 path to the root directory of the local repo. This
-will disable the automatic downloading for that dependency.
-
-+----------------+---------------------+-----------------------------------------------------+
-| Dependency | Cmake variable | Git repo URL |
-+================+=====================+=====================================================+
-| Mbed Crypto | MBEDCRYPTO_PATH | https://github.com/ARMmbed/mbedtls |
-+----------------+---------------------+-----------------------------------------------------+
-| tf-m-tests | TFM_TEST_REPO_PATH | https://git.trustedfirmware.org/TF-M/tf-m-tests.git |
-+----------------+---------------------+-----------------------------------------------------+
-| MCUboot | MCUBOOT_PATH | https://github.com/mcu-tools/mcuboot |
-+----------------+---------------------+-----------------------------------------------------+
-| psa-arch-tests | PSA_ARCH_TESTS_PATH | https://github.com/ARM-software/psa-arch-tests |
-+----------------+---------------------+-----------------------------------------------------+
-
-For required versions of the dependencies, refer to ``config/config_base.cmake``.
-
-.. Note::
- - Some patches are required to the mbedtls repo to allow building it as part of
- TF-M. While these patches are being upstreamed they are stored in
- ``lib/ext/mbedcrypo``. In order to use a local copy of Mbed Crypto it is
- required to apply all patch files in this directory.
-
-.. Note::
- - CMSIS 5 is provided by the TF-M tests repo. If you wish to use a different
- source for CMSIS 5, it can be configured using CMSIS_5_PATH.
-
-TF-M Tests
-==========
-
-Dependency auto downloading is used by default.
-The TF-M build system downloads the tf-m-tests repo with a fixed version
-specified by ``TFM_TEST_REPO_VERSION`` in
-:file:`lib/ext/tf-m-tests/repo_config_base.cmake`.
-The version can be a release tag or a commit hash.
-
-Developers who want a different version of tf-m-tests can override
-``TFM_TEST_REPO_PATH`` to a local copy with the desired version.
-
-As the test repo is part of the TF-M project and coupled with TF-M repo,
-the version should be updated when there are dependency changes between the TF-M
-repo and the test repo and when there is a complete change merged in test repo.
-
-A complete change is one or more patches that are for the same purpose, for
-example a new test suite or enhancements on the test cases.
-Patches in one change can be merge individually provided they do not break
-anything or cause any regressions.
-But the version in the TF-M gets updated only when all the patches are merged.
-
-Example: building TF-M for AN521 platform with local Mbed Crypto
-================================================================
-
-Prepare Mbed Crypto repository
-------------------------------
-
-This is only required to be done once. For dependencies that do not have any
-``.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 config_base.cmake>
- git apply <TF-M base folder>/trusted-firmware-m/lib/ext/mbedcrypo/*.patch
-
-.. Note::
- - <Mbed Crypto base folder> does not need to have any fixed posisition related
- to the TF-M repo.
-
-Build TF-M
-----------
-
-With new cmake syntax
-
-.. code-block:: bash
-
- cd <TF-M base folder>
- cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
- cmake --build cmake_build -- install
-
-Alternately using traditional cmake syntax
-
-.. code-block:: bash
-
- cd <TF-M base folder>
- mkdir cmake_build
- cd cmake_build
- cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DMBEDCRYPTO_PATH=<Mbed Crypto base folder>/mbedtls
- make install
+ cmake -S . -B build_test -DCONFIG_SPE_PATH=<Absolute path to>/build_spe/api_ns
+ cmake --build build_test
--------------
diff --git a/docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst b/docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst
index 7d7f42d..79e87da 100644
--- a/docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst
+++ b/docs/integration_guide/platform/porting_tfm_to_a_new_hardware.rst
@@ -7,10 +7,6 @@
how to port a platform on the TF-M build system and which interfaces must
exist on the platform for TF-M (S and NS) to run on this new platform.
-******************
-TF-M in a nutshell
-******************
-For an overview please refer to :doc:`Introduction </introduction/readme>`.
*************
Prerequisites
@@ -72,11 +68,9 @@
*****************
The platform selection when building TF-M is set via the CMake
variable TFM_PLATFORM. This variable holds part of the path to the platform.
-
When using ``-DTFM_PLATFORM=arm/mps2/an521`` or ``-DTFM_PLATFORM=an521``
TF-M build system will look for the platform in
<TF-M ROOT>/platform/ext/target/arm/mps2/an521.
-
Therefore all hardware dependent code for your platform should go to
<TF-M ROOT>/platform/ext/target/.
@@ -130,6 +124,12 @@
Depending on the level of integration you want with TF-M some files or
information will be mandatory for the build system to build working firmware.
+Please note that platform folder provides source for building both :term:`SPE`
+and :term:`NSPE` parts. The SPE builds directly from the source tree while files
+necessary for NSPE platform support are installed to ``<Artifact folder>``
+for building TF-M application as decribed in the
+:doc:`Build instructions </building/tfm_build_instruction>`.
+
Questions to be answered:
- Will the platform use MCUboot as the second stage bootloader?
@@ -139,26 +139,26 @@
This optional second stage bootloader is set-up via the bl2 target in
the CMakelists.txt file (see below).
-
- - Will the platform support the Non-Secure world?
+ - Will the platform support the Non-Secure world application?
A platform can be designed to only support the secure world, in which
case we would refer to it as a secure enclave. TF-M build system allows
the developer to strip all Non-Secure world related code out of the
final image. Most platforms, and especially the ones intended to be
generic or to have a Non-Secure application will require Non-Secure world
- support.
-
- This optional Non-Secure world is set-up via the tfm_ns target in the
- CMakelists.txt file (see below).
+ support. In that case a platform shall instruct build system on the file
+ set for exporting to Non-Secure world.
- How does the non-secure world communicate with the secure world?
TF-M supports running the non-secure world on the same CPU as the secure
world, communicating via TrustZone or running the non-secure world on
- a separate CPU, communicating via a mailbox.
+ a separate CPU, communicating via a mailbox. The platform is responsible
+ for configuring toolchains with correct CPU and architecture related
+ features for secure and non-secure worlds.
- The architecture is configured in the config.cmake file (see below).
+ The architecture for secure world is configured in the cpuarch.cmake
+ file (see below).
- How does the FLASH need to be split between worlds?
@@ -194,7 +194,8 @@
(MANDATORY)
- This is the entry point for the build system to build your platform.
+ This is the entry point for the build system to build your platform on the secure side and
+ also export files to build Non-Secure side.
it must:
@@ -202,37 +203,34 @@
This folder will contain two files flash_layout.h_ and region_defs.h_
- - Add scatter files to the bl2, tfm_s, and/or tfm_ns target. [SCATTER_]
+ - Add scatter files to the bl2 and tfm_s targets. [SCATTER_]
- Please note that TF-M provides a common scatter file, for the bl2, tfm_s, tfm_ns targets, which can be used in most cases. [SCATTER_COMMON_]
+ Please note that TF-M provides a common scatter file for the bl2, tfm_s and
+ tfm_ns targets, which can be used in most cases.
- - Add startup files to the bl2, tfm_s, and/or tfm_ns target. [STARTUP_]
- - Add required sources and includes for the bl2, tfm_s and tfm_ns target (if supported) [SOURCES_INCLUDES_]
- - Link to the correct version of the CMSIS RTX libraries (from ``lib/ext/CMSIS_5/CMakeLists.txt``) [CMSIS_RTX_]
+ - Add startup files to the bl2 and tfm_s targets. [STARTUP_]
+ - Add required sources and includes for the bl2 and tfm_s targets [SOURCES_INCLUDES_]
+ - Install all files required for building the platform in the Non-secure application [INSTALL_]
-preload.cmake :
----------------
+ The installation section expands the common installation script with the platform specific files.
+ The following predefined variables are availble to address the respective subfolders
+ of the target ``<Artifact folder>``.
- (MANDATORY)
-
- This file tells the build system the main hardware information such as the
- main processor (e.g. m0plus) and architecture (e.g. armv6-m).
-
- This file should not contain any other CMake configuration variables.
- [preload_cmake_]
-
-preload_ns.cmake:
------------------
-
- If platform is a dual core then it may provide a preload_ns.cmake, which is
- the equivalent of preload.cmake but for the second core.
-
- If the platform is single core, this file should not be present.
-
- If the platform is dual core but both cores have the same architecture,
- this file is optional.
-
- [preload_cmake_]
+ +-------------------------------------+------------------------------------------------------------+
+ | name | description |
+ +=====================================+============================================================+
+ |INSTALL_INTERFACE_INC_DIR | interface/include - interface header files |
+ +-------------------------------------+------------------------------------------------------------+
+ |INSTALL_INTERFACE_SRC_DIR | interface/src - interface source files |
+ +-------------------------------------+------------------------------------------------------------+
+ |INSTALL_INTERFACE_LIB_DIR | interface/lib - interface libraries |
+ +-------------------------------------+------------------------------------------------------------+
+ |INSTALL_IMAGE_SIGNING_DIR | image_signing tools and files |
+ +-------------------------------------+------------------------------------------------------------+
+ |INSTALL_CMAKE_DIR | CMake modules for Non-secure app build |
+ +-------------------------------------+------------------------------------------------------------+
+ |INSTALL_PLATFORM_NS_DIR | NS platform source files |
+ +-------------------------------------+------------------------------------------------------------+
config.cmake:
-------------
@@ -266,10 +264,6 @@
+-------------------------------------+------------------------------------------------------------+
|PLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT | Wheter the platform has firmware update support |
+-------------------------------------+------------------------------------------------------------+
- |PLATFORM_SLIH_IRQ_TEST_SUPPORT | Wheter the platform has SLIH test support |
- +-------------------------------------+------------------------------------------------------------+
- |PLATFORM_FLIH_IRQ_TEST_SUPPORT | Wheter the platform has FLIH test support |
- +-------------------------------------+------------------------------------------------------------+
|PSA_API_TEST_TARGET | The target platform name of PSA API test |
+-------------------------------------+------------------------------------------------------------+
|PLATFORM_SVC_HANDLERS | Whether the platform has specific SVC handling |
@@ -279,12 +273,62 @@
[config_cmake_]
-install.cmake:
+cpuarch.cmake:
--------------
- If there are platform-specific files that need to be installed, this file
- can be provided to do that.
+ (MANDATORY)
+ This file contains hardware information such as the main processor and architecture of the SPE
+ CPU.
+ On single-core platforms, it should be installed to ``<Artifact folder>`` for NSPE build.
+ On multi-core platforms, two cpuarch.cmake files should be added.
+
+ - a SPE specific ``cpuarch.cmake`` used in SPE build
+ - an NSPE one which should be installed to ``<Artifact folder>`` with filename ``cpuarch.cmake``
+ for NSPE build. See `ns/cpuarch_ns.cmake`_.
+
+ +-------------------------+------------------------------------------------------------+
+ | name | description |
+ +=========================+============================================================+
+ |TFM_SYSTEM_PROCESSOR | The SPE Processor the platform is using |
+ +-------------------------+------------------------------------------------------------+
+ |TFM_SYSTEM_ARCHITECTURE | The architecture of the processor |
+ +-------------------------+------------------------------------------------------------+
+ |CONFIG_TFM_FP_ARCH | The Float Point architecture flag for toolchain |
+ +-------------------------+------------------------------------------------------------+
+ |CONFIG_TFM_FP_ARCH_ASM | The Float Point architecture flag for assembly code |
+ +-------------------------+------------------------------------------------------------+
+
+tests/tfm_tests_config.cmake:
+-----------------------------
+
+ (OPTIONAL)
+
+ This file contains platform-specific config options for TF-M regression tests.
+ The ``tests`` folder should installed to <Artifact folder>/platform for NSPE build.
+ Here are some examples.
+
+ +--------------------------------+------------------------------------------------------------+
+ | name | description |
+ +================================+============================================================+
+ |PLATFORM_SLIH_IRQ_TEST_SUPPORT | Whether the platform has SLIH test support |
+ +-------------------------+-------------------------------------------------------------------+
+ |PLATFORM_FLIH_IRQ_TEST_SUPPORT | Whether the platform has FLIH test support |
+ +--------------------------------+------------------------------------------------------------+
+
+tests/psa_arch_tests_config.cmake:
+----------------------------------
+
+ (OPTIONAL)
+
+ This file contains platform-specific config options for PSA API tests.
+ Here are some examples.
+
+ +--------------------------------+------------------------------------------------------------+
+ | name | description |
+ +================================+============================================================+
+ |PSA_API_TEST_TARGET | The target platform name of PSA API test |
+ +--------------------------------+------------------------------------------------------------+
startup files:
---------------
@@ -544,6 +588,33 @@
- implement the `platform_svc_handlers`_ function which handles SVC.
- enable ``PLATFORM_SVC_HANDLERS`` config option.
+ns/CMakeLists.txt
+-----------------
+
+ (MANDATORY)
+
+ This is CMake script for building the platform support on NSPE side. It's
+ copied to ``<Artifact folder>`` in the installation phase and instructs on
+ how to build **platform_ns** target. The default NSPE build script expects
+ this target definition and extends it with files, common for all TF-M platforms.
+
+ Note::
+ This file shall define and use paths of installed directories in ``<Artifact folder>``,
+ instead of paths in TF-M platform folder.
+
+ [NSCMakeLists.txt_]
+
+ns/cpuarch_ns.cmake
+-------------------
+
+ (MANDATORY for multi-core platforms)
+
+ This file contains the hardware information for the NSPE CPU.
+ It should be installed to ``<Artifact folder>/platform`` for NSPE build,
+ ranamed to ``cpuarch.cmake``.
+
+ [cpuarch.cmake_]
+
.. _Functions:
Functions
@@ -648,23 +719,25 @@
Annex
=====
+CMake build system snippets examples
+
.. _PLATFORM_REGION_DEFS:
-::
+CMakeLists.txt: Defining regions for Secure world platform and all linked to it.
- [PLATFORM_REGION_DEFS]
+.. code-block:: CMake
+
target_include_directories(platform_region_defs
INTERFACE
<folder name under the platform folder - usually named platform>
)
-------------
-
.. _SCATTER:
-::
+CMakeLists.txt: Scatter files for SPE platform and bootloader
- [SCATTER]
+.. code-block:: CMake
+
target_add_scatter_file(bl2
$<$<C_COMPILER_ID:ARMClang>:${PLATFORM_DIR}/ext/common/armclang/tfm_common_bl2.sct>
$<$<C_COMPILER_ID:GNU>:${PLATFORM_DIR}/ext/common/gcc/tfm_common_bl2.ld>
@@ -675,27 +748,13 @@
$<$<C_COMPILER_ID:GNU>:${PLATFORM_DIR}/ext/common/gcc/tfm_common_s.ld>
$<$<C_COMPILER_ID:IAR>:${PLATFORM_DIR}/ext/common/iar/tfm_common_s.icf>
)
- target_add_scatter_file(tfm_ns
- $<$<C_COMPILER_ID:ARMClang>:${PLATFORM_DIR}/ext/common/armclang/tfm_common_ns.sct>
- $<$<C_COMPILER_ID:GNU>:${PLATFORM_DIR}/ext/common/gcc/tfm_common_ns.ld>
- $<$<C_COMPILER_ID:IAR>:${PLATFORM_DIR}/ext/common/iar/tfm_common_ns.icf>
- )
-
-------------
-
-.. _SCATTER_COMMON:
-
-::
-
- <TF-M ROOT>/platform/ext/common/<TOOLCHAIN>/
-
-------------
.. _STARTUP:
-::
+CMakeLists.txt: Startup files for SPE platform and bootloader
- [STARTUP]
+.. code-block:: CMake
+
target_sources(bl2
PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/<folder to platform>/device/source/startup_<platform name>.c
@@ -704,27 +763,19 @@
PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/<folder to platform>/device/source/startup_<platform name>.c
)
- target_sources(tfm_ns
- PRIVATE
- ${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/<folder to platform>/device/source/startup_<platform name>.c
- )
-
-------------
.. _SOURCES_INCLUDES:
-::
+CMakeLists.txt: The Secure world platform sources
- [SOURCES_INCLUDES]
+.. code-block:: CMake
+
target_include_directories(platform_bl2
PUBLIC
)
target_include_directories(platform_s
PUBLIC
)
- target_include_directories(platform_ns
- PUBLIC
- )
target_sources(platform_bl2
PRIVATE
@@ -732,9 +783,6 @@
target_sources(platform_s
PRIVATE
)
- target_sources(platform_ns
- PRIVATE
- )
target_sources(tfm_spm
PRIVATE
target_cfg.c
@@ -742,47 +790,40 @@
tfm_hal_platform.c
)
-------------
+.. _INSTALL:
-.. _CMSIS_RTX:
+CMakeLists.txt: installation for the Non-Secure world platform build
-::
+.. code-block:: CMake
- [CMSIS_RTX]
- target_link_libraries(CMSIS_5_tfm_ns
- INTERFACE
- <CMSIS_5_RTX_CM0 | CMSIS_5_RTX_CM3 | CMSIS_5_RTX_V8MBN | CMSIS_5_RTX_V8MMN>
- )
+ install(FILES ${PLATFORM_DIR}/ext/common/uart_stdout.c
+ native_drivers/arm_uart_drv.c
+ native_drivers/timer_cmsdk/timer_cmsdk.c
+ cmsis_drivers/Driver_USART.c
+ retarget/platform_retarget_dev.c
+ cmsis_core/an521_ns_init.c
+ DESTINATION ${INSTALL_PLATFORM_NS_DIR})
-------------
-
-.. _preload_cmake:
-
-::
-
- [preload_cmake]
- set(TFM_SYSTEM_PROCESSOR <value>) # The format is that same as the format used in the -mcpu= argument of GNUARM or ARMCLANG. The special +modifier syntax must not be used.
- set(TFM_SYSTEM_ARCHITECTURE <value>) # The format is that same as the format used in the -march= argument of GNUARM or ARMCLANG. The special +modifier syntax must not be used.
- set(TFM_SYSTEM_DSP <value>)
- set(CRYPTO_HW_ACCELERATOR_TYPE <value>)
-
-------------
+ install(DIRECTORY ${PLATFORM_DIR}/ext/common
+ ${PLATFORM_DIR}/ext/driver
+ DESTINATION ${INSTALL_PLATFORM_NS_DIR}/ext)
.. _config_cmake:
-::
+config.cmake
- [config_cmake]
+.. code-block:: CMake
+
set(CONFIG_TFM_USE_TRUSTZONE ON)
set(TFM_MULTI_CORE_TOPOLOGY OFF)
set(BL2 OFF CACHE BOOL "Whether to build BL2")
set(NS FALSE CACHE BOOL "Whether to build NS app" FORCE)
-------------
-
.. _check_config.cmake:
-::
+check_config.cmake
+
+.. code-block:: CMake
function(tfm_invalid_config)
if (${ARGV})
@@ -801,6 +842,39 @@
# Requires armclang >= 6.10.1
tfm_invalid_config((CMAKE_C_COMPILER_ID STREQUAL "ARMClang") AND (CMAKE_C_COMPILER_VERSION VERSION_LESS "6.10.1"))
+.. _NSCMakeLists.txt:
+
+/ns/CMakeLists.txt:
+
+.. code-block:: CMake
+
+ add_library(platform_ns)
+
+ target_sources(platform_ns
+ PRIVATE
+ arm_uart_drv.c
+ timer_cmsdk.c
+ uart_stdout.c
+ Driver_USART.c
+ PUBLIC
+ cmsis_core/startup_an521.c
+ )
+
+ target_include_directories(platform_ns
+ PUBLIC
+ include
+ cmsis
+ cmsis_core
+ )
+
+ target_compile_definitions(platform_ns
+ PUBLIC
+ $<$<BOOL:${PLATFORM_DEFAULT_CRYPTO_KEYS}>:PLATFORM_DEFAULT_CRYPTO_KEYS>
+ )
+
+.. _cpuarch.cmake:
+
*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
+
*Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company)
or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*