Docs: Move build instruction and user guide into technical reference
Move build instruction document and user guide document from getting
started into technical references folder. Rename 'tfm_user_guide.rst'
to 'tfm_run_instruction.rst'. This will make the document structure
more clear for readers.
Signed-off-by: Summer Qin <summer.qin@arm.com>
Change-Id: I69d46151f2cb97c828c1b82775ffd1af9032ed45
diff --git a/docs/technical_references/instructions/index.rst b/docs/technical_references/instructions/index.rst
new file mode 100644
index 0000000..19a6e43
--- /dev/null
+++ b/docs/technical_references/instructions/index.rst
@@ -0,0 +1,12 @@
+TF-M Detailed Instructions
+==========================
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/instructions/tfm_build_instruction.rst b/docs/technical_references/instructions/tfm_build_instruction.rst
new file mode 100644
index 0000000..485d917
--- /dev/null
+++ b/docs/technical_references/instructions/tfm_build_instruction.rst
@@ -0,0 +1,571 @@
+##################
+Build instructions
+##################
+Please make sure you have all required software installed as explained in the
+:doc:`software requirements </docs/getting_started/tfm_sw_requirement>`.
+
+****************
+TF-M build steps
+****************
+TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
+build environment. The instructions are below.
+
+Cmake version ``3.15.0`` or higher is required.
+
+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:`docs/technical_references/instructions/tfm_build_instruction:Manual
+dependency management`
+
+.. Note::
+
+ - For building with Armclang compiler version 6.10.0+, please follow the note
+ in :doc:`software requirements </docs/getting_started/tfm_sw_requirement>`.
+ - For building with the IAR toolchain, please see the notes in
+ :doc:`IAR software requirements <tfm_build_instruction_iar>`
+
+.. _tfm_cmake_configuration:
+
+Cmake configuration
+===================
+
+All configuration options are provided by cmake variables, and their default
+values, with docstrings, can be found in ``config/config_default.cmake``.
+
+Configuration is provided in multiple stages. Each stage will not override any
+config that has already been set at any of the prior stages.
+
+ 1. Command-line variable settings are applied.
+ 2. If the ``TFM_EXTRA_CONFIG_PATH`` variable has been set, that file is
+ loaded.
+ 3. If TEST_PSA_TEST is set, then PSA API test related config is applied from
+ ``config/tests/config_test_psa_api.cmake``.
+ 4. If it exists, CMAKE_BUILD_TYPE specific config is applied from
+ ``config/build_type/<build_type>.cmake``.
+ 5. Target specific config from ``platform/ext/target/<target_platform>/config.cmake``
+ is applied.
+ 6. If CRYPTO_HW_ACCELERATOR is set, then a config specific to the
+ accelerator type is applied if it exists.
+ 7. If it exists, TFM Profile specific config is applied from
+ ``config/profile/<tfm_profile>.cmake``.
+ 8. ``config/config_default.cmake`` is loaded.
+
+.. Warning::
+ This means that command-line settings are not applied when they conflict
+ with required platform settings. If it is required to override platform
+ settings (this is not usually a good idea) then TFM_EXTRA_CONFIG_PATH should be
+ used.
+
+Required cmake parameters for building TF-M
+-------------------------------------------
+
++----------------------+-------------------------------------------------------+
+| Parameter | Description |
++======================+=======================================================+
+| TFM_PLATFORM | The target platform as a path from the base directory |
+| | ``/platform/ext/target``, or as an absolute path. |
++----------------------+-------------------------------------------------------+
+
+By default release configuration builds. Alternate build types can be controlled
+by the CMAKE_BUILD_TYPE variable.
+
+Build type
+----------
+
+Build type is controlled by the ``CMAKE_BUILD_TYPE`` variable. The possible
+types are:
+
+ - ``Debug``
+ - ``Relwithdebinfo``
+ - ``Release``
+ - ``Minsizerel``
+
+``Release`` is default.
+
+Both ``Debug`` and ``Relwithdebinfo`` will include debug symbols in the output
+files. ``Relwithdebinfo``, ``Release`` and ``Minsizerel`` have optimization
+turned on and hence will produce smaller, faster code. ``Minsizerel`` will
+produce the smallest code, and hence is often a good idea on RAM or flash
+constrained systems.
+
+Other cmake parameters
+----------------------
+
+The full list of default options is in ``config/config_default.cmake``. Several
+important options are listed below.
+
+
++---------------------+----------------------------------------+---------------+
+| Parameter | Description | Default value |
++=====================+========================================+===============+
+| BL2 | Build level 2 secure bootloader. | ON |
++---------------------+----------------------------------------+---------------+
+| NS | Build NS app. Required for test code. | ON |
++---------------------+----------------------------------------+---------------+
+| TFM_PSA_API | Use PSA api (IPC mode) instead of | OFF |
+| | secure library mode. | |
++---------------------+----------------------------------------+---------------+
+| 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). | |
++---------------------+----------------------------------------+---------------+
+
+Regression test configuration
+-----------------------------
+
+Regression test configuration is controlled entirely by the ``TEST_S`` and
+``TEST_NS`` cmake variables.
+
+If regression testing is enabled, it will then enable all tests for the enabled
+secure partitions. If IPC mode is enabled via ``TFM_PSA_API`` the IPC tests will
+be enabled. QCBOR and T_COSE tests are linked to the Initial Attestation
+partition, as they are only used there. Multicore tests will be enabled if
+``TFM_MULTI_CORE_TOPOLOGY`` is enabled.
+
+Some cryptographic tests can be enabled and disabled. This is done to prevent
+false failures from being reported when a smaller Mbed Crypto config is being
+used which does not support all features.
+
++-----------------------------+-------------------------------------+---------------+
+| Parameter | Description | Default value |
++=============================+=====================================+===============+
+| TFM_CRYPTO_TEST_ALG_CBC | Test CBC cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CCM | Test CCM cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CFB | Test CFB cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CTR | Test CTR cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_GCM | Test GCM cryptography mode | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_SHA_512 | Test SHA-512 cryptography algorithm | ON |
++-----------------------------+-------------------------------------+---------------+
+| TFM_CRYPTO_TEST_HKDF | Test SHA-512 cryptography algorithm | ON |
++-----------------------------+-------------------------------------+---------------+
+
+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 are the design documents in the ``docs/technical_references/profiles/``
+directory.
+
+PSA test configuration
+----------------------
+
+PSA tests are configured by using the ``TEST_PSA_API`` cmake variable. The
+variable should be set to the name of the test suite that is desired. It is
+_not_ supported to set both ``TEST_PSA_API`` and ``TEST_S`` or ``TEST_NS``.
+
+The Functional API tests are:
+ - ``CRYPTO``
+ - ``INITIAL_ATTESTATION``
+ - ``STORAGE`` (INTERNAL_TRUSTED_STORAGE and PROTECTED_STORAGE)
+ - ``INTERNAL_TRUSTED_STORAGE``
+ - ``PROTECTED_STORAGE``
+
+The Firmware Framework test suites are:
+ - ``IPC``
+
+Note that these map directly to the ``SUITE`` cmake variable used in the
+psa-arch-tests documentation.
+
+Migration from legacy buildsystem
+---------------------------------
+
+The previous (legacy) cmake buildsystem made use of separate configuration
+files, where now build options are controlled by variables. For ease of
+transition, a table below is provided that maps the legacy files to the current
+variables, in the format of cmake command line parameters.
+
++------------------------------------------+---------------------------------------+
+| File | Cmake command line |
++==========================================+=======================================+
+| ConfigDefault.cmake | <No options> |
++------------------------------------------+---------------------------------------+
+| ConfigCoreIPC.cmake | -DTFM_PSA_API=ON |
++------------------------------------------+---------------------------------------+
+| ConfigCoreIPCTfmLevel2.cmake | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+---------------------------------------+
+| ConfigDefaultProfileS.cmake | -DTFM_PROFILE=profile_small |
++------------------------------------------+---------------------------------------+
+| ConfigDefaultProfileM.cmake | -DTFM_PROFILE=profile_medium |
++------------------------------------------+---------------------------------------+
+| ConfigRegression.cmake | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+---------------------------------------+
+| ConfigRegressionIPC.cmake | -DTEST_NS=ON -DTEST_S=ON |
+| | -DTFM_PSA_API=ON |
++------------------------------------------+---------------------------------------+
+| ConfigRegressionIPCTfmLevel2.cmake | -DTEST_NS=ON -DTEST_S=ON |
+| | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+---------------------------------------+
+| ConfigRegressionProfileS.cmake | -DTFM_PROFILE=profile_small |
+| | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+---------------------------------------+
+| ConfigRegressionProfileM.cmake | -DTFM_PROFILE=profile_medium |
+| | -DTEST_NS=ON -DTEST_S=ON |
++------------------------------------------+---------------------------------------+
+| ConfigPsaApiTest.cmake | -DTEST_PSA_API=<test_suite> |
++------------------------------------------+---------------------------------------+
+| ConfigPsaApiTestIPC.cmake | -DTEST_PSA_API=<test_suite> |
+| | -DTFM_PSA_API=ON |
++------------------------------------------+---------------------------------------+
+| ConfigPsaApiTestIPCTfmLevel2.cmake | -DTEST_PSA_API=<test_suite> |
+| | -DTFM_PSA_API=ON |
+| | -DTFM_ISOLATION_LEVEL=2 |
++------------------------------------------+---------------------------------------+
+| ConfigDefaultProfileM.cmake | -DTFM_PROFILE=profile_medium |
+| + profile_m_config_ext_ps_disabled.cmake | -DTFM_PARTITION_PROTECTED_STORAGE=OFF |
++------------------------------------------+---------------------------------------+
+
+There has also been some changes to the PSA manifest file generation. The files
+are now generated into a seperate tree in the ``<tfm build dir>/generated``
+directory. Therefore they have been removed from the source tree. Any changes
+should be made only to the template files.
+
+The api for the ``tools/tfm_parse_manifest_list.py`` script has also changed
+slightly. It is no longer required to be run manually as it is run as part of
+cmake.
+
+*******************
+TF-M build examples
+*******************
+
+.. Note::
+ By default, CMAKE_BUILD_TYPE is set to Release, for debug support change
+ this to Debug. See below for an example.
+
+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 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug
+ 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 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make install
+
+.. Note::
+ Unix Makefiles is the default generator. Ninja is also supported by setting
+ -GNinja
+
+.. Note::
+
+ It is recommended to build each different build configuration in a separate
+ build directory.
+
+As seen above, the toolchain can be set using the -DTFM_TOOLCHAIN_FILE parameter. Without
+it, the build command takes the GNU ARM toolchain as default, so there is no need
+to explicitly include it. In case other toolchain is required, i.e. ARM Clang, simply
+specify in the command line
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_ARMCLANG.cmake -DTEST_S=ON -DTEST_NS=ON
+ cmake --build cmake_build -- install
+
+Regression Tests for the AN521 target platform
+==============================================
+
+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.
+
+.. 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
+
+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_S=ON -DTEST_NS=ON
+ make install
+
+Build for PSA Functional API compliance tests
+=============================================
+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
+PSA API tests simultaneously is **not** supported.
+
+The value of the TEST_PSA_API variable is the suite 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 base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=CRYPTO
+ 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 -DTEST_PSA_API=CRYPTO
+ make install
+
+Build for PSA FF (IPC) compliance tests
+=======================================
+
+The build system provides support for building and integrating the PSA FF
+compliance test. This support is controlled by the TEST_PSA_API variable:
+
+.. code-block:: bash
+
+ -DTEST_PSA_API=IPC
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTEST_PSA_API=IPC -DTFM_PSA_API=ON
+ 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 -DTEST_PSA_API=IPC -DTFM_PSA_API=ON
+ 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.
+
+Building the documentation
+==========================
+Please ensure the dependencies for building the documentation are installed
+as explained in the :doc:`software requirements </docs/getting_started/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 can be requested by invoking `tfm_docs_userguide_pdf/
+tfm_docs_userguide_pdf`
+
+.. 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>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
+
+The documentation files will be available under the directory::
+
+ cmake_doc/docs/reference_manual
+
+Building the User Guide
+^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
+
+The documentation files will be available under the directory::
+
+ cmake_doc/docs/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>
+ mkdir build_docs
+ cp docs/conf.py build_docs/conf.py
+ cd 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
+
+****************************
+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_default.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.
+
+.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+.. _Doxygen: https://www.doxygen.nl
+
+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 ``config/config_default.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 a lot,
+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_default.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
+
+--------------
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/instructions/tfm_build_instruction_iar.rst b/docs/technical_references/instructions/tfm_build_instruction_iar.rst
new file mode 100644
index 0000000..b9e8b2d
--- /dev/null
+++ b/docs/technical_references/instructions/tfm_build_instruction_iar.rst
@@ -0,0 +1,63 @@
+###################################################
+Additional build instructions for the IAR toolchain
+###################################################
+
+Follow the instructions in
+:doc:`software requirements <tfm_build_instruction>`, but replace the -DTFM_TOOLCHAIN_FILE setting with toolchain_IARARM.cmake.
+
+
+Notes for building with IARARM
+------------------------------
+
+ IAR Embedded Workbench for ARM (EWARM) versions 8.42 or later are required.
+
+ Currently the MUSCA_B1 and MUSCA_S1 targets are not supported with IARARM,
+ due to lack of testing. The FVP_SSE300_MPS2 target is currently not supported by IARARM.
+
+ cmake needs to be version 3.14 or newer.
+
+ The V8M IAR CMSIS_5 RTX libraries in CMSIS_5 5.5.0 has a problem and has been updated in
+ CMSIS_5 5.7.0. The updated libraries are part of the tf-m-tests repo and no special instructions
+ are needed when the libraries from this repo are used.
+
+ For all configurations and build options some of the QCBOR tests fail due to the tests not handling
+ double float NaN:s according to the Arm Runtime ABI. This should be sorted out in the future.
+
+Example: building TF-M for AN521 platform using IAR:
+====================================================
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_IARARM.cmake
+ 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 -DTFM_TOOLCHAIN_FILE=../toolchain_IARARM.cmake
+ make install
+
+Regression Tests for the AN521 target platform
+==============================================
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_IARARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ 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 -DTFM_TOOLCHAIN_FILE=../toolchain_IARARM.cmake -DTEST_S=ON -DTEST_NS=ON
+ make install
+
+ *Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/instructions/tfm_run_instruction.rst b/docs/technical_references/instructions/tfm_run_instruction.rst
new file mode 100644
index 0000000..965d3e9
--- /dev/null
+++ b/docs/technical_references/instructions/tfm_run_instruction.rst
@@ -0,0 +1,576 @@
+##################################
+Run TF-M examples on Arm platforms
+##################################
+Instructions for how to run TF-M and example test application on Arm platforms.
+
+Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
+Follow :doc:`secure boot </docs/technical_references/tfm_secure_boot>` to build the
+binaries with or without BL2 bootloader.
+
+****************************************************************
+Execute TF-M example and 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`_ .
+
+.. Note::
+ The name of the reference model's executable can vary depending on toolchain.
+
+ - SMM-SSE-200 for `Keil MDK`_
+
+ - FVP_MPS2_AEMv8M for `Fixed Virtual Platforms`_ and `Arm Development Studio`_
+
+ For more information please refer to the appropriate toolchain's
+ documentation: `Keil MDK Documentation`_ ,
+ `Fixed Virtual Platforms Documentation`_ ,
+ `Arm Development Studio Documentation`_
+
+To run the example code on an SSE-200 Fast-Model
+================================================
+Using FVP_MPS2_AEMv8M provided by `Arm Development Studio`_ 2019.1.
+
+Example application and regression tests without BL2 bootloader
+---------------------------------------------------------------
+Add ``tfm_s.axf`` and ``tfm_ns.axf`` to symbol files in Debug Configuration
+menu.
+
+.. code-block:: bash
+
+ <DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=<build_dir>/bin/tfm_s.axf \
+ --data cpu0=<build_dir>/bin/tfm_ns.bin@0x00100000
+
+Example application and regression tests with BL2 bootloader
+------------------------------------------------------------
+To test TF-M with bootloader, one must apply the following changes:
+
+- Add ``bl2.axf`` to symbol files in DS-5 in Debug Configuration
+ menu.
+- Replace the last two lines of the previous command with this:
+
+.. code-block:: bash
+
+ --application cpu0=<build_dir>/bin/bl2.axf \
+ --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10080000
+
+Test software upgrade with BL2 bootloader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+BL2 bootloader is mandatory to test software update. Furthermore two TF-M blob
+must be built. Outputs of example application and regression test can be used to
+test it. Load output of example application to the primary slot (0x10080000) and
+output of regression test to the secondary slot (0x10180000). Add the following
+line to the end of the previous chapter:
+
+.. code-block:: bash
+
+ --data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10180000
+
+To run the example code on SSE 200 FPGA on MPS2 board
+=====================================================
+FPGA image is available to download
+`here <https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2>`__
+
+To run BL2 bootloader and TF-M example application and tests in the MPS2 board,
+it is required to have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board SD
+card. The image should be located in
+``<MPS2 device name>/MB/HBI0263<board revision letter>/AN521``
+
+The MPS2 board tested is HBI0263C referred also as MPS2+.
+
+.. Warning::
+
+ If you change the exe names, MPS2 expects file names in 8.3 format.
+
+Example application
+-------------------
+#. Copy ``bl2.bin`` and ``tfm_s_ns_signed.bin`` files from
+ ``<build_dir>/bin`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x10000000
+ IMAGE0FILE: \Software\bl2.bin ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_s_ns_signed.bin ; TF-M example application binary blob
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: primary slot
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests
+----------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xcf
+ [INF] Boot source: primary slot
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the protected storage service ####
+ Running Test Suite PS secure interface tests (TFM_PS_TEST_2XXX)...
+
+ > Executing 'TFM_PS_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+.. Note::
+
+ PS reliability tests take a few minutes to run on the MPS2.
+
+Example application without BL2 bootloader
+------------------------------------------
+#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
+ ``<build_dir>/bin`` to
+ ``<MPS2 device name>/SOFTWARE/``
+#. Open ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Update the ``AN521/images.txt`` file as follows::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x10000000
+ IMAGE0FILE: \Software\tfm_s.bin ; Secure code
+ IMAGE1ADDRESS: 0x00100000
+ IMAGE1FILE: \Software\tfm_ns.bin ; Non-secure code
+
+#. Close ``<MPS2 device name>/MB/HBI0263C/AN521/images.txt``
+#. Unmount/eject the ``<MPS2 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+Regression tests without BL2 bootloader
+---------------------------------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the protected storage service ####
+ Running Test Suite PS secure interface tests (TFM_PS_TEST_2XXX)...
+
+ > Executing 'TFM_PS_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2004'
+ Description: 'Write interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2005'
+ Description: 'Read interface'
+ ....
+
+*******************************************************************
+Execute TF-M example and regression tests on Musca test chip boards
+*******************************************************************
+.. Note::
+
+ Before executing any images on Musca-B1 board, please check the
+ :doc:`target platform readme </platform/ext/target/arm/musca_b1/sse_200/readme>`
+ to have the correct setup.
+
+Example application with BL2 bootloader
+=======================================
+
+#. Create a unified hex file comprising of both ``bl2.bin`` and
+ ``tfm_s_ns_signed.bin``.
+
+ - For Musca-B1
+
+ - Windows::
+
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 bin\tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 bin/tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - For Musca-S1
+
+ - Windows::
+
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 bin\tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 bin/tfm_s_ns_signed.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+#. Power up the Musca board by connecting it to a computer with a USB lead.
+ Press the ``PBON`` button if the green ``ON`` LED does not immediately turn
+ on. The board should appear as a USB drive.
+#. Copy ``tfm.hex`` to the USB drive. The orange ``PWR`` LED should start
+ blinking.
+#. Once the ``PWR`` LED stops blinking, power cycle or reset the board to boot
+ from the new image.
+#. After completing the procedure you should see the following messages on the
+ DAPLink UART (baud 115200 8n1)::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0xd9
+ [INF] Boot source: primary slot
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests with BL2 bootloader
+====================================
+.. note::
+
+ As the Internal Trusted Storage and Protected Storage tests use persistent
+ storage, it is recommended to erase the storage area before running the
+ tests. Existing data may prevent the tests from running to completion if,
+ for example, there is not enough free space for the test data or the UIDs
+ used by the tests have already been created with the write-once flag set.
+ Repeated test runs can be done without erasing between runs.
+
+ To erase the storage when flashing an image, ``-fill 0xFF <start_addr>
+ <end_addr>`` can be added to the ``srec_cat`` command used to create the
+ combined hex file. The ``<start_addr>`` and ``<end_addr>`` are the start and
+ end addresses of the storage area, found in the board's ``flash_layout.h``
+ file. The board's flash can also be erased via a debugger; see your IDE's
+ documentation for instructions.
+
+After completing the procedure you should see the following messages on the
+DAPLink UART (baud 115200 8n1)::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
+ [INF] Boot source: primary slot
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the protected storage service ####
+ Running Test Suite PS secure interface tests (TFM_PS_TEST_2XXX)...
+ > Executing 'TFM_PS_TEST_2001'
+ Description: 'Create interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2002'
+ Description: 'Get handle interface (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2003'
+ Description: 'Get handle with null handle pointer (DEPRECATED)'
+ This test is DEPRECATED and the test execution was SKIPPED
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2004'
+ Description: 'Get attributes interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2005'
+ Description: 'Get attributes with null attributes struct pointer'
+ ....
+
+PSA API tests
+=============
+Follow the build instructions for the PSA API tests and then follow the above
+procedures for flashing the image to the board. The PSA API tests are linked
+into the TF-M binaries and will automatically run. A log similar to the
+following should be visible on the UART; it is normal for some tests to be
+skipped but there should be no failed tests::
+
+ [Sec Thread] Secure image initializing!
+ Booting TFM v1.1
+ Non-Secure system starting...
+
+ ***** PSA Architecture Test Suite - Version 1.0 *****
+
+ Running.. Storage Suite
+ ******************************************
+
+ TEST: 401 | DESCRIPTION: UID not found check
+ [Info] Executing tests from non-secure
+
+ [Info] Executing ITS tests
+ [Check 1] Call get API for UID 6 which is not set
+ [Check 2] Call get_info API for UID 6 which is not set
+ [Check 3] Call remove API for UID 6 which is not set
+ [Check 4] Call get API for UID 6 which is removed
+ [Check 5] Call get_info API for UID 6 which is removed
+ [Check 6] Call remove API for UID 6 which is removed
+ [Check 7] Call get API for different UID 5
+ [Check 8] Call get_info API for different UID 5
+ [Check 9] Call remove API for different UID 5
+
+ [Info] Executing PS tests
+ [Check 1] Call get API for UID 6 which is not set
+ [Check 2] Call get_info API for UID 6 which is not set
+ [Check 3] Call remove API for UID 6 which is not set
+ [Check 4] Call get API for UID 6 which is removed
+ [Check 5] Call get_info API for UID 6 which is removed
+ [Check 6] Call remove API for UID 6 which is removed
+ [Check 7] Call get API for different UID 5
+ [Check 8] Call get_info API for different UID 5
+ [Check 9] Call remove API for different UID 5
+
+ TEST RESULT: PASSED
+
+ ******************************************
+
+ <further tests removed from log for brevity>
+
+ ************ Storage Suite Report **********
+ TOTAL TESTS : 17
+ TOTAL PASSED : 11
+ TOTAL SIM ERROR : 0
+ TOTAL FAILED : 0
+ TOTAL SKIPPED : 6
+ ******************************************
+
+.. note::
+ The Internal Trusted Storage and Protected Storage flash areas must be wiped
+ before running the Storage test suites.
+
+ Many IDEs for embedded development (such as Keil µVision) offer a function
+ to erase a device's flash. Refer to your IDE's documentation for
+ instructions.
+
+ Another way this can be achieved is by using ``srec_cat`` with the ``-fill``
+ parameter to fill the corresponding area in the binary with the erase value
+ of the flash (``0xFF``).
+
+ Refer to the platform flash layout for appropriate addresses to erase on
+ other platforms.
+
+ This step is not required on targets that emulate flash storage in RAM, as
+ it will be erased each time the device is reset. Note, however, that a warm
+ reset may not clear SRAM contents, so it may be necessary to power the
+ device off and on again between test runs.
+
+Example application or regression tests on Musca-B1 without BL2 bootloader
+==========================================================================
+
+Follow the above procedures, but create a unified hex file out of ``tfm_s.bin``
+and ``tfm_ns.bin``:
+
+- Windows::
+
+ srec_cat.exe bin\tfm_s.bin -Binary -offset 0xA000000 bin\tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
+
+- Linux::
+
+ srec_cat bin/tfm_s.bin -Binary -offset 0xA000000 bin/tfm_ns.bin -Binary -offset 0xA080000 -o tfm.hex -Intel
+
+Example application or regression tests on Musca-B1 using the Secure Enclave
+============================================================================
+
+Follow the above procedures, but to create a unified hex please check the
+:doc:`Musca-B1 Secure Enclave readme </platform/ext/target/arm/musca_b1/secure_enclave/readme>`.
+
+********************************************************
+Execute TF-M example and regression tests on MPS3 boards
+********************************************************
+
+To run the example code on CoreLink SSE-200 Subsystem for MPS3 (AN524)
+======================================================================
+FPGA image is available to download `here <https://www.arm.com/products/development-tools/development-boards/mps3>`__
+
+To run BL2 bootloader and TF-M example application and tests in the MPS3 board,
+it is required to have SMM-SSE-200 for MPS3 (AN524) image in the MPS3 board
+SD card. The image should be located in
+``<MPS3 device name>/MB/HBI<BoardNumberBoardrevision>/AN524``
+
+And the current boot memory for AN524 is QSPI flash, so you need to set the
+correct REMAP option in
+``<MPS3 device name>/MB/HBI<BoardNumberBoardrevision>/AN524/an524_v1.txt``
+
+::
+
+ REMAP: QSPI ;REMAP boot device BRAM/QSPI. Must match REMAPVAL below.
+ REMAPVAL: 1 ;REMAP register value e.g. 0-BRAM. 1-QSPI
+
+The MPS3 board tested is HBI0309B.
+
+.. Note::
+ If you change the exe names, MPS3 expects file names in 8.3 format.
+
+Example application
+-------------------
+#. Copy ``bl2.bin`` and ``tfm_s_ns_signed.bin`` files from
+ build dir to ``<MPS3 device name>/SOFTWARE/``
+#. Open ``<MPS3 device name>/MB/HBI0309B/AN524/images.txt``
+#. Update the ``images.txt`` file as follows::
+
+ TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
+
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+
+ IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ IMAGE0ADDRESS: 0x00000000 ;Please select the required executable program
+ IMAGE0FILE: \SOFTWARE\bl2.bin
+ IMAGE1UPDATE: AUTO
+ IMAGE1ADDRESS: 0x00040000
+ IMAGE1FILE: \SOFTWARE\tfm_s_ns_signed.bin
+
+#. Close ``<MPS3 device name>/MB/HBI0309B/AN524/images.txt``
+#. Unmount/eject the ``<MPS3 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic= good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=unset, copy_done=0x43, image_ok=0xff
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x40000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+Regression tests
+----------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic= good, copy_done=0xff, image_ok=0xff
+ [INF] Scratch: magic=unset, copy_done=0x9, image_ok=0xff
+ [INF] Boot source: slot 0
+ [INF] Swap type: none
+ [INF] Bootloader chainload address offset: 0x40000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ > Executing 'TFM_PS_TEST_2001'
+ Description: 'Set interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2002'
+ Description: 'Set interface with create flags'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2003'
+ Description: 'Set interface with NULL data pointer'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2004'
+ Description: 'Set interface with invalid data length'
+ TEST PASSED!
+ ....
+
+.. Note::
+ Some of the attestation tests take a few minutes to run on the MPS3.
+
+Example application without BL2 bootloader
+------------------------------------------
+#. Copy ``tfm_s.bin`` and ``tfm_ns.bin`` files from
+ build dir to ``<MPS3 device name>/SOFTWARE/``
+#. Open ``<MPS3 device name>/MB/HBI0309B/AN524/images.txt``
+#. Update the ``images.txt`` file as follows::
+
+ TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
+
+ [IMAGES]
+ TOTALIMAGES: 2 ;Number of Images (Max: 32)
+
+ IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ IMAGE0ADDRESS: 0x00000000 ;Please select the required executable program
+ IMAGE0FILE: \SOFTWARE\tfm_s.bin
+ IMAGE1UPDATE: AUTO
+ IMAGE1ADDRESS: 0x000C0000
+ IMAGE1FILE: \SOFTWARE\tfm_ns.bin
+
+#. Close ``<MPS3 device name>/MB/HBI0309B/AN521/images.txt``
+#. Unmount/eject the ``<MPS3 device name>`` unit
+#. Reset the board to execute the TF-M example application
+#. After completing the procedure you should be able to visualize on the serial
+ port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+Regression tests without BL2 bootloader
+---------------------------------------
+After completing the procedure you should be able to visualize on the serial
+port (baud 115200 8n1) the following messages::
+
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ > Executing 'TFM_PS_TEST_2001'
+ Description: 'Set interface'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2002'
+ Description: 'Set interface with create flags'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2003'
+ Description: 'Set interface with NULL data pointer'
+ TEST PASSED!
+ > Executing 'TFM_PS_TEST_2004'
+ Description: 'Set interface with invalid data length'
+ TEST PASSED!
+ ....
+
+Firmware upgrade and image validation with BL2 bootloader
+=========================================================
+High level operation of BL2 bootloader and instructions for testing firmware
+upgrade is described in :doc:`secure boot </docs/technical_references/tfm_secure_boot>`.
+
+--------------
+
+.. _Arm Development Studio: https://developer.arm.com/tools-and-software/embedded/arm-development-studio
+.. _Arm Development Studio Documentation: https://developer.arm.com/tools-and-software/embedded/arm-development-studio/learn/docs
+.. _Fixed Virtual Platforms: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms
+.. _Fixed Virtual Platforms Documentation: https://developer.arm.com/documentation/100966/latest
+.. _Keil MDK: http://www2.keil.com/mdk5
+.. _Keil MDK Documentation: https://www2.keil.com/mdk5/docs
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*