Docs: Restructure the documents
Restructure the file category to let it more friendly to users.
Signed-off-by: Summer Qin <summer.qin@arm.com>
Change-Id: I7ced0e2d700ce03423e472e0098608f3445ba169
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 4b08906..c6d8d34 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -2,12 +2,15 @@
======================
.. toctree::
:maxdepth: 1
- :caption: Contents
:glob:
:numbered:
- *
+ tfm_sw_requirement
+ tfm_build_instruction
+ tfm_build_instruction_iar
+ tfm_user_guide
+ /tools/index
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, 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
deleted file mode 100644
index 752c332..0000000
--- a/docs/getting_started/os_migration_guide_armv8m.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-#########################################################
-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
index cdfcab5..453d1d9 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -167,7 +167,7 @@
TF-M Profiles are implemented as a single cmake configuration file, under the
``config/profile`` directory. A good understanding can be gained quickly by
looking at the Profile configuration files, but the ultimate reference for
-Profiles are the design documents in the ``docs/design_documents/profiles/``
+Profiles are the design documents in the ``docs/technical_references/profiles/``
directory.
PSA test configuration
@@ -563,4 +563,4 @@
--------------
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_integration_guide.rst b/docs/getting_started/tfm_integration_guide.rst
deleted file mode 100644
index a37a4cb..0000000
--- a/docs/getting_started/tfm_integration_guide.rst
+++ /dev/null
@@ -1,180 +0,0 @@
-#################
-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)
-- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
-- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3)
-- 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)
-- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547)
-- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs)
-- nRF9160 DK (Cortex-M33)
-- nRF5340 PDK/DK (Cortex-M33 Application MCU)
-
-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 subsystems supported by the MPS3 board can be found in:
-`MPS3 homepage <https://developer.arm.com/products/system-design/development-boards/fpga-prototyping-boards/mps3>`__
-
-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 Corstone-300 FVPs can be found in:
-`Arm Ecosystem FVPs homepage <https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps>`__
-
-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>`__
-
-More information about the nRF5340 PDK platform can be found in:
-`nRF5340 PDK product page <https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF5340-PDK>`__
-
-More information about the nRF9160 DK platform can be found in:
-`nRF9160 DK product page <https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF9160-DK>`__
-
-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
-``<install_dir>/interface`` 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 ``<install_dir>/interface/include``
-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.
-
-**********************************
-Integration with non-Cmake systems
-**********************************
-
-Generated Files
-===============
-
-Files that are derived from PSA manifests are generated at build-time by cmake.
-For integration with systems that do no use cmake, the files must be generated
-manually.
-
-The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
-arguments will be needed to be provided. Please refer to
-``tfm_parse_manifest_list.py --help`` for more details.
-
-Some variables are used in the template files, these will need to be set in the
-environment before the script will succeed when the script is not run via cmake.
-
---------------
-
-*Copyright (c) 2017-2021, 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
deleted file mode 100644
index 44fd343..0000000
--- a/docs/getting_started/tfm_ns_client_identification.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-###########################
-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
deleted file mode 100644
index 95d3f68..0000000
--- a/docs/getting_started/tfm_secure_boot.rst
+++ /dev/null
@@ -1,808 +0,0 @@
-###########
-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
-*******************************
-By default, the MCUboot project from
-`GitHub <https://github.com/mcu-tools/mcuboot>`__ is used as the secure
-bootloader in TF-M. The repository is going to be automatically downloaded by
-CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION``
-CMake variable. If you wish to use a locally downloaded copy, the CMake variable
-``MCUBOOT_PATH`` can be set to its location. This document contains information
-about how MCUboot has been integrated to TF-M. For further information about
-MCUboot design please refer to the `MCUBoot homepage <https://www.mcuboot.com/>`__.
-
-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!
-
-The private key must be stored in a safe place outside of the repository.
-``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository,
-or installed through the pip package manager) 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>/bin/tfm_s_ns_signed.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 direct execute-in-place 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.
-
-Direct execute-in-place operation
-=================================
-This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
-switch (see `Build time configuration`_). When enabling direct-xip 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.
-
-To select which slot the image is to be executed from, set
-``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create
-two build directories when building images using this mode, as intermediate
-dependencies cannot be reused due to changes in the flash layout.
-
-.. Note::
-
- Only single image boot is supported with direct-xip upgrade mode.
-
-RAM Loading firmware upgrade
-============================
-Musca-S supports an image upgrade mode that is separate to the other (overwrite,
-swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer
-to the table below). Like the direct-xip 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 load`` upgrade mode.
-
-Summary of different modes for image upgrade
-============================================
-Different implementations of the image upgrade operation (whether through
-overwriting, swapping, direct-xip 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]_| direct-xip [5]_| RAM load [6]_|
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN521 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN519 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| FVP_SSE300_MPS2 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| LPC55S69 | Yes | Yes | No | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| Musca-B1 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| Musca-S1 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN524 | Yes | No | No | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN547 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| PSoC64 | Yes | No | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| STM_DISCO_L562QE | No | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| nRF9160 DK | Yes | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| nRF5340 PDK/DK | Yes | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-
-.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF``
-
-.. [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 direct-xip, assign the "DIRECT_XIP" 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 load, assign the "RAM_LOAD" string to the
- ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
- configuration file, or include this macro definition in the command line
-
-*******************
-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:
-
- - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
- minimum required version of the secure image.
- - ``MCUBOOT_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 -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_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 by cmake variables.
-
-- 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_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"):
- - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite.
- - **"SWAP":** Activate swapping firmware upgrade operation.
- - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade
- operation.
- - **"RAM_LOAD":** 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):
- - **RSA:** Image is signed with RSA algorithm
-- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072):
- - **2048:** Image is signed with 2048 bit key.
- - **3072:** Image is signed with 3072 bit key.
-- 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 (imgtool uses
- ``--public_key_format=full``). 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 (imgtool uses
- ``--public_key_format=hash``). 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:
-
- - **OFF**
- - **ERROR**
- - **WARNING**
- - **INFO**
- - **DEBUG**
-
- The logging in MCUBoot can be disabled and thus the code size can be reduced
- by setting it to ``OFF``. Its value depends on the build type. If the build
- type is ``Debug`` then default value is ``INFO``. In case of different kinds
- of ``Release`` builds the default value is ``OFF``. The default value can
- be overridden through the command line or in the CMake GUI regardless of the
- build type.
-- MCUBOOT_ENC_IMAGES (default: False):
- - **True:** Adds encrypted image support in the source and encrypts the
- resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot
- repository.
- - **False:** Doesn't add encrypted image support and doesn't encrypt the
- image.
-
- .. Note::
- The decryption takes place during the upgrade process, when the images
- are being moved between the slots. This means that boards that don't
- already have an image on them with MCUBoot that has been compiled with
- ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load
- an encrypted image to such boards, an upgrade needs to be executed. This
- can be done by using MCUBoot, putting an image in the secondary image
- area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the
- ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using
- ``SWAP``, an image is needed in the primary image area as well, to
- trigger the update.
-
- .. Warning::
- DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is
- exclusively for testing!
-
-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 direct execute-in-place or
-the 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 -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=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_S``.
-
-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 -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=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_S``. 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 MCUboot repository in the ``scripts``
-folder or can be installed with the pip package manager.
-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_s_ns.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>/bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \
- -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>/bin/tfm_s.bin \
- <build_dir>/bin/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
-
- <ARM_DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
- --parameter fvp_mps2.platform_type=2 \
- --parameter cpu0.baseline=0 \
- --parameter cpu0.INITVTOR_S=0x10000000 \
- --parameter cpu0.semihosting-enable=0 \
- --parameter fvp_mps2.DISABLE_GATING=0 \
- --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
- --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal0.quiet=0 \
- --parameter fvp_mps2.telnetterminal1.quiet=1 \
- --parameter fvp_mps2.telnetterminal2.quiet=1 \
- --application cpu0=<build_dir>/bin/bl2.axf \
- --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=<regresssion_build_dir>/bin/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\bl2.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\bl2.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)...
- ...
-
-Direct execute-in-place 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 "DIRECT_XIP"
- before build.
-- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir.
-- 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
-
- <ARM_DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \
- --parameter fvp_mps2.platform_type=2 \
- --parameter cpu0.baseline=0 \
- --parameter cpu0.INITVTOR_S=0x10000000 \
- --parameter cpu0.semihosting-enable=0 \
- --parameter fvp_mps2.DISABLE_GATING=0 \
- --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
- --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal0.quiet=0 \
- --parameter fvp_mps2.telnetterminal1.quiet=1 \
- --parameter fvp_mps2.telnetterminal2.quiet=1 \
- --application cpu0=<build_dir>/bin/bl2.axf \
- --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=<regresssion_build_dir>/bin/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\bl2.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 bin/bl2.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 bin\bl2.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\bl2.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_LOAD"
-(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-S, its ``flash_layout.h`` file in the ``platform``
-folder should include ``#define IMAGE_LOAD_ADDRESS #0xA0020000``
-
-Executing firmware upgrade on Musca-S board
---------------------------------------------
-After two images have been built, they can be concatenated to create the
-combined image using ``srec_cat``:
-
-- Linux::
-
- srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
-
-- Windows::
-
- srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -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 0xA0020000
- [INF] Booting image from SRAM at address 0xA0020000
- [INF] Bootloader chainload address offset: 0x20000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
-
---------------
-
-****************************************
-Integration with Firmware Update service
-****************************************
-The shim layer of the Firmware Update partition calls the APIs in
-bootutil_misc.c to control the image status.
-
-- Call ``boot_write_magic()`` to make the image as a candidate image for booting.
-- Call ``boot_set_confirmed()`` to make the image as a permanent image.
-
-.. Note::
- Currently, in direct-xip mode and ram-load mode, TF-M cannot get the
- information of which slot contains the running image from the bootloader.
- So the Firmware Update partition cannot decide where to write the new
- image. As a result, the firmware update service is not supported in
- direct-xip mode and ram-load mode.
-
-*Copyright (c) 2018-2021, 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
deleted file mode 100644
index 8cd664e..0000000
--- a/docs/getting_started/tfm_secure_irq_handling.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-###################
-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 of the 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. The IRQ line nums and sources are defined by
- each platform: for example, they are defined in ``platform_irq.h`` for the
- Musca-S1 platform. When defining new macros in ``tfm_peripherals_def.h``, it
- is important the macro name matches the platform's handler function for that
- IRQ source.
-- ``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 has to be present in the vector
- table as the handler of the IRQ. The platform startup functions are specified
- in the vector table defined in the platform secure startup file. The user
- should verify the names of the generated handlers match for a given platform
- 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-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst
index 55648f4..d2b0193 100644
--- a/docs/getting_started/tfm_user_guide.rst
+++ b/docs/getting_started/tfm_user_guide.rst
@@ -5,8 +5,8 @@
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.
+Follow :doc:`secure boot </docs/technical_references/tfm_secure_boot>` to build the
+binaries with or without BL2 bootloader.
****************************************************************
Execute TF-M example and regression tests on MPS2 boards and FVP
@@ -565,7 +565,7 @@
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>`.
+upgrade is described in :doc:`secure boot </docs/technical_references/tfm_secure_boot>`.
--------------
@@ -576,4 +576,4 @@
.. _Keil MDK: http://www2.keil.com/mdk5
.. _Keil MDK Documentation: https://www2.keil.com/mdk5/docs
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*