Docs: Restructuring and new layout
This patch implements a set of user-experiences aimed
changes.It modifies the documentation structure and
switches to a more reactive design for the rtd theme.
* The documentation layout has been redesigned to be more
intuitive,easier to maintain and and scale.
* The landing page introduces a new dashboard.
* Introduced dedicated space for release documents, and
changelog has been modified to directly source content
from referenced documents.
* Added quick-link navigation for items that need emphasis.
* Relevant design documents can now be grouped in suf-folders.
* There is dedicated space for custom platform, and third
party tools documents.
* Wildcard and regex matching has been introduced to indexes.
Change-Id: Ib02d17d5d26187d397ba17317788cf2a01401b07
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..4b08906
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,13 @@
+Getting Started Guides
+======================
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/os_migration_guide_armv8m.rst b/docs/getting_started/os_migration_guide_armv8m.rst
new file mode 100644
index 0000000..752c332
--- /dev/null
+++ b/docs/getting_started/os_migration_guide_armv8m.rst
@@ -0,0 +1,42 @@
+#########################################################
+Generic OS migration from Armv7-M to Armv8-M architecture
+#########################################################
+The purpose of this document is to list a set of requirements needed for
+migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
+
+********************
+List of requirements
+********************
+- If the same OS codebase is used for both Secure and Non Secure builds, it is
+ suggested to put specific code targeted to the Non Secure build under a
+ compile time switch, e.g. ``#if (DOMAIN_NS == 1U)``. The OS build system in
+ this case needs to be amended accordingly to support this new switch.
+- If the OS implements stack limit checking, the ``PSPLIM`` register
+ needs to be initialized and properly handled during thread context switch
+ operations.
+- If the OS manipulates directly the Link Register, the default Link Register
+ value used in Handler mode transitions needs to be differentiated between
+ Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
+- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
+ as described
+ `here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
+ , and would like to use the non-secure client identification feature of TF-M,
+ then it also have to use the
+ ``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
+ API function provided by TF-M, as described in
+ :doc:`NS client identification documentation <tfm_ns_client_identification>`.
+- if the OS doesn't support the API mentioned above, it should set
+ ``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
+- .. Note::
+
+ This is NOT REQUIRED when the Non Secure OS build is meant
+ to be integrated with TF-M running in Secure world.
+
+ If generic function calls into Secure world have to be supported in Non Secure
+ builds, integrate an API for secure stack memory management (e.g. the
+ TrustZone API for secure stack memory management described in
+ ``tz_context.h``).
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
new file mode 100644
index 0000000..121ef84
--- /dev/null
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -0,0 +1,357 @@
+##################
+Build instructions
+##################
+Please make sure you have all required software installed as explained in the
+:doc:`software requirements <tfm_sw_requirement>`.
+
+The external dependecies are briefly listed in the
+:ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
+
+The configuration-table
+:ref:`docs/getting_started/tfm_build_instruction:Configuring the build` section
+explains all the supported build parameters:
+
+****************
+TF-M build steps
+****************
+TF-M uses `cmake <https://cmake.org/overview/>`__ to provide an out-of-source
+build environment. The instructions are below.
+
+.. Note::
+
+ It is recommended to build each different build configurations in separate
+ directories.
+
+Getting the source-code
+=======================
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git
+ git clone https://github.com/ARMmbed/mbed-crypto.git -b mbedcrypto-3.0.1
+ git clone https://github.com/ARM-software/CMSIS_5.git -b 5.5.0
+
+ # If CMSIS was cloned before the git-lfs dependency was installed,
+ # use the following command to download the binaries.
+ cd CMSIS_5 && git lfs pull
+
+.. Note::
+ `CMSIS_5` now uses `git-lfs` for storing large size binaries so the cloning
+ process has changed from previous releases. Please refer to the `CMSIS_5`
+ documentation for more details.
+
+.. Note::
+ For building with Armclang compiler version 6.10.0, please follow the note
+ in :ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
+
+.. Note::
+ For building with the IAR toolchain, please see the notes in
+ :doc:`software requirements <tfm_build_instruction_iar>`
+
+Build steps for the AN521 target platform:
+==========================================
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_build
+ cd cmake_build
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
+ cmake --build ./ -- install
+
+Regression Tests for the AN521 target platform
+==============================================
+*TF-M build regression tests on Linux*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+*TF-M build regression tests on Windows*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+Build for PSA Developer API compliance tests
+============================================
+The build system provides the support for linking with prebuilt PSA Developer
+API compliance NS test libraries when using the ``ConfigPsaApiTest.cmake``,
+``ConfigPsaApiTestIPC.cmake`` or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config
+file. The build system assumes that the PSA API compliance test suite is checked
+out at the same level of the TF-M root folder and the default name for the build
+folder has been used when compiling the PSA API compliance tests. Each set of
+tests for the Internal Trusted Storage, Protected Storage, Crypto and Attestation
+services needs to be enabled at the build configuration step by defining::
+
+ -DPSA_API_TEST_INTERNAL_TRUSTED_STORAGE=ON
+ -DPSA_API_TEST_PROTECTED_STORAGE=ON
+ -DPSA_API_TEST_STORAGE=ON
+ -DPSA_API_TEST_CRYPTO=ON
+ -DPSA_API_TEST_INITIAL_ATTESTATION=ON
+
+respectively for the corresponding service. For example, to enable the PSA API
+tests for the Crypto service only:
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_psa_test
+ cd cmake_psa_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTest.cmake` -DPSA_API_TEST_CRYPTO=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+Build for PSA FF (IPC) compliance tests
+=======================================
+
+The build system assumes that the PSA FF compliance test suite is checked out
+at the same level of the TF-M root folder and the default name for the build
+folder has been used when compiling the PSA FF compliance tests.
+
+Parse the PSA FF compliance tests partition manifests using a tool script named
+as ``tfm_parse_manifest_list.py``. This tool updates the TFM partitions data
+structure with PSA test suite partitions detail and creates the manifest output
+files that are required for the PSA test suite build. Using these manifest
+output files, build the PSA FF compliance tests as per the instructions
+given in the PSA FF compliance tests README.
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ python tools/tfm_parse_manifest_list.py -m tools/tfm_psa_ff_test_manifest_list.yaml append
+
+The build system provides the support for linking with prebuilt PSA FF
+compliance NS and S test libraries when using the ``ConfigPsaApiTestIPC.cmake``
+or ``ConfigPsaApiTestIPCTfmLevel2.cmake`` config file. The PSA FF compliance
+tests need to be enabled at the build configuration step by defining::
+
+ -DPSA_API_TEST_IPC=ON.
+
+For example, to enable the PSA FF tests for ConfigPsaApiTestIPCTfmLevel2.cmake
+config :
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_psa_test
+ cd cmake_psa_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigPsaApiTestIPCTfmLevel2.cmake` -DPSA_API_TEST_IPC=ON -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG ../
+ cmake --build ./ -- install
+
+Location of build artifacts
+===========================
+The build system defines an API which allow easy usage of build
+artifacts. The ``install`` build target copies all files which might be needed
+as a dependency by external tools or build systems to the
+``<build_dir>/install/outputs``
+directory, with the following directory hierarchy:
+
+::
+
+ <build_dir>/install/outputs/fvp/
+ <build_dir>/install/outputs/<target_platform>/
+
+There is one folder for FVP testing, with more elaborate naming and
+there is an other for testing on target hardware platform (AN521, etc.), where
+naming convention is aligned with 8.3 format. The dependency tree of
+``install`` build target ensures a proper update (i.e. build) of all output
+files before the actual installation step takes place. As such it is suggested
+to use this build target to build TF-M.
+
+Export dependency files for NS applications
+-------------------------------------------
+An NS application requires a number of files to interface with TF-M.
+The build system exports these files as part of the ``install`` target and
+places them in to a single directory::
+
+ <build_dir>/install/export/tfm
+
+Further details on how to integrate a new NS app with TF-M are available in the
+:doc:`integration guide <tfm_integration_guide>`.
+
+Building the documentation
+==========================
+Please ensure the dependencies for building the firmware and the
+documentation are installed as explained in the
+:doc:`software requirements <tfm_sw_requirement>`.
+
+Building PDF output is optional and can be disabled by removing LaTex from the
+PATH.
+
+.. Note::
+ For building the documentation all tools needed to build the firmware must
+ be available.
+
+Building the Reference Manual
+-----------------------------
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ mkdir cmake_doc
+ cd cmake_doc
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
+ cmake --build ./ -- install_doc
+
+The documentation files will be available under the directory::
+
+ cmake_doc/install/doc/reference_manual
+
+Building the User Guide
+-----------------------
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ mkdir cmake_doc
+ cd cmake_doc
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
+ cmake --build ./ -- install_userguide
+
+The documentation files will be available under the directory::
+
+ cmake_doc/install/doc/user_guide
+
+*********************
+Configuring the build
+*********************
+The build configuration for TF-M is provided to the build system using command
+line arguments:
+
+.. list-table::
+ :widths: 20 80
+
+ * - -DPROJ_CONFIG=<file>
+ - Specifies the way the application is built.
+
+ | <file> is the absolute path to configurations file
+ named as ``Config<APP_NAME>.cmake``.
+ | i.e. On Linux:
+ ``-DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake```
+
+ * - -DTARGET_PLATFORM=<target platform name>
+ - Specifies the target platform.
+ Supported platforms:
+
+ - Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+ ``-DTARGET_PLATFORM=AN521``
+ - Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+ ``-DTARGET_PLATFORM=AN519``
+ - Arm SSE-123 Example Subsystem for MPS2+ (AN539)
+ ``-DTARGET_PLATFORM=AN539``
+ - Cortex-M55 SSE-300 subsystem for MPS2+ FVP
+ ``-DTARGET_PLATFORM=FVP_SSE300_MPS2``
+ - Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_A``
+ - Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_B1``
+ - Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
+ ``-DTARGET_PLATFORM=MUSCA_S1``
+ - Cortex-M33 SSE-200 subsystem for MPS3 (AN524)
+ ``-DTARGET_PLATFORM=AN524``
+ - Cypress CYS0644ABZI-S2D44 board (PSoC64 platform)
+ ``-DTARGET_PLATFORM=psoc64``
+ See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc64_spec>`
+ - DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS platform)
+ ``-DTARGET_PLATFORM=SSE-200_AWS``
+ - DISCO_L562QE board (Cortex-M33 STM32L562)
+ ``-DTARGET_PLATFORM=STM_DISCO_L562QE``
+ See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
+ - NUCLEO_L552ZE_Q (Cortex-M33 STM32L552)
+ ``-DTARGET_PLATFORM=SSTM_NUCLEO_L552ZE_Q``
+ See :doc:`STM32L5xx platform specifics </platform/ext/target/stm/stm32l5xx/readme>`
+
+ * - -DCOMPILER=<compiler name>
+ - Specifies the compiler toolchain
+ The possible values are:
+
+ - ``ARMCLANG``
+ - ``GNUARM``
+ * - -DCMAKE_BUILD_TYPE=<build type>
+ - Configures debugging support.
+ The possible values are:
+
+ - ``Debug``
+ - ``Release``
+ - ``Relwithdebinfo``
+ - ``Minsizerel``
+ * - -DMBEDCRYPTO_DEBUG=<ON|OFF>
+ - Enables debug symbols for Mbed Crypto library. If a cryptographic
+ accelerator is enabled then this will also enable debug symbols and
+ logging for any accelerator libraries.
+ * - -DBUILD_DWARF_VERSION=<dwarf version>
+ - Configures DWARF version.
+ The possible values are:
+
+ - 2
+ - 3
+ - 4
+
+.. Note::
+ Follow :doc:`secure boot <./tfm_secure_boot>` to build the binaries with or
+ without BL2 bootloader.
+
+**************
+Configurations
+**************
+Configurations files under `configs` are TF-M provided configurations for building.
+They are used by the `-DPROJ_CONFIG` argument for the build command line.
+The following table describes the differences between the configurations:
+
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| Configuration | Model [1]_ | TF-M LVL [2]_ | Regression [3]_ | Core Test [4]_ | IPC Test [5]_ | PSA API Test [6]_ | Comment |
++========================+============+===============+=================+================+===============+===================+=========================+
+| Default | Library | 1 | No | No | No | No | TF-M, no tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| Regression | Library | 1 | Yes | Yes | No | No | TF-M & Regression tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| CoreIPC | IPC | 1 | No | No | No | No | TF-M, no tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| CoreIPCTfmLevel2 | IPC | 2 | No | No | No | No | TF-M, no tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| RegressionIPC | IPC | 1 | Yes | Yes | Yes | No | TF-M & Regression tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| RegressionIPCTfmLevel2 | IPC | 2 | Yes | Yes | Yes | No | TF-M & Regression tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| PsaApiTest | Library | 1 | No | No | No | Yes | TF-M & PSA API tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| PsaApiTestIPC | IPC | 1 | No | No | No | Yes | TF-M & PSA API tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| PsaApiTestIPCTfmLevel2 | IPC | 2 | No | No | No | Yes | TF-M & PSA API tests |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| DefaultProfileS | Library | 1 | No | No | No | No | TF-M Profile Small, |
+| | | | | | | | no tests [7]_ |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+| RegressionProfileS | Library | 1 | Yes | Yes | No | No | TF-M Profile Small & |
+| | | | | | | | Regression tests [7]_ |
++------------------------+------------+---------------+-----------------+----------------+---------------+-------------------+-------------------------+
+
+.. [1] Which TF-M Model is set: `CORE_IPC`. If `CORE_IPC` is set to true then the model is IPC model, otherwise it's library model.
+
+.. [2] The TF-M isolation level `TFM_LVL`. Currently Library model supports level 1. IPC model supports level 1 and 2.
+
+.. [3] Build regression tests or not: `REGRESSION`.
+
+.. [4] Build core tests or not: `CORE_TEST`.
+
+.. [5] Build IPC tests or not: `IPC_TEST`. It can be only enabled in IPC model
+
+.. [6] Build for PSA API compliance tests or not: `PSA_API_TEST`.
+
+.. [7] Profile Small config doesn't cover all the platforms. Please check
+ Profile Small config files to find out the supported platforms.
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_build_instruction_iar.rst b/docs/getting_started/tfm_build_instruction_iar.rst
new file mode 100644
index 0000000..b62d51d
--- /dev/null
+++ b/docs/getting_started/tfm_build_instruction_iar.rst
@@ -0,0 +1,82 @@
+###################################################
+Additional build instructions for the IAR toolchain
+###################################################
+
+Follow the instructions in
+:doc:`software requirements <tfm_build_instruction>`, but replace the -DCOMPILER= setting with IARARM.
+
+
+Notes for building with IARARM
+------------------------------
+
+ IAR Embedded Workbench for ARM (EWARM) versions 8.42 or later are required.
+
+ Currently the MUSCA_B1, MUSCA_S1 and SSE-200_AWS targets are not supported with IARARM,
+ due to lack of testing. The FVP_SSE300_MPS2 target is currently not supported by IARARM.
+
+ bash needs to be installed and used by cmake for the build steps.
+
+ 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. However 5.7.0 causes link errors and is currently unsupported in tf-m. Use
+ the 5.5.0 branch and replace the libraries in .../CMSIS_5/CMSIS/RTOS2/RTX/Library/IAR
+ with the ones from 5.7.0.
+
+ This will be sorted out once tf-m upgrades to use CMSIS_5 5.7.0 (or later)
+
+ 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.
+
+ Some minor changes to the mbed-crypto pack is required to allow building TF-M with the
+ IAR tools. This will be sorted out once tf-m upgrades to >3.1.0
+
+ For mbed-crypto (CMakeLists.txt):
+
+.. code-block:: bash
+
+ if(CMAKE_COMPILER_IS_IAR)
+ - set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts --warnings_are_errors -Ohz")
+ + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --warn_about_c_style_casts")
+ + set(CMAKE_C_FLAGS_RELEASE "-Ohz")
+ + set(CMAKE_C_FLAGS_DEBUG "--debug -On")
+ + set(CMAKE_C_FLAGS_CHECK "--warnings_are_errors")
+ endif(CMAKE_COMPILER_IS_IAR)
+
+
+Build steps:
+============
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_build
+ cd cmake_build
+ cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM
+ cmake --build ./ -- install
+
+Regression Tests for the AN521 target platform
+==============================================
+*TF-M build regression tests on Linux*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM ../
+ cmake --build ./ -- install
+
+*TF-M build regression tests on Windows*
+
+.. code-block:: bash
+
+ cd <TF-M base folder>
+ cd trusted-firmware-m
+ mkdir cmake_test
+ cd cmake_test
+ cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -am ../configs/ConfigRegression.cmake` -DTARGET_PLATFORM=AN521 -DCOMPILER=IARARM ../
+ cmake --build ./ -- install
+
+ *Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_integration_guide.rst b/docs/getting_started/tfm_integration_guide.rst
new file mode 100644
index 0000000..e4b56d1
--- /dev/null
+++ b/docs/getting_started/tfm_integration_guide.rst
@@ -0,0 +1,155 @@
+#################
+Integration guide
+#################
+The purpose of this document is to provide a guide on how to integrate TF-M
+with other hardware platforms and operating systems.
+
+*****************
+How to build TF-M
+*****************
+Follow the :doc:`Build instructions <tfm_build_instruction>`.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions <tfm_build_instruction>`.
+
+*************************
+How to add a new platform
+*************************
+The hardware platforms currently supported are:
+
+- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+- Arm SSE-123 Example Subsystem for MPS2+ (AN539)
+- Cortex-M55 SSE-300 subsystem for MPS2+ FVP
+- Musca-A test chip board (Cortex-M33 SSE-200 subsystem)
+- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
+- CoreLink SSE-200 Subsystem for MPS3 (AN524)
+- DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS)
+- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs)
+
+The files related to the supported platforms are contained under the
+``platform`` subfolder. The platform specific files are under
+``platform/ext/target``, which is organised by boards
+(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common``
+is used to store source and header files which are platform generic.
+
+More information about subsystems supported by the MPS2+ board can be found in:
+`MPS2+ homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps2>`__
+
+More information about the Musca-A test chip board can be found in:
+`Musca-A homepage <https://developer.arm.com/products/system-design/development-boards/iot-test-chips-and-boards/musca-a-test-chip-board>`__
+
+More information about the Musca-B1 test chip board can be found in:
+`Musca-B1 homepage <https://www.arm.com/products/development-tools/development-boards/musca-b1-iot>`__
+
+More information about the Musca-S1 test chip board can be found in:
+`Musca-S1 homepage <https://www.arm.com/company/news/2019/05/arm-demonstrates-new-iot-test-chip-and-board>`__
+
+More information about subsystems supported by the MPS3 board can be found in:
+`MPS3 homepage <https://www.arm.com/products/development-tools/development-boards/mps3>`__
+
+More information about the SSE-200_AWS platform can be found in:
+`SSE-200_AWS product page <https://aws.amazon.com/marketplace/pp/ARM-DesignStart-FPGA-on-Cloud-Cortex-M33-based-pla/B082DMMTLW>`__
+
+More information about the STM32L5xx platform can be found in:
+`STM32L5 series product page <https://www.st.com/content/st_com/en/products/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus/stm32-ultra-low-power-mcus/stm32l5-series.html>`__
+
+Generic drivers and startup/scatter files
+=========================================
+The addition of a new platform means the creation of a new subfolder inside
+``target/<board_name>`` to provide an implementation of the drivers currently
+used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the
+drivers, startup and scatter files need to be provided for the supported
+toolchains.
+
+There are also board specific drivers which are used by the board
+platform to interact with the external world, for example during tests, that
+have to be provided, e.g. to blink LEDs or count time in the MPS2 board.
+
+.. Note::
+
+ Currently ITS, PS and BL2 bootloader use different flash interface
+
+Target configuration files
+==========================
+Inside the base root folder of the selected target, each implementation has to
+provide its own copy of ``target_cfg.c/.h``. This file has target specific
+configuration functions and settings that are called by the TF-M during the
+platform configuration step during TF-M boot. Examples of the configurations
+performed during this phase are the MPC configuration, the SAU configuration,
+or eventually PPC configuration if supported by the hardware platform.
+Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect
+the stdout on UART (this is currently used by TF-M to log messages).
+
+Platform retarget files
+=======================
+An important part that each new platform has to provide is the set of retarget
+files which are contained inside the ``retarget`` folder. These files define the
+peripheral base addresses for the platform, both for the secure and non-secure
+aliases (when available), and bind those addresses to the base addresses used by
+the devices available in the hardware platform.
+
+***************************
+How to integrate another OS
+***************************
+To work with TF-M, the OS needs to support the Armv8-M architecture and, in
+particular, it needs to be able to run in the non-secure world. More
+information about OS migration to the Armv8-M architecture can be found in the
+:doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon the system
+configuration this may require configuring drivers to use appropriate address
+ranges.
+
+Interface with TF-M
+===================
+The files needed for the interface with TF-M are exported at the
+``<build_dir>/install/export/tfm`` path. The NS side is only allowed to call
+TF-M secure functions (veneers) from the NS Thread mode. For this reason, the
+API is a collection of functions in the ``<build_dir>/install/export/tfm/inc``
+directory. For example, the interface for the Protected Storage (PS) service
+is described in the file ``psa_ps_api.h`` as a collection of functions that
+call service veneer functions. This API is a wrapper for the secure veneers,
+and returns the return value from the service to the caller.
+
+The protected storage service uses a numerical ID, to identify the clients that
+use the service. For details see
+:doc:`ns client identification documentation <tfm_ns_client_identification>`.
+
+Interface with non-secure world regression tests
+================================================
+A non-secure application that wants to run the non-secure regression tests
+needs to call the ``tfm_non_secure_client_run_tests()``. This function is
+exported into the header file ``test_framework_integ_test.h`` inside the
+``<build_dir>/install`` folder structure in the test specific files,
+i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
+tests are precompiled and delivered as a static library which is available in
+``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
+needs to link against the library to be able to invoke the
+``tfm_non_secure_client_run_tests()`` function. The PS non-secure side
+regression tests rely on some OS functionality e.g. threads, mutexes etc. These
+functions comply with CMSIS RTOS2 standard and have been exported as thin
+wrappers defined in ``os_wrapper.h`` contained in
+``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
+implementation of these wrappers to be able to run the tests.
+
+NS client Identification
+========================
+See
+:doc:`ns client identification documentation <tfm_ns_client_identification>`.
+
+*********************
+Non-secure interrupts
+*********************
+Non-secure interrupts are allowed to preempt Secure thread mode.
+With the current implementation, a NSPE task can spoof the identity of another
+NSPE task. This is an issue only when NSPE has provisions for task isolation.
+Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
+to NS interrupts to the lower half of available priorities so that it wouldn't
+be possible for any non-secure interrupt to preempt a higher-priority secure
+interrupt.
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_ns_client_identification.rst b/docs/getting_started/tfm_ns_client_identification.rst
new file mode 100644
index 0000000..44fd343
--- /dev/null
+++ b/docs/getting_started/tfm_ns_client_identification.rst
@@ -0,0 +1,43 @@
+###########################
+Non-Secure Identity Manager
+###########################
+The ID of the current application/thread is known by TF-M, and the PS service
+queries the ID of the currently running client via a dedicated API.
+
+The identity of secure clients can be tracked by TF-M core, because it also
+manages the contexts of the partitions. However to differentiate NS clients, it
+relies on the services provided by the NS OS.
+
+Tracking of context changes are possible by relying on the NS OS calling the
+Thread Context Management for Armv8-M TrustZone APIs, as described
+`here <https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html>`__
+
+However TF-M needs an extra API, to assign a client ID to the TZ context created
+as a result of the
+``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call.
+
+To do this, the
+``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be
+called from an SVC handler, with the client ID of the currently running client.
+
+In the current implementation of TF-M, an SVC call is provided for the NS
+clients to be called at the beginning of their main function.
+
+``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``
+
+The SVC call handler of the above SVC maps the name of the current thread to a
+hardcoded client id, and sends it to the TF-M core via the earlier discussed
+API.
+
+The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``.
+
+The system integrators **may** implement the non-secure ID mapping based on
+their application/threat model.
+
+In case the NS OS doesn't use the Thread Context Management for Armv8-M
+TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
+client ID to it automatically.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_secure_boot.rst b/docs/getting_started/tfm_secure_boot.rst
new file mode 100644
index 0000000..39e3146
--- /dev/null
+++ b/docs/getting_started/tfm_secure_boot.rst
@@ -0,0 +1,792 @@
+###########
+Secure boot
+###########
+For secure devices it is security critical to enforce firmware authenticity to
+protect against execution of malicious software. This is implemented by building
+a trust chain where each step in the execution chain authenticates the next
+step before execution. The chain of trust in based on a "Root of Trust" which
+is implemented using asymmetric cryptography. The Root of Trust is a combination
+of an immutable bootloader and a public key (ROTPK).
+
+.. Warning::
+ In order to implement a proper chain of trust functionality, it is
+ mandatory that the first stage bootloader and ROTPK is stored in an
+ **immutable** way. To achieve this the bootloader code must be stored and
+ executed from ROM or such part of flash memory which supports write
+ protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If
+ the SoC has a built-in BL1 (immutable) bootloader and the immutability of
+ TF-M secure boot code is not guaranteed then TF-M secure boot code must be
+ authenticated by BL1 bootloader before execution. If immutability of root
+ of trust (first stage bootloader + ROTPK) is not ensured then there is a
+ risk that the secure boot process could be bypassed, which could lead to
+ arbitrary code execution on the device. Current TF-M secure boot code is
+ intended to be a second stage bootloader, therefore it requires
+ authentication before execution. If TF-M secure boot code is used as a first
+ stage bootloader then it must be stored according to the above requirements.
+
+*******************************
+Second stage bootloader in TF-M
+*******************************
+To implement secure boot functionality an external project MCUBoot has been
+integrated to TF-M. For further information please refer to the
+`MCUBoot homepage <https://www.mcuboot.com/>`__. Original source-code is
+available at `GitHub <https://github.com/JuulLabs-OSS/mcuboot>`__. This document
+contains information about MCUBoot modifications and how MCUBoot has been
+integrated to TF-M.
+
+Bootloader is started when CPU is released from reset. It runs in secure mode.
+It authenticates the firmware image by hash (SHA-256) and digital signature
+(RSA-3072) validation. Public key, that the checks happens against, can be built
+into the bootloader image or can be provisioned to the SoC during manufacturing.
+Metadata of the image is delivered together with the image itself in a header
+and trailer section. In case of successful authentication, bootloader passes
+execution to the secure image. Execution never returns to bootloader until
+next reset.
+
+A default RSA key pair is stored in the repository, public key is in ``keys.c``
+and private key is in ``root-rsa-3072.pem``.
+
+.. Warning::
+ DO NOT use them in production code, they are exclusively for testing!
+
+Private key must be stored in a safe place outside of the repository.
+``Imgtool.py`` can be used to generate new key pairs.
+
+The bootloader can handle the secure and non-secure images independently
+(multiple image boot) or together (single image boot). In case of multiple image
+boot they are signed independently with different keys and they can be updated
+separately. In case of single image boot the secure and non-secure image is
+handled as a single blob, therefore they must be contiguous in the device
+memory. In this case they are signed together and also they can be updated only
+together. In order to have the same artefacts at the end of the build regardless
+of how the images are handled (independently or together) the images are always
+concatenated. In case of single image boot they are concatenated first and then
+signed. In case of multiple image boot they are separately signed first and then
+concatenated. Preparation of payload is done by Python scripts:
+``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M
+payload can be found in: ``<build_dir>/install/outputs/fvp/tfm_sign.bin``
+
+*********************
+Integration with TF-M
+*********************
+MCUBoot assumes a predefined memory layout which is described below (applicable
+for AN521). It is mandatory to define the primary slot and the secondary slot
+partitions, but their size and location can be changed::
+
+ - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
+ - 0x0008_0000 - 0x000F_FFFF: Primary slot : Single binary blob:
+ Secure + Non-Secure image;
+ Primary memory partition
+ - 0x0008_0000 - 0x0008_03FF: Common image header
+ - 0x0008_0400 - 0x0008_xxxx: Secure image
+ - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
+ - 0x0010_0400 - 0x0010_xxxx: Non-secure image
+ - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of combined image
+
+ - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image;
+ Secondary memory partition, structured
+ identically to the primary slot
+ - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image
+ swapping
+
+Multiple image boot requires a slightly different layout::
+
+ - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
+ - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image
+ - 0x0008_0000 - 0x0008_03FF: Secure image header
+ - 0x0008_0400 - 0x000x_xxxx: Secure image
+ - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of secure image
+
+ - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image
+ - 0x0010_0000 - 0x0010_03FF: Non-secure image header
+ - 0x0010_0400 - 0x001x_xxxx: Non-secure image
+ - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of non-secure image
+
+ - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image
+ - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image
+
+ - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image
+ swapping, used for secure and non-secure
+ image as well
+
+**************************
+Firmware upgrade operation
+**************************
+MCUBoot handles only the firmware authenticity check after start-up and the
+firmware switch part of the firmware update process. Downloading the new version
+of the firmware is out-of-scope for MCUBoot. MCUBoot supports three different
+ways to switch to the new firmware and it is assumed that firmware images are
+executed-in-place (XIP). The default behaviour is the overwrite-based image
+upgrade. In this case the active firmware is always executed from the primary
+slot and the secondary slot is a staging area for new images. Before executing
+the new firmware image, the content of the primary slot must be overwritten with
+the content of the secondary slot (the new firmware image). The second option is
+the image swapping strategy when the content of the two memory slots must be
+physically swapped. This needs the scratch area to be defined in the memory
+layout. The third option is the non-swapping version, which eliminates the
+complexity of image swapping and its administration. Active image can be
+executed from either memory slot, but new firmware must be linked to the address
+space of the proper (currently inactive) memory slot.
+
+Overwrite operation
+===================
+Active image is stored in the primary slot, and this image is started always by
+the bootloader. Therefore images must be linked to the primary slot. If the
+bootloader finds a valid image in the secondary slot, which is marked for
+upgrade, then the content of the primary slot will be simply overwritten with
+the content of the secondary slot, before starting the new image from the
+primary slot. After the content of the primary slot has been successfully
+overwritten, the header and trailer of the new image in the secondary slot is
+erased to prevent the triggering of another unnecessary image upgrade after a
+restart. The overwrite operation is fail-safe and resistant to power-cut
+failures. For more details please refer to the MCUBoot
+`documentation <https://www.mcuboot.com/mcuboot/design.html>`__.
+
+Swapping operation
+==================
+This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
+switch (see `Build time configuration`_). With swapping image upgrade strategy
+the active image is also stored in the primary slot and it will always be
+started by the bootloader. If the bootloader finds a valid image in the
+secondary slot, which is marked for upgrade, then contents of the primary slot
+and the secondary slot will be swapped, before starting the new image from the
+primary slot. Scratch area is used as a temporary storage place during image
+swapping. Update mark from the secondary slot is removed when the swapping is
+successful. The boot loader can revert the swapping as a fall-back mechanism to
+recover the previous working firmware version after a faulty update. The swap
+operation is fail-safe and resistant to power-cut failures. For more details
+please refer to the MCUBoot
+`documentation <https://www.mcuboot.com/mcuboot/design.html>`__.
+
+.. Note::
+
+ After a successful image upgrade the firmware can mark itself as "OK" at
+ runtime by setting the image_ok flag in the flash. When this happens, the
+ swap is made "permanent" and MCUBoot will then still choose to run it
+ during the next boot. Currently TF-M does not set the image_ok flag,
+ therefore the bootloader will always perform a "revert" (swap the images
+ back) during the next boot.
+
+Non-swapping operation
+======================
+This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
+switch (see `Build time configuration`_). When enabling non-swapping operation
+then the active image flag is moved between slots during firmware upgrade. If
+firmware is executed-in-place (XIP), then two firmware images must be generated.
+One of them is linked to be executed from the primary slot memory region and the
+other from the secondary slot. The firmware upgrade client, which downloads the
+new image, must be aware, which slot hosts the active firmware and which acts as
+a staging area and it is responsible for downloading the proper firmware image.
+At boot time MCUBoot inspects the version number in the image header and passes
+execution to the newer firmware version. New image must be marked for upgrade
+which is automatically done by Python scripts at compile time. Image
+verification is done the same way in all operational modes. If new image fails
+during authentication then MCUBoot erases the memory slot and starts the other
+image, after successful authentication.
+
+At build time automatically two binaries are generated::
+
+ <build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin : Image linked for the primary slot memory partition
+
+ <build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin : Image linked for the secondary slot memory partition
+
+.. Note::
+
+ Only single image boot is supported with non-swapping upgrade mode.
+
+RAM Loading firmware upgrade
+============================
+Musca-A supports an image upgrade mode that is separate to the other (overwrite,
+swapping and non-swapping) modes. This is the ``RAM loading`` mode (please refer
+to the table below). Like the non-swapping mode, this selects the newest image
+by reading the image version numbers in the image headers, but instead of
+executing it in place, the newest image is copied to RAM for execution. The load
+address, the location in RAM where the image is copied to, is stored in the
+image header.
+
+.. Note::
+
+ Only single image boot is supported with RAM loading upgrade mode.
+
+Summary of different modes for image upgrade
+============================================
+Different implementations of the image upgrade operation (whether through
+overwriting, swapping, non-swapping or loading into RAM and executing from
+there) are supported by the platforms. The table below shows which of these
+modes are supported by which platforms:
+
++---------------------+-----------------+----------------------------------------------------------+
+| | Without BL2 [1]_| With BL2 [2]_ |
++=====================+=================+===============+==========+=============+=================+
+| | XIP | XIP | XIP | XIP | Not XIP |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| | | Overwrite [3]_| Swap [4]_| No-swap [5]_| RAM loading [6]_|
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| AN521 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| AN519 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| AN539 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| FVP_SSE300_MPS2 | NO | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| LPC55S69 | No | No | No | No | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| Musca-A | No | No | No | No | Yes |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| Musca-B1 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| Musca-S1 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| AN524 | Yes | No | No | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| PSoC64 | Yes | No | No | No | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| SSE-200_AWS | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| STM_DISCO_L562QE | No | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+-------------+-----------------+
+
+.. [1] To disable BL2, please turn off the ``BL2`` compiler switch in the
+ build configuration file (``bl2/ext/mcuboot/MCUBootConfig.cmake``) or
+ in the command line
+
+.. [2] BL2 is enabled by default
+
+.. [3] The image executes in-place (XIP) and is in Overwrite mode for image
+ update by default
+
+.. [4] To enable XIP Swap mode, assign the "SWAP" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+.. [5] To enable XIP No-swap, assign the "NO_SWAP" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+.. [6] To enable RAM loading, assign the "RAM_LOADING" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+**************************
+Using the original MCUBoot
+**************************
+The original MCUBoot from `GitHub <https://github.com/JuulLabs-OSS/mcuboot>`__
+can also be used as the bootloader in TF-M. However please note that the
+original MCUBoot doesn't support the ``No-swap`` and ``RAM loading`` upgrade
+strategies, therefore those platforms that doesn't support other upgrade
+strategies (e.g. ``Overwrite``) cannot be used with the original MCUBoot at the
+moment.
+
+To use the upstream MCUBoot it must be cloned into the TF-M base folder
+first (into which the TF-M was cloned previously). After the original MCUBoot
+code is present at the required location the ``MCUBOOT_REPO=UPSTREAM`` option
+must be added to the command line at the CMake configuration step::
+
+ cd <TF-M base folder>
+ git clone https://github.com/JuulLabs-OSS/mcuboot.git -b v1.5.0
+ cd <TF-M build folder>
+ cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DMCUBOOT_REPO=UPSTREAM ../
+
+*******************
+Multiple image boot
+*******************
+It is possible to update the firmware images independently to support the
+scenario when secure and non-secure images are provided by different vendors.
+Multiple image boot is supported only together with the overwrite and swap
+firmware upgrade modes.
+
+It is possible to describe the dependencies of the images on each other in
+order to avoid a faulty upgrade when incompatible versions would be installed.
+These dependencies are part of the image manifest area.
+The dependencies are composed from two parts:
+
+ - **Image identifier:** The number of the image which the current image (whose
+ manifest area contains the dependency entry) depends on. The image identifier
+ starts from 0.
+
+ - **Minimum version:** The minimum version of other image must be present on
+ the device by the end of the upgrade (both images might be updated at the
+ same time).
+
+Dependencies can be added to the images at compile time with the following
+compile time switches:
+
+ - ``S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
+ minimum required version of the secure image.
+ - ``NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the
+ minimum required version of the non-secure image.
+
+Example of how to provide the secure image minimum version::
+
+ cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DS_IMAGE_MIN_VER=1.2.3+4 ../
+
+********************
+Signature algorithms
+********************
+MbedTLS library is used to sign the images. The list of supported signing
+algorithms:
+
+ - `RSA-2048`
+ - `RSA-3072`: default
+
+Example keys stored in:
+
+ - ``root-rsa-2048.pem`` : Used to sign single image (S+NS) or secure image
+ in case of multiple image boot
+ - ``root-rsa-2048_1.pem`` : Used to sign non-secure image in case of multiple
+ image boot
+ - ``root-rsa-3072.pem`` : Used to sign single image (S+NS) or secure image
+ in case of multiple image boot
+ - ``root-rsa-3072_1.pem`` : Used to sign non-secure image in case of multiple
+ image boot
+
+************************
+Build time configuration
+************************
+MCUBoot related compile time switches can be set in the build configuration
+file::
+
+ bl2/ext/mcuboot/MCUBootConfig.cmake
+
+Compile time switches:
+
+- BL2 (default: True):
+ - **True:** TF-M built together with bootloader. MCUBoot is executed after
+ reset and it authenticates TF-M and starts secure code.
+ - **False:** TF-M built without bootloader. Secure image linked to the
+ beginning of the device memory and executed after reset. If it is false
+ then using any of the further compile time switches is invalid.
+- MCUBOOT_REPO (default: "TF-M"):
+ - **"TF-M":** Use TF-M's MCUBoot fork as bootloader which is located in the
+ bl2/ext/mcuboot folder.
+ - **"UPSTREAM":** Use the original (upstream) MCUBoot as bootloader. Before
+ selecting this option please read the `Using the original MCUBoot`_
+ section for more information and the limitations of using this option.
+- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"):
+ - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite.
+ - **"SWAP":** Activate swapping firmware upgrade operation.
+ - **"NO_SWAP":** Activate non-swapping firmware upgrade operation.
+ - **"RAM_LOADING":** Activate RAM loading firmware upgrade operation, where
+ the latest image is copied to RAM and runs from there instead of being
+ executed in-place.
+- MCUBOOT_SIGNATURE_TYPE (default: RSA-3072):
+ - **RSA-3072:** Image is signed with RSA-3072 algorithm
+ - **RSA-2048:** Image is signed with RSA-2048 algorithm
+- MCUBOOT_IMAGE_NUMBER (default: 2):
+ - **1:** Single image boot, secure and non-secure images are signed and
+ updated together.
+ - **2:** Multiple image boot, secure and non-secure images are signed and
+ updatable independently.
+- MCUBOOT_HW_KEY (default: True):
+ - **True:** The hash of public key is provisioned to the SoC and the image
+ manifest contains the whole public key. MCUBoot validates the key before
+ using it for firmware authentication, it calculates the hash of public key
+ from the manifest and compare against the retrieved key-hash from the
+ hardware. This way MCUBoot is independent from the public key(s).
+ Key(s) can be provisioned any time and by different parties.
+ - **False:** The whole public key is embedded to the bootloader code and the
+ image manifest contains only the hash of the public key. MCUBoot validates
+ the key before using it for firmware authentication, it calculates the
+ hash of built-in public key and compare against the retrieved key-hash
+ from the image manifest. After this the bootloader can verify that the
+ image was signed with a private key that corresponds to the retrieved
+ key-hash (it can have more public keys embedded in and it may have to look
+ for the matching one). All the public key(s) must be known at MCUBoot
+ build time.
+- MCUBOOT_LOG_LEVEL:
+ Can be used to configure the level of logging in MCUBoot. The possible
+ values are the following:
+
+ - **LOG_LEVEL_OFF**
+ - **LOG_LEVEL_ERROR**
+ - **LOG_LEVEL_WARNING**
+ - **LOG_LEVEL_INFO**
+ - **LOG_LEVEL_DEBUG**
+
+ The logging in MCUBoot can be disabled and thus the code size can be reduced
+ by setting it to ``LOG_LEVEL_OFF``. Its value depends on the build type. If
+ the build type is ``Debug`` and a value has been provided (e.g. through the
+ command line or the CMake GUI) then that value will be used, otherwise it is
+ ``LOG_LEVEL_INFO`` by default. In case of different kinds of ``Release``
+ builds its value is set to ``LOG_LEVEL_OFF`` (any other value will be
+ overridden).
+
+Image versioning
+================
+An image version number is written to its header by one of the Python scripts,
+and this number is used by the bootloader when the non-swapping or RAM loading
+mode is enabled. It is also used in case of multiple image boot when the
+bootloader checks the image dependencies if any have been added to the images.
+
+The version number of the image (single image boot) can manually be passed in
+through the command line in the cmake configuration step::
+
+ cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DIMAGE_VERSION=1.2.3+4 ../
+
+Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
+where the missing numbers are automatically set to zero. The image version
+number argument is optional, and if it is left out, then the version numbers of
+the image(s) being built in the same directory will automatically change. In
+this case, the last component (the build number) automatically increments from
+the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
+**until a number is explicitly provided**. If automatic versioning is in place
+and then an image version number is provided for the first time, the new number
+will take precedence and be used instead. All subsequent image versions are
+then set to the last number that has been specified, and the build number would
+stop incrementing. Any new version numbers that are provided will overwrite
+the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
+versioning, please start a clean build without specifying the image version
+number at all. In case of multiple image boot there are separate compile time
+switches for both images to provide their version: ``IMAGE_VERSION_S`` and
+``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION``.
+
+Security counter
+================
+Each signed image contains a security counter in its manifest. It is used by the
+bootloader and its aim is to have an independent (from the image version)
+counter to ensure rollback protection by comparing the new image's security
+counter against the original (currently active) image's security counter during
+the image upgrade process. It is added to the manifest (to the TLV area that is
+appended to the end of the image) by one of the Python scripts when signing the
+image. The value of the security counter is security critical data and it is in
+the integrity protected part of the image. The last valid security counter
+should always be stored in a non-volatile and trusted component of the device
+and its value should always be increased if a security flaw was fixed in the
+current image version. The value of the security counter (single image boot) can
+be specified at build time in the cmake configuration step::
+
+ cmake -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG -DSECURITY_COUNTER=42 ../
+
+The security counter can be independent from the image version, but not
+necessarily. Alternatively, if it is not specified at build time with the
+``SECURITY_COUNTER`` option the Python script will automatically generate it
+from the image version number (not including the build number) and this value
+will be added to the signed image. In case of multiple image boot there are
+separate compile time switches for both images to provide their security counter
+value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used
+instead of ``SECURITY_COUNTER``. If these are not defined then the security
+counter values will be derived from the corresponding image version similar to
+the single image boot.
+
+***************************
+Signing the images manually
+***************************
+Normally the build system handles the signing (computing hash over the image
+and security critical manifest data and then signing the hash) of the firmware
+images. However, the images also can be signed manually by using the ``imgtool``
+Python program which is located in the ``bl2/ext/mcuboot/scripts`` directory.
+Issue the ``python3 imgtool.py sign --help`` command in the directory for more
+information about the mandatory and optional arguments. The tool takes an image
+in binary or Intel Hex format and adds a header and trailer that MCUBoot is
+expecting. In case of single image boot after a successful build the
+``tfm_full.bin`` build artifact (contains the concatenated secure and non-secure
+images) must be passed to the script and in case of multiple image boot the
+``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed
+images.
+
+Signing the secure image manually in case of multiple image boot
+================================================================
+
+::
+
+ python3 bl2/ext/mcuboot/scripts/imgtool.py sign \
+ --layout <build_dir>/image_macros_preprocessed_s.c \
+ -k <tfm_dir>/bl2/ext/mcuboot/root-rsa-3072.pem \
+ --public-key-format full \
+ --align 1 \
+ -v 1.2.3+4 \
+ -d "(1,1.2.3+0)" \
+ -s 42 \
+ -H 0x400 \
+ <build_dir>/install/outputs/AN521/tfm_s.bin \
+ <build_dir>/tfm_s_signed.bin
+
+************************
+Testing firmware upgrade
+************************
+As downloading the new firmware image is out of scope for MCUBoot, the update
+process is started from a state where the original and the new image are already
+programmed to the appropriate memory slots. To generate the original and a new
+firmware package, TF-M is built twice with different build configurations.
+
+Overwriting firmware upgrade
+============================
+Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases
+(single image boot), but with two different build configurations: default and
+regression. Save the artifacts between builds, because second run can overwrite
+original binaries. Download default build to the primary slot and regression
+build to the secondary slot.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+.. code-block:: bash
+
+ <DS5_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>/bl2/ext/mcuboot/mcuboot.axf \
+ --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
+
+The following message will be shown in case of successful firmware upgrade:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Swap type: test
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x100000 bytes
+ [INF] Bootloader chainload address offset: 0x80000
+ [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)...
+ ...
+
+To update the secure and non-secure images separately (multiple image boot),
+set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default
+configuration value) and follow the same instructions as in case of single image
+boot.
+
+Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board
+------------------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 4 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image
+ IMAGE3ADDRESS: 0x10200000
+ IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image
+
+Note that both the concatenated binary blob (the images are signed separately
+and then concatenated) and the separate signed images can be downloaded to the
+device because on this platform (AN521) both the primary slots and the secondary
+slots are contiguous areas in the Flash (see `Integration with TF-M`_). The
+following message will be shown in case of successful firmware upgrades:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Swap type: test
+ [INF] Swap type: test
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+ TFM level is: 1
+ [Sec Thread] Jumping to non-secure code...
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ ...
+
+Swapping firmware upgrade
+=============================
+Follow the same instructions and platform related configurations as in case of
+overwriting build including these changes:
+
+- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP"
+ before build.
+- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image
+ boot) or "2" (multiple image boot) before build.
+
+During single image boot the following message will be shown in case of
+successful firmware upgrade, ``Swap type: test`` indicates that images were
+swapped:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3
+ [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2
+ [INF] Boot source: primary slot
+ [INF] Swap type: test
+ [INF] Bootloader chainload address offset: 0x80000
+ [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)...
+ ...
+
+Non-swapping firmware upgrade
+=============================
+Follow the same instructions and platform related configurations as in case of
+overwriting build including these changes:
+
+- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "NO_SWAP"
+ before build.
+- Make sure the image version number was increased between the two build runs
+ either by specifying it manually or by checking in the build log that it was
+ incremented automatically.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+
+.. code-block:: bash
+
+ <DS5_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>/bl2/ext/mcuboot/mcuboot.axf \
+ --data cpu0=<default_build_dir>/install/outputs/fvp/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=<regresssion_build_dir>/install/outputs/fvp/tfm_s_ns_signed_1.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\mcuboot.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
+
+Executing firmware upgrade on Musca-B1 and Musca-S1 boards
+----------------------------------------------------------
+After the two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+- Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade,
+notice that image with higher version number (``version=1.2.3.5``) is executed:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: version=1.2.3.4, magic= good, image_ok=0x3
+ [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3
+ [INF] Booting image from the secondary slot
+ [INF] Bootloader chainload address offset: 0xa0000
+ [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 firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524)
+-------------------------------------------------------------------------
+
+::
+
+ TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
+
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+
+ IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \SOFTWARE\mcuboot.bin ;BL2 bootloader
+ IMAGE1UPDATE: AUTO
+ IMAGE1ADDRESS: 0x00040000
+ IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob
+ IMAGE2UPDATE: AUTO
+ IMAGE2ADDRESS: 0x000C0000
+ IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob
+
+RAM loading firmware upgrade
+============================
+To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOADING"
+(either in the configuration file or through the command line), and then specify
+a destination load address in RAM where the image can be copied to and executed
+from. The ``IMAGE_LOAD_ADDRESS`` macro must be specified in the target dependent
+files, for example with Musca-A, its ``flash_layout.h`` file in the ``platform``
+folder should include ``#define IMAGE_LOAD_ADDRESS #0x10020000``
+
+Executing firmware upgrade on Musca-A board
+--------------------------------------------
+After two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux::
+
+ srec_cat bl2/ext/mcuboot/mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
+
+- Windows::
+
+ srec_cat.exe bl2\ext\mcuboot\mcuboot.bin -Binary -offset 0x200000 tfm_sign_old.bin -Binary -offset 0x220000 tfm_sign_new.bin -Binary -offset 0x320000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade when,
+RAM loading is enabled, notice that image with higher version number
+(``version=0.0.0.2``) is executed:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3
+ [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3
+ [INF] Image has been copied from the secondary slot in flash to SRAM address 0x10020000
+ [INF] Booting image from SRAM at address 0x10020000
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_secure_irq_handling.rst b/docs/getting_started/tfm_secure_irq_handling.rst
new file mode 100644
index 0000000..bde9a25
--- /dev/null
+++ b/docs/getting_started/tfm_secure_irq_handling.rst
@@ -0,0 +1,175 @@
+###################
+Secure IRQ handling
+###################
+
+The Armv8-M Architecture makes it possible to configure interrupts to target
+secure state.
+
+TF-M makes it possible for secure partitions to get notified of secure
+interrupts.
+
+By default TF-M sets up interrupts to target NS state. To configure an interrupt
+to target secure state and assign a handler to it, the manifest of the partition
+must be edited.
+
+See the following example:
+
+
+.. code-block:: yaml
+
+ {
+ "name": "...",
+ "type": "...",
+ "priority": "...",
+
+ ...
+
+ "irqs": [
+ {
+ "source": "5",
+ "signal": "DUAL_TIMER"
+ },
+ {
+ "source": "TFM_IRQ_LINE_TIMER_1",
+ "signal": "TIMER_1"
+ "tfm_irq_priority": 64,
+ }
+ ],
+
+ ...
+
+ }
+
+To set up a handler in a partition, the ``irqs`` node must be added. A single
+secure partition can have handlers registered for multiple IRQs, in this case
+the list ``irqs`` has multiple elements in it.
+
+An IRQ handler is defined by the following nodes:
+
+- ``source``: The IRQ number or the name IRQ line. With the name of the IRQ
+ line, there must be defined a macro in ``tfm_peripherals_def.h`` which is
+ substituted to the IRQ line num.
+- ``signal`` The name of the signal for this IRQ
+- ``tfm_irq_priority``: The priority of the IRQ. This number must be in the
+ range [0-255] inclusive. Please note that some of the less significant bits of
+ this value might be dropped based on the number of priority bits implemented
+ in the platform.
+
+.. important::
+
+ The name of the privileged interrupt handler is derived from the node
+ specifying the IRQ line number.
+
+ - In case ``source`` is IRQ number, the name of the handler becomes
+ ``void irq_<number>_Handler(void)``.
+ - In case ``source`` is defined IRQ macro, the name of the handler becomes
+ ``void <macro>_Handler(void)``.
+
+ This is important, because the derived name have to be present in the vector
+ table as the handler of the IRQ.
+
+.. Note::
+
+ ``signal`` and ``source`` are mandatory.
+
+ ``tfm_irq_priority`` is optional. If ``tfm_irq_priority`` is not set for an
+ IRQ, the default is value is ``TFM_DEFAULT_SECURE_IRQ_PRIOTITY``.
+
+If an IRQ handler is registered, TF-M will:
+
+- Set the IRQ with number or macro to target secure state
+- Set the priority of IRQ with number or macro to ``tfm_irq_priority`` or to
+ the default.
+
+TF-M configures the interrupt lines to be disabled by default. Interrupts for a
+service can be enabled by the secure service by calling
+``void tfm_enable_irq(psa_signal_t irq_signal)``. The function can be called in
+the service init function.
+
+Library model
+=============
+
+In Library model a function with the name derived from the value of the
+``source`` property is generated. This function will be put in the vector table
+by the linker (as the handlers in the startup assembly are defined as weak
+symbols). The code generated for this function will forward the call to the
+function with the name of the value of the ``signal`` property post-fixed with
+``_isr``.
+
+.. hint::
+
+ for a signal ``"signal": "DUAL_TIMER"`` the name of the handler function is
+ ``DUAL_TIMER_isr``
+
+The signature of the IRQ handler in the partition must be the following:
+
+.. code-block:: c
+
+ void partition_irq_handler(void);
+
+The detailed description on how secure interrupt handling works in the Library
+model see
+`Secure Partition Interrupt Handling design document <https://developer.trustedfirmware.org/w/tf_m/design/secure_partition_interrupt_handling/>`_.
+
+IPC model
+=========
+
+The detailed description on how secure interrupt handling works in the IPC
+model, see the
+`PSA Firmware Framework and RoT Services specification <https://pages.arm.com/psa-resources-ff.html>`_.
+
+**********************
+Implementation details
+**********************
+
+Library model implementation
+============================
+
+As a result of the function call like behaviour of secure services in library
+model, some information that is critical for the SPM to keep track of partition
+states, is stored on the stack of the active partitions. When an interrupt
+happens, and a handler partition is set to running state, it has access to its
+whole stack, and could corrupt the data stacked by the SPM. To prevent this, a
+separate Context stack is introduced for each secure partition, that is used by
+the SPM to save this information before starting to execute secure partition
+code.
+
+A stack frame to this context stack is pushed when the execution in the
+partition is interrupted, and when a handler in the partition interrupts another
+service. So the maximal stack usage can happen in the following situation:
+
+Consider secure partition 'A'. 'A' is running, and then it is interrupted by
+an other partition. Then the lowest priority interrupt of 'A' is triggered.
+Then before the handler returns, the partition is interrupted by another
+partition's handler. Then before the running handler returns, the second
+lowest interrupt of 'A' is triggered. This can go until the highest priority
+interrupt of 'A' is triggered, and then this last handler is interrupted. At
+this point the context stack looks like this:
+
+.. code-block::
+
+ +------------+
+ | [intr_ctx] |
+ | [hndl_ctx] |
+ | . |
+ | . |
+ | . |
+ | [intr_ctx] |
+ | [hndl_ctx] |
+ | [intr_ctx] |
+ +------------+
+
+ Legend:
+ [intr_ctx]: Frame pushed when the partition is interrupted
+ [hndl_ctx]: Frame pushed when the partition is handling an interrupt
+
+So the max stack size can be calculated as a function of the IRQ count of 'A':
+
+.. code-block::
+
+
+ max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size))
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst
new file mode 100644
index 0000000..2c3d555
--- /dev/null
+++ b/docs/getting_started/tfm_sw_requirement.rst
@@ -0,0 +1,566 @@
+#####################
+Software requirements
+#####################
+
+.. |DS5_VERSION| replace:: v5.29.1
+.. |KEIL_VERSION| replace:: v5.25.2
+.. |DEV_STUDIO_VERSION| replace:: 2018.0
+
+A quick reference table is included in the
+:ref:`docs/getting_started/tfm_sw_requirement:Tool & Dependency overview` section
+of this document.
+
+****************************
+Supported build environments
+****************************
+
+TF-M officially supports a limited set of build environments and setups. In
+this context, official support means that the environments listed below
+are actively used by team members and active developers hence users should
+be able to recreate the same configurations by following the instructions
+described below. In case of problems, the TF-M team provides support
+only for these environments, but building in other environments can still be
+possible.
+
+The following environments are supported:
+
+ - Ubuntu 16.04 x64
+ - Ubuntu 18.04 x64
+ - Windows 10 x64 + git-bash (MinGW) + gnumake from DS-5 or msys2.
+ - Windows 10 x64 + Cygwin x64 (example configuration is provided for
+ this Windows setup only).
+
+.. note::
+ Some tools (i.e. python3 and CMake) must NOT be installed from
+ Cygwin and instead a native windows version is needed. Please see the
+ chapter `Windows + Cygwin setup`_ below.
+
+*********************
+Supported C compilers
+*********************
+
+To compile TF-M code, at least one of the supported compiler toolchains have to
+be available in the build environment. The currently supported compiler
+versions are:
+
+ - Arm Compiler v6.10
+ - Arm Compiler v6.11
+ - Arm Compiler v6.12
+ - Arm Compiler v6.13
+ - GNU Arm compiler v6.3.1
+ - GNU Arm compiler v7.3
+
+.. Note::
+ - The Arm compilers above are provided via Keil uVision |KEIL_VERSION|
+ or greater, DS-5 |DS5_VERSION| or greater, and Development Studio
+ |DEV_STUDIO_VERSION| or greater, or they can be downloaded as standalone
+ packages from
+ `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__.
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+ - The GNU Arm compiler can be downloaded from
+ `here <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`__.
+ On the page select *GNU Arm Embedded Toolchain: 6-2017-q1-update*
+ or *GNU Arm Embedded Toolchain: 7-2018-q2-update*
+
+************************
+Supported CMake versions
+************************
+
+The build-system is CMake based and supports the following versions:
+
+ - 3.7
+ - 3.10
+ - 3.11
+ - 3.12
+ - 3.13
+ - 3.14
+
+.. Note::
+ - Please use the latest build version available (i.e. 3.7.2 instead of
+ 3.7.0).
+ While it is preferable to use the newest version this is not required
+ and any version from the above list should work.
+ - Recent versions of CMake can be downloaded from
+ https://cmake.org/download/, and older releases are available from
+ https://cmake.org/files.
+ - For Cygwin users, please use a native windows CMake version
+ instead of the version installed with Cygwin.
+
+***************************
+Supported GNU make versions
+***************************
+
+The TF-M team builds using the "Unix Makefiles" generator of CMake and
+thus GNU make is needed for the build. On Linux please use the version
+available from the official repository of your distribution.
+
+On Windows the following binaries are supported:
+
+ - GNU make v4.2.1 executable from Cygwin
+ - GNU make v4.2.1 executable from msys2
+ - GNU make v4.2 executable from DS5 |DS5_VERSION| (see <DS5 directory>/bin)
+
+CMake is quiet tolerant to GNU make versions and basically any
+"reasonably recent" GNU make version shall work.
+
+CMake generators other than "Unix Makefiles" may work, but are not
+officially supported.
+
+*********************
+External dependencies
+*********************
+
+In order to build TF-M the following external projects are required:
+
+ - `Mbed Crypto library <https://github.com/ARMmbed/mbed-crypto>`__ v3.0.1
+ is used as crypto library on the secure side
+ - `CMSIS Version 5 <https://github.com/ARM-software/CMSIS_5>`__ v5.5.0
+ is used to import RTX for the example non-secure app
+
+Each of the listed dependencies should be placed in a common root directory
+with trustedfirmware-m
+
+.. code-block:: bash
+
+ .
+ ├── CMSIS_5
+ ├── mbed-crypto
+ └── trusted-firmware-m
+
+.. Note::
+ `CMSIS_5` v5.5.0 has a known issue, affecting compilation using
+ Arm Compiler v6.10. Please refer to
+ `CMSIS release notes <https://github.com/ARM-software/CMSIS_5/releases>`__.
+ for guidance.
+
+********************************************
+Tools for configuring and programming boards
+********************************************
+
+For stm32l5xx boards, `STM32_Programmer_CLI <https://www.st.com/en/development-tools/stm32cubeprog.html>`__
+is used to configure security protections and to write the code in internal flash.
+A version is available for Linux and Windows host machine.
+
+**************
+Example setups
+**************
+
+This section lists dependencies and some exact and tested steps to set-up a
+TF-M-m build environment under various OSes.
+
+Ubuntu setup
+============
+
+Install the following tools:
+
+- DS-5 |DS5_VERSION|.
+- Git tools v2.10.0
+- Git Large File Storage (git-lfs)
+- CMake (see the "Supported CMake versions" chapter)
+- GNU Make (see the "Supported make versions" chapter)
+- Python3 and the pip package manager (from Python 3.4 it's included)
+- Python3 packages: *cryptography, pyasn1, yaml, jinja2 v2.10, cbor v1.0.0*
+
+ .. code-block:: bash
+
+ pip3 install --user cryptography pyasn1 pyyaml jinja2 cbor
+
+- SRecord v1.58 (for Musca test chip boards)
+
+Setup a shell to enable compiler toolchain and CMake after installation.
+------------------------------------------------------------------------
+
+To import Arm Compiler v6.10 in your bash shell console:
+
+.. Warning::
+ Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH=<DS-5_PATH>/sw/ARMCompiler6.10/bin:$PATH
+ export ARM_TOOL_VARIANT=ult
+ export ARM_PRODUCT_PATH=<DS-5_PATH>/sw/mappings
+ export ARMLMD_LICENSE_FILE=<LICENSE_FILE_PATH>
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+To import GNU Arm in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/bin:$PATH
+
+Windows + Cygwin setup
+======================
+
+Install the following tools:
+
+- uVision |KEIL_VERSION| or DS-5 |DS5_VERSION| (DS-5 Ultimate Edition) which
+ provides the Arm Compiler v6.10 compiler or GNU Arm compiler v6.3.1.
+- Git client latest version (https://git-scm.com/download/win)
+- Git Large File Storage (`native Windows version <https://git-lfs.github.com/>`__,
+- CMake (`native Windows version <https://cmake.org/download/>`__,
+ see the `Supported CMake versions`_ chapter)
+- `Cygwin <https://www.cygwin.com/>`__. Tests done with version 2.877
+ (64 bits)
+- GNU make should be installed by selecting appropriate package during
+ cygwin
+ installation.
+- Python3 `(native Windows version) <https://www.python.org/downloads/>`__ and
+ the pip package manager (from Python 3.4 it's included)
+- Python3 packages: *cryptography, pyasn1, yaml, jinja2 v2.10, cbor v1.0.0*
+
+ .. code-block:: bash
+
+ pip3 install --user cryptography pyasn1 pyyaml jinja2 cbor
+
+- `SRecord v1.63 <https://sourceforge.net/projects/srecord/>`__ (for Musca test
+ chip boards)
+
+Setup Cygwin to enable a compiler toolchain and CMake after installation.
+-------------------------------------------------------------------------
+
+If applicable, import Arm Compiler v6.10 in your shell console. To make this
+change permanent, add the command line into ~/.bashrc
+
+Armclang + DS-5
+^^^^^^^^^^^^^^^
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based on
+ specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+ - Arm licensing related environment variables must use Windows paths, and not
+ the Cygwin specific one relative to */cygrive*.
+
+.. code-block:: bash
+
+ export PATH=/cygdrive/c/<DS-5_PATH>/sw/ARMCompiler6.10/bin:$PATH
+ export ARM_PRODUCT_PATH=C:/<DS-5_PATH>/sw/mappings
+ export ARM_TOOL_VARIANT=ult
+ export ARMLMD_LICENSE_FILE=<LICENSE_FILE_PATH>
+
+Armclang + Keil MDK Arm
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. Note::
+
+ - Arm compiler specific environment variable may need updating based
+ on specific products and licenses as explained in
+ `product-and-toolkit-configuration <https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration>`__.
+
+.. code-block:: bash
+
+ export PATH=/cygdrive/c/<uVision path>/ARM/ARMCLANG/bin:$PATH
+
+GNU Arm
+^^^^^^^
+
+If applicable, import GNU Arm compiler v6.3.1 in your shell console. To make
+this change permanent, add the command line into ~/.bashrc
+
+.. code-block:: bash
+
+ export PATH=<GNU Arm path>/bin:$PATH
+
+CMake
+^^^^^
+
+To import CMake in your bash shell console:
+
+.. code-block:: bash
+
+ export PATH=/cygdrive/c/<CMake path>/bin:$PATH
+
+Building the documentation
+==========================
+
+The build system is prepared to support generation of two documents.
+The Reference Manual which is Doxygen based, and the User Guide which is
+Sphinx based. Both document can be generated in HTML and PDF format.
+
+.. Note::
+
+ Support for document generation in the build environment is not mandatory.
+ Missing document generation tools will not block building the TF-M
+ firmware.
+
+To compile the TF-M Reference Manual
+------------------------------------
+
+The following additional tools are needed:
+
+ - Doxygen v1.8.0 or later
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen graphviz default-jre
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+For PDF generation:
+
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen-latex
+
+Windows + Cygwin
+""""""""""""""""
+
+Download and install the following tools:
+ - `Doxygen
+ 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
+ - `Graphviz
+ 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+ - `MikTeX <https://miktex.org/download>`__
+
+ .. Note::
+ When building the documentation the first time, MikTeX might prompt for
+ installing missing LaTeX components. Please allow the MikTeX package
+ manager to set-up these.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+::
+
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from DS5 installation.
+
+::
+
+ export PLANTUML_JAR_PATH=c:/plantuml/plantuml.jar
+ export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+
+To compile the TF-M User Guide
+------------------------------
+
+The following additional tools are needed:
+
+ - Python3 and the following modules:
+ - Sphinx v1.7.9
+ - m2r v0.2.0
+ - sphinxcontrib-plantuml
+ - sphinx-rtd-theme
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+
+For PDF generation the following tools are needed in addition to the
+above list:
+
+ - LaTeX
+ - PdfLaTeX
+
+Set-up the needed tools
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+
+.. code-block:: bash
+
+ sudo apt-get install -y python3 graphviz default-jre
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+For PDF generation:
+
+.. code-block:: bash
+
+ sudo apt-get install -y doxygen-latex
+
+Windows + Cygwin
+""""""""""""""""
+Download and install the following tools:
+ - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
+ - Pip packages *m2r, Sphinx, sphinx-rtd-theme sphinxcontrib-plantuml*
+
+ .. code-block:: bash
+
+ pip --user install m2r Sphinx sphinx-rtd-theme sphinxcontrib-plantuml
+
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the DS5 installation or can be
+ `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+For PDF generation:
+
+- `MikTeX <https://miktex.org/download>`__
+
+.. Note::
+ When building the documentation the first time, MikTeX might
+ prompt for installing missing LaTeX components. Please allow the MikTeX
+ package manager to set-up these.
+
+Configure the shell
+^^^^^^^^^^^^^^^^^^^
+
+Linux
+"""""
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
+Windows + Cygwin
+""""""""""""""""
+
+Assumptions for the settings below:
+
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from DS5 installation.
+
+.. code-block:: bash
+
+ export PLANTUML_JAR_PATH=c:/plantuml/plantuml.jar
+ export PATH=$PATH:/cygdrive/c/<DS-5 path>/sw/java/bin
+
+**************************
+Tool & Dependency overview
+**************************
+
+To build the TF-M firmware the following tools are needed:
+
+.. csv-table:: Tool dependencies
+ :header: "Name", "Version", "Component"
+
+ "C compiler",See `Supported C compilers`_,"Firmware"
+ "CMake",See `Supported CMake versions`_,
+ "GNU Make",See `Supported GNU make versions`_,
+ "CMSIS 5",See `External dependencies`_,
+ "mbed-crypto",See `External dependencies`_,
+ "Python",3.x,"Firmware, User Guide"
+ "yaml",,"Firmware"
+ "pyasn1",,"Firmware"
+ "jinja2",,"Firmware"
+ "cryptography",,"Firmware"
+ "cbor",,"Firmware"
+ "Doxygen",">1.8","Reference manual"
+ "Sphinx",">1.4","User Guide"
+ "sphinxcontrib-plantuml",,"User Guide"
+ "sphinx-trd-theme",,"User Guide"
+ "Git",,
+ "PlantUML",">v1.2018.11","Reference Manual, User Guide"
+ "Graphviz dot",">v2.38.0","Reference manual"
+ "Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
+ "LaTex",,"pdf version of Reference Manual and User Guide"
+ "PdfLaTex",,"pdf version of Reference Manual and User Guide"
+
+Dependency chain:
+
+.. uml::
+
+ @startuml
+ skinparam state {
+ BackgroundColor #92AEE0
+ FontColor black
+ FontSize 16
+ AttributeFontColor black
+ AttributeFontSize 16
+ BackgroundColor<<pdf>> #A293E2
+ BackgroundColor<<doc>> #90DED6
+ }
+ state fw as "Firmware" : TF-M binary
+ state c_comp as "C Compiler" : C99
+ state gmake as "GNU make"
+ state u_guide as "User Guide" <<doc>>
+ state refman as "Reference Manual" <<doc>>
+ state rtd_theme as "sphinx-rtd-theme" <<doc>>
+ state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
+ state JRE as "JRE" <<doc>> : Java Runtime Environment
+ state gwiz as "Graphwiz dot" <<doc>>
+ state Sphinx as "Sphinx" <<doc>>
+ state m2r as "m2r" <<doc>>
+ state PlantUML as "PlantUML" <<doc>>
+ state LaTex as "LaTex" <<pdf>>
+ state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
+ state Doxygen as "Doxygen" <<doc>>
+
+ [*] --> fw
+ fw --> c_comp
+ fw --> CMake
+ CMake --> gmake
+ fw --> cryptography
+ fw --> pyasn1
+ fw --> yaml
+ fw --> jinja2
+ fw --> cbor
+ cryptography --> Python3
+ pyasn1 --> Python3
+ yaml --> Python3
+ jinja2 --> Python3
+ cbor --> Python3
+
+ [*] --> u_guide
+ u_guide --> Sphinx
+ Sphinx --> m2r
+ Sphinx --> rtd_theme
+ Sphinx --> sphnix_puml
+ m2r --> Python3
+ rtd_theme --> Python3
+ sphnix_puml --> Python3
+ Sphinx --> PlantUML
+ PlantUML --> JRE
+ PlantUML --> gwiz
+ Sphinx --> LaTex
+ LaTex --> PdfLaTex
+
+ [*] --> refman
+ refman --> Doxygen
+ Doxygen --> PlantUML
+ Doxygen --> LaTex
+ state Legend {
+ state x as "For PDF generation only" <<pdf>>
+ state y as "For document generation only" <<doc>>
+ state z as "Mandatory"
+ }
+
+ @enduml
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst
new file mode 100644
index 0000000..eaf33f6
--- /dev/null
+++ b/docs/getting_started/tfm_user_guide.rst
@@ -0,0 +1,474 @@
+##########
+User guide
+##########
+How to compile and run TF-M and example test application for CoreLink
+SSE-200 subsystem on the MPS2 board and on the Fast Model(FVP).
+
+Follow :doc:`build instruction <tfm_build_instruction>` to build the binaries.
+Follow :doc:`secure boot <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 run correctly on
+SMM-SSE-200 for MPS2 (AN521) and on the Fixed Virtual Platform model
+FVP_MPS2_AEMv8M version 11.2.23.
+
+To run the example code on FVP_MPS2_AEMv8M
+==========================================
+Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1.
+
+.. Note::
+ FVP reference guide can be found
+ `here <https://developer.arm.com/docs/100966/latest>`__
+
+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
+
+ <DS5_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>/install/outputs/fvp/tfm_s.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/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 ``mcuboot.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>/install/outputs/fvp/mcuboot.axf \
+ --data cpu0=<build_dir>/install/outputs/fvp/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>/install/outputs/fvp/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 ``mcuboot.bin`` and ``tfm_sign.bin`` files from
+ ``<build_dir>/install/outputs/AN521/`` 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\mcuboot.bin ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.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>/install/outputs/AN521/`` 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/musca_b1/readme>`
+ to have the correct setup.
+
+Example application with BL2 bootloader
+=======================================
+
+#. Create a unified hex file comprising of both ``mcuboot.bin`` and
+ ``tfm_sign.bin``.
+
+ - For Musca-A
+
+ - Windows::
+
+ srec_cat.exe install\outputs\MUSCA_A\mcuboot.bin -Binary -offset 0x200000 install\outputs\MUSCA_A\tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat install/outputs/MUSCA_A/mcuboot.bin -Binary -offset 0x200000 install/outputs/MUSCA_A/tfm_sign.bin -Binary -offset 0x220000 -o tfm.hex -Intel
+
+ - For Musca-B1
+
+ - Windows::
+
+ srec_cat.exe install\outputs\MUSCA_B1\mcuboot.bin -Binary -offset 0xA000000 install\outputs\MUSCA_B1\tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat install/outputs/MUSCA_B1/mcuboot.bin -Binary -offset 0xA000000 install/outputs/MUSCA_B1/tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - For Musca-S1
+
+ - Windows::
+
+ srec_cat.exe install\outputs\MUSCA_S1\mcuboot.bin -Binary -offset 0xA000000 install\outputs\MUSCA_S1\tfm_sign.bin -Binary -offset 0xA020000 -o tfm.hex -Intel
+
+ - Linux::
+
+ srec_cat install/outputs/MUSCA_S1/mcuboot.bin -Binary -offset 0xA000000 install/outputs/MUSCA_S1/tfm_sign.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
+====================================
+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'
+ ....
+
+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 install\outputs\MUSCA_B1\tfm_s.bin -Binary -offset 0xA000000 install\outputs\MUSCA_B1\tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+- Linux::
+
+ srec_cat install/outputs/MUSCA_B1/tfm_s.bin -Binary -offset 0xA000000 install/outputs/MUSCA_B1/tfm_ns.bin -Binary -offset 0xA060000 -o tfm.hex -Intel
+
+********************************************************
+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 ``mcuboot.bin`` and ``tfm_sign.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\mcuboot.bin
+ IMAGE1UPDATE: AUTO
+ IMAGE1ADDRESS: 0x00040000
+ IMAGE1FILE: \SOFTWARE\tfm_sign.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 <tfm_secure_boot>`.
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*