Merge pull request #70 from theotherjimmy/update-tfm-pre-1.6.0

Update to TFM 1.6.0

CMakeLists.txt

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -7,24 +7,12 @@
 
 cmake_minimum_required(VERSION 3.15)
 
-include(version.cmake)
+include(cmake/version.cmake)
 
 ############################ CONFIGURATION #####################################
 
-if (IS_ABSOLUTE "${TFM_PLATFORM}")
-    file(RELATIVE_PATH TFM_PLATFORM_RELATIVE_PATH
-        "${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target"
-        ${TFM_PLATFORM})
-    set(TFM_PLATFORM "${TFM_PLATFORM_RELATIVE_PATH}" CACHE STRING "Target platform set as an absolute path." FORCE)
-endif()
-
-# Some compiler flags depend on the CPU / platform config. This include should
-# be run before the toolchain file so the compiler can be configured properly.
-if (NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/platform/ext/target/${TFM_PLATFORM}/preload.cmake)
-    Message(FATAL_ERROR "Unsupported TFM_PLATFORM ${TFM_PLATFORM}")
-else()
-    include(platform/ext/target/${TFM_PLATFORM}/preload.cmake)
-endif()
+# Configure TFM_PLATFORM
+include(${CMAKE_SOURCE_DIR}/config/tfm_platform.cmake)
 
 if(TFM_SYSTEM_MVE)
     message(FATAL_ERROR "Hardware MVE is currently not supported in TF-M")
@@ -90,23 +78,24 @@ endif()
 add_subdirectory(lib/ext)
 add_subdirectory(lib/fih)
 add_subdirectory(tools)
-if(NS)
-    # Set to ${TFM_TEST_REPO_PATH}/app by default
-    add_subdirectory(${TFM_APP_PATH} ${CMAKE_CURRENT_BINARY_DIR}/app)
-    add_subdirectory(${TFM_NS_LOG_PATH} ${CMAKE_CURRENT_BINARY_DIR}/ns_log)
-endif()
 add_subdirectory(secure_fw)
+
+if(NS OR TFM_S_REG_TEST OR TFM_NS_REG_TEST OR TEST_BL2 OR TEST_BL1_1 OR TEST_BL1_2)
+    add_subdirectory(${TFM_TEST_REPO_PATH} ${CMAKE_CURRENT_BINARY_DIR}/tf-m-tests)
+endif()
+
 add_subdirectory(interface)
 if(BL2)
     add_subdirectory(bl2)
 endif()
-add_subdirectory(platform)
 
-if(TFM_NS_REG_TEST OR TFM_S_REG_TEST)
-    # Set to ${TFM_TEST_REPO_PATH}/test by default
-    add_subdirectory(${TFM_TEST_PATH} ${CMAKE_CURRENT_BINARY_DIR}/test)
+if(BL1 AND PLATFORM_DEFAULT_BL1)
+    add_subdirectory(bl1/bl1_2)
+    add_subdirectory(bl1/bl1_1)
 endif()
 
+add_subdirectory(platform)
+
 include(cmake/install.cmake)
 
 if(CRYPTO_HW_ACCELERATOR)

bl1/bl1_1/CMakeLists.txt

@@ -0,0 +1,104 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+add_subdirectory(lib)
+add_subdirectory(shared_lib)
+add_executable(bl1_1)
+
+set_target_properties(bl1_1
+    PROPERTIES
+        SUFFIX ".axf"
+        RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+)
+
+add_convert_to_bin_target(bl1_1)
+
+target_link_options(bl1_1
+    PRIVATE
+        $<$<C_COMPILER_ID:GNU>:-Wl,-Map=${CMAKE_BINARY_DIR}/bin/bl1_1.map>
+        $<$<C_COMPILER_ID:ARMClang>:--map>
+        $<$<C_COMPILER_ID:IAR>:--map\;${CMAKE_BINARY_DIR}/bin/bl1_1.map>
+)
+
+target_sources(bl1_1
+    PRIVATE
+        main.c
+)
+
+target_link_libraries(bl1_1
+    PRIVATE
+        bl1_1_lib
+        bl1_1_shared_lib
+        platform_bl1
+        $<$<BOOL:${TEST_BL1_1}>:bl1_1_tests>
+)
+
+target_compile_definitions(bl1_1
+    PRIVATE
+        $<$<BOOL:${TEST_BL1_1}>:TEST_BL1_1>
+)
+
+target_share_symbols(bl1_1 ${CMAKE_CURRENT_SOURCE_DIR}/bl1_1_shared_symbols.txt)
+
+################################################################################
+
+add_library(signing_layout_bl1_2 OBJECT signing_layout.c)
+target_compile_options(signing_layout_bl1_2
+    PRIVATE
+        $<$<C_COMPILER_ID:GNU>:-E\;-xc>
+        $<$<C_COMPILER_ID:ARMClang>:-E\;-xc>
+        $<$<C_COMPILER_ID:IAR>:--preprocess=ns\;$<TARGET_OBJECTS:signing_layout_bl1_2>>
+)
+target_link_libraries(signing_layout_bl1_2
+    PRIVATE
+        platform_region_defs
+)
+
+################################################################################
+get_target_property(bin_dir bl1_2 RUNTIME_OUTPUT_DIRECTORY)
+
+add_custom_target(bl1_2_padded_bin
+    ALL
+    SOURCES bl1_2_padded.bin
+    SOURCES bl1_2_padded_hash.bin
+)
+
+add_custom_command(OUTPUT bl1_2_padded.bin bl1_2_padded_hash.bin
+    OUTPUT ${bin_dir}/bl1_2_padded.bin ${bin_dir}/bl1_2_padded_hash.bin
+    DEPENDS $<TARGET_FILE_DIR:bl1_2>/bl1_2.bin bl1_2_bin signing_layout_bl1_2
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_bl1_2_img.py
+    COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_bl1_2_img.py
+                    --input_file $<TARGET_FILE_DIR:bl1_2>/bl1_2.bin
+                    --img_output_file bl1_2_padded.bin
+                    --hash_output_file bl1_2_padded_hash.bin
+                    --signing_layout_file $<TARGET_OBJECTS:signing_layout_bl1_2>
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/bl1_2_padded.bin $<TARGET_FILE_DIR:bl1_2>
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/bl1_2_padded_hash.bin $<TARGET_FILE_DIR:bl1_2>
+)
+
+################################################################################
+
+add_custom_target(bl1_provisioning_bundle
+    ALL
+    SOURCES bl1_provisioning_bundle.bin
+)
+
+add_custom_command(OUTPUT bl1_provisioning_bundle.bin
+    DEPENDS ${TFM_BL2_ENCRYPTION_KEY_PATH}
+    DEPENDS $<TARGET_FILE_DIR:bl1_2>/bl1_2_padded_hash.bin
+    DEPENDS $<TARGET_FILE_DIR:bl2>/bl2_signed_hash.bin
+    DEPENDS $<TARGET_FILE_DIR:bl1_2>/bl1_2_padded.bin
+    bl1_2_padded_bin bl2_signed_bin
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_provisioning_bundle.py
+    COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_provisioning_bundle.py
+                    --bl2_encryption_key_input_file ${TFM_BL2_ENCRYPTION_KEY_PATH}
+                    --bl1_2_padded_hash_input_file $<TARGET_FILE_DIR:bl1_2>/bl1_2_padded_hash.bin
+                    --bl2_signed_hash_input_file $<TARGET_FILE_DIR:bl2>/bl2_signed_hash.bin
+                    --bl1_2_input_file $<TARGET_FILE_DIR:bl1_2>/bl1_2_padded.bin
+                    --bundle_output_file bl1_provisioning_bundle.bin
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/bl1_provisioning_bundle.bin $<TARGET_FILE_DIR:bl1_1>
+)

bl1/bl1_1/bl1_1_shared_symbols.txt

@@ -0,0 +1,36 @@
+bl1_sha256_compute
+bl1_aes_256_ctr_decrypt
+bl1_otp_read_nv_counter
+bl1_otp_write_nv_counter
+bl1_otp_read_bl2_image_hash
+bl1_otp_read_key
+bl1_otp_read
+mbedtls_init
+crypto_hw_accelerator_init
+crypto_hw_accelerator_finish
+fih_delay_init
+fih_delay_finish
+bl_secure_memeql
+bl_secure_memcpy
+
+fih_delay_random_uchar
+_fih_cfi_ctr
+FIH_FAILURE
+FIH_SUCCESS
+_fih_mask
+fih_cfi_decrement
+fih_cfi_get_and_increment
+fih_cfi_validate
+fih_panic_loop
+
+SystemInit
+boot_platform_init
+boot_platform_post_init
+boot_platform_quit
+bl1_image_get_flash_offset
+stdio_output_string
+Driver_FLASH0
+platform_code_is_bl1_2
+
+run_testsuite
+tfm_log_printf

bl1/bl1_1/lib/CMakeLists.txt

@@ -0,0 +1,26 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+add_library(bl1_1_lib INTERFACE)
+
+target_sources(bl1_1_lib
+    INTERFACE
+        $<$<BOOL:${TFM_BL1_DEFAULT_PROVISIONING}>:${CMAKE_CURRENT_SOURCE_DIR}/provisioning.c>
+        $<$<BOOL:${TFM_BL1_2_IN_OTP}>:${CMAKE_CURRENT_SOURCE_DIR}/image_otp.c>
+        $<$<NOT:$<BOOL:${TFM_BL1_2_IN_OTP}>>:${CMAKE_CURRENT_SOURCE_DIR}/image_flash.c>
+)
+
+target_include_directories(bl1_1_lib
+    INTERFACE
+        interface
+)
+
+target_link_libraries(bl1_1_lib
+    INTERFACE
+        bl1_1_shared_lib
+        platform_bl1
+)

bl1/bl1_1/lib/image_flash.c

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "image.h"
+
+#include "Driver_Flash.h"
+#include "flash_layout.h"
+#include "region_defs.h"
+#include "fih.h"
+
+extern ARM_DRIVER_FLASH FLASH_DEV_NAME;
+
+fih_int bl1_read_bl1_2_image(uint8_t *image)
+{
+    uint32_t flash_offset;
+    fih_int fih_rc;
+
+    fih_rc = fih_int_encode(FLASH_DEV_NAME.ReadData(BL1_2_IMAGE_FLASH_OFFSET,
+                                                    image,
+                                                    BL1_2_CODE_SIZE);
+
+    FIH_RET(fih_rc);
+}

bl1/bl1_1/lib/image_otp.c

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "image.h"
+
+#include "region_defs.h"
+#include "tfm_plat_otp.h"
+
+fih_int bl1_read_bl1_2_image(uint8_t *image)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_otp_read(PLAT_OTP_ID_BL1_2_IMAGE, BL1_2_CODE_SIZE,
+                                 image);
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    FIH_RET(fih_rc);
+}

bl1/bl1_1/lib/interface/image.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_1_IMAGE_H
+#define BL1_1_IMAGE_H
+
+#include <stdint.h>
+#include "fih.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+fih_int bl1_read_bl1_2_image(uint8_t *image);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_1_IMAGE_H */

bl1/bl1_1/lib/provisioning.c

@@ -0,0 +1,117 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "tfm_plat_provisioning.h"
+
+#include "cmsis_compiler.h"
+#include "tfm_plat_otp.h"
+#include "tfm_attest_hal.h"
+#include "psa/crypto.h"
+#include "region_defs.h"
+#include "log.h"
+
+#include <string.h>
+
+#define ASSEMBLY_AND_TEST_PROV_DATA_MAGIC 0xC0DEFEED
+
+__PACKED_STRUCT bl1_assembly_and_test_provisioning_data_t {
+    uint32_t magic;
+    uint8_t bl2_encryption_key[32];
+    uint8_t bl1_2_image_hash[32];
+    uint8_t bl2_image_hash[32];
+    uint8_t bl1_2_image[BL1_2_CODE_SIZE];
+};
+
+static const struct bl1_assembly_and_test_provisioning_data_t *bl1_assembly_and_test_prov_data =
+                    (struct bl1_assembly_and_test_provisioning_data_t *)PROVISIONING_DATA_START;
+
+void tfm_plat_provisioning_check_for_dummy_keys(void)
+{
+}
+
+int tfm_plat_provisioning_is_required(void)
+{
+    enum tfm_plat_err_t err;
+    enum plat_otp_lcs_t lcs;
+
+    err = tfm_plat_otp_read(PLAT_OTP_ID_LCS, sizeof(lcs), (uint8_t *)&lcs);
+    if (err != TFM_PLAT_ERR_SUCCESS) {
+        return err;
+    }
+
+    return lcs == PLAT_OTP_LCS_ASSEMBLY_AND_TEST
+        || lcs == PLAT_OTP_LCS_PSA_ROT_PROVISIONING;
+}
+
+enum tfm_plat_err_t provision_assembly_and_test(void)
+{
+    enum tfm_plat_err_t err;
+
+    err = tfm_plat_otp_write(PLAT_OTP_ID_KEY_BL2_ENCRYPTION,
+                             sizeof(bl1_assembly_and_test_prov_data->bl2_encryption_key),
+                             bl1_assembly_and_test_prov_data->bl2_encryption_key);
+    if (err != TFM_PLAT_ERR_SUCCESS && err != TFM_PLAT_ERR_UNSUPPORTED) {
+        return err;
+    }
+
+    err = tfm_plat_otp_write(PLAT_OTP_ID_BL1_2_IMAGE_HASH,
+                             sizeof(bl1_assembly_and_test_prov_data->bl1_2_image_hash),
+                             bl1_assembly_and_test_prov_data->bl1_2_image_hash);
+    if (err != TFM_PLAT_ERR_SUCCESS && err != TFM_PLAT_ERR_UNSUPPORTED) {
+        return err;
+    }
+
+    err = tfm_plat_otp_write(PLAT_OTP_ID_BL2_IMAGE_HASH,
+                             sizeof(bl1_assembly_and_test_prov_data->bl2_image_hash),
+                             bl1_assembly_and_test_prov_data->bl2_image_hash);
+    if (err != TFM_PLAT_ERR_SUCCESS && err != TFM_PLAT_ERR_UNSUPPORTED) {
+        return err;
+    }
+
+    err = tfm_plat_otp_write(PLAT_OTP_ID_BL1_2_IMAGE,
+                             sizeof(bl1_assembly_and_test_prov_data->bl1_2_image),
+                             bl1_assembly_and_test_prov_data->bl1_2_image);
+    if (err != TFM_PLAT_ERR_SUCCESS && err != TFM_PLAT_ERR_UNSUPPORTED) {
+        return err;
+    }
+
+    return err;
+}
+
+enum tfm_plat_err_t tfm_plat_provisioning_perform(void)
+{
+    enum tfm_plat_err_t err;
+    enum plat_otp_lcs_t lcs;
+
+    err = tfm_plat_otp_read(PLAT_OTP_ID_LCS, sizeof(lcs), (uint8_t *)&lcs);
+    if (err != TFM_PLAT_ERR_SUCCESS) {
+        return err;
+    }
+
+    BL1_LOG("[INF] Beginning BL1 provisioning\r\n");
+
+#ifdef TFM_DUMMY_PROVISIONING
+    BL1_LOG("\033[1;31m[WRN] ");
+    BL1_LOG("TFM_DUMMY_PROVISIONING is not suitable for production! ");
+    BL1_LOG("This device is \033[1;1mNOT SECURE");
+    BL1_LOG("\033[0m\r\n");
+#endif /* TFM_DUMMY_PROVISIONING */
+
+    if (lcs == PLAT_OTP_LCS_ASSEMBLY_AND_TEST) {
+        if (bl1_assembly_and_test_prov_data->magic != ASSEMBLY_AND_TEST_PROV_DATA_MAGIC) {
+            BL1_LOG("[ERR] No valid ASSEMBLY_AND_TEST provisioning data found\r\n");
+            return TFM_PLAT_ERR_INVALID_INPUT;
+        }
+
+        err = provision_assembly_and_test();
+        if (err != TFM_PLAT_ERR_SUCCESS) {
+            return err;
+        }
+    }
+
+    return TFM_PLAT_ERR_SUCCESS;
+}

bl1/bl1_1/main.c

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "crypto.h"
+#include "otp.h"
+#include "tfm_plat_provisioning.h"
+#include "boot_hal.h"
+#include "region_defs.h"
+#include "log.h"
+#include "util.h"
+#include "image.h"
+#include "fih.h"
+
+fih_int validate_image_at_addr(uint8_t *image)
+{
+    uint8_t computed_bl1_2_hash[BL1_2_HASH_SIZE];
+    uint8_t stored_bl1_2_hash[BL1_2_HASH_SIZE];
+    fih_int fih_rc = FIH_FAILURE;
+
+    FIH_CALL(bl1_sha256_compute, fih_rc, image, BL1_2_CODE_SIZE,
+                                     computed_bl1_2_hash);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_CALL(bl1_otp_read_bl1_2_image_hash, fih_rc, stored_bl1_2_hash);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_CALL(bl_secure_memeql, fih_rc, computed_bl1_2_hash,
+                                       stored_bl1_2_hash, BL1_2_HASH_SIZE);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_RET(FIH_SUCCESS);
+}
+
+int main(void)
+{
+    fih_int fih_rc = FIH_FAILURE;
+
+    fih_rc = fih_int_encode_zero_equality(boot_platform_init());
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_PANIC;
+    }
+    BL1_LOG("[INF] Starting TF-M BL1_1\r\n");
+
+    fih_rc = bl1_otp_init();
+
+    if (tfm_plat_provisioning_is_required()) {
+        if (tfm_plat_provisioning_perform()) {
+            BL1_LOG("[ERR] BL1_2 provisioning failed\r\n");
+            FIH_PANIC;
+        }
+    }
+
+    tfm_plat_provisioning_check_for_dummy_keys();
+
+    fih_rc = fih_int_encode_zero_equality(boot_platform_post_init());
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_PANIC;
+    }
+
+#ifdef TEST_BL1_1
+    run_bl1_1_testsuite();
+#endif /* TEST_BL1_1 */
+
+    /* Copy BL1_2 from OTP into SRAM*/
+    FIH_CALL(bl1_read_bl1_2_image, fih_rc, (uint8_t *)BL1_2_CODE_START);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_PANIC;
+    }
+
+    FIH_CALL(validate_image_at_addr, fih_rc, (uint8_t *)BL1_2_CODE_START);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] BL1_2 image failed to validate\r\n");
+        FIH_PANIC;
+    }
+
+    BL1_LOG("[INF] Jumping to BL1_2\r\n");
+    /* Jump to BL1_2 */
+    boot_platform_quit((struct boot_arm_vector_table *)BL1_2_CODE_START);
+
+    /* This should never happen */
+    FIH_PANIC;
+}

bl1/bl1_1/scripts/create_bl1_2_img.py

@@ -0,0 +1,54 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+import argparse
+import hashlib
+import os
+import sys
+sys.path.append(os.path.join(os.path.dirname(os.path.realpath(__file__)), "../../../bl2/ext/mcuboot/scripts"))
+import macro_parser
+import struct
+
+def hash_binary_blob(blob):
+   hash = hashlib.sha256()
+   hash.update(blob)
+   return hash.digest()
+
+def struct_pack(objects, pad_to=0):
+    defstring = "<"
+    for obj in objects:
+        defstring += str(len(obj)) + "s"
+
+    size = struct.calcsize(defstring)
+    if size < pad_to:
+        defstring += str(pad_to - size) + "x"
+
+    return (bytes(struct.pack(defstring, *objects)))
+
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--input_file", help="the image to process", required=True)
+parser.add_argument("--img_output_file", help="image output file", required=True)
+parser.add_argument("--hash_output_file", help="hash output file", required=True)
+parser.add_argument("--signing_layout_file", help="signing layout file", required=True)
+args = parser.parse_args()
+
+with open(args.input_file, "rb") as in_file:
+    bl1_2_code = in_file.read()
+
+bl1_2_partition_size = macro_parser.evaluate_macro(args.signing_layout_file,
+                                    ".*(RE_BL1_2_BIN_SIZE) = *(.*)",
+                                    1, 2, True)['RE_BL1_2_BIN_SIZE']
+
+image = struct_pack([bl1_2_code], pad_to=bl1_2_partition_size)
+hash = hash_binary_blob(image)
+
+with open(args.img_output_file, "wb") as img_out_file:
+    img_out_file.write(image)
+
+with open(args.hash_output_file, "wb") as hash_out_file:
+    hash_out_file.write(hash)

bl1/bl1_1/scripts/create_provisioning_bundle.py

@@ -0,0 +1,51 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+import argparse
+import struct
+
+def struct_pack(objects, pad_to=0):
+    defstring = "<"
+    for obj in objects:
+        defstring += str(len(obj)) + "s"
+
+    size = struct.calcsize(defstring)
+    if size < pad_to:
+        defstring += str(pad_to - size) + "x"
+
+    return (bytes(struct.pack(defstring, *objects)))
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--bl2_encryption_key_input_file", help="the key that BL2 was encrypted with", required=True)
+parser.add_argument("--bl1_2_padded_hash_input_file", help="the hash of the final bl1_2 image", required=True)
+parser.add_argument("--bl2_signed_hash_input_file", help="the hash of the final bl2 image", required=True)
+parser.add_argument("--bl1_2_input_file", help="the final bl1_2 image", required=True)
+parser.add_argument("--bundle_output_file", help="bundle output file", required=True)
+args = parser.parse_args()
+
+with open(args.bl2_encryption_key_input_file, "rb") as in_file:
+    bl1_2_encryption_key = in_file.read()
+
+with open(args.bl1_2_padded_hash_input_file, "rb") as in_file:
+    bl1_2_padded_hash = in_file.read()
+
+with open(args.bl2_signed_hash_input_file, "rb") as in_file:
+    bl2_signed_hash = in_file.read()
+
+with open(args.bl1_2_input_file, "rb") as in_file:
+    bl1_2 = in_file.read()
+
+bundle = struct_pack([
+    int("0xC0DEFEED", 16).to_bytes(4, 'little'),
+    bl1_2_encryption_key,
+    bl1_2_padded_hash,
+    bl2_signed_hash,
+    bl1_2,
+])
+
+with open(args.bundle_output_file, "wb") as out_file:
+    out_file.write(bundle)

bl1/bl1_1/shared_lib/CMakeLists.txt

@@ -0,0 +1,102 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+add_library(bl1_1_shared_lib STATIC)
+add_library(bl1_1_shared_lib_interface INTERFACE)
+
+target_include_directories(bl1_1_shared_lib_interface
+    INTERFACE
+        interface
+        $<$<BOOL:${TFM_BL1_DEFAULT_OTP}>:${CMAKE_CURRENT_SOURCE_DIR}/otp>
+)
+
+target_link_libraries(bl1_1_shared_lib_interface
+    INTERFACE
+        psa_interface
+        tfm_fih_headers
+)
+
+target_sources(bl1_1_shared_lib
+    PRIVATE
+        $<$<BOOL:${TFM_BL1_SOFTWARE_CRYPTO}>:crypto/crypto_mbedcrypto>
+        $<$<BOOL:${TFM_BL1_DUMMY_TRNG}>:trng/trng_dummy.c>
+        ./util.c
+        $<$<BOOL:${TFM_BL1_DEFAULT_OTP}>:./otp/otp_default.c>
+)
+
+target_link_libraries(bl1_1_shared_lib
+    PUBLIC
+        bl1_1_shared_lib_interface
+        platform_region_defs
+        tfm_fih_implementation
+    PRIVATE
+        $<$<BOOL:${TFM_BL1_SOFTWARE_CRYPTO}>:bl1_1_crypto_mbedcrypto>
+        $<$<AND:$<NOT:$<BOOL:${TFM_BL1_SOFTWARE_CRYPTO}>>,$<BOOL:${CRYPTO_HW_ACCELERATOR}>>:bl1_crypto_hw>
+)
+
+target_compile_options(bl1_1_shared_lib_interface
+    INTERFACE
+        #Prevents warnings caused by C99 static assert workaround
+        -Wno-unused-local-typedefs
+)
+
+target_compile_definitions(bl1_1_shared_lib_interface
+    INTERFACE
+        $<$<BOOL:${TEST_BL1_1}>:TEST_BL1_1>
+        MCUBOOT_FIH_PROFILE_HIGH
+)
+
+if(TFM_BL1_SOFTWARE_CRYPTO)
+    cmake_policy(SET CMP0079 NEW)
+
+    set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
+    set(CMAKE_POLICY_DEFAULT_CMP0048 NEW)
+    set(ENABLE_TESTING OFF)
+    set(ENABLE_PROGRAMS OFF)
+    set(MBEDTLS_FATAL_WARNINGS OFF)
+    set(ENABLE_DOCS OFF)
+    set(INSTALL_MBEDTLS_HEADERS OFF)
+    set(LIB_INSTALL_DIR ${CMAKE_CURRENT_BINARY_DIR}/mbedcrypto/install)
+
+    set(lib_target bl1_1_crypto_mbedcrypto_libs)
+    set(mbedcrypto_target bl1_1_crypto_mbedcrypto)
+    set(mbedtls_target bl1_1_crypto_mbedtls)
+    set(mbedx509_target bl1_1_crypto_mbedx509)
+    set(MBEDTLS_TARGET_PREFIX bl1_1_crypto_)
+
+    # Mbedcrypto is quite a large lib, and it uses too much memory for it to be
+    # reasonable to build it in debug info. As a compromise, if `debug` build type
+    # is selected mbedcrypto will build under `relwithdebinfo` which preserved debug
+    # symbols whild optimizing space.
+    set(SAVED_BUILD_TYPE ${CMAKE_BUILD_TYPE})
+    set(CMAKE_BUILD_TYPE ${MBEDCRYPTO_BUILD_TYPE})
+    add_subdirectory(${MBEDCRYPTO_PATH} ${CMAKE_CURRENT_BINARY_DIR}/mbedcrypto)
+    set(CMAKE_BUILD_TYPE ${SAVED_BUILD_TYPE} CACHE STRING "Build type: [Debug, Release, RelWithDebInfo, MinSizeRel]" FORCE)
+
+    if(NOT TARGET bl1_1_crypto_mbedcrypto)
+        message(FATAL_ERROR "Target bl1_1_crypto_mbedcrypto does not exist. Have the patches in ${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto been applied to the mbedcrypto repo at ${MBEDCRYPTO_PATH} ?
+        Hint: The command might be `cd ${MBEDCRYPTO_PATH} && git apply ${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/*.patch`")
+    endif()
+
+    target_include_directories(bl1_1_crypto_mbedcrypto
+        PUBLIC
+            ./crypto
+    )
+
+    target_compile_definitions(bl1_1_crypto_mbedcrypto
+        PUBLIC
+            MBEDTLS_CONFIG_FILE="mbedcrypto_config.h"
+            # Workaround for https://github.com/ARMmbed/mbedtls/issues/1077
+            $<$<OR:$<STREQUAL:${CMAKE_SYSTEM_ARCHITECTURE},armv8-m.base>,$<STREQUAL:${CMAKE_SYSTEM_ARCHITECTURE},armv6-m>>:MULADDC_CANNOT_USE_R7>
+    )
+
+    target_compile_options(bl1_1_crypto_mbedcrypto
+        PRIVATE
+            $<$<C_COMPILER_ID:GNU>:-Wno-unused-parameter>
+            $<$<C_COMPILER_ID:ARMClang>:-Wno-unused-parameter>
+    )
+endif()

bl1/bl1_1/shared_lib/crypto/crypto_mbedcrypto.c

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "crypto.h"
+
+#include <string.h>
+#include "mbedtls/sha256.h"
+#include "mbedtls/aes.h"
+#include "mbedtls/memory_buffer_alloc.h"
+#include "otp.h"
+
+static int mbedtls_is_initialised = 0;
+static uint8_t mbedtls_memory_buf[256];
+
+static void mbedtls_init(uint8_t mbedtls_memory_buf[], size_t size)
+{
+    mbedtls_memory_buffer_alloc_init(mbedtls_memory_buf,
+                                     size);
+}
+
+int32_t bl1_sha256_compute(const uint8_t *data,
+                           size_t data_length,
+                           uint8_t *hash)
+{
+    int rc = 0;
+    fih_int fih_rc;
+    mbedtls_sha256_context ctx;
+
+    if (!mbedtls_is_initialised) {
+        mbedtls_init(mbedtls_memory_buf, sizeof(mbedtls_memory_buf));
+        mbedtls_is_initialised = 1;
+    }
+
+    mbedtls_sha256_init(&ctx);
+
+    rc = mbedtls_sha256_starts(&ctx, 0);
+    fih_rc = fih_int_encode_zero_equality(rc);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        goto out;
+    }
+
+    rc = mbedtls_sha256_update(&ctx, data, data_length);
+    fih_rc = fih_int_encode_zero_equality(rc);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        goto out;
+    }
+
+    rc = mbedtls_sha256_finish(&ctx, hash);
+    fih_rc = fih_int_encode_zero_equality(rc);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        goto out;
+    }
+
+out:
+    mbedtls_sha256_free(&ctx);
+    FIH_RET(fih_rc);
+}
+
+int32_t bl1_aes_256_ctr_decrypt(enum tfm_bl1_key_id_t key_id,
+                                uint8_t *counter,
+                                const uint8_t *ciphertext,
+                                size_t ciphertext_length,
+                                uint8_t *plaintext)
+{
+    int rc = 0;
+    uint8_t stream_block[16];
+    uint8_t key_buf[32];
+    mbedtls_aes_context ctx;
+    size_t nc_off = 0;
+
+    if (ciphertext_length == 0) {
+        return 0;
+    }
+
+    if (ciphertext == NULL || plaintext == NULL || counter == NULL) {
+        return -2;
+    }
+
+    if (!mbedtls_is_initialised) {
+        mbedtls_init(mbedtls_memory_buf, sizeof(mbedtls_memory_buf));
+        mbedtls_is_initialised = 1;
+    }
+
+    mbedtls_aes_init(&ctx);
+    rc = otp_read_key(key_id, key_buf);
+    if (rc) {
+        goto out;
+    }
+
+    rc = mbedtls_aes_setkey_enc(&ctx, key_buf, 256);
+    if (rc) {
+        goto out;
+    }
+
+    rc = mbedtls_aes_crypt_ctr(&ctx, ciphertext_length, &nc_off, counter,
+                               stream_block, ciphertext, plaintext);
+    if (rc) {
+        goto out;
+    }
+
+out:
+    mbedtls_aes_free(&ctx);
+
+    memset(key_buf, 0, 32);
+    memset(stream_block, 0, 16);
+
+    return rc;
+}

bl1/bl1_1/shared_lib/crypto/mbedcrypto_config.h

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+
+#ifndef BL1_1_MBEDCRYPO_CONFIG_H
+#define BL1_1_MBEDCRYPO_CONFIG_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define MBEDTLS_PLATFORM_C
+#define MBEDTLS_PLATFORM_MEMORY
+#define MBEDTLS_MEMORY_BUFFER_ALLOC_C
+
+#define MBEDTLS_SHA256_C
+#define MBEDTLS_SHA224_C
+
+#define MBEDTLS_AES_C
+#define MBEDTLS_CIPHER_MODE_CTR
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_1_MBEDCRYPO_CONFIG_H */

bl1/bl1_1/shared_lib/interface/crypto.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_1_CRYPTO_H
+#define BL1_1_CRYPTO_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#define CTR_IV_LEN 16
+
+#include "crypto_key_defs.h"
+#include "fih.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Calculates a SHA-256 hash of the input data */
+fih_int bl1_sha256_compute(const uint8_t *data,
+                           size_t data_length,
+                           uint8_t *hash);
+
+/* Performs AES-256-CTR decryption */
+int32_t bl1_aes_256_ctr_decrypt(enum tfm_bl1_key_id_t key_id,
+                                uint8_t *counter,
+                                const uint8_t *ciphertext,
+                                size_t ciphertext_length,
+                                uint8_t *plaintext);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_1_CRYPTO_H */

bl1/bl1_1/shared_lib/interface/crypto_key_defs.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_1_CRYPTO_KEY_DEFS_H
+#define BL1_1_CRYPTO_KEY_DEFS_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef HUK_SIZE
+#define HUK_SIZE (32)
+#endif /* HUK_SIZE */
+
+#ifndef BL2_ENCRYPTION_KEY_SIZE
+#define BL2_ENCRYPTION_KEY_SIZE (32)
+#endif /* BL2_ENCRYPTION_KEY_SIZE */
+
+ enum tfm_bl1_key_id_t {
+    TFM_BL1_KEY_HUK,
+    TFM_BL1_KEY_BL2_ENCRYPTION,
+#ifdef TEST_BL1_1
+    TFM_BL1_KEY_TEST_1,
+    TFM_BL1_KEY_TEST_2,
+#endif /* TEST_BL1_1 */
+
+  tfm_bl1_key_max,
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_1_CRYPTO_KEY_DEFS_H */

bl1/bl1_1/shared_lib/interface/log.h

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_LOG_H
+#define BL1_LOG_H
+
+#include "uart_stdout.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef TFM_BL1_LOGGING
+#define BL1_LOG(str) do { \
+    const unsigned char msg[] = str; \
+    stdio_output_string(msg, sizeof(msg)); \
+} while (0)
+#else
+#define BL1_LOG(str)
+#endif /* TFM_BL1_LOGGING */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_LOG_H */

bl1/bl1_1/shared_lib/interface/otp.h

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_1_OTP_H
+#define BL1_1_OTP_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "fih.h"
+#include "crypto_key_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef BL1_2_HASH_SIZE
+#define BL1_2_HASH_SIZE 32
+#endif /* BL1_2_HASH_SIZE */
+
+#ifndef BL2_HASH_SIZE
+#define BL2_HASH_SIZE 32
+#endif /* BL1_2_HASH_SIZE */
+
+#ifndef TFM_OTP_NV_COUNTER_NUMBER
+#define TFM_OTP_NV_COUNTER_NUMBER 4u
+#endif /* !TFM_OTP_NV_COUNTER_NUMBER */
+
+#ifndef TFM_OTP_NV_COUNTER_SIZE_IN_BITS
+#define TFM_OTP_NV_COUNTER_SIZE_IN_BITS 32u
+#endif /* !TFM_OTP_NV_COUNTER_SIZE_IN_BITS */
+
+/* Use ceiling division so we always have at least the correct amount of bits */
+#define TFM_OTP_NV_COUNTER_BYTES ((TFM_OTP_NV_COUNTER_SIZE_IN_BITS + 7) / 8)
+
+enum tfm_bl1_nv_counter_id_t {
+    BL1_NV_COUNTER_ID_BL2_IMAGE,
+};
+
+/* Initialise OTP system */
+fih_int bl1_otp_init(void);
+
+/* Get hash of OTP bootloader image */
+fih_int bl1_otp_read_bl1_2_image_hash(uint8_t *hash);
+
+/* Get hash of OTP bootloader image */
+fih_int bl1_otp_read_bl2_image_hash(uint8_t *hash);
+
+/* Gets value of NV counter */
+fih_int bl1_otp_read_nv_counter(enum tfm_bl1_nv_counter_id_t counter_id,
+                                uint32_t *count);
+
+/* Sets value of NV counter, if greater than current */
+fih_int bl1_otp_write_nv_counter(enum tfm_bl1_nv_counter_id_t counter_id,
+                                 uint32_t count);
+
+/* Load the key with the given ID into the key buf */
+fih_int bl1_otp_read_key(enum tfm_bl1_key_id_t key_id, uint8_t *key_buf);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_1_OTP_H */

bl1/bl1_1/shared_lib/interface/trng.h

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* Generates random bytes */
+int32_t bl1_trng_generate_random(uint8_t *output, size_t output_size);

bl1/bl1_1/shared_lib/interface/util.h

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_UTIL_H
+#define BL1_UTIL_H
+
+#include <stddef.h>
+
+#include "fih.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief                  Compares the given regions of memory for equality.
+ *
+ * \param[in]  ptr1        Pointer to the first memory region.
+ * \param[in]  ptr2        Pointer to the second memory region.
+ * \param[in]  size        Size of the two memory regions.
+ *
+ * \note                   This function is hardened against both fault
+ *                         injection and differential power analysis, and is
+ *                         constant time (except for time taken for TRNG
+ *                         invocations).
+ *
+ * \note                   The ordering of comparisons in this function is
+ *                         randomised. This is done by comparing in the forward
+ *                         direction for a uniform random number of elements
+ *                         between 1 and 8 inclusive, and then comparing in the
+ *                         reverse direction for a uniform random number of
+ *                         elements between 1 and 8 inclusive. This is repeated
+ *                         until the comparison is done.
+ *
+ * \note                   This function only checks equality, and does not
+ *                         return any information about the elements which
+ *                         differ, so is semantically different to memcmp.
+ *
+ * \retval FIH_SUCCESS     The two given memory regions are identical.
+ * \retval FIH_FAILURE     The two given memory regions are not identical, or a
+ *                         failure has occurred and they cannot be compared.
+ */
+fih_int bl_secure_memeql(const void *ptr1, const void *ptr2, size_t num);
+
+/**
+ * \brief                  Copies the values in memory at source to the memory
+ *                         at destination, for a given size.
+ *
+ * \param[in]  source      Source memory to copy from.
+ * \param[in]  num         Number of bytes to be copied.
+ * \param[out] destination Destination memory to copy into.
+ *
+ * \note                   This function is hardened against both fault
+ *                         injection and differential power analysis.
+ *
+ * \note                   The ordering of copying in this function is
+ *                         randomised. This is done by comparing in the forward
+ *                         direction for a uniform random number of elements
+ *                         between 1 and 8 inclusive, and then copying in the
+ *                         reverse direction for a uniform random number of
+ *                         elements between 1 and 8 inclusive. This is repeated
+ *                         until the copying is done.
+ *
+ * \retval FIH_SUCCESS     The copy completed successfully.
+ * \retval FIH_FAILURE     A failure has occurred and the copy has not been
+ *                         completed.
+ */
+fih_int bl_secure_memcpy(void *destination, const void *source, size_t num);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_UTIL_H */

bl1/bl1_1/shared_lib/otp/otp_default.c

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "otp.h"
+
+#include <stdint.h>
+
+#include "region_defs.h"
+#include "tfm_plat_otp.h"
+#include "tfm_plat_nv_counters.h"
+#include "util.h"
+
+#ifdef TEST_BL1_1
+extern uint8_t tfm_bl1_key_test_1_buf[];
+extern uint8_t tfm_bl1_key_test_2_buf[];
+#endif /* TEST_BL1_1 */
+
+fih_int bl1_otp_read(uint8_t *dst, uint8_t *src, size_t size);
+fih_int bl1_otp_write(uint8_t *dst, uint8_t *src, size_t size);
+
+fih_int bl1_otp_init(void)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_otp_init();
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    plat_err = tfm_plat_init_nv_counter();
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    return fih_rc;
+}
+
+fih_int bl1_otp_read_bl1_2_image_hash(uint8_t *hash)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_otp_read(PLAT_OTP_ID_BL1_2_IMAGE_HASH, BL1_2_HASH_SIZE,
+                                 hash);
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    FIH_RET(fih_rc);
+}
+
+fih_int bl1_otp_read_bl2_image_hash(uint8_t *hash)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_otp_read(PLAT_OTP_ID_BL2_IMAGE_HASH, BL2_HASH_SIZE,
+                                 hash);
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    FIH_RET(fih_rc);
+}
+
+fih_int bl1_otp_read_nv_counter(enum tfm_bl1_nv_counter_id_t counter_id,
+                                uint32_t *count)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_read_nv_counter(PLAT_NV_COUNTER_BL1_0,
+                                        sizeof(uint32_t), (uint8_t *)count);
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    FIH_RET(fih_rc);
+}
+
+fih_int bl1_otp_write_nv_counter(enum tfm_bl1_nv_counter_id_t counter_id,
+                                 uint32_t count)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    plat_err = tfm_plat_set_nv_counter(PLAT_NV_COUNTER_BL1_0, count);
+    fih_rc = fih_int_encode_zero_equality(plat_err);
+
+    FIH_RET(fih_rc);
+}
+
+fih_int bl1_otp_read_key(enum tfm_bl1_key_id_t key_id, uint8_t *key_buf)
+{
+    fih_int fih_rc;
+    enum tfm_plat_err_t plat_err;
+
+    switch (key_id) {
+    case TFM_BL1_KEY_HUK:
+        plat_err = tfm_plat_otp_read(PLAT_OTP_ID_HUK, 32, key_buf);
+        fih_rc = fih_int_encode_zero_equality(plat_err);
+        break;
+    case TFM_BL1_KEY_BL2_ENCRYPTION:
+        plat_err = tfm_plat_otp_read(PLAT_OTP_ID_KEY_BL2_ENCRYPTION, 32,
+                                     key_buf);
+        fih_rc = fih_int_encode_zero_equality(plat_err);
+        break;
+#ifdef TEST_BL1_1
+    case TFM_BL1_KEY_TEST_1:
+        memcpy(key_buf, tfm_bl1_key_test_1_buf, 32);
+        fih_rc = FIH_SUCCESS;
+        break;
+    case TFM_BL1_KEY_TEST_2:
+        memcpy(key_buf, tfm_bl1_key_test_2_buf, 32);
+        fih_rc = FIH_SUCCESS;
+        break;
+#endif /* TEST_BL1_1 */
+    default:
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_RET(fih_rc);
+}

bl1/bl1_1/shared_lib/trng/trng_dummy.c

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "trng.h"
+#include <string.h>
+
+int32_t bl1_trng_generate_random(uint8_t *output, size_t output_size)
+{
+    if (output_size == 0) {
+        return 0;
+    }
+
+    if (output == NULL) {
+        return -1;
+    }
+
+    memset(output, 4, output_size);
+    return 0;
+}
+
+unsigned char fih_delay_random_uchar(void)
+{
+    return 4;
+}

bl1/bl1_1/shared_lib/util.c

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "util.h"
+
+#include "trng.h"
+#include "fih.h"
+
+/* The average roll should be 4 by the CLT, and our secrets are usually 32
+ * bytes. Do 8 + 3 so there's a bit of extra. Should always be odd so the reseed
+ * oscillates between before and after the forward step.
+ */
+#define RNG_CHUNK_BYTES  (11)
+/* Reverse every between 0 and 7 bytes */
+#define SHUFFLE_MASK     (0x7)
+
+fih_int bl_secure_memeql(const void *ptr1, const void *ptr2, size_t num)
+{
+    fih_int is_equal = FIH_SUCCESS;
+    size_t block_start;
+    size_t block_end;
+    size_t curr = 0;
+    uint8_t rnd[RNG_CHUNK_BYTES];
+    size_t rnd_curr_idx = sizeof(rnd);
+
+    /* Do comparison. Every n bytes (where n is random between 1 and 9),
+     * reverse the direction.
+     */
+    while (curr < num) {
+        /* Only generate more entropy if we've run out */
+        if (rnd_curr_idx == sizeof(rnd)) {
+            bl1_trng_generate_random(rnd, sizeof(rnd));
+            rnd_curr_idx = 0;
+        }
+
+        /* Forward case. Always at least one byte */
+        block_start = curr;
+        block_end = curr + (rnd[rnd_curr_idx++] & SHUFFLE_MASK) + 1;
+
+        if (block_end > num) {
+            block_end = num;
+        }
+
+        for (; curr < block_end; curr++) {
+            if (((uint8_t *)ptr1)[curr] != ((uint8_t *)ptr2)[curr]) {
+                is_equal = FIH_FAILURE;
+            }
+        }
+
+
+        /* Only generate more entropy if we've run out */
+        if (rnd_curr_idx == sizeof(rnd)) {
+            bl1_trng_generate_random(rnd, sizeof(rnd));
+            rnd_curr_idx = 0;
+        }
+
+        /* Reverse case. Always at least one byte */
+        block_start = curr;
+        block_end = curr + (rnd[rnd_curr_idx++] & SHUFFLE_MASK) + 1;
+
+        if (block_end > num) {
+            block_end = num;
+        }
+
+        for (curr = block_end - 1; curr >= block_start; curr--) {
+            if (((uint8_t *)ptr1)[curr] != ((uint8_t *)ptr2)[curr]) {
+                is_equal = FIH_FAILURE;
+            }
+        }
+        curr = block_end;
+    }
+    if (curr != num) {
+        FIH_PANIC;
+    }
+
+    FIH_RET(is_equal);
+}
+
+fih_int bl_secure_memcpy(void *destination, const void *source, size_t num)
+{
+    size_t block_start;
+    size_t block_end;
+    int64_t curr = 0;
+    uint8_t rnd[RNG_CHUNK_BYTES];
+    size_t rnd_curr_idx = sizeof(rnd);
+
+    /* Do copy. Every n bytes (where n is random between 1 and 17), reverse the
+     * direction.
+     */
+    while (curr < num) {
+        /* Only generate more entropy if we've run out */
+        if (rnd_curr_idx == sizeof(rnd)) {
+            bl1_trng_generate_random(rnd, sizeof(rnd));
+            rnd_curr_idx = 0;
+        }
+
+        /* Forward case */
+        bl1_trng_generate_random(rnd, sizeof(rnd));
+        block_start = curr;
+        block_end = curr + (rnd[rnd_curr_idx++] & SHUFFLE_MASK) + 1;
+
+        if (block_end > num) {
+            block_end = num;
+        }
+
+        for (; curr < block_end; curr++) {
+            ((uint8_t *)destination)[curr] = ((uint8_t *)source)[curr];
+        }
+
+
+        /* Only generate more entropy if we've run out */
+        if (rnd_curr_idx == sizeof(rnd)) {
+            bl1_trng_generate_random(rnd, sizeof(rnd));
+            rnd_curr_idx = 0;
+        }
+
+        /* Reverse case */
+        block_start = curr;
+        block_end = curr + (rnd[rnd_curr_idx++] & SHUFFLE_MASK) + 1;
+
+        if (block_end > num) {
+            block_end = num;
+        }
+
+        for (curr = block_end - 1; block_start <= curr; curr--) {
+            ((uint8_t *)destination)[curr] = ((uint8_t *)source)[curr];
+        }
+        curr = block_end;
+    }
+    if (curr != num) {
+        FIH_PANIC;
+    }
+
+    FIH_RET(FIH_SUCCESS);
+}

bl1/bl1_1/signing_layout.c

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+#include "region_defs.h"
+/* Enumeration that is used by the create_img.py script
+ * for correct binary generation when nested macros are used
+ */
+enum image_attributes {
+    RE_BL1_2_BIN_SIZE = BL1_2_CODE_SIZE,
+};

bl1/bl1_2/CMakeLists.txt

@@ -0,0 +1,97 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+add_subdirectory(lib)
+
+add_executable(bl1_2)
+
+set_target_properties(bl1_2
+    PROPERTIES
+        SUFFIX ".axf"
+        RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+)
+
+add_convert_to_bin_target(bl1_2)
+
+target_link_options(bl1_2
+    PRIVATE
+        $<$<C_COMPILER_ID:GNU>:-Wl,-Map=${CMAKE_BINARY_DIR}/bin/bl1_2.map>
+        $<$<C_COMPILER_ID:ARMClang>:--map>
+        $<$<C_COMPILER_ID:IAR>:--map\;${CMAKE_BINARY_DIR}/bin/bl1_2.map>
+)
+
+target_sources(bl1_2
+    PRIVATE
+        main.c
+)
+
+target_link_libraries(bl1_2
+    PRIVATE
+        bl1_1_shared_lib_interface
+        bl1_2_lib
+        platform_bl1_interface
+        $<$<BOOL:${TEST_BL1_2}>:bl1_2_tests>
+)
+
+target_compile_definitions(bl1_2
+    PRIVATE
+        $<$<BOOL:${TFM_BL1_MEMORY_MAPPED_FLASH}>:TFM_BL1_MEMORY_MAPPED_FLASH>
+        $<$<BOOL:${TEST_BL1_2}>:TEST_BL1_2>
+)
+
+target_link_shared_code(bl1_2
+    bl1_1
+)
+
+add_dependencies(bl1_2
+    bl1_1_shared_lib
+)
+
+################################################################################
+
+set(FLASH_AREA_NUM ${TFM_BL2_IMAGE_FLASH_AREA_NUM})
+configure_file(signing_layout.c.in signing_layout_bl2.c @ONLY)
+
+add_library(signing_layout_bl2 OBJECT ${CMAKE_CURRENT_BINARY_DIR}/signing_layout_bl2.c)
+target_compile_options(signing_layout_bl2
+    PRIVATE
+        $<$<C_COMPILER_ID:GNU>:-E\;-xc>
+        $<$<C_COMPILER_ID:ARMClang>:-E\;-xc>
+        $<$<C_COMPILER_ID:IAR>:--preprocess=ns\;$<TARGET_OBJECTS:signing_layout_bl2>>
+)
+target_link_libraries(signing_layout_bl2
+    PRIVATE
+        platform_region_defs
+)
+
+################################################################################
+get_target_property(bin_dir bl2 RUNTIME_OUTPUT_DIRECTORY)
+
+add_custom_target(bl2_signed_bin
+    ALL
+    SOURCES bl2_signed.bin
+    SOURCES bl2_signed_hash.bin
+    SOURCES ${bin_dir}/bl2_signed.bin
+    SOURCES ${bin_dir}/bl2_signed_hash.bin
+)
+
+add_custom_command(OUTPUT bl2_signed.bin bl2_signed_hash.bin
+    OUTPUT ${bin_dir}/bl2_signed.bin ${bin_dir}/bl2_signed_hash.bin
+    DEPENDS $<TARGET_FILE_DIR:bl2>/bl2.bin bl2_bin signing_layout_bl2
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_bl2_img.py
+    COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/scripts/create_bl2_img.py
+                    --input_file $<TARGET_FILE_DIR:bl2>/bl2.bin
+                    --img_output_file bl2_signed.bin
+                    --hash_output_file bl2_signed_hash.bin
+                    --encrypt_key_file ${TFM_BL2_ENCRYPTION_KEY_PATH}
+                    --signing_layout_file $<TARGET_OBJECTS:signing_layout_bl2>
+                    --img_version ${TFM_BL1_IMAGE_VERSION_BL2}
+                    --img_security_counter ${TFM_BL1_IMAGE_SECURITY_COUNTER_BL2}
+                    --header_size ${BL1_HEADER_SIZE}
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/bl2_signed.bin $<TARGET_FILE_DIR:bl2>
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/bl2_signed_hash.bin $<TARGET_FILE_DIR:bl2>
+)

bl1/bl1_2/bl2_dummy_encryption_key.bin

@@ -0,0 +1 @@
+
#Eg‰
#Eg‰
#Eg‰
#Eg‰
#Eg‰
#Eg‰
#

bl1/bl1_2/lib/CMakeLists.txt

@@ -0,0 +1,28 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+add_library(bl1_2_lib STATIC)
+
+target_include_directories(bl1_2_lib
+    PUBLIC
+        ./interface
+    PRIVATE
+        .
+)
+
+target_sources(bl1_2_lib
+    PRIVATE
+        ./image.c
+)
+
+target_link_libraries(bl1_2_lib
+    PUBLIC
+        platform_common_interface
+    PRIVATE
+        platform_bl1_interface
+        bl1_1_shared_lib_interface
+)

bl1/bl1_2/lib/image.c

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "image.h"
+
+#include "Driver_Flash.h"
+#include "flash_layout.h"
+#include "region_defs.h"
+#include "fih.h"
+
+extern ARM_DRIVER_FLASH FLASH_DEV_NAME;
+
+int32_t __WEAK bl1_image_get_flash_offset(uint32_t image_id)
+{
+    switch (image_id) {
+    case 0:
+        return FLASH_AREA_0_OFFSET;
+    case 1:
+        return FLASH_AREA_1_OFFSET;
+    default:
+        FIH_PANIC;
+    }
+}
+
+fih_int bl1_image_copy_to_sram(uint32_t image_id, uint8_t *out)
+{
+    uint32_t flash_offset;
+    fih_int fih_rc;
+
+    flash_offset = bl1_image_get_flash_offset(image_id);
+    fih_rc = fih_int_encode(FLASH_DEV_NAME.ReadData(flash_offset, out,
+                                                    sizeof(struct bl1_2_image_t)));
+
+    FIH_RET(fih_rc);
+}

bl1/bl1_2/lib/interface/image.h

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef BL1_2_IMAGE_H
+#define BL1_2_IMAGE_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include "crypto.h"
+#include "region_defs.h"
+#include "cmsis_compiler.h"
+#include "fih.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define BL1_2_IMAGE_DECRYPT_MAGIC_EXPECTED 0xDEADBEEF
+#define PAD_SIZE (BL1_HEADER_SIZE - CTR_IV_LEN - 1292 - \
+                  sizeof(struct tfm_bl1_image_version_t) - 2 * sizeof(uint32_t))
+
+__PACKED_STRUCT tfm_bl1_image_version_t {
+    uint8_t  major;
+    uint8_t  minor;
+    uint16_t revision;
+    uint32_t build_num;
+};
+
+__PACKED_STRUCT bl1_2_image_t {
+    __PACKED_STRUCT  {
+        uint8_t ctr_iv[CTR_IV_LEN];
+        uint8_t sig[1292];
+    } header;
+    __PACKED_STRUCT {
+        struct tfm_bl1_image_version_t version;
+        uint32_t security_counter;
+
+        __PACKED_STRUCT {
+            uint32_t decrypt_magic;
+            uint8_t pad[PAD_SIZE];
+            uint8_t data[IMAGE_BL2_CODE_SIZE];
+        } encrypted_data;
+    } protected_values;
+};
+
+int32_t bl1_image_get_flash_offset(uint32_t image_id);
+
+fih_int bl1_image_copy_to_sram(uint32_t image_id, uint8_t *out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BL1_2_IMAGE_H */

bl1/bl1_2/main.c

@@ -0,0 +1,212 @@
+/*
+ * Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#include "crypto.h"
+#include "otp.h"
+#include "boot_hal.h"
+#include "uart_stdout.h"
+#include "fih.h"
+#include "util.h"
+#include "log.h"
+#include "image.h"
+#include "region_defs.h"
+
+extern uint32_t platform_code_is_bl1_2;
+
+static fih_int image_hash_check(struct bl1_2_image_t *img)
+{
+    uint8_t computed_bl2_hash[BL2_HASH_SIZE];
+    uint8_t stored_bl2_hash[BL2_HASH_SIZE];
+    fih_int fih_rc = FIH_FAILURE;
+
+    FIH_CALL(bl1_sha256_compute, fih_rc, (uint8_t *)&img->protected_values,
+                                         sizeof(img->protected_values),
+                                         computed_bl2_hash);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(fih_rc);
+    }
+
+    FIH_CALL(bl1_otp_read_bl2_image_hash, fih_rc, stored_bl2_hash);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(fih_rc);
+    }
+
+    FIH_CALL(bl_secure_memeql, fih_rc, computed_bl2_hash, stored_bl2_hash,
+                                       BL2_HASH_SIZE);
+    FIH_RET(fih_rc);
+}
+
+static fih_int is_image_security_counter_valid(struct bl1_2_image_t *img)
+{
+    uint32_t security_counter;
+    fih_int fih_rc;
+
+    FIH_CALL(bl1_otp_read_nv_counter, fih_rc, BL1_NV_COUNTER_ID_BL2_IMAGE,
+                                          &security_counter);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(FIH_FAILURE);
+    }
+
+    /* Encodes 0 to true and 1 to false, so the actual comparison is flipped */
+    FIH_RET(
+        fih_int_encode_zero_equality(security_counter
+                                     > img->protected_values.security_counter));
+}
+
+static fih_int is_image_signature_valid(struct bl1_2_image_t *img)
+{
+    fih_int fih_rc = FIH_FAILURE;
+
+#ifdef TFM_BL1_PQ_CRYPTO
+    /* TODO */
+#else
+    FIH_CALL(image_hash_check, fih_rc, img);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_RET(FIH_FAILURE);
+    }
+#endif /* TFM_BL1_PQ_CRYPTO */
+
+    FIH_RET(fih_rc);
+}
+
+fih_int validate_image_at_addr(struct bl1_2_image_t *image)
+{
+    fih_int fih_rc = FIH_FAILURE;
+
+    FIH_CALL(is_image_signature_valid, fih_rc, image);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] BL2 image signature failed to validate\r\n");
+        FIH_RET(FIH_FAILURE);
+    }
+    FIH_CALL(is_image_security_counter_valid, fih_rc, image);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] BL2 image security_counter failed to validate\r\n");
+        FIH_RET(FIH_FAILURE);
+    }
+
+    /* TODO work out if the image actually boots before updating the counter */
+    FIH_CALL(bl1_otp_write_nv_counter, fih_rc, BL1_NV_COUNTER_ID_BL2_IMAGE,
+                                               image->protected_values.security_counter);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] NV counter update failed\r\n");
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_RET(FIH_SUCCESS);
+}
+
+fih_int copy_and_decrypt_image(uint32_t image_id)
+{
+    int rc;
+#ifdef TFM_BL1_MEMORY_MAPPED_FLASH
+    fih_int fih_rc;
+#endif /* TFM_BL1_MEMORY_MAPPED_FLASH */
+    struct bl1_2_image_t *image_to_decrypt;
+    struct bl1_2_image_t *image_after_decrypt =
+        (struct bl1_2_image_t *)BL2_IMAGE_START;
+
+#ifdef TFM_BL1_MEMORY_MAPPED_FLASH
+    /* If we have memory-mapped flash, we can do the decrypt directly from the
+     * flash and output to the SRAM. This is significantly faster if the AES
+     * invocation calls through to a crypto accelerator with a DMA, and slightly
+     * faster otherwise.
+     */
+    image_to_decrypt = (struct bl1_2_image_t *)(FLASH_BASE_ADDRESS +
+                       bl1_image_get_flash_offset(image_id));
+
+    /* Copy everything that isn't encrypted, to prevent TOCTOU attacks and
+     * simplify logic.
+     */
+    FIH_CALL(bl_secure_memcpy, fih_rc, image_after_decrypt,
+                        image_to_decrypt,
+                        sizeof(struct bl1_2_image_t) -
+                        sizeof(image_after_decrypt->protected_values.encrypted_data));
+#else
+    /* If the flash isn't memory-mapped, defer to the flash driver to copy the
+     * entire block in to SRAM. We'll then do the decrypt in-place.
+     */
+    bl1_image_copy_to_sram(image_id, (uint8_t *)BL2_IMAGE_START);
+    image_to_decrypt = (struct bl1_2_image_t *)BL2_IMAGE_START;
+#endif /* TFM_BL1_MEMORY_MAPPED_FLASH */
+
+    rc = bl1_aes_256_ctr_decrypt(TFM_BL1_KEY_BL2_ENCRYPTION,
+                        image_to_decrypt->header.ctr_iv,
+                        (uint8_t *)&image_to_decrypt->protected_values.encrypted_data,
+                        sizeof(image_after_decrypt->protected_values.encrypted_data),
+                        (uint8_t *)&image_after_decrypt->protected_values.encrypted_data);
+    if (rc) {
+        FIH_RET(fih_int_encode_zero_equality(rc));
+    }
+
+    if (image_after_decrypt->protected_values.encrypted_data.decrypt_magic
+            != BL1_2_IMAGE_DECRYPT_MAGIC_EXPECTED) {
+        FIH_RET(FIH_FAILURE);
+    }
+
+    FIH_RET(FIH_SUCCESS);
+}
+
+static fih_int validate_image(uint32_t image_id)
+{
+    fih_int fih_rc = FIH_FAILURE;
+    struct bl1_2_image_t *image;
+
+    FIH_CALL(copy_and_decrypt_image, fih_rc, image_id);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] BL2 image failed to decrypt\r\n");
+        FIH_RET(FIH_FAILURE);
+    }
+    image = (struct bl1_2_image_t *)BL2_IMAGE_START;
+
+    BL1_LOG("[INF] BL2 image decrypted successfully\r\n");
+
+    FIH_CALL(validate_image_at_addr, fih_rc, image);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[ERR] BL2 image failed to validate\r\n");
+        FIH_RET(FIH_FAILURE);
+    }
+
+    BL1_LOG("[INF] BL2 image validated successfully\r\n");
+
+    FIH_RET(FIH_SUCCESS);
+}
+
+int main(void)
+{
+    platform_code_is_bl1_2 = 1;
+    fih_int fih_rc = FIH_FAILURE;
+
+    fih_rc = fih_int_encode_zero_equality(boot_platform_init());
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_PANIC;
+    }
+    BL1_LOG("[INF] starting TF-M bl1_2\r\n");
+
+    fih_rc = fih_int_encode_zero_equality(boot_platform_post_init());
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        FIH_PANIC;
+    }
+
+#ifdef TEST_BL1_2
+    run_bl1_2_testsuite();
+#endif /* TEST_BL1_2 */
+
+    BL1_LOG("[INF] Attempting to boot image 0\r\n");
+    FIH_CALL(validate_image, fih_rc, 0);
+    if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+        BL1_LOG("[INF] Attempting to boot image 1\r\n");
+        FIH_CALL(validate_image, fih_rc, 1);
+        if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
+            FIH_PANIC;
+        }
+    }
+
+    BL1_LOG("[INF] Jumping to BL2\r\n");
+    boot_platform_quit((struct boot_arm_vector_table *)BL2_CODE_START);
+
+    FIH_PANIC;
+}

bl1/bl1_2/scripts/create_bl2_img.py

@@ -0,0 +1,112 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+import hashlib
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.backends import default_backend
+import secrets
+import argparse
+import os
+import sys
+sys.path.append(os.path.join(os.path.dirname(os.path.realpath(__file__)), "../../../bl2/ext/mcuboot/scripts"))
+import macro_parser
+import struct
+
+def struct_pack(objects, pad_to=0):
+    defstring = "<"
+    for obj in objects:
+        defstring += str(len(obj)) + "s"
+
+    size = struct.calcsize(defstring)
+    if size < pad_to:
+        defstring += str(pad_to - size) + "x"
+
+    return (bytes(struct.pack(defstring, *objects)))
+
+def parse_version(version_string):
+    version = [0, 0, 0, 0]
+    split = version_string.split("+")
+    if len(split) > 1:
+        version[3] = int(split[1])
+    split = split[0].split(".")
+    for i in range(len(split)):
+        version[i] = int(split[i])
+
+    return struct_pack([version[0].to_bytes(1, "little"),
+                        version[1].to_bytes(1, "little"),
+                        version[2].to_bytes(2, "little"),
+                        version[3].to_bytes(4, "little")])
+
+def sign_binary_blob(blob):
+    return int(0).to_bytes(1292, 'little') # TODO LMS
+
+def hash_binary_blob(blob):
+   hash = hashlib.sha256()
+   hash.update(blob)
+   return hash.digest()
+
+def encrypt_binary_blob(blob, counter_val):
+    with open(args.encrypt_key_file, "rb") as encrypt_key_file:
+        encrypt_key = encrypt_key_file.read()
+
+    cipher = Cipher(algorithms.AES(encrypt_key), modes.CTR(counter_val))
+    return cipher.encryptor().update(blob)
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--input_file", help="the image to process", required=True)
+parser.add_argument("--img_version", help="version of the image", required=True)
+parser.add_argument("--img_security_counter", help="Secuity counter value for the image", required=True)
+parser.add_argument("--encrypt_key_file", help="encryption key file", required=True)
+parser.add_argument("--sign_key_file", help="signing key file", required=False)
+parser.add_argument("--img_output_file", help="image output file", required=True)
+parser.add_argument("--hash_output_file", help="hash output file", required=False)
+parser.add_argument("--signing_layout_file", help="signing layout file", required=True)
+parser.add_argument("--header_size", help="size of the header", required=True)
+args = parser.parse_args()
+
+with open(args.input_file, "rb") as in_file:
+    bl2_code = in_file.read()
+
+counter_val = secrets.token_bytes(12) + int(0).to_bytes(4, 'little')
+
+version = parse_version(args.img_version)
+
+bl2_partition_size = macro_parser.evaluate_macro(args.signing_layout_file,
+                                    ".*(RE_BL2_BIN_SIZE) = *(.*)",
+                                    1, 2, True)['RE_BL2_BIN_SIZE']
+
+plaintext = struct_pack([
+    int("0xDEADBEEF", 16).to_bytes(4, 'little'),
+    int(0).to_bytes(int(args.header_size, 0) - (1292 + 16 + 8 + 4 + 4), 'little'),
+    bl2_code,
+    ],
+    pad_to=bl2_partition_size - (1292 + 16 + 8 + 4))
+
+ciphertext = encrypt_binary_blob(plaintext, counter_val)
+
+data_to_sign = struct_pack([
+    version,
+    int(args.img_security_counter, 16).to_bytes(4, 'little'),
+    plaintext,
+    ])
+
+hash = hash_binary_blob(data_to_sign)
+sig = sign_binary_blob(data_to_sign)
+
+image = struct_pack([
+    counter_val,
+    sig,
+    version,
+    int(args.img_security_counter, 16).to_bytes(4, 'little'),
+    ciphertext,
+    ])
+
+with open(args.img_output_file, "wb") as img_out_file:
+    img_out_file.write(image)
+
+with open(args.hash_output_file, "wb") as hash_out_file:
+    hash_out_file.write(hash)

bl1/bl1_2/signing_layout.c.in

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+#include "flash_layout.h"
+/* Enumeration that is used by the create_img.py script
+ * for correct binary generation when nested macros are used
+ */
+enum image_attributes {
+    RE_BL2_BIN_SIZE = FLASH_AREA_@FLASH_AREA_NUM@_SIZE,
+};

bl1/config/bl1_config_default.cmake

@@ -0,0 +1,26 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+set(TFM_BL2_ENCRYPTION_KEY_PATH         ${CMAKE_SOURCE_DIR}/bl1/bl1_2/bl2_dummy_encryption_key.bin CACHE STRING "Path to binary key to use for encrypting BL2")
+set(TFM_BL2_IMAGE_FLASH_AREA_NUM        0           CACHE STRING    "Which flash area BL2 is stored in")
+
+set(TFM_BL1_MEMORY_MAPPED_FLASH         ON          CACHE BOOL      "Whether BL1 can directly access flash content")
+
+set(TFM_BL1_LOGGING                     ON          CACHE BOOL      "Whether BL1 will log to uart")
+set(TFM_BL1_DEFAULT_OTP                 ON          CACHE BOOL      "Whether BL1_1 will use default OTP memory")
+set(TFM_BL1_DEFAULT_PROVISIONING        ON          CACHE BOOL      "Whether BL1_1 will use default provisioning")
+set(TFM_BL1_SOFTWARE_CRYPTO             ON          CACHE BOOL      "Whether BL1_1 will use software crypto")
+set(TFM_BL1_DUMMY_TRNG                  ON          CACHE BOOL      "Whether BL1_1 will use dummy TRNG")
+
+set(TFM_BL1_IMAGE_VERSION_BL2           "1.9.0+0"   CACHE STRING    "Image version of BL2 image")
+set(TFM_BL1_IMAGE_SECURITY_COUNTER_BL2  1           CACHE STRING    "Security counter value to include with BL2 image")
+
+set(TFM_BL1_2_IN_OTP                    TRUE        CACHE BOOL      "Whether BL1_2 is stored in OTP")
+
+set(BL1_HEADER_SIZE                     0x800       CACHE STRING    "BL1 Header size")
+set(BL1_TRAILER_SIZE                    0x000       CACHE STRING    "BL1 Trailer size")
+

bl2/CMakeLists.txt

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -34,6 +34,7 @@ target_include_directories(bl2
 target_link_libraries(bl2
     PRIVATE
         tfm_boot_status
+        $<$<BOOL:${TEST_BL2}>:mcuboot_tests>
 )
 
 target_compile_options(bl2
@@ -51,6 +52,8 @@ target_link_options(bl2
 target_compile_definitions(bl2
     PRIVATE
         $<$<BOOL:${DEFAULT_MCUBOOT_FLASH_MAP}>:DEFAULT_MCUBOOT_FLASH_MAP>
+        $<$<BOOL:${PLATFORM_PSA_ADAC_SECURE_DEBUG}>:PLATFORM_PSA_ADAC_SECURE_DEBUG>
+        $<$<BOOL:${TEST_BL2}>:TEST_BL2>
 )
 
 add_convert_to_bin_target(bl2)
@@ -100,17 +103,17 @@ set(CMAKE_BUILD_TYPE ${MBEDCRYPTO_BUILD_TYPE})
 add_subdirectory(${MBEDCRYPTO_PATH} ${CMAKE_CURRENT_BINARY_DIR}/mbedcrypto EXCLUDE_FROM_ALL)
 set(CMAKE_BUILD_TYPE ${SAVED_BUILD_TYPE} CACHE STRING "Build type: [Debug, Release, RelWithDebInfo, MinSizeRel]" FORCE)
 
-if(NOT TARGET bl2_mbedcrypto)
-    message(FATAL_ERROR "Target bl2_mbedcrypto does not exist. Have the patches in ${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto been applied to the mbedcrypto repo at ${MBEDCRYPTO_PATH} ?
+if(NOT TARGET ${MBEDTLS_TARGET_PREFIX}mbedcrypto)
+    message(FATAL_ERROR "Target ${MBEDTLS_TARGET_PREFIX}mbedcrypto does not exist. Have the patches in ${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto been applied to the mbedcrypto repo at ${MBEDCRYPTO_PATH} ?
     Hint: The command might be `cd ${MBEDCRYPTO_PATH} && git apply ${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/*.patch`")
 endif()
 
-target_link_libraries(bl2_mbedcrypto
+target_link_libraries(${MBEDTLS_TARGET_PREFIX}mbedcrypto
     PUBLIC
         bl2_mbedcrypto_config
 )
 
-target_include_directories(bl2_mbedcrypto
+target_include_directories(${MBEDTLS_TARGET_PREFIX}mbedcrypto
     PUBLIC
         ${MBEDCRYPTO_PATH}/library
 )
@@ -133,7 +136,7 @@ target_compile_options(bl2_mbedx509
 ############################### CODE SHARING ###################################
 
 if (TFM_CODE_SHARING)
-    compiler_create_shared_code(bl2 ${CMAKE_CURRENT_SOURCE_DIR}/src/shared_symbol_template.txt)
+    target_share_symbols(bl2 ${CMAKE_CURRENT_SOURCE_DIR}/bl2_shared_symbols.txt)
 
     if (NOT EXISTS ${MBEDCRYPTO_PATH}/library/code_share.c)
         message(FATAL_ERROR "File ${MBEDCRYPTO_PATH}/library/code_share.c does not exist.

bl2/bl2_shared_symbols.txt

@@ -0,0 +1,18 @@
+mbedtls_asn1*
+mbedtls_mpi*
+mbedtls_platform*
+mbedtls_rsa*
+
+mbedtls_md*
+
+mbedtls_internal_sha256*
+mbedtls_sha256_free
+mbedtls_sha256_init
+mbedtls_sha256_finish
+mbedtls_sha256_starts
+
+mbedtls_calloc*
+mbedtls_free*
+
+mbedtls_exit*
+memset_func*

bl2/ext/mcuboot/CMakeLists.txt

@@ -77,8 +77,8 @@ configure_file(include/mcuboot_config/mcuboot_config.h.in
 
 find_package(Python3)
 
-set(FLASH_AREA_NUM 0)
 set(IMAGE_TYPE "S_IMAGE")
+set(FLASH_AREA_NUM ${MCUBOOT_S_IMAGE_FLASH_AREA_NUM})
 if (MCUBOOT_IMAGE_NUMBER GREATER 1)
     configure_file(signing_layout.c.in signing_layout_s.c @ONLY)
     add_library(signing_layout_s OBJECT ${CMAKE_CURRENT_BINARY_DIR}/signing_layout_s.c)
@@ -153,8 +153,8 @@ add_custom_command(OUTPUT tfm_s_signed.bin
     COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/tfm_s_signed.bin $<TARGET_FILE_DIR:bl2>
 )
 
-set(FLASH_AREA_NUM 1)
 set(IMAGE_TYPE "NS_IMAGE")
+set(FLASH_AREA_NUM ${MCUBOOT_NS_IMAGE_FLASH_AREA_NUM})
 configure_file(signing_layout.c.in signing_layout_ns.c @ONLY)
 
 add_library(signing_layout_ns OBJECT ${CMAKE_CURRENT_BINARY_DIR}/signing_layout_ns.c)

bl2/ext/mcuboot/bl2_main.c

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2012-2014 Wind River Systems, Inc.
- * Copyright (c) 2017-2021 Arm Limited.
+ * Copyright (c) 2017-2022 Arm Limited.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,6 +31,9 @@
 #include "uart_stdout.h"
 #include "tfm_plat_otp.h"
 #include "tfm_plat_provisioning.h"
+#ifdef TEST_BL2
+#include "mcuboot_suites.h"
+#endif /* TEST_BL2 */
 
 /* Avoids the semihosting issue */
 #if defined (__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
@@ -73,7 +76,7 @@ static void do_boot(struct boot_rsp *rsp)
                                          rsp->br_hdr->ih_hdr_size);
     }
 
-#if MCUBOOT_LOG_LEVEL > MCUBOOT_LOG_LEVEL_OFF
+#if MCUBOOT_LOG_LEVEL > MCUBOOT_LOG_LEVEL_OFF || TEST_BL2
     stdio_uninit();
 #endif
 
@@ -94,7 +97,7 @@ int main(void)
      */
     mbedtls_memory_buffer_alloc_init(mbedtls_mem_buf, BL2_MBEDTLS_MEM_BUF_LEN);
 
-#if MCUBOOT_LOG_LEVEL > MCUBOOT_LOG_LEVEL_OFF
+#if MCUBOOT_LOG_LEVEL > MCUBOOT_LOG_LEVEL_OFF || TEST_BL2
     stdio_init();
 #endif
 
@@ -128,6 +131,16 @@ int main(void)
         FIH_PANIC;
     }
 
+    /* Perform platform specific post-initialization */
+    if (boot_platform_post_init() != 0) {
+        BOOT_LOG_ERR("Platform post init failed");
+        FIH_PANIC;
+    }
+
+#ifdef TEST_BL2
+    (void)run_mcuboot_testsuite();
+#endif /* TEST_BL2 */
+
     FIH_CALL(boot_go, fih_rc, &rsp);
     if (fih_not_eq(fih_rc, FIH_SUCCESS)) {
         BOOT_LOG_ERR("Unable to find bootable image");

bl2/ext/mcuboot/flash_map_extended.c

@@ -1,7 +1,7 @@
 /*
  * Copyright (c) 2018 Nordic Semiconductor ASA
  * Copyright (c) 2015 Runtime Inc
- * Copyright (c) 2019-2020 Arm Limited.
+ * Copyright (c) 2019-2022 Arm Limited.
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -85,8 +85,7 @@ int flash_area_read_is_empty(const struct flash_area *fa, uint32_t off,
 
     BOOT_LOG_DBG("read_is_empty area=%d, off=%#x, len=%#x",
                  fa->fa_id, off, len);
-
-    rc = DRV_FLASH_AREA(fa)->ReadData(fa->fa_off + off, dst, len);
+    rc = flash_area_read(fa, off, dst, len);
     if (rc) {
         return -1;
     }

bl2/ext/mcuboot/include/target.h

@@ -96,6 +96,7 @@ by target"
 #endif
 #endif /* (MCUBOOT_IMAGE_NUMBER == 2) */
 
+#if defined(MCUBOOT_SWAP_USING_SCRATCH)
 #ifndef FLASH_AREA_SCRATCH_OFFSET
 #error "FLASH_AREA_SCRATCH_OFFSET must be defined by the target"
 #endif
@@ -108,6 +109,7 @@ by target"
 #error "FLASH DEV_NAME_SCRATCH and DEVICE_ID_SCRATCH must be simultaneously defined \
 or not by target"
 #endif
+#endif /* defined(MCUBOOT_SWAP_USING_SCRATCH) */
 
 #ifndef FLASH_DEV_NAME
 #error "BL2 supports CMSIS flash interface and device name must be specified"

bl2/ext/mcuboot/mcuboot_default_config.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2021, Arm Limited. All rights reserved.
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -7,9 +7,14 @@
 
 ########################## MCUBoot #############################################
 
+set(TEST_BL2                            OFF         CACHE BOOL      "Whether to build bl2 tests")
+
 set(DEFAULT_MCUBOOT_SECURITY_COUNTERS   ON          CACHE BOOL      "Whether to use the default security counter configuration defined by TF-M project")
 set(DEFAULT_MCUBOOT_FLASH_MAP           ON          CACHE BOOL      "Whether to use the default flash map defined by TF-M project")
 
+set(MCUBOOT_S_IMAGE_FLASH_AREA_NUM      0           CACHE STRING    "ID of the flash area containing the primary Secure image")
+set(MCUBOOT_NS_IMAGE_FLASH_AREA_NUM     1           CACHE STRING    "ID of the flash area containing the primary Non-Secure image")
+
 set(MCUBOOT_IMAGE_NUMBER                2           CACHE STRING    "Whether to combine S and NS into either 1 image, or sign each seperately")
 set(MCUBOOT_EXECUTION_SLOT              1           CACHE STRING    "Slot from which to execute the image, used for XIP mode")
 set(MCUBOOT_LOG_LEVEL                   "INFO"      CACHE STRING    "Level of logging to use for MCUboot [OFF, ERROR, WARNING, INFO, DEBUG]")
@@ -22,7 +27,7 @@ set(MCUBOOT_ALIGN_VAL                   1           CACHE STRING    "align optio
 # Specifying a scope of the accepted values of MCUBOOT_UPGRADE_STRATEGY for
 # platforms to choose a specific upgrade strategy for images. These certain
 # configurations will be used to facilitate the later validation.
-set_property(CACHE MCUBOOT_UPGRADE_STRATEGY PROPERTY STRINGS "OVERWRITE_ONLY;SWAP;DIRECT_XIP;RAM_LOAD")
+set_property(CACHE MCUBOOT_UPGRADE_STRATEGY PROPERTY STRINGS "OVERWRITE_ONLY;SWAP_USING_SCRATCH;SWAP_USING_MOVE;DIRECT_XIP;RAM_LOAD")
 
 # Specifying a scope of the accepted values of MCUBOOT_ALIGN_VAL for
 # platforms requiring specific flash alignmnent

bl2/ext/mcuboot/signing_layout.c.in

@@ -14,7 +14,7 @@ enum image_attributes {
     RE_NON_SECURE_IMAGE_OFFSET   = NON_SECURE_IMAGE_OFFSET,
     RE_NON_SECURE_IMAGE_MAX_SIZE = NON_SECURE_IMAGE_MAX_SIZE,
 #ifdef IMAGE_LOAD_ADDRESS
-    RE_IMAGE_LOAD_ADDRESS = IMAGE_LOAD_ADDRESS,
+    RE_IMAGE_LOAD_ADDRESS        = IMAGE_LOAD_ADDRESS,
 #endif
     RE_SIGN_BIN_SIZE = FLASH_AREA_@FLASH_AREA_NUM@_SIZE,
 #ifdef IMAGE_ROM_FIXED

bl2/src/default_flash_map.c

@@ -34,11 +34,13 @@
 #define FLASH_DEVICE_ID_3 FLASH_DEVICE_ID
 #endif
 
+#if defined(MCUBOOT_SWAP_USING_SCRATCH)
 /* When undefined FLASH_DEV_NAME_SCRATCH or FLASH_DEVICE_ID_SCRATCH , default */
 #if !defined(FLASH_DEV_NAME_SCRATCH) || !defined(FLASH_DEVICE_ID_SCRATCH)
 #define FLASH_DEV_NAME_SCRATCH  FLASH_DEV_NAME
 #define FLASH_DEVICE_ID_SCRATCH FLASH_DEVICE_ID
 #endif
+#endif  /* defined(MCUBOOT_SWAP_USING_SCRATCH) */
 
 #define ARRAY_SIZE(arr) (sizeof(arr)/sizeof((arr)[0]))
 
@@ -80,6 +82,7 @@ const struct flash_area flash_map[] = {
         .fa_size = FLASH_AREA_3_SIZE,
     },
 #endif
+#if defined(MCUBOOT_SWAP_USING_SCRATCH)
     {
         .fa_id = FLASH_AREA_SCRATCH_ID,
         .fa_device_id = FLASH_DEVICE_ID_SCRATCH,
@@ -87,6 +90,7 @@ const struct flash_area flash_map[] = {
         .fa_off = FLASH_AREA_SCRATCH_OFFSET,
         .fa_size = FLASH_AREA_SCRATCH_SIZE,
     },
+#endif /* defined(MCUBOOT_SWAP_USING_SCRATCH) */
 };
 
 const int flash_map_entry_num = ARRAY_SIZE(flash_map);

bl2/src/flash_map.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2021, Arm Limited. All rights reserved.
+ * Copyright (c) 2019-2022, Arm Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  *
@@ -30,6 +30,13 @@
 extern const struct flash_area flash_map[];
 extern const int flash_map_entry_num;
 
+/* Valid entries for data item width */
+static const uint32_t data_width_byte[] = {
+    sizeof(uint8_t),
+    sizeof(uint16_t),
+    sizeof(uint32_t),
+};
+
 /*
  * Check the target address in the flash_area_xxx operation.
  */
@@ -90,18 +97,15 @@ void flash_area_close(const struct flash_area *area)
 int flash_area_read(const struct flash_area *area, uint32_t off, void *dst,
                     uint32_t len)
 {
-    uint32_t remaining_len;
+    uint32_t remaining_len, read_length;
     uint32_t aligned_off;
+    uint32_t item_number;
+
+    /* The maximum value of data_width is 4 bytes. */
     uint8_t temp_buffer[sizeof(uint32_t)];
-    uint8_t align_unit, i = 0;
+    uint8_t data_width, i = 0, j;
     int ret = 0;
 
-    /* Valid entries for data item width */
-    uint32_t data_width_byte[] = {
-        sizeof(uint8_t),
-        sizeof(uint16_t),
-        sizeof(uint32_t),
-    };
     ARM_FLASH_CAPABILITIES DriverCapabilities;
 
     BOOT_LOG_DBG("read area=%d, off=%#x, len=%#x", area->fa_id, off, len);
@@ -115,30 +119,55 @@ int flash_area_read(const struct flash_area *area, uint32_t off, void *dst,
      * Data type size is specified by the data_width in ARM_FLASH_CAPABILITIES.
      */
     DriverCapabilities = DRV_FLASH_AREA(area)->GetCapabilities();
-    align_unit = data_width_byte[DriverCapabilities.data_width];
-    aligned_off = FLOOR_ALIGN(off, align_unit);
+    data_width = data_width_byte[DriverCapabilities.data_width];
+    aligned_off = FLOOR_ALIGN(off, data_width);
 
-    /* Read the first align_unit long data if `off` is not aligned. */
+    /* Read the first data_width long data if `off` is not aligned. */
     if (aligned_off != off) {
         ret = DRV_FLASH_AREA(area)->ReadData(area->fa_off + aligned_off,
                                              temp_buffer,
-                                             align_unit);
+                                             1);
         if (ret < 0) {
             return ret;
         }
 
+        /* Record how many target data have been read. */
+        read_length = off - aligned_off + len >= data_width ?
+                                        data_width - (off - aligned_off) : len;
+
         /* Copy the read data from off. */
-        for (i = 0; i + off - aligned_off < align_unit; i++) {
+        for (i = 0; i < read_length; i++) {
             ((uint8_t *)dst)[i] = temp_buffer[i + off - aligned_off];
         }
-        remaining_len -= align_unit - (off - aligned_off);
+        remaining_len -= read_length;
     }
 
-    /* CMSIS ARM_FLASH_ReadData does not require the alignment of `cnt`.*/
+    /* The `cnt` parameter in CMSIS ARM_FLASH_ReadData indicates number of data
+     * items to read.
+     */
     if (remaining_len) {
-        ret = DRV_FLASH_AREA(area)->ReadData(area->fa_off + off + i,
-                                             (uint8_t *)dst + i,
-                                             remaining_len);
+        item_number = remaining_len / data_width;
+        if (item_number) {
+            ret = DRV_FLASH_AREA(area)->ReadData(area->fa_off + off + i,
+                                                (uint8_t *)dst + i,
+                                                item_number);
+            if (ret < 0) {
+                return ret;
+            }
+            remaining_len -= item_number * data_width;
+        }
+    }
+    if (remaining_len) {
+        ret = DRV_FLASH_AREA(area)->ReadData(
+                            area->fa_off + off + i + item_number * data_width,
+                            temp_buffer,
+                            1);
+        if (ret < 0) {
+            return ret;
+        }
+        for (j = 0; j < remaining_len; j++) {
+            ((uint8_t *)dst)[i + item_number * data_width + j] = temp_buffer[j];
+        }
     }
 
     /* CMSIS ARM_FLASH_ReadData can return the number of data items read or
@@ -163,7 +192,8 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
 #else
     uint8_t len_padding[FLASH_PROGRAM_UNIT - 1];
 #endif
-
+    ARM_FLASH_CAPABILITIES DriverCapabilities;
+    uint8_t data_width;
     /* The PROGRAM_UNIT aligned value of `off` */
     uint32_t aligned_off;
 
@@ -175,7 +205,7 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
     uint32_t src_written_idx = 0;
     uint32_t add_padding_size, len_padding_size;
     uint32_t write_size;
-    uint32_t last_unit_start_off = 0;
+    uint32_t last_unit_start_off;
     /*
      *    aligned_off           off           last_unit_start_off
      *        |                  |                     |
@@ -197,6 +227,10 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
         return -1;
     }
 
+    DriverCapabilities = DRV_FLASH_AREA(area)->GetCapabilities();
+    data_width = data_width_byte[DriverCapabilities.data_width];
+
+    if (FLASH_PROGRAM_UNIT)
     /* Read the bytes from aligned_off to off. */
     if (flash_area_read(area, aligned_off, add_padding, add_padding_size)) {
         return -1;
@@ -241,8 +275,8 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
             return -1;
         }
         if (DRV_FLASH_AREA(area)->ProgramData(area->fa_off + aligned_off,
-                                              add_padding,
-                                              FLASH_PROGRAM_UNIT)) {
+                                        add_padding,
+                                        FLASH_PROGRAM_UNIT / data_width) < 0) {
             return -1;
         }
     }
@@ -263,7 +297,7 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
             if (DRV_FLASH_AREA(area)->ProgramData(
                                            area->fa_off + off + src_written_idx,
                                            src,
-                                           write_size)) {
+                                           write_size / data_width) < 0) {
                 return -1;
             }
             src_written_idx += write_size;
@@ -295,7 +329,7 @@ int flash_area_write(const struct flash_area *area, uint32_t off,
             if (DRV_FLASH_AREA(area)->ProgramData(
                                 area->fa_off + off + last_unit_start_off,
                                 add_padding,
-                                FLASH_PROGRAM_UNIT)) {
+                                FLASH_PROGRAM_UNIT / data_width) < 0) {
                 return -1;
             }
         }

bl2/src/provisioning.c

@@ -23,9 +23,9 @@ __PACKED_STRUCT bl2_assembly_and_test_provisioning_data_t {
     uint8_t bl2_rotpk_1[32];
     uint8_t bl2_rotpk_2[32];
 
-#ifdef BL1
-    uint8_t bl1_rotpk_0[32];
-#endif /* BL1 */
+#ifdef PLATFORM_PSA_ADAC_SECURE_DEBUG
+    uint8_t secure_debug_pk[32];
+#endif /* PLATFORM_PSA_ADAC_SECURE_DEBUG */
 };
 
 #ifdef TFM_DUMMY_PROVISIONING
@@ -78,27 +78,15 @@ static const struct bl2_assembly_and_test_provisioning_data_t bl2_assembly_and_t
 #else
 #error "No public key available for given signing algorithm."
 #endif /* MCUBOOT_SIGN_RSA_LEN */
-#ifdef BL1
-#if (MCUBOOT_SIGN_RSA_LEN == 2048)
-    /* bl2 rotpk 0 */
+
+#ifdef PLATFORM_PSA_ADAC_SECURE_DEBUG
     {
-        0xfc, 0x57, 0x01, 0xdc, 0x61, 0x35, 0xe1, 0x32,
-        0x38, 0x47, 0xbd, 0xc4, 0x0f, 0x04, 0xd2, 0xe5,
-        0xbe, 0xe5, 0x83, 0x3b, 0x23, 0xc2, 0x9f, 0x93,
-        0x59, 0x3d, 0x00, 0x01, 0x8c, 0xfa, 0x99, 0x94,
+        0xf4, 0x0c, 0x8f, 0xbf, 0x12, 0xdb, 0x78, 0x2a,
+        0xfd, 0xf4, 0x75, 0x96, 0x6a, 0x06, 0x82, 0x36,
+        0xe0, 0x32, 0xab, 0x80, 0xd1, 0xb7, 0xf1, 0xbc,
+        0x9f, 0xe7, 0xd8, 0x7a, 0x88, 0xcb, 0x26, 0xd0,
     },
-#elif (MCUBOOT_SIGN_RSA_LEN == 3072)
-    /* bl1 rotpk 0 */
-    {
-        0xbf, 0xe6, 0xd8, 0x6f, 0x88, 0x26, 0xf4, 0xff,
-        0x97, 0xfb, 0x96, 0xc4, 0xe6, 0xfb, 0xc4, 0x99,
-        0x3e, 0x46, 0x19, 0xfc, 0x56, 0x5d, 0xa2, 0x6a,
-        0xdf, 0x34, 0xc3, 0x29, 0x48, 0x9a, 0xdc, 0x38,
-    },
-#else
-#error "No public key available for given signing algorithm."
-#endif /* MCUBOOT_SIGN_RSA_LEN */
-#endif /* BL1 */
+#endif /* PLATFORM_PSA_ADAC_SECURE_DEBUG */
 };
 #else
 static const struct bl2_assembly_and_test_provisioning_data_t bl2_assembly_and_test_prov_data;
@@ -159,14 +147,14 @@ enum tfm_plat_err_t provision_assembly_and_test(void)
         return err;
     }
 
-#ifdef BL1
-    err = tfm_plat_otp_write(PLAT_OTP_ID_BL1_ROTPK_0,
-                             sizeof(bl2_assembly_and_test_prov_data.bl1_rotpk_0),
-                             bl2_assembly_and_test_prov_data.bl1_rotpk_0);
+#ifdef PLATFORM_PSA_ADAC_SECURE_DEBUG
+    err = tfm_plat_otp_write(PLAT_OTP_ID_SECURE_DEBUG_PK,
+                             sizeof(bl2_assembly_and_test_prov_data.secure_debug_pk),
+                             bl2_assembly_and_test_prov_data.secure_debug_pk);
     if (err != TFM_PLAT_ERR_SUCCESS && err != TFM_PLAT_ERR_UNSUPPORTED) {
         return err;
     }
-#endif /* BL1 */
+#endif /* PLATFORM_PSA_ADAC_SECURE_DEBUG */
 
     return err;
 }

bl2/src/shared_symbol_template.txt

@@ -1,34 +0,0 @@
-# -----------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# -----------------------------------------------------------
-
-#Groups of functions that can be always shared with no exceptions
-mbedtls_asn1
-
-mbedtls_mpi
-
-mbedtls_platform
-
-mbedtls_rsa
-
-#This group is only relevant if BL2 image encryption is on
-mbedtls_md
-
-#This group has two functions that cause runtime errors when shared, so the
-#error-free ones are listed piece by piece
-mbedtls_internal_sha256
-mbedtls_sha256_free
-mbedtls_sha256_init
-mbedtls_sha256_ret
-mbedtls_sha256_starts_ret
-
-#Symbols necessary to make sharing additional functions possible
-mbedtls_calloc
-mbedtls_free
-
-#Miscellaneous functions
-mbedtls_exit
-memset_func

cmake/Common/FilterSharedSymbols.cmake

@@ -1,60 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-# A CMake script which is meant to filter some wanted symbols based on a template file
-# from another text file, which contains all the extracted symbols from an executable.
-#
-# INPUT parameters:
-#   SHARED_SYMBOL_TEMPLATE - Text file contains wanted symbol name templates to be shared (i.e.: mbedtls_)
-#   ALL_SYMBOLS        - Text file, which contains all the extracted symbols from an executable.
-#                        Produced in previous step of the code sharing process.
-#
-# OUTPUTS produced by this script:
-#   - shared_symbols_addr.txt  List of the name, type and absolute address of symbols which
-#                              match with the patterns in the symbol template file
-#   - shared_symbols_name.txt  List of only the names of symbols which match with the
-#                              patterns in the symbol template file
-
-file(STRINGS ${SHARED_SYMBOL_TEMPLATE} SHARED_SYMBOL_TEMPLATE)
-file(STRINGS ${ALL_SYMBOLS}        ALL_SYMBOLS)
-
-# In 'arm-none-eabi-nm' and 'armclang --symdefs' output 'T' indicates the global
-# symbols which can be shared between independently linked executables.
-# 'D' is necessary to share two specific function pointers: 'mbedtls_calloc_func'
-# and 'mbedtls_free_func'. These also need the 'static' keyword removed in mbed-crypto
-set(_SHARED_SYMBOL_TYPES "T;D")
-
-foreach(_SYMBOL_TEMPLATE IN LISTS SHARED_SYMBOL_TEMPLATE)
-    string(SUBSTRING _SYMBOL_TEMPLATE 0 1 FIRST_CHAR)
-    if (NOT _SYMBOL_TEMPLATE STREQUAL "" AND NOT FIRST_CHAR STREQUAL "#")
-        foreach(_ONE_SYMBOL IN LISTS ALL_SYMBOLS)
-            foreach(_TEXT IN LISTS _SHARED_SYMBOL_TYPES)
-                string(FIND ${_ONE_SYMBOL} "${_TEXT} ${_SYMBOL_TEMPLATE}" POSITION)
-                if (NOT POSITION EQUAL -1)
-                    # Get matching symbol name and its address
-                    list(APPEND SHARED_SYMBOL_ADDR_LIST "${_ONE_SYMBOL}")
-
-                    # Get matching symbol name
-                    string(SUBSTRING ${_ONE_SYMBOL} ${POSITION} 200 _ONE_SYMBOL_NAME)
-                    string(REPLACE "${_TEXT} " "" _ONE_SYMBOL_NAME ${_ONE_SYMBOL_NAME})
-                    list(APPEND SHARED_SYMBOL_NAME_LIST "${_ONE_SYMBOL_NAME}")
-                endif()
-            endforeach()
-        endforeach()
-    endif()
-endforeach()
-
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/shared_symbols_addr.txt "#<SYMDEFS>#\n")
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/shared_symbols_name.txt "")
-
-foreach(_SYMBOL IN LISTS SHARED_SYMBOL_ADDR_LIST)
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/shared_symbols_addr.txt "${_SYMBOL}\n")
-endforeach()
-
-foreach(_SYMBOL IN LISTS SHARED_SYMBOL_NAME_LIST)
-    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/shared_symbols_name.txt "${_SYMBOL}\n")
-endforeach()

cmake/Common/StripUnsharedCode.cmake

@@ -1,40 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-# A CMake script to strip that part of an executable which is not meant to be
-# shared among distinct binaries (code reuse). Only used by GNUARM tool chain.
-#
-# INPUT parameters:
-#   SHARED_SYMBOLS_FILE  -  File which contains the list of shared symbols.
-#   EXECUTABLE_TO_STRIP  -  A copy of the original executable, which contains the sharable code.
-#                           From this copy of the executable the unshared code and symbols
-#                           are removed.
-#
-# OUTPUTS produced by this script:
-#   - EXECUTABLE_TO_STRIP  -  Output file (stripped) has the same name as input file.
-
-find_program(GNUARM_STRIP arm-none-eabi-strip)
-if (GNUARM_STRIP STREQUAL "GNUARM_STRIP-NOTFOUND")
-    message(FATAL_ERROR "StripUnsharedCode.cmake: mandatory tool '${GNUARM_STRIP}' is missing.")
-endif()
-
-# Want to strip all unwanted symbols in one go, so concatenate those which must be kept
-file(STRINGS ${SHARED_SYMBOLS_FILE} SHARED_SYMBOL_NAME)
-foreach(_SYMBOL IN LISTS SHARED_SYMBOL_NAME)
-    list(APPEND ARGUMENT "-K${_SYMBOL}")
-endforeach()
-
-execute_process(COMMAND ${GNUARM_STRIP} ${ARGUMENT} ${EXECUTABLE_TO_STRIP}
-                TIMEOUT 120
-                OUTPUT_VARIABLE _RES
-                ERROR_VARIABLE  _RES
-                RESULT_VARIABLE _STATUS_CODE
-                OUTPUT_STRIP_TRAILING_WHITESPACE)
-
-if (_STATUS_CODE GREATER 0)
-    message(FATAL_ERROR "ERROR: Failed to execute ${GNUARM_STRIP} ${_RES}")
-endif()

cmake/Common/WeakenSymbols.cmake

@@ -1,77 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-# A CMake script to weaken identical symbols in the target linked libraries to avoid
-# symbol collision at linking time between shared code and other libraries.
-# i.e.: Shared cryptographic code between MCUBoot and secure runtime firmware.
-#
-# INPUT parameters:
-#   LIB_LIST          - List of all libraries which are linked to the target, and are using
-#                       the shared code.
-#   SHARED_CODE_PATH  - The location of the shared code. It could be outside of TF-M repository.
-#
-# OUTPUTS produced by this script:
-#   The libraries might be modified by this script, if they contain the same symbols
-#   as the shared code.
-
-# TODO: Library search path is modified manually to include path for platform
-#       related libraries.
-
-find_program(OBJCOPY arm-none-eabi-objcopy)
-if (OBJCOPY STREQUAL "OBJCOPY-NOTFOUND")
-    message(FATAL_ERROR "WeakenSymbols.cmake: mandatory tool 'arm-none-eabi-objcopy' is missing.")
-endif()
-
-# Macro to collect all libraries where an *.a file is found
-macro(LIBRARY_DIRECTORIES return_list)
-    file(GLOB_RECURSE new_list *.a)
-    set(dir_list "")
-    foreach(file_path ${new_list})
-        get_filename_component(dir_path ${file_path} PATH)
-        set(dir_list ${dir_list} ${dir_path})
-    endforeach()
-    list(REMOVE_DUPLICATES dir_list)
-    set(${return_list} ${dir_list})
-endmacro()
-
-# Create a library search path for static libraries
-LIBRARY_DIRECTORIES(LIBRARY_PATH)
-
-# Workaround to include directories outside of 'secure_fw' folder for platform
-list(APPEND LIBRARY_PATH ${CMAKE_CURRENT_BINARY_DIR}/../platform/ext/accelerator/cc312/crypto_service_cc312 # Musca-B1: libcrypto_service_cc312.a
-                         ${CMAKE_CURRENT_BINARY_DIR}/../platform/ext/accelerator
-                         ${CMAKE_CURRENT_BINARY_DIR}/../platform
-)
-
-# When invoking the CMake scripts the original list separator(;) is replaced with space.
-# Need to convert back to be able to handle as a list.
-string(REPLACE " " ";" _LIB_LIST ${LIB_LIST})
-
-# Want to weaken all shared symbols in one go, so first concatenate them.
-# There are libraries which might not contain any of these, but it does
-# not cause any issue, the command does not return with error code.
-file(STRINGS ${SHARED_CODE_PATH}/shared_symbols_name.txt SHARED_SYMBOL_NAME)
-foreach(_SYMBOL IN LISTS SHARED_SYMBOL_NAME)
-    list(APPEND ARGUMENT "-W${_SYMBOL}")
-endforeach()
-
-# Iterate over each library and set potentially colliding symbols to be weak
-foreach(LIB IN LISTS _LIB_LIST)
-    find_file(LIB_FULL_PATH "lib${LIB}.a" PATHS ${LIBRARY_PATH} PATH_SUFFIXES Common NO_DEFAULT_PATH)
-    if (NOT ${LIB_FULL_PATH} STREQUAL "LIB_FULL_PATH-NOTFOUND")
-        execute_process(COMMAND ${OBJCOPY} ${ARGUMENT} ${LIB_FULL_PATH}
-                        TIMEOUT 120
-                        OUTPUT_VARIABLE _RES
-                        ERROR_VARIABLE  _RES
-                        RESULT_VARIABLE _STATUS_CODE
-                        OUTPUT_STRIP_TRAILING_WHITESPACE)
-        if (_STATUS_CODE GREATER 0)
-            message(FATAL_ERROR "ERROR: Failed to execute ${OBJCOPY} ${_RES}")
-        endif()
-    endif()
-    unset(LIB_FULL_PATH CACHE)
-endforeach()

cmake/install.cmake

@@ -1,18 +1,13 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 # Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
 #-------------------------------------------------------------------------------
 
-# Generate correct filename
-string(TOUPPER ${TFM_PLATFORM} TFM_PLATFORM_UPPERCASE)
-string(REGEX REPLACE "-" "_" TFM_PLATFORM_UPPERCASE_UNDERSCORE ${TFM_PLATFORM_UPPERCASE})
-string(REGEX REPLACE "^(\\.\\.([\\/\\\\]))+" "EXTERNAL\\2" TFM_PLATFORM_UPPERCASE_UNDERSCORE_NO_PARENT_DIR ${TFM_PLATFORM_UPPERCASE_UNDERSCORE})
-
 install(DIRECTORY ${CMAKE_BINARY_DIR}/bin/
-        DESTINATION ${TFM_INSTALL_PATH}/outputs/${TFM_PLATFORM_UPPERCASE_UNDERSCORE_NO_PARENT_DIR}
+        DESTINATION ${TFM_INSTALL_PATH}/outputs
 )
 
 set(INTERFACE_INC_DIR ${CMAKE_SOURCE_DIR}/interface/include)
@@ -54,6 +49,7 @@ if (TFM_MULTI_CORE_TOPOLOGY)
     install(FILES       ${INTERFACE_INC_DIR}/multi_core/tfm_multi_core_api.h
                         ${INTERFACE_INC_DIR}/multi_core/tfm_ns_mailbox.h
                         ${INTERFACE_INC_DIR}/multi_core/tfm_mailbox.h
+                        ${INTERFACE_INC_DIR}/multi_core/tfm_ns_mailbox_test.h
                         ${CMAKE_BINARY_DIR}/generated/interface/include/tfm_mailbox_config.h
             DESTINATION ${INSTALL_INTERFACE_INC_DIR})
 elseif (NOT TFM_PSA_API)
@@ -110,6 +106,7 @@ endif()
 
 if(TFM_PARTITION_FIRMWARE_UPDATE)
     install(FILES       ${INTERFACE_INC_DIR}/psa/update.h
+                        ${CMAKE_BINARY_DIR}/generated/interface/include/psa/fwu_config.h
             DESTINATION ${INSTALL_INTERFACE_INC_DIR}/psa)
     install(FILES       ${INTERFACE_INC_DIR}/tfm_fwu_defs.h
             DESTINATION ${INSTALL_INTERFACE_INC_DIR})

cmake/version.cmake

@@ -0,0 +1,14 @@
+# Note: this file is modified from upstream to directly include the  version.
+# We have decided to do it manually so that it is easier to test a PR, as
+# we won't have to have a tag for that PR.
+# Further, this message might create a merge conflict which would inform future
+# version updaters to correct the version in this file.
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+set(TFM_VERSION_FULL "v1.6.0+8cffe127")
+set(TFM_VERSION "1.6.0")

config/build_type/debug.cmake

@@ -8,3 +8,5 @@
 set(MBEDCRYPTO_BUILD_TYPE               relwithdebinfo CACHE STRING "Build type of Mbed Crypto library")
 set(TFM_SPM_LOG_LEVEL                   TFM_SPM_LOG_LEVEL_DEBUG CACHE STRING "Set debug SPM log level as Debug level")
 set(TFM_PARTITION_LOG_LEVEL             TFM_PARTITION_LOG_LEVEL_DEBUG CACHE STRING "Set debug SP log level as Debug level")
+
+set(CONFIG_TFM_HALT_ON_CORE_PANIC       ON         CACHE BOOL      "On fatal errors in the secure firmware, halt instead of rebooting.")

config/build_type/minsizerel.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -8,3 +8,4 @@
 set(MCUBOOT_LOG_LEVEL                   "OFF"      CACHE STRING    "Level of logging to use for MCUboot [OFF, ERROR, WARNING, INFO, DEBUG]")
 set(TFM_SPM_LOG_LEVEL                   TFM_SPM_LOG_LEVEL_SILENCE CACHE STRING "Set minsizerel SPM log level as Silence level")
 set(TFM_PARTITION_LOG_LEVEL             TFM_PARTITION_LOG_LEVEL_SILENCE CACHE STRING "Set minsizerel SP log level as Silence level")
+set(TFM_BL1_LOGGING                     OFF          CACHE BOOL      "Whether BL1 will log to uart")

config/build_type/release.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -9,3 +9,4 @@ set(MBEDCRYPTO_BUILD_TYPE               minsizerel CACHE STRING    "Build type o
 set(MCUBOOT_LOG_LEVEL                   "OFF"      CACHE STRING    "Level of logging to use for MCUboot [OFF, ERROR, WARNING, INFO, DEBUG]")
 set(TFM_SPM_LOG_LEVEL                   TFM_SPM_LOG_LEVEL_SILENCE CACHE STRING "Set release SPM log level as Silence level")
 set(TFM_PARTITION_LOG_LEVEL             TFM_PARTITION_LOG_LEVEL_SILENCE CACHE STRING "Set release SP log level as Silence level")
+set(TFM_BL1_LOGGING                     OFF          CACHE BOOL      "Whether BL1 will log to uart")

config/check_config.cmake

@@ -1,5 +1,6 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
+# Copyright (c) 2021, Cypress Semiconductor Corporation. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -19,11 +20,6 @@ function(tfm_invalid_config)
     endif()
 endfunction()
 
-tfm_invalid_config(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_LESS "7.3.1")
-
-# Incorrect behaviour of ArmClang v6.17 was identified during v1.5.0 release. The issue reported.
-tfm_invalid_config(CMAKE_C_COMPILER_ID STREQUAL "ARMClang" AND CMAKE_C_COMPILER_VERSION VERSION_GREATER_EQUAL "6.17.0")
-
 set (TFM_L3_PLATFORM_LISTS arm/mps2/an521 arm/musca_b1/sse_200 stm/stm32l562e_dk)
 set (VALID_ISOLATION_LEVELS 1 2 3)
 
@@ -36,6 +32,7 @@ tfm_invalid_config(TFM_ISOLATION_LEVEL GREATER 1 AND PSA_FRAMEWORK_HAS_MM_IOVEC)
 tfm_invalid_config(TFM_LIB_MODEL AND PSA_FRAMEWORK_HAS_MM_IOVEC)
 
 tfm_invalid_config(TFM_MULTI_CORE_TOPOLOGY AND TFM_LIB_MODEL)
+tfm_invalid_config(TFM_MULTI_CORE_TOPOLOGY AND TFM_NS_MANAGE_NSID)
 tfm_invalid_config(TFM_PLAT_SPECIFIC_MULTI_CORE_COMM AND NOT TFM_MULTI_CORE_TOPOLOGY)
 
 tfm_invalid_config((TFM_S_REG_TEST OR TFM_NS_REG_TEST) AND TEST_PSA_API)
@@ -56,11 +53,11 @@ tfm_invalid_config(TEST_PSA_API STREQUAL "STORAGE" AND NOT TFM_PARTITION_PROTECT
 
 ########################## FPU ################################################
 
-tfm_invalid_config(CONFIG_TFM_SPE_FP LESS 0 OR CONFIG_TFM_SPE_FP GREATER 2)
-tfm_invalid_config(NOT CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CONFIG_TFM_SPE_FP GREATER 0)
-tfm_invalid_config((NOT CONFIG_TFM_FP_ARCH) AND (CONFIG_TFM_SPE_FP GREATER 0))
-tfm_invalid_config((NOT TFM_PSA_API) AND (CONFIG_TFM_SPE_FP GREATER 0))
-tfm_invalid_config(CONFIG_TFM_SPE_FP STREQUAL "0" AND CONFIG_TFM_LAZY_STACKING_SPE)
+tfm_invalid_config(NOT (CONFIG_TFM_FP STREQUAL "soft" OR CONFIG_TFM_FP STREQUAL "hard"))
+tfm_invalid_config(NOT CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CONFIG_TFM_FP STREQUAL "hard")
+tfm_invalid_config((NOT CONFIG_TFM_FP_ARCH) AND CONFIG_TFM_FP STREQUAL "hard")
+tfm_invalid_config((NOT TFM_PSA_API) AND CONFIG_TFM_FP STREQUAL "hard")
+tfm_invalid_config(CONFIG_TFM_FP STREQUAL "soft" AND CONFIG_TFM_LAZY_STACKING)
 
 ########################## BL2 #################################################
 
@@ -77,7 +74,6 @@ tfm_invalid_config(BL2 AND (NOT MCUBOOT_ALIGN_VAL IN_LIST MCUBOOT_ALIGN_VAL_LIST
 set(TFM_CODE_SHARING_PLATFORM_LISTS arm/mps2/an521 arm/musca_b1/sse_200) # Without crypto hw acceleration
 tfm_invalid_config(NOT TFM_CODE_SHARING STREQUAL "OFF" AND NOT TFM_PLATFORM IN_LIST TFM_CODE_SHARING_PLATFORM_LISTS)
 tfm_invalid_config(NOT TFM_CODE_SHARING STREQUAL "OFF" AND CRYPTO_HW_ACCELERATOR)
-tfm_invalid_config(TFM_CODE_SHARING STREQUAL "OFF" AND TFM_CODE_SHARING_PATH)
 
 ########################## Platform ############################################
 
@@ -85,10 +81,6 @@ tfm_invalid_config(OTP_NV_COUNTERS_RAM_EMULATION AND NOT (PLATFORM_DEFAULT_OTP O
 tfm_invalid_config(PLATFORM_DEFAULT_NV_COUNTERS AND  NOT PLATFORM_DEFAULT_OTP_WRITEABLE)
 tfm_invalid_config(TFM_DUMMY_PROVISIONING AND  NOT PLATFORM_DEFAULT_OTP_WRITEABLE)
 
-####################### SP META Pointer ########################################
-
-tfm_invalid_config(TFM_SP_META_PTR_ENABLE AND TFM_LIB_MODEL)
-
 ####################### Firmware Update Parttion ###############################
 
 tfm_invalid_config(TFM_PARTITION_FIRMWARE_UPDATE AND NOT TFM_PARTITION_PLATFORM)
@@ -109,8 +101,16 @@ tfm_invalid_config(TFM_PARTITION_AUDIT_LOG AND NOT TFM_LIB_MODEL)
 tfm_invalid_config(CRYPTO_NV_SEED AND CRYPTO_HW_ACCELERATOR)
 tfm_invalid_config(NOT CRYPTO_NV_SEED AND NOT CRYPTO_HW_ACCELERATOR)
 
+######################## TF-M Porfile config check #############################
+
+tfm_invalid_config(TFM_PROFILE STREQUAL "profile_small" AND CONFIG_TFM_SPM_BACKEND_IPC)
+
 ########################### Test check config ##################################
 
 if(TFM_S_REG_TEST OR TFM_NS_REG_TEST)
     include(${TFM_TEST_PATH}/config/check_config.cmake)
 endif()
+
+###################### Compiler check for FP support ###########################
+
+include(config/cp_check.cmake)

config/config_default.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -9,13 +9,15 @@ set(TFM_TOOLCHAIN_FILE                  ${CMAKE_SOURCE_DIR}/toolchain_GNUARM.cma
 set(TFM_PLATFORM                        ""          CACHE STRING    "Platform to build TF-M for. Must be either a relative path from [TF-M]/platform/ext/target, or an absolute path.")
 set(CROSS_COMPILE                       arm-none-eabi CACHE STRING  "Cross-compilation triplet")
 
-set(BL2_HEADER_SIZE                     0x000       CACHE STRING    "Header size")
-set(BL2_TRAILER_SIZE                    0x000       CACHE STRING    "Trailer size")
+set(BL1                                 OFF         CACHE BOOL      "Whether to build BL1")
+set(BL2                                 ON          CACHE BOOL      "Whether to build BL2")
 set(NS                                  ON          CACHE BOOL      "Whether to build NS app")
 
 set(TEST_S                              OFF         CACHE BOOL      "Whether to build S regression tests")
 set(TEST_NS                             OFF         CACHE BOOL      "Whether to build NS regression tests")
 set(TEST_PSA_API                        ""          CACHE STRING    "Which (if any) of the PSA API tests should be compiled")
+set(TEST_BL1_1                          OFF         CACHE BOOL      "Whether to build BL1_1 tests")
+set(TEST_BL1_2                          OFF         CACHE BOOL      "Whether to build BL1_2 tests")
 
 # TFM_LIB_MODEL is the only user configuration for Library Model selection.
 # TFM_PSA_API becomes an internal variable. Please do NOT use it in build command line.
@@ -24,6 +26,8 @@ set(TFM_ISOLATION_LEVEL                 1           CACHE STRING    "Isolation l
 set(PSA_FRAMEWORK_HAS_MM_IOVEC          OFF         CACHE BOOL      "Enable MM-IOVEC")
 set(TFM_PROFILE                         ""          CACHE STRING    "Profile to use")
 set(TFM_FIH_PROFILE                     OFF         CACHE STRING    "Fault injection hardening profile [OFF, LOW, MEDIUM, HIGH]")
+set(CONFIG_TFM_CONN_HANDLE_MAX_NUM      8           CACHE STRING    "The maximal number of secure services that are connected or requested at the same time")
+set(CONFIG_TFM_SPM_BACKEND              "IPC"       CACHE STRING    "The SPM backend [IPC, SFN]")
 
 # An NSPE client_id is provided by the NSPE OS via the SPM or directly by the SPM.
 # When `TFM_NS_MANAGE_NSID` is `ON`, TF-M supports NSPE OS providing NSPE client_id.
@@ -40,21 +44,22 @@ set(TFM_SPM_LOG_LEVEL                   TFM_SPM_LOG_LEVEL_INFO          CACHE ST
 set(TFM_PARTITION_LOG_LEVEL             TFM_PARTITION_LOG_LEVEL_INFO    CACHE STRING    "Set default Secure Partition log level as INFO level")
 
 set(TFM_CODE_SHARING                    OFF         CACHE PATH      "Enable code sharing between MCUboot and secure firmware")
-set(TFM_CODE_SHARING_PATH               ""          CACHE PATH      "Path to repo which shares code with secure firmware")
 
 set(TFM_INSTALL_PATH                    ${CMAKE_BINARY_DIR}/install CACHE PATH "Path to which to install TF-M files")
 
 set(TFM_DEBUG_SYMBOLS                   ON          CACHE BOOL      "Add debug symbols. Note that setting CMAKE_BUILD_TYPE to Debug or RelWithDebInfo will also add debug symbols.")
 set(TFM_CODE_COVERAGE                   OFF         CACHE BOOL      "Whether to build the binary for lcov tools")
 
-set(TFM_SP_META_PTR_ENABLE              OFF         CACHE BOOL      "Use Partition Metadata Pointer")
-
 set(TFM_PXN_ENABLE                      OFF         CACHE BOOL      "Use Privileged execute never (PXN)")
 
 set(TFM_EXCEPTION_INFO_DUMP             OFF         CACHE BOOL      "On fatal errors in the secure firmware, capture info about the exception. Print the info if the SPM log level is sufficient.")
 
-set(CONFIG_TFM_SPE_FP                   0           CACHE STRING    "FP ABI type in SPE: 0-software, 1-hybird, 2-hardware")
-set(CONFIG_TFM_LAZY_STACKING_SPE        OFF         CACHE BOOL      "Disable lazy stacking from SPE")
+set(CONFIG_TFM_HALT_ON_CORE_PANIC       OFF         CACHE BOOL       "On fatal errors in the secure firmware, halt instead of rebooting.")
+
+set(CONFIG_TFM_FP                       "soft"      CACHE STRING    "FP ABI type in SPE and NSPE: soft-Software ABI, hard-Hardware ABI")
+set(CONFIG_TFM_LAZY_STACKING            OFF         CACHE BOOL      "Enable/disable lazy stacking")
+
+set(CONFIG_TFM_DOORBELL_API             ON          CACHE BOOL      "Enable the doorbell APIs")
 
 ############################ Platform ##########################################
 
@@ -69,6 +74,8 @@ set(CRYPTO_HW_ACCELERATOR               OFF         CACHE BOOL      "Whether to
 
 set(OTP_NV_COUNTERS_RAM_EMULATION       OFF         CACHE BOOL      "Enable OTP/NV_COUNTERS emulation in RAM. Has no effect on non-default implementations of the OTP and NV_COUNTERS")
 
+set(PLATFORM_DEFAULT_BL1                ON          CACHE STRING    "Whether to use default BL1 or platform-specific one")
+
 set(PLATFORM_DEFAULT_ATTEST_HAL         ON          CACHE BOOL      "Use default attest hal implementation.")
 set(PLATFORM_DEFAULT_NV_COUNTERS        ON          CACHE BOOL      "Use default nv counter implementation.")
 set(PLATFORM_DEFAULT_CRYPTO_KEYS        ON          CACHE BOOL      "Use default crypto keys implementation.")
@@ -83,8 +90,17 @@ set(PLATFORM_DEFAULT_PROVISIONING       ON          CACHE BOOL      "Use default
 set(TFM_DUMMY_PROVISIONING              ON          CACHE BOOL      "Provision with dummy values. NOT to be used in production")
 set(PLATFORM_IS_FVP                     FALSE       CACHE BOOL      "Whether to enable FVP or FPGA build of the platform.")
 
-############################ Partitions ########################################
+set(PLATFORM_PSA_ADAC_SECURE_DEBUG      FALSE       CACHE BOOL      "Whether to use psa-adac secure debug.")
+set(PLATFORM_PSA_ADAC_SOURCE_PATH       "DOWNLOAD"  CACHE PATH      "Path to source dir of psa-adac.")
+set(PLATFORM_PSA_ADAC_VERSION           "427923cc0152578d536fb2065154d5d0dd874910" CACHE STRING "The version of psa-adac to use.")
 
+set(BL1_HEADER_SIZE                     0x000       CACHE STRING    "BL1 Header size")
+set(BL1_TRAILER_SIZE                    0x000       CACHE STRING    "BL1 Trailer size")
+
+set(BL2_HEADER_SIZE                     0x000       CACHE STRING    "BL2 Header size")
+set(BL2_TRAILER_SIZE                    0x000       CACHE STRING    "BL2 Trailer size")
+
+############################ Partitions ########################################
 set(TFM_PARTITION_PROTECTED_STORAGE     ON          CACHE BOOL      "Enable Protected Storage partition")
 set(PS_CREATE_FLASH_LAYOUT              ON          CACHE BOOL      "Create flash FS if it doesn't exist for Protected Storage partition")
 set(PS_ENCRYPTION                       ON          CACHE BOOL      "Enable encryption for Protected Storage partition")
@@ -133,12 +149,14 @@ set(TFM_PARTITION_PSA_PROXY             OFF         CACHE BOOL      "Enable PSA
 set(FORWARD_PROT_MSG                    OFF         CACHE BOOL      "Whether to forward all PSA RoT messages to a Secure Enclave")
 set(TFM_PARTITION_FIRMWARE_UPDATE       OFF         CACHE BOOL      "Enable firmware update partition")
 set(TFM_FWU_BOOTLOADER_LIB              "mcuboot"   CACHE STRING    "Bootloader configure file for Firmware Update partition")
+set(PSA_FWU_MAX_BLOCK_SIZE              1024        CACHE STRING    "The maximum permitted size for block in psa_fwu_write, in bytes.")
+set(TFM_FWU_BUF_SIZE                    ""          CACHE STRING    "Size of the FWU internal data transfer buffer (defaults to PSA_FWU_MAX_BLOCK_SIZE if not set)")
 
 ################################## Dependencies ################################
 
 set(MBEDCRYPTO_PATH                     "DOWNLOAD"  CACHE PATH      "Path to Mbed Crypto (or DOWNLOAD to fetch automatically")
-set(MBEDCRYPTO_VERSION                  "mbedtls-3.0.0" CACHE STRING "The version of Mbed Crypto to use")
-set(MBEDCRYPTO_GIT_REMOTE               "https://github.com/ARMmbed/mbedtls.git" CACHE STRING "The URL (or path) to retrieve MbedTLS from.")
+set(MBEDCRYPTO_VERSION                  "mbedtls-3.1.0" CACHE STRING "The version of Mbed Crypto to use")
+set(MBEDCRYPTO_GIT_REMOTE               "https://github.com/Mbed-TLS/mbedtls.git" CACHE STRING "The URL (or path) to retrieve MbedTLS from.")
 set(MBEDCRYPTO_BUILD_TYPE               "${CMAKE_BUILD_TYPE}" CACHE STRING "Build type of Mbed Crypto library")
 set(TFM_MBEDCRYPTO_CONFIG_PATH
   "${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_default.h" CACHE PATH
@@ -153,7 +171,7 @@ set(MCUBOOT_PATH                        "DOWNLOAD"        CACHE PATH      "Path
 set(MCUBOOT_VERSION                     "v1.9.0"  CACHE STRING    "The version of MCUboot to use")
 
 set(PSA_ARCH_TESTS_PATH                 "DOWNLOAD"  CACHE PATH      "Path to PSA arch tests (or DOWNLOAD to fetch automatically")
-set(PSA_ARCH_TESTS_VERSION              "v21.10_API1.3_ADAC_ALPHA-1"   CACHE STRING    "The version of PSA arch tests to use")
+set(PSA_ARCH_TESTS_VERSION              "f7e8495"   CACHE STRING    "The version of PSA arch tests to use")
 
 ################################################################################
 ################################################################################
@@ -167,4 +185,4 @@ set_property(CACHE TFM_FIH_PROFILE PROPERTY STRINGS "OFF;LOW;MEDIUM;HIGH")
 
 ########################## FP #################################################
 
-set_property(CACHE CONFIG_TFM_SPE_FP PROPERTY STRINGS "0;1;2")
+set_property(CACHE CONFIG_TFM_FP PROPERTY STRINGS "soft;hard")

config/cp_check.cmake

@@ -0,0 +1,28 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+###################### Check compiler for FP vulnerability #####################
+
+# Check compiler with mitigation for the VLLDM instruction security vulnerability or not.
+# For more information, please check https://developer.arm.com/support/arm-security-updates/vlldm-instruction-security-vulnerability.
+if (CONFIG_TFM_FP STREQUAL "hard")
+    # Create test C file.
+    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/cvetest.c "int x;")
+    # Compile with mitigation -mfix-cmse-cve-2021-35465.
+    execute_process (
+        COMMAND ${CMAKE_C_COMPILER} -mfix-cmse-cve-2021-35465 -S ${CMAKE_CURRENT_BINARY_DIR}/cvetest.c -o ${CMAKE_CURRENT_BINARY_DIR}/cvetest.s
+        RESULT_VARIABLE ret
+        ERROR_VARIABLE err
+    )
+    file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/cvetest.c)
+    # Check result
+    if(NOT ret EQUAL 0)
+        message(FATAL_ERROR "To enable FPU usage in SPE and NSPE both, please use the compiler with '-mfix-cmse-cve-2021-35465' support")
+    else()
+        file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/cvetest.s)
+    endif()
+endif()

config/cp_config_default.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2021, Arm Limited. All rights reserved.
+# Copyright (c) 2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -12,6 +12,6 @@ if (NOT DEFINED CONFIG_TFM_FP_ARCH)
     return()
 endif()
 
-if (CONFIG_TFM_SPE_FP STREQUAL "1" OR CONFIG_TFM_SPE_FP STREQUAL "2")
-    set(CONFIG_TFM_LAZY_STACKING_SPE     ON          CACHE BOOL      "Enable lazy stacking from SPE")
+if (CONFIG_TFM_FP STREQUAL "hard")
+    set(CONFIG_TFM_LAZY_STACKING         ON          CACHE BOOL      "Enable lazy stacking")
 endif()

config/profile/profile_small.cmake

@@ -1,12 +1,11 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
 #-------------------------------------------------------------------------------
 
 set(TFM_PROFILE                         profile_small CACHE STRING  "Profile to use")
-set(TFM_LIB_MODEL                       ON          CACHE BOOL      "Use secure library model instead of PSA API (IPC model)")
 set(TFM_ISOLATION_LEVEL                 1           CACHE STRING    "Isolation level")
 
 ########################## BL2 #################################################
@@ -40,3 +39,9 @@ set(TFM_PARTITION_AUDIT_LOG             OFF         CACHE BOOL      "Enable Audi
 
 set(TFM_MBEDCRYPTO_CONFIG_PATH          "${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h" CACHE PATH "Config to use for Mbed Crypto")
 
+# If it is specified to select SFN model in build command, enable SFN model in
+# Profile Small.
+# Otherwise, enable Library model in Profile Small by default.
+if (NOT DEFINED CONFIG_TFM_SPM_BACKEND)
+    set(TFM_LIB_MODEL                   ON          CACHE BOOL      "Use secure library model instead of IPC model")
+endif()

config/set_config.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -42,17 +42,24 @@ if (TFM_PROFILE)
     include(config/profile/${TFM_PROFILE}.cmake)
 endif()
 
+include(${CMAKE_SOURCE_DIR}/config/tfm_build_log_config.cmake)
+
 # Load TF-M model specific default config
 if (TFM_LIB_MODEL)
     include(config/tfm_library_config_default.cmake)
-else()
+elseif (CONFIG_TFM_SPM_BACKEND STREQUAL "SFN")
+    include(config/tfm_sfn_config_default.cmake)
+else() #The default backend is IPC
     include(config/tfm_ipc_config_default.cmake)
 endif()
 
+# Load bl1 config
+if (BL1 AND PLATFORM_DEFAULT_BL1)
+    include(${CMAKE_SOURCE_DIR}/bl1/config/bl1_config_default.cmake)
+endif()
+
 # Load MCUboot specific default.cmake
-# Set BL2 to ON by default, OFF if the platform specifically defines this property
-set(BL2 ON CACHE BOOL "Whether to build BL2")
-if (BL2)
+if (NOT DEFINED BL2 OR BL2)
     include(${CMAKE_SOURCE_DIR}/bl2/ext/mcuboot/mcuboot_default_config.cmake)
 endif()
 

config/tfm_build_log_config.cmake

@@ -0,0 +1,19 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+set(CONFIG_TFM_BUILD_LOG_QUIET              OFF     CACHE BOOL      "Disable build logs")
+
+if(CONFIG_TFM_BUILD_LOG_QUIET)
+    set(CMAKE_INSTALL_MESSAGE               NEVER   CACHE BOOL      "Output installation message generated by the install() command[ALWAYS,LAZY,NEVER]")
+    set(CONFIG_TFM_PARTITION_QUIET          ON      CACHE BOOL      "Disable printing of partition configuration during build")
+    set(CONFIG_TFM_MEMORY_USAGE_QUIET       ON      CACHE BOOL      "Disable the memory usage report")
+    set(CONFIG_TFM_PARSE_MANIFEST_QUIET     ON      CACHE BOOL      "Parse manifest quietly")
+else()
+    set(CONFIG_TFM_PARTITION_QUIET          OFF     CACHE BOOL      "Disable printing of partition configuration during build")
+    set(CONFIG_TFM_MEMORY_USAGE_QUIET       OFF     CACHE BOOL      "Disable the memory usage report")
+    set(CONFIG_TFM_PARSE_MANIFEST_QUIET     OFF     CACHE BOOL      "Parse manifest quietly")
+endif()

config/tfm_ipc_config_default.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
+# Copyright (c) 2020-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -7,4 +7,7 @@
 
 ############################ Partitions ########################################
 
-set(TFM_PSA_API          ON          CACHE BOOL      "Use PSA API instead of secure library model")
+set(TFM_PSA_API                 ON          CACHE BOOL      "Use PSA API instead of secure library model")
+set(CONFIG_TFM_SPM_BACKEND_IPC  ON)
+set(CONFIG_TFM_SPM_BACKEND_SFN  OFF)
+set(CONFIG_TFM_PARTITION_META   ON)

config/tfm_library_config_default.cmake

@@ -1,5 +1,5 @@
 #-------------------------------------------------------------------------------
-# Copyright (c) 2021, Arm Limited. All rights reserved.
+# Copyright (c) 2021-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
@@ -9,3 +9,4 @@
 
 set(TFM_PSA_API                 OFF          CACHE BOOL      "Use PSA API instead of secure library model")
 set(TFM_PARTITION_AUDIT_LOG     ON           CACHE BOOL      "Enable Audit Log partition")
+set(CONFIG_TFM_PARTITION_META   OFF)

config/tfm_platform.cmake

@@ -0,0 +1,49 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+set(TARGET_PATH "${CMAKE_SOURCE_DIR}/platform/ext/target")
+
+if (NOT IS_ABSOLUTE "${TFM_PLATFORM}" AND NOT IS_DIRECTORY "${TARGET_PATH}/${TFM_PLATFORM}")
+    # If TFM_PLATFORM is not a relative patch to ${TARGET_PATH}, then it could
+    # be a platform name, for example an521. Search directories which contain
+    # the "preload.cmake" and find the the match one.
+
+    # Get the list of directories which have preload.cmake
+    file(GLOB_RECURSE PLATFORM_PATHS ${TARGET_PATH} "preload.cmake")
+
+    # Search the list with platform name and store the result in PLATFORM_PATHS
+    list(FILTER PLATFORM_PATHS INCLUDE REGEX "${TFM_PLATFORM}")
+
+    # Get the length of list PLATFORM_PATHS
+    list(LENGTH PLATFORM_PATHS _PLATFORM_NUM)
+
+    if (${_PLATFORM_NUM} STREQUAL 1)
+        # Get the absolute path of the platform
+        get_filename_component(PLATFORM_ABS_PATH ${PLATFORM_PATHS} DIRECTORY)
+        set(TFM_PLATFORM ${PLATFORM_ABS_PATH} CACHE STRING "Target platform set as an absolute path." FORCE)
+    elseif (${_PLATFORM_NUM} STREQUAL 0)
+        Message(FATAL_ERROR "Platform ${TFM_PLATFORM} is not found in TF-M")
+    elseif (${_PLATFORM_NUM} GREATER 1)
+        Message(FATAL_ERROR "Two or more platforms ${TFM_PLATFORM} are found in TF-M")
+    endif()
+endif()
+
+# If TFM_PLATFORM is an absolute path which maybe inputed by developer or
+# transformed from platform name by the process above, it will be converted to
+# relative path here.
+if (IS_ABSOLUTE "${TFM_PLATFORM}")
+    file(RELATIVE_PATH TFM_PLATFORM_RELATIVE_PATH ${TARGET_PATH} ${TFM_PLATFORM})
+    set(TFM_PLATFORM "${TFM_PLATFORM_RELATIVE_PATH}" CACHE STRING "Target platform set as an relative path." FORCE)
+endif()
+
+# Some compiler flags depend on the CPU / platform config. This include should
+# be run before the toolchain file so the compiler can be configured properly.
+if (NOT EXISTS "${TARGET_PATH}/${TFM_PLATFORM}/preload.cmake" OR NOT EXISTS "${TARGET_PATH}/${TFM_PLATFORM}/CMakeLists.txt")
+    Message(FATAL_ERROR "Unsupported TFM_PLATFORM ${TFM_PLATFORM}")
+else()
+    include(platform/ext/target/${TFM_PLATFORM}/preload.cmake)
+endif()

config/tfm_sfn_config_default.cmake

@@ -0,0 +1,14 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2022, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+############################ Partitions ########################################
+
+set(TFM_PSA_API                 ON          CACHE BOOL      "Use PSA API instead of secure library model")
+set(CONFIG_TFM_DOORBELL_API     OFF         CACHE BOOL      "Enable the doorbell APIs")
+set(CONFIG_TFM_SPM_BACKEND_IPC  OFF)
+set(CONFIG_TFM_SPM_BACKEND_SFN  ON)
+set(CONFIG_TFM_PARTITION_META   OFF)

docs/CMakeLists.txt

@@ -23,13 +23,14 @@ find_package(LATEX COMPONENTS PDFLATEX)
 
 ################################## ENV #########################################
 
-include(../version.cmake)
+include(../cmake/version.cmake)
 
 project("Trusted Firmware M. Documentation" VERSION ${TFM_VERSION} LANGUAGES)
 
+set(SPHINXCFG_SOURCE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINXCFG_CONFIG_PATH ${CMAKE_CURRENT_SOURCE_DIR})
 set(SPHINXCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/user_guide)
-set(SPHINX_TMP_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/temp)
-set(SPHINXCFG_TEMPLATE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in")
+
 set(DOXYCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/reference_manual)
 set(DOXYCFG_DOXYGEN_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
 
@@ -37,36 +38,17 @@ set(DOXYCFG_DOXYGEN_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
 set(DOXYCFG_DOXYGEN_BUILD False)
 
 ################################## SPHINX ######################################
-set(SPHINXCFG_COPY_FILES True)
-set(SPHINXCFG_RENDER_CONF True)
-
-add_custom_target(tfm_docs_sphinx_cfg
-    DEPENDS ${SPHINX_TMP_DOC_DIR}/conf.py
-)
-add_custom_command(OUTPUT ${SPHINX_TMP_DOC_DIR}/conf.py
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_TMP_DOC_DIR}
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
-    MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/conf.py
-    BYPRODUCTS ${SPHINX_TMP_DOC_DIR}
-)
-
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/tfm_env.py.in ${SPHINX_TMP_DOC_DIR}/tfm_env.py @ONLY)
 
 if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R2_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
 
-    file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
+    file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst)
 
-    add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
-        OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
-        COMMAND "${SPHINX_EXECUTABLE}" -W -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
-        WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
-        DEPENDS tfm_docs_sphinx_cfg
+    add_custom_target(tfm_docs_userguide_html ALL
+        COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
+        WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
         DEPENDS ${SPHINXCFG_DOC_FILES}
     )
-    add_custom_target(tfm_docs_userguide_html ALL
-        DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
-        DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
-    )
+
     add_dependencies(docs tfm_docs_userguide_html)
 
     if (LATEX_PDFLATEX_FOUND)
@@ -92,10 +74,9 @@ endif()
 
 ################################## DOXYGEN #####################################
 
-configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
-
 if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
 
+    configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
     file(GLOB_RECURSE DOXYCFG_DOC_FILES ${CMAKE_SOURCE_DIR}/*.c ${CMAKE_SOURCE_DIR}/*.h)
 
     add_custom_command(OUTPUT ${DOXYCFG_OUTPUT_PATH}/html

docs/_static/css/tfm_custom.css

@@ -5,9 +5,11 @@
 #
 #----------------------------------------------------------------------------*/
 
-/* Expand width to fill screen */
-.wy-nav-content {
-   max-width: none;
+/* Limit page width */
+@media only screen and (min-width: 780px) {
+    .wy-nav-content {
+        max-width: 1100px;
+    }
 }
 
 /* Flexbox Tile Grid Settings  */
@@ -30,16 +32,16 @@
     -webkit-box-flex: 0;
         -ms-flex: 0 0 auto;
             flex: 0 0 auto;
-    width: 220px;
+    width: 200px;
     text-align: center;
     margin: 1rem;
 }
 
 .grid-item a {
     display: block;
-    width: 220px;
-    height: 220px;
-    padding: 22px;
+    width: 190px;
+    height: 190px;
+    padding: 12px;
     display: -webkit-box;
     display: -ms-flexbox;
     display: flex;
@@ -59,27 +61,17 @@
 }
 
 .grid-item h2 {
-    font-size: 1.1rem;
+    font-size: 1rem;
+    margin-bottom: 0.5rem;
 }
 
 .grid-item img {
-    margin-bottom: 1.1rem;
     max-width: 75%;
+    margin-bottom: 0.5rem;
 }
 
+
 .grid-item a:hover {
     background-color: #32cd32;
     color: white;
 }
-
-
-.grid-item p {
-    margin-top: 0.5rem;
-    color: #333e48;
-}
-
-.grid-icon {
-   line-height: 1.8;
-   font-size: 6rem;
-   color: #343131;
-}

docs/conf.py

@@ -1,32 +1,220 @@
-# -----------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
+# -*- coding: utf-8 -*-
+#-------------------------------------------------------------------------------
+# Copyright (c) 2019-2022, Arm Limited. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #
-# -----------------------------------------------------------------------------
+#-------------------------------------------------------------------------------
+
+# Configuration file for the Sphinx documentation builder.
 #
-# Configuration file override for the Sphinx documentation builder.
-#
-# This file is used when Sphinx build is  invoked directly at this level.
-# It will trigger a copy-files operation and render a new configuration
-# using either auto-detected or cmake provided  parameters.
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
 import os
 import sys
+import re
+from subprocess import check_output
 
-# Attempt to find the tools directory by recursing up to five levels of parents
-root_path = os.path.dirname(os.path.abspath(__file__))
+# -- Project information -----------------------------------------------------
 
-for i in range(5):
-    root_path = os.path.dirname(root_path)
-    doc_path = os.path.join(root_path, "tools", "documentation")
-    if os.path.isdir(doc_path):
-        sys.path.insert(0, os.path.abspath(doc_path))
-sys.path.append("./")
+project = 'Trusted Firmware-M'
+copyright = '2017-2022, ARM CE-OSS'
+author = 'ARM CE-OSS'
+title = 'User Guide'
 
-# Trigger the copy operation logic
-import tfm_copy_files
+# -- Extract current version -------------------------------------------------
 
-# Import the rendered configuration into global scope
-from tfm_cmake_defaults import *
+try:
+    vrex = re.compile(r'TF-M(?P<GIT_VERSION>v.+?)'
+                      r'(-[0-9]+-g)?(?P<GIT_SHA>[a-f0-9]{7,})?$')
 
-from conf_rendered import *
+    version = check_output("git describe --tags --always",
+                            shell = True, encoding = 'UTF-8')
+
+    _v = vrex.match(version)
+    release = _v.group('GIT_VERSION')
+    if _v.group('GIT_SHA'):
+        version = release + "+" + _v.group('GIT_SHA')[:7]
+
+except:
+    version = release = 'Unknown'
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.4'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.imgmath',
+    'm2r2', #Support markdown files. Needed for external code.
+    'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
+    'sphinxcontrib.plantuml', #Add support for PlantUML drawings
+    'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
+    'sphinx_tabs.tabs' #Enable tab extension in Sphinx
+]
+
+# PlantUML
+plantuml = 'java -jar ' + os.environ['PLANTUML_JAR_PATH']
+
+#Make auso section labals generated be prefixed with file name.
+autosectionlabel_prefix_document=True
+#Add auso section label for level 2 headers only.
+autosectionlabel_maxdepth=2
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
+                    'platform/ext/target/cypress/psoc64/security/keys/readme.rst',
+                    'lib/ext/**']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'collapse_navigation' : False,
+    'prev_next_buttons_location' : None,   # Hide Prev and Next buttons
+#    'display_version': True,    # Show version under logo
+    'sticky_navigation': True,
+    'navigation_depth': 2,
+}
+
+# Remove the "View page source" link from the top of docs pages
+html_show_sourcelink = False
+
+#
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to configuration directory. They are copied after the builtin static
+# files, so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Set the documentation logo relative to configuration directory
+html_logo = '_static/images/tf_logo_white.png'
+
+# Set the documentation favicon
+html_favicon = '_static/images/favicon.ico'
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+#Disable adding conf.py copyright notice to HTML output
+html_show_copyright = False
+
+# Disable showing Sphinx footer message:
+# "Built with Sphinx using a theme provided by Read the Docs. "
+html_show_sphinx = False
+
+#Add custom css for HTML. Used to allow full page width rendering
+def setup(app):
+    app.add_css_file('css/tfm_custom.css')
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TF-M doc'
+
+rst_prolog = """
+.. |TFM_VERSION| replace:: version
+"""
+
+# Enable figures and tables auto numbering
+numfig = True
+numfig_secnum_depth = 0
+numfig_format = {
+    'figure': 'Figure %s:',
+    'table': 'Table %s:',
+    'code-block': 'Listing %s:',
+    'section': '%s'
+}
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'TF-M.tex', title,
+     author, 'manual'),
+]
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+#man_pages = [
+#    (master_doc, 'tf-m', title,
+#     [author], 7)
+#]
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+#texinfo_documents = [
+#    (master_doc, 'TF-M', title,
+#     author, 'TF-M', 'Trusted Firmware for Cortex-M',
+#     'Miscellaneous'),
+#]
+
+# -- Extension configuration -------------------------------------------------

docs/conf.py.in

@@ -1,202 +0,0 @@
-# -*- coding: utf-8 -*-
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019-2021, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------#
-
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../docs'))
-
-# -- Project information -----------------------------------------------------
-
-project = 'Trusted Firmware-M'
-copyright = '2017-2019, ARM CE-OSS'
-author = 'ARM CE-OSS'
-title = 'User Guide'
-
-# The short X.Y version
-version = '@SPHINXCFG_TFM_VERSION@'
-# The full version, including alpha/beta/rc tags
-release = '@SPHINXCFG_TFM_VERSION_FULL@'
-
-
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.4'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx.ext.imgmath',
-    'm2r2', #Support markdown files. Needed for external code.
-    'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
-    'sphinxcontrib.plantuml', #Add support for PlantUML drawings
-    'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
-    'sphinx_tabs.tabs' #Enable tab extension in Sphinx
-]
-
-#Location of PlantUML
-plantuml = '@Java_JAVA_EXECUTABLE@ -jar @PLANTUML_JAR_PATH@'
-
-#Make auso section labals generated be prefixed with file name.
-autosectionlabel_prefix_document=True
-#Add auso section label for level 2 headers only.
-autosectionlabel_maxdepth=2
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = ['.rst', '.md']
-
-# The master toctree document.
-master_doc = 'index'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
-                    'platform/ext/target/cypress/psoc64/security/keys/readme.rst',
-                    'lib/ext/**']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-html_theme_options = {'collapse_navigation': False}
-#
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['@TFM_ROOT_DIR@/docs/_static']
-
-# Set the documentation logo
-html_logo = '@TFM_ROOT_DIR@/docs/_static/images/tf_logo_white.png'
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
-
-#Disable adding conf.py copyright notice to HTML output
-html_show_copyright = False
-
-#Add custom css for HTML. Used to allow full page width rendering
-def setup(app):
-    app.add_css_file('css/tfm_custom.css')
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'TF-M doc'
-
-rst_prolog = """
-.. |TFM_VERSION| replace:: @SPHINXCFG_TFM_VERSION@
-"""
-
-# Enable figures and tables auto numbering
-numfig = True
-numfig_secnum_depth = 0
-numfig_format = {
-    'figure': 'Figure %s:',
-    'table': 'Table %s:',
-    'code-block': 'Listing %s:',
-    'section': '%s'
-}
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'TF-M.tex', title,
-     author, 'manual'),
-]
-
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-#man_pages = [
-#    (master_doc, 'tf-m', title,
-#     [author], 7)
-#]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-#texinfo_documents = [
-#    (master_doc, 'TF-M', title,
-#     author, 'TF-M', 'Trusted Firmware for Cortex-M',
-#     'Miscellaneous'),
-#]
-
-
-# -- Extension configuration -------------------------------------------------

docs/contributing/code_review_guide.rst

@@ -4,7 +4,7 @@ Code Review Guideline
 The purpose of this document is to clarify design items to be reviewed during
 the code review process.
 
-Please contact :doc:`maintainers </docs/contributing/maintainers>` or write an e-mail
+Please contact :doc:`maintainers </contributing/maintainers>` or write an e-mail
 thread on the `TF-M mailing list <mailto:tf-m@lists.trustedfirmware.org>`_ for
 any questions.
 
@@ -13,9 +13,9 @@ List of the guidelines
 **********************
 The prerequisites before going to the review stage:
 
-- Read the :doc:`Contributing Process </docs/contributing/contributing_process>`
+- Read the :doc:`Contributing Process </contributing/contributing_process>`
   to know basic concepts.
-- Read the :doc:`Source Structure </docs/technical_references/design_docs/source_structure>`
+- Read the :doc:`Source Structure </technical_references/design_docs/source_structure>`
   for structure related reference.
 
 The review guidelines consist of these items:

docs/contributing/coding_guide.rst

@@ -18,7 +18,7 @@ remain within clear scope.
 The guidance below is provided as a help. It isn't meant to be a definitive
 list.
 
-As implied in the :doc:`contributing guide </docs/contributing/contributing_process>`
+As implied in the :doc:`contributing guide </contributing/contributing_process>`
 maintainers have the right to decide on what's acceptable in case of any
 divergence.
 

docs/contributing/contributing_process.rst

@@ -5,12 +5,12 @@ Contributions to the TF-M project need to follow the process below.
 
 .. Note::
 
-   Please contact :doc:`maintainers </docs/contributing/maintainers>` for any
+   Please contact :doc:`maintainers </contributing/maintainers>` for any
    questions.
 
-- Subscribe to `TF-M development
-  <https://lists.trustedfirmware.org/mailman/listinfo/tf-m>`_ if not subscribed
-  already.
+- Subscribe to `TF-M development mailing list
+  <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org>`_
+  if not subscribed already.
 - Refer to the `Roadmap
   <https://developer.trustedfirmware.org/w/tf_m/planning>`_ or send a mail to
   the tf-m@lists.trustedfirmware.org to check if this work is already
@@ -19,22 +19,22 @@ Contributions to the TF-M project need to follow the process below.
   <https://developer.trustedfirmware.org/maniphest>`_, put as many details as
   possible in the description. Add 'Trusted Firmware M' in the 'Tags' field.
 - For non-trivial changes, need to follow the design proposal process
-  :doc:`Design Proposal Process </docs/contributing/tfm_design_proposal_process>`
+  :doc:`Design Proposal Guideline </contributing/tfm_design_proposal_guideline>`
   for the TF-M project.
 - After the design has been accepted by the maintainer(s), a corresponding
   patch should be posted; follow guidelines below:
 
   - Clone the TF-M code on your own machine from `TF-M git repository
     <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`_.
-  - Follow the :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`,
-    :doc:`Build Instructions </docs/technical_references/instructions/tfm_build_instruction>` and
-    :doc:`Coding Guide </docs/contributing/coding_guide>` for the TF-M project.
+  - Follow the :doc:`TF-M getting started </getting_started/tfm_getting_started>`,
+    :doc:`Build Instructions </technical_references/instructions/tfm_build_instruction>` and
+    :doc:`Coding Guide </contributing/coding_guide>` for the TF-M project.
   - Make your changes in logical chunks to help reviewers. Each commit should
     be a separate review and either work properly or be squashed after the
     review and before merging.
   - Update documentation in docs/ folder if needed.
   - Test your changes and add details to the commit description.
-  - The code is accepted under :doc:`DCO </docs/contributing/dco>`, Developer
+  - The code is accepted under :doc:`DCO </contributing/dco>`, Developer
     Certificate of Origin, so you must add following fields to your
     commit description:
 
@@ -66,7 +66,7 @@ Contributions to the TF-M project need to follow the process below.
 
        git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master
 
-- Add relevant :doc:`maintainers </docs/contributing/maintainers>` for reviewing
+- Add relevant :doc:`maintainers </contributing/maintainers>` for reviewing
   the patch.
 - You may be asked to provide further details or make additional changes.
 - You can discuss further with maintainer(s) by directly over email if
@@ -77,4 +77,4 @@ Contributions to the TF-M project need to follow the process below.
 
 --------------
 
-*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*

docs/contributing/dco.rst

@@ -3,7 +3,7 @@
 Developer Certificate of Origin
 ###############################
 
-.. include:: /dco.txt
+.. include:: ../../dco.txt
    :literal:
 
 

docs/contributing/doc_guidelines.rst

@@ -20,7 +20,7 @@ The following short-list provides a quick summary of the rules.
 
 - If the patch modifies a present file, the file's style should be followed
 - If creating a new file,
-  :doc:`integration guide </docs/integration_guide/tfm_integration_guide>` can be used as a reference.
+  :doc:`integration guide </integration_guide/index>` can be used as a reference.
 - When a new style is to be expressed, consult the `Python Documentation Guidelines`_
 
 *************
@@ -186,8 +186,8 @@ will not be added to the index (So it cannot be referenced if needed)
    +--------------+--------------+-------------+
 
 Other types of tables such as list-tables and csv-tables are also permitted, as
-seen on :doc:`/docs/getting_started/tfm_getting_started` and
-:doc:`/docs/releases/1.0`
+seen on :doc:`/getting_started/tfm_getting_started` and
+:doc:`/releases/1.0`
 
 
 External Links
@@ -236,7 +236,7 @@ A document included in the documentation can be referenced by the `doc:` notatio
 
 .. code-block:: restructuredtext
 
-    :doc:`integration guide </docs/integration_guide/tfm_integration_guide>`
+    :doc:`integration guide </integration_guide/tfm_integration_guide>`
 
 The path is relative to the root of the Trusted Firmware-M code.
 
@@ -260,7 +260,7 @@ Glossary term
 =============
 
 For technical terms and abbreviations, the recommended guidance is to add an
-entry to the :doc:`/docs/glossary` and refer to it, using the `term:`
+entry to the :doc:`/glossary` and refer to it, using the `term:`
 directive
 
 
@@ -293,7 +293,7 @@ References
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _Restructed Text: https://docutils.sourceforge.io/rst.html
 .. _Python Documentation Guidelines: https://devguide.python.org/documenting/#style-guide
-.. _Pygments Lexers: https://pygments.org/docs/lexers/
+.. _Pygments Lexers: https://pygments.org/lexers/
 
 --------------
 

docs/contributing/index.rst

@@ -3,10 +3,14 @@ Contribution Guidelines
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-
-    *
+    :titlesonly:
 
+    The process <contributing_process>
+    Code review <code_review_guide>
+    Maintainers and Owners <maintainers>
+    coding_guide
+    Documentation <doc_guidelines>
+    Design proposal <tfm_design_proposal_guideline>
 
 --------------
 

docs/contributing/lic.rst

@@ -3,7 +3,7 @@
 License
 #######
 
-.. include:: /license.rst
+.. include:: ../../license.rst
 
 -----------
 

docs/contributing/maintainers.rst

@@ -36,7 +36,7 @@ Bootloader and FWU
 
 Tamas Ban
     :email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
-    :github: `tamban01 <https://github.com/tamban01>`__
+    :github: `tamasban <https://github.com/tamasban>`__
 
 Sherry Zhang
     :email: `Sherry.Zhang2@arm.com <Sherry.Zhang2@arm.com>`__
@@ -158,21 +158,9 @@ Jamie McCrae
 Nordic Semiconductor Platforms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Ioannis Glaropoulos
-    :email: `ioannis.glaropoulos@nordicsemi.no <ioannis.glaropoulos@nordicsemi.no>`__
-    :github: `ioannisg <https://github.com/ioannisg>`__
-
-Andrzej Głąbek
-    :email: `andrzej.glabek@nordicsemi.no <andrzej.glabek@nordicsemi.no>`__
-    :github: `anangl <https://github.com/anangl>`__
-
-Øyvind Rønningstad
-    :email: `oyvind.ronningstad@nordicsemi.no <oyvind.ronningstad@nordicsemi.no>`__
-    :github: `oyvindronningstad <https://github.com/oyvindronningstad>`__
-
-Sebastian Bøe
-    :email: `sebastian.boe@nordicsemi.no <sebastian.boe@nordicsemi.no>`__
-    :github: `SebastianBoe <https://github.com/SebastianBoe>`__
+Joakim Andersson
+    :email: `joakim.andersson@nordicsemi.no <joakim.andersson@nordicsemi.no>`__
+    :github: `joerchan <https://github.com/joerchan>`__
 
 
 Nuvoton Platform:

docs/contributing/tfm_design_proposal_guideline.rst

@@ -0,0 +1,118 @@
+#########################
+Design proposal guideline
+#########################
+
+The design proposal guideline specifies the steps to propose and upload design
+proposals to TF-M. Those steps are lightweight and flexible to make sure that
+contributors can focus more on actual code implementation and iteration.
+
+The guideline encourages developers to share design proposal via
+TF-M mailing list [1]_ and TF-M technical forum (tech forum) [2]_.
+The design details can be discussed via code reviews of actual implementations.
+
+Typical steps are shown as the diagram below.
+
+.. uml::
+
+  @startuml
+
+  title Design proposal process
+
+  [*] --> propose : Non-trivial changes
+
+  state "Propose general ideas" as propose {
+    state "TF-M mailing list" as mail_list : Contributors send emails to mailing list\nto describe the design.
+    state "TF-M tech forum" as tech_forum : Contributors present the design\nin tech forum.
+
+    [*] --> mail_list
+    [*] --> tech_forum
+  }
+
+  note bottom of propose : Optional but strongly recommended
+
+  [*] --> upload
+  note right of upload : No prerequisites
+  propose --> upload
+
+  state "Upstream changes" as upload : Contributors upstream code patch\nand integration guide to gerrit.
+  state "Code review" as review : Reviewer review changes of\ncode and documents.\nChanges pass verifications.
+  state "Broadcast patches" as broadcast : Contributors ask for review\nin mailing list.
+  state "Approve and merge" as approve : Code owners approve changes.\nMaintainers merge patches.
+
+  upload --> broadcast : Optional
+  upload --> review
+
+  broadcast --> review
+  review --> review : Update implementation
+  review --> approve
+  approve --> [*]
+
+  @enduml
+
+Discussion in TF-M mailing list and tech forum
+==============================================
+
+It is **highly recommended** to propose and discuss designs in TF-M mailing list
+or TF-M tech forum, before or while the code implementation is under review.
+
+It is efficient and flexible to directly discuss design proposal via TF-M
+mailing list and TF-M tech forum. Contributors can receive quick and broad
+feedback from TF-M community.
+
+Although it is optional to present the ideas in mailing list or tech forum, it
+will help reviewers understand the design much better and expedite the code
+review process.
+
+Code review of details
+======================
+
+It is straightforward and convenient for contributors and reviewers to
+deliberate over design and implementation details via code review.
+
+Contributors can implement their design proposal and upstream the patch set to
+TF-M gerrit [3]_ for code review.
+For non-trivial changes or new major features, it is **strongly suggested** to
+propose the design to TF-M mailing list and tech forum in advance.
+
+Contributors don't have to wait for any approvals before upstreaming patches,
+even if the changes are non-trivial.
+No formal design document in advance is required anymore.
+
+The review process is the same as the general one [4]_, with some specific
+requirements:
+
+  - Contributors can send an email to TF-M mailing list to ask for review.
+  - If it requires additional reviewers besides code owners and maintainers,
+    contributors shall add the specific reviewers in the review list.
+  - Authors shall clearly specify the design purpose and briefly describe the
+    implementation in the commit message.
+  - Authors shall put essential comments and notes in code for the code changes.
+
+Code owners and maintainers may require contributors to further verify the
+implementation besides normal per-patch CI test. Contributors shall provide the
+verification results as requested.
+
+Integration guide and manual
+============================
+
+Contributors can create an integration guide or a user manual to describe how to
+integrate the new features related to the design proposal.
+
+Contributors shall update the corresponding documents if the design changes
+existing implementation.
+
+*********
+Reference
+*********
+
+.. [1] `TF-M mailing list <https://lists.trustedfirmware.org/mailman3/lists/tf-m.lists.trustedfirmware.org/>`_
+
+.. [2] `TF-M technical forum <https://www.trustedfirmware.org/meetings/tf-m-technical-forum/>`_
+
+.. [3] `TF-M gerrit <https://review.trustedfirmware.org/q/project:TF-M/trusted-firmware-m>`_
+
+.. [4] :doc:`Contributing process </contributing/contributing_process>`
+
+-------------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*

docs/contributing/tfm_design_proposal_process.rst

@@ -1,155 +0,0 @@
-Design proposal process
-=======================
-
-:Author: Gyorgy Szing
-:Organisation: Arm Limited
-:Contact: Gyorgy Szing <gyorgy.szing@arm.com>
-
-Purpose and Content
--------------------
-This document describes the steps of adding/changing Trusted Firmware design. It
-specifies:
-
-  - The documentation format to be used.
-  - The information which shall be captured.
-  - The steps of the process.
-  - The location where the information shall be captured during the process.
-
-General
--------
-The Trusted Firmware project uses the
-`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ format with
-`Sphinx <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-extensions for documentation. Design documents shall be captured in this format.
-
-Design documents are kept under version control at the project's
-`Gerrit server <https://review.trustedfirmware.org>`_. All decisions made and
-important information gathered during the design discussion, which is  not part
-of the design document shall be captured as Gerrit comments or notes for
-archiving purposes. To meet this requirement this process encourages the use of
-the Gerrit web UI for communication.
-
-
-Status of a document
----------------------
-The status of the document is captured in a *reST filed* called *Status*.
-Bibliographic fields like the *Status* shall be kept near to the top of the
-document after the document title.
-
-Example document fragment::
-
-    TF-M Crypto Service design
-    --------------------------
-
-    :Author: Antonio de Angelis
-    :Organization: Arm Limited
-    :Contact: Antonio de Angelis <antonio.deangelis@arm.com>
-
-Design documents are kept in three different sections of the documentation
-reflecting the status of the document. The status of the document determines
-the section it is in. Open (*Draft* and *Detailed* status) and accepted design
-documents shall be put to the ``docs/technical_references`` directory.
-
-.. important::
-  - 'Author' and 'Organization' can be *OPTIONAL* but at least one of them is
-    *MANDATORY*.
-  - 'Contact' is *MANDATORY* and must be valid for contacting with 'Author'
-    or 'Organization'.
-  - 'Status' is *OPTIONAL* if the design document is managed under a version
-    control tool. In this 'Status' field not available case, a guideline can be:
-
-    - No review comments given design is a *Draft* design.
-    - Positive review comments given design is a *Detailed* design.
-    - Merged design is an *Accepted* design.
-
-Preparation
--------------
-In order to work on TF-M documentation the TF-M git repository has to be
-available locally. Setting up the documentation tools will allow pre-viewing the
-documentation file in preparation.
-For information on what tools are needed please refer to
-:doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`. To see
-how to get a local copy of the TF-M repository please see
-:doc:`build instructions </docs/technical_references/instructions/tfm_build_instruction>`
-
-Process steps
--------------
-
-- Write the design proposal in the format that is described in this document
-  with the *Status* set to *Draft* if *Status* field is provided. Put it to the
-  ``docs/technical_references`` directory and create a pull request.
-- Start an e-mail thread on the
-  `TF-M mailing list <mailto:tf-m@lists.trustedfirmware.org>`_ for discussing
-  the proposal.
-- Build initial consensus within the community about the proposed design
-  change, rework it according to the feedbacks and identify members who would
-  like to participate in the detailed review.
-- When the "short list" of members who are willing to participate in the
-  detailed review is established, set the *Status* field to *Detailed* if
-  *Status* field is provided and push the change to Gerrit.
-- Add the members of the "short list" to the Gerrit review as reviewers.
-- The detailed discussion then takes place in the Gerrit review and gets
-  recorded there.
-  Additional changes are submitted as new commits to the review.
-- When the proposal is accepted and *Status* field is provided, the *Status*
-  field is set to *Accepted* and update the change then get merged.
-
-.. uml::
-
-  @startuml
-  !define DRAFT_DIR **docs/technical_references/**
-  !define REJECTED_DIR **docs/technical_references/rejected/**
-  !define GERRIT_URL https://review.trustedfirmware.org
-  !define GERRIT_LINK [[GERRIT_URL trustedfirmware.org]]
-  !define MAINTAINER_RST_URL https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/maintainers.rst
-  !define TFM_MAILING_LIST mailto:tf-m@lists.trustedfirmware.org
-  !define NO_DECISION **no**
-  !define YES_DECISION **yes**
-  !define STATUS_DRAFT **Draft**
-  !define STATUS_DETAILED **Detailed**
-  !define STATUS_REJECTED **Rejected**
-  !define STATUS_ACCEPTED **Accepted**
-
-  title Design Proposal Process
-
-  start
-  :Create first draft.in [[http://docutils.sourceforge.net/rst.html ReST format]];
-  :Set it's available 'Status' field to STATUS_DRAFT.;
-
-  :Add your document under DRAFT_DIR.;
-  :Create pull-request at GERRIT_LINK.;
-  partition "Initial review." {
-      :Start an e-mail thread at [[TFM_MAILING_LIST tf-m mailing list]].;
-      repeat
-          :Build initial consensus within the
-           community about the proposed design change.;
-          :Gather developers interested in detailed review.;
-       repeat while (Ready for detailed review?)
-  }
-
-  partition "Detailed review." {
-      :Set available 'Status' field to STATUS_DETAILED.;
-      :Add reviewers to pull request.;
-
-      repeat
-         :Discuss design in Gerrit comments/notes.;
-         :Log the result of discussions over
-          other communication channels
-          as Gerrit comments/notes.;
-         :Push new document version if needed.;
-      repeat while (Consensus reached?)
-  }
-
-  if (Design is accepted?) then (STATUS_ACCEPTED)
-      :Sets available 'Status' field to STATUS_ACCEPTED.;
-      ://Submit// the pull-request.;
-  else (STATUS_REJECTED)
-  endif
-
-  stop
-
-  @enduml
-
---------------
-
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*

docs/getting_started/index.rst

@@ -2,11 +2,6 @@ Getting Started Guides
 ======================
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :numbered:
 
-    tfm_getting_started
+.. include:: tfm_getting_started.rst
 
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*

docs/getting_started/tfm_getting_started.rst

@@ -1,6 +1,44 @@
-####################################
-Select and set up build environments
-####################################
+##################
+First Things First
+##################
+
+************
+Prerequisite
+************
+Trusted Firmware M provides a reference implementation of platform security
+architecture  reference implementation aligning with PSA Certified guidelines.
+It is assumed that the reader is familiar with specifications can be found at
+`Platform Security Architecture Resources <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>`__.
+
+The current TF-M implementation specifically targets TrustZone for ARMv8-M so a
+good understanding of the v8-M architecture is also necessary. A good place to
+get started with ARMv8-M is
+`developer.arm.com <https://developer.arm.com/architectures/cpu-architecture/m-profile>`__.
+
+**************************
+Build and run instructions
+**************************
+Trusted Firmware M source code is available on
+`git.trustedfirmware.org <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/>`__.
+
+To build & run TF-M:
+
+    - Follow the this guide to set up and check your environment.
+    - Follow the
+      :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`
+      to compile and build the TF-M source.
+    - Follow the :doc:`Run TF-M examples on Arm platforms </technical_references/instructions/run_tfm_examples_on_arm_platforms>`
+      for information on running the example.
+
+To port TF-M to a another system or OS, follow the
+:doc:`OS Integration Guide </integration_guide/index>`
+
+:doc:`Contributing Guidelines </contributing/contributing_process>` contains guidance on how to
+contribute to this project.
+
+#########################
+Set up 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
@@ -115,7 +153,7 @@ 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.1+
+    - Arm Compiler v6.10.1 ~ v6.14.1
 
       .. tabs::
 
@@ -126,9 +164,11 @@ versions are:
 
                 .. code-block:: bash
 
-                    export PATH=<ARM_CLANG_PATH>/sw/ARMCompiler6.10.1/bin:$PATH
+                    export PATH=<ARM_CLANG_PATH>/bin:$PATH
                     export ARM_PRODUCT_PATH=<ARM_CLANG_PATH>/sw/mappings
 
+              - Configure proper tool variant and license.
+
           .. group-tab:: Windows
 
               - Download the standalone packages from `here <https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-6>`__.
@@ -136,13 +176,16 @@ versions are:
 
                 .. code-block:: bash
 
-                    set PATH=<ARM_CLANG_PATH>\sw\ARMCompiler6.10.1\bin;$PATH
+                    set PATH=<ARM_CLANG_PATH>\bin;$PATH
                     set ARM_PRODUCT_PATH=<ARM_CLANG_PATH>\sw\mappings
 
+              - Configure proper tool variant and license.
+
       .. note::
 
-          ArmClang compiler *v6.17* may cause MemManage fault in TF-M higher level isolations.
-          The issue is under investigation and recommended to avoid using this version.
+          Arm compiler starting from *v6.15* may cause MemManage fault in TF-M
+          higher isolation levels. The issue is under investigation and
+          recommended to using versions prior to v6.15.
 
     - GNU Arm compiler v7.3.1+
 
@@ -239,6 +282,20 @@ as an example:
             cmake -G"Unix Makefiles" .. -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON
             make install
 
+
+        .. note::
+           The latest Windows support long paths, but if you are less lucky
+           then you can reduce paths by moving the build directory closer to
+           the root, using the 'out of tree' build.
+           For example to build in ``C:\build`` folder you can:
+
+           .. code-block:: bash
+
+               cd trusted-firmware-m
+               cmake -G"Unix Makefiles" -S . -B C:/build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug -DTEST_S=ON -DTEST_NS=ON
+               cmake --build C:/build -- install
+
+
 ###########################
 Run AN521 regression sample
 ###########################
@@ -350,8 +407,9 @@ To build the TF-M firmware the following tools are needed:
    - Python v3.x
    - a set of python modules listed in ``tools/requiremtns.txt``
 
+****************
 Dependency chain
-----------------
+****************
 
 .. uml::
 
@@ -390,17 +448,15 @@ Dependency chain
     imgtool --> python
    @enduml
 
-##########
-Next steps
-##########
+.. rubric:: Next steps
 
 Here are some next steps for exploring TF-M:
 
-    - Detailed :doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>`.
-    - :doc:`IAR Build instructions </docs/technical_references/instructions/tfm_build_instruction_iar>`.
-    - Try other :doc:`Samples and Demos </docs/technical_references/instructions/run_tfm_examples_on_arm_platforms>`.
-    - :doc:`Documentation generation </docs/technical_references/instructions/documentation_generation>`.
+    - Detailed :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
+    - :doc:`IAR Build instructions </technical_references/instructions/tfm_build_instruction_iar>`.
+    - Try other :doc:`Samples and Demos </technical_references/instructions/run_tfm_examples_on_arm_platforms>`.
+    - :doc:`Documentation generation </technical_references/instructions/documentation_generation>`.
 
 --------------
 
-*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*

docs/glossary.rst

@@ -2,35 +2,31 @@
 Glossary of terms and abbreviations
 ###################################
 
-************
-TF-M related
-************
 .. glossary::
+    :sorted:
 
     Application RoT
-    Application Root of Trust
         `PSA term`_. The security domain in which additional security services
         are implemented.
 
     HAL
-    Hardware Abstraction Layer
+        Hardware Abstraction Layer:
         Interface to abstract hardware-oriented operations and provides a set of
         APIs to the upper layers.
 
     RoT
-    Root of Trust
+        Root of Trust:
         `PSA term`_. This is the minimal set of software, hardware and data that
         is implicitly trusted in the platform — there is no software or hardware
         at a deeper level that can verify that the Root of Trust is authentic
         and unmodified.
 
     RoT Service
-    Root of Trust Service.
         `PSA term`_. A set of related security operations that are implemented
         in a Secure Partition.
 
-    NSPE : TF-M related
-    Non Secure Processing Enviroment
+    NSPE
+        Non Secure Processing Enviroment:
         `PSA term`_. In TF-M this means non secure domain typically running an
         OS using services provided by TF-M.
 
@@ -44,111 +40,92 @@ TF-M related
         `PSA term`_. Platform Security Architecture Firmware Framework for M.
 
     PSA RoT
-    PSA Root of Trust
         `PSA term`_. This defines the most trusted security domain within a PSA
         system.
 
-    SFN : TF-M related
-    Secure Function
+    SFN
+        Secure Function:
         The function entry to a secure service. Multiple SFN per SS are
         permitted.
 
-    SP : TF-M related
+    SP
     Secure Partition
         A logical container for secure services.
 
-    SPE : TF-M related
-    Secure Processing Environment
+    SPE
+        Secure Processing Environment:
         `PSA term`_. In TF-M this means the secure domain protected by TF-M.
 
-    SPM : TF-M related
+    SPM
     Secure Partition Manager
         The TF-M component responsible for enumeration, management and isolation
         of multiple Secure Partitions within the TEE.
 
-    SPRT : TF-M related
-    Secure Partition Runtime
+    SPRT
+        Secure Partition Runtime:
         The TF-M component responsible for Secure Partition runtime
         functionalities.
 
-    SPRTL : TF-M related
-    Secure Partition Runtime Library
+    SPRTL
+        Secure Partition Runtime Library:
         A library contains the SPRT code and data.
 
-    SS : TF-M related
-    Secure Service
+    SS
+        Secure Service:
         A component within the TEE that is atomic from a security/trust point of
         view, i.e. which is viewed as a single entity from a TF-M point of view.
 
-    PS : TF-M related
+    PS
     Protected Storage
-        Protected storage service provided by TF-M.
+       One of PSA services provided by TF-M.
 
-    ITS : TF-M related
+    ITS
     Internal Trusted Storage
-        Internal Trusted Storage service provided by TF-M.
+       One of PSA services provided by TF-M.
 
     TFM
     TF-M
-    Trusted Firmware-M
-    Trusted Firmware for M-class
+        Trusted Firmware-M or Trusted Firmware for M-class.
         ARM TF-M provides a reference implementation of secure world software
         for ARMv8-M.
 
     TBSA-M
-    Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M
+        Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M.
         TBSA term. See `Trusted Base System Architecture for Armv6-M, Armv7-M
         and Armv8-M`_
 
-****************
-SSE-200 platform
-****************
-.. glossary::
-
-    MPC : SSE-200 platform
-    Memory Protection Controller
+    MPC
+        Memory Protection Controller:
         Bus slave-side security controller for memory regions.
 
-    PPC : SSE-200 platform
-    Peripheral Protection Controller
+    PPC
+        Peripheral Protection Controller:
         Bus slave-side security controller for peripheral access.
 
-************
-v8M-specific
-************
-.. glossary::
-
-    S/NS : v8M-specific
-    Secure/Non-secure
+    S/NS
+        Secure/Non-secure:
         The separation provided by TrustZone hardware components in the system.
 
-    SAU : v8M-specific
-    Secure Attribution Unit
+    SAU
+        Secure Attribution Unit:
         Hardware component providing isolation between Secure, Non-secure
         Callable and Non-secure addresses.
 
-***************
-M-class Generic
-***************
-.. glossary::
-
     AAPCS
-    ARM Architecture Procedure Call Standard
+        ARM Architecture Procedure Call Standard:
         The AAPCS defines how subroutines can be separately written, separately
         compiled, and separately assembled to work together. It describes a
         contract between a calling routine and a called routine
 
-    MPU : M-class Generic
-    Memory Protection Unit
+    MPU
+        Memory Protection Unit:
         Hardware component providing privilege control.
 
     SVC
-    SuperVisor Call
+        SuperVisor Call:
         ARMv7M assembly instruction to call a privileged handler function
 
-*********
-Reference
-*********
+.. rubric:: Reference
 
 | `PSA Firmware_Framework for M`_
 

docs/index.rst

@@ -1,13 +1,3 @@
-:Page authors: Gyorgy Szing <gyorgy.szing@arm.com>
-
-..
-   The build-system will copy all documents into a temporary directory tree
-   before the documentation is built.
-   This file will be copied to the top level and thus please use relative paths
-   as if this file would be in <TFM_ROOT_DIR>.
-
-   The values between @ characters will be filled in by CMake.
-
 Trusted Firmware-M Documentation
 ================================
 
@@ -15,7 +5,7 @@ Trusted Firmware-M Documentation
 
     <ul class="grid">
         <li class="grid-item">
-            <a href="docs/introduction/readme.html">
+            <a href="introduction/readme.html">
                 <img alt="" src="_static/images/tfm-introduction.png"/>
                 <h2>Introduction</h2>
             </a>
@@ -23,7 +13,7 @@ Trusted Firmware-M Documentation
                architecture, features, and licensing.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/getting_started/index.html">
+            <a href="getting_started/index.html">
                <img alt="" src="_static/images/tfm-documentation.png"/>
                <h2>Getting Started</h2>
             </a>
@@ -38,7 +28,7 @@ Trusted Firmware-M Documentation
             <p>List of supported boards and platforms.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/contributing/index.html">
+            <a href="contributing/index.html">
                 <img alt="" src="_static/images/tfm-contribution.png"/>
                 <h2>Contribution</h2>
             </a>
@@ -46,21 +36,21 @@ Trusted Firmware-M Documentation
                to submit patches directly to the project.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/integration_guide/index.html">
+            <a href="integration_guide/index.html">
                 <img alt="" src="_static/images/tfm-integration.png"/>
                 <h2>Integration</h2>
             </a>
             <p>Guidelines for integration with TF-M.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/technical_references/index.html">
+            <a href="technical_references/design_docs/index.html">
                 <img alt="" src="_static/images/tfm-reference.png"/>
                 <h2>References</h2>
             </a>
             <p>Design documents.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/security/index.html">
+            <a href="security/index.html">
                 <img alt="" src="_static/images/tfm.png"/>
                 <h2>Security</h2>
             </a>
@@ -68,7 +58,7 @@ Trusted Firmware-M Documentation
                is addressed within the TF-M project.</p>
         </li>
         <li class="grid-item">
-            <a href="docs/releases/index.html">
+            <a href="releases/index.html">
                 <img alt="" src="_static/images/tfm-release.png"/>
                 <h2>Releases</h2>
             </a>
@@ -77,32 +67,44 @@ Trusted Firmware-M Documentation
     </ul>
 
 .. toctree::
-    :caption: Table of Contents
-    :name: mastertoc
-    :titlesonly:
+    :caption: Overview
     :maxdepth: 1
     :hidden:
 
-    Home<self>
-    docs/introduction/index
-    docs/getting_started/index
-    platform/ext/index
-    docs/contributing/index
-    docs/integration_guide/index
-    docs/technical_references/index
-    docs/security/index
-    docs/releases/index
+    introduction/index
+    Getting Started <getting_started/index>
+    security/index
+    releases/index
+    Glossary <glossary>
 
+.. toctree::
+    :caption: Development
+    :maxdepth: 1
+    :hidden:
+
+    Platform Selection<platform/ext/index>
+    Building <technical_references/instructions/tfm_build_instruction>
+    integration_guide/index
+    technical_references/design_docs/index
+    Tools <tools/index>
+
+.. toctree::
+    :caption: Contribution
+    :titlesonly:
+    :hidden:
+
+    Guidelines <contributing/index>
+    contributing/lic
+    DCO <contributing/dco>
 
 .. toctree::
     :maxdepth: 2
     :hidden:
-    :caption: Quick Links
+    :caption: Links
 
     API Reference <https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/reference_manual/html/index.html>
     Security Center <https://developer.trustedfirmware.org/w/collaboration/security_center>
-    Platform Security Architecture <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>
-    docs/glossary
+    PSA <https://www.arm.com/architecture/security-features/platform-security>
 
 --------------
 

docs/integration_guide/index.rst

@@ -1,12 +1,140 @@
+#################
 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.
+
+
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    */index
-    *
+    NS client integration <non-secure_client_extension_integration_guide.rst>
+    OS migration to Armv8-M <os_migration_guide_armv8m.rst>
+    tfm_fpu_support.rst
+    tfm_secure_irq_integration_guide.rst
+    Adding a Test Suite <tfm_test_suites_addition.rst>
+    How to add a partition <services/tfm_secure_partition_addition>
+
+.. toctree::
+    :maxdepth: 2
+
+    platform/index
+    services/index
+
+
+*****************
+How to build TF-M
+*****************
+Follow the :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
+
+*************************
+How to add a new platform
+*************************
+
+:doc:`Porting TF-M to a New Hardware </integration_guide/platform/porting_TFM_to_a_new_hardware>`
+contains guidance on how to add a new platform.
+
+***************************
+How to integrate another OS
+***************************
+
+OS migration to Armv8-M platforms
+=================================
+To work with TF-M on Armv8-M platforms, 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.
+
+TF-M interface header files are exported in ``<install_dir>/interface/include``
+directory. For example, the Protected Storage (PS) service PSA API is declared
+in the file ``<install_dir>/interface/include/psa/protected_storage.h``.
+
+TF-M also exports a reference implementation of PSA APIs for NS clients in the
+``<install_dir>/interface/src``.
+
+On Armv8-M TrustZone based platforms, NS OS shall implement interface API
+``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
+APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
+of ``tfm_ns_interface_dispatch()``.
+TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
+Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
+``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
+See ``interface/src/tfm_ns_interface.c.example`` for more details.
+
+TF-M provides a reference implementation of NS mailbox on multi-core platforms,
+under folder ``interface/src/multi_core``.
+See :doc:`Mailbox design </technical_references/design_docs/dual-cpu/mailbox_design_on_dual_core_system>`
+for TF-M multi-core mailbox design.
+
+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
+========================
+
+The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
+If SPM manages the NSID (default option), then the same NSID (-1) will be used
+for all connections from NS clients.
+For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
+used for different NS clients. See
+:doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`.
+
+*********************
+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) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*

docs/integration_guide/os_migration_guide_armv8m.rst

@@ -18,7 +18,7 @@ List of requirements
   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 manages the non-secure client identification, pelase check the
-  :doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`.
+  :doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`.
 
 --------------
 

docs/integration_guide/platform/index.rst

@@ -0,0 +1,13 @@
+Porting to a new platform
+=========================
+
+.. toctree::
+    :maxdepth: 1
+
+    porting_TFM_to_a_new_hardware
+    /platform/readme
+    /platform/ext/readme
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*

docs/integration_guide/platform/porting_TFM_to_a_new_hardware.rst

@@ -10,7 +10,7 @@ exist on the platform for TF-M (S and NS) to run on this new platform.
 ******************
 TF-M in a nutshell
 ******************
-For an overview please refer to :doc:`Introduction </docs/introduction/readme>`.
+For an overview please refer to :doc:`Introduction </introduction/readme>`.
 
 *************
 Prerequisites
@@ -19,12 +19,12 @@ Building environnement
 ======================
 Make sure you have a working build environnement and that you can build
 TF-M on AN521 following the
-:doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>`.
+:doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
 
 Toolchains and software requirements
 ====================================
 
-Please follow the :doc:`Getting started guide </docs/getting_started/tfm_getting_started>`.
+Please follow the :doc:`Getting started guide </getting_started/tfm_getting_started>`.
 
 CMSIS Drivers
 =============
@@ -59,7 +59,7 @@ In a nutshell, this should be a 6 iterative steps process:
 
     #. Running the regression tests
 
-        - See :doc:`Running TF-M on Arm platforms </docs/technical_references/instructions/run_tfm_examples_on_arm_platforms>`
+        - See :doc:`Running TF-M on Arm platforms </technical_references/instructions/run_tfm_examples_on_arm_platforms>`
           as an example
 
 
@@ -69,9 +69,9 @@ File architecture
 The platform selection when building TF-M is set via the CMake
 variable TFM_PLATFORM. This variable holds part of the path to the platform.
 
-When using -DTFM_PLATFORM="``arm/mps2/an521``" (as in the build instruction example)
+When using ``-DTFM_PLATFORM=arm/mps2/an521`` or ``-DTFM_PLATFORM=an521``
 TF-M build system will look for the platform in
-<TF-M ROOT>/platform/ext/target/``arm/mps2/an521``.
+<TF-M ROOT>/platform/ext/target/arm/mps2/an521.
 
 Therefore all hardware dependent code for your platform should go to
 <TF-M ROOT>/platform/ext/target/.
@@ -331,7 +331,7 @@ region_defs.h:
     +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+
     |S_MSP_STACK_SIZE                  | Size of the Secure (S) world Main stack                           | yes                                           |
     +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+
-    |S_PSP_STACK_SIZE                  | Size of the Secure (S) world Process stack                        | yes                                           |
+    |S_PSP_STACK_SIZE                  | Size of the Secure (S) world Process stack                        | no for IPC model                              |
     +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+
     |NS_HEAP_SIZE                      | Size of the Non-Secure (NS) world Heap                            | if tfm_ns is built                            |
     +----------------------------------+-------------------------------------------------------------------+-----------------------------------------------+
@@ -409,10 +409,6 @@ CMSIS_Driver/Driver_Flash.c:
     Refer to the CMSIS `FLASH <https://www.keil.com/pack/doc/CMSIS/Driver/html/group__flash__interface__gr.html>`_
     documentation.
 
-    Note: there is a known misalignment with the current CMSIS Flash interface
-    in TF-M. Currently TF-M expects and returns the size whereas CMSIS Flash
-    specifies the number of elements.
-
 CMSIS_Driver/Driver_USART.c:
 ----------------------------
 
@@ -771,4 +767,4 @@ Annex
     # Requires armclang >= 6.10.1
     tfm_invalid_config((CMAKE_C_COMPILER_ID STREQUAL "ARMClang") AND (CMAKE_C_COMPILER_VERSION VERSION_LESS "6.10.1"))
 
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*

docs/integration_guide/services/index.rst

@@ -5,7 +5,13 @@ Services
     :maxdepth: 1
     :glob:
 
-    *
+    Initial Attestation <tfm_attestation_integration_guide>
+    Audit Log <tfm_audit_integration_guide>
+    Crypto <tfm_crypto_integration_guide>
+    Internal Storage <tfm_its_integration_guide>
+    Platform <tfm_platform_integration_guide>
+    Protected Storage <tfm_ps_integration_guide>
+    PSA Proxy <tfm_psa_proxy_integration_guide>
 
 --------------
 

docs/integration_guide/services/tfm_attestation_integration_guide.rst

@@ -587,13 +587,13 @@ Regression test
 ===============
 
 The initial attestation token is verified by the attestation test suite in
-``test/suites/attestation``. The test suite is responsible for verifying the
-token signature and parsing the token to verify its encoding and the presence of
-the mandatory claims. This test suite can be executed on the device. It is part
-of the regression test suite. The test suite is configurable in the
-``test/suites/attestation/attest_token_test_values.h`` header file. In this file
-there are two attributes for each claim which are configurable (more details
-in the header file):
+``test/secure_fw/suites/attestation``. The test suite is responsible for
+verifying the token signature and parsing the token to verify its encoding and
+the presence of the mandatory claims. This test suite can be executed on the
+device. It is part of the regression test suite. The test suite is configurable
+in the ``test/secure_fw/suites/attestation/attest_token_test_values.h`` header
+file. In this file there are two attributes for each claim which are
+configurable (more details in the header file):
 
  - Requirements of presence: optional or mandatory
  - Expected value: Value check can be disabled or expected value can be provided
@@ -605,33 +605,30 @@ and built with initial attestation regresstion test when tests are enabled.
 Initial attestation regression test verifies the IAT generated by initial
 attestation service with the exported public key.
 
-Some develep boards are provisioned in runtime with a random initial attestation
-key pair, whose public key is unknown to regression test. Select test flag
-``ATTEST_TEST_GET_PUBLIC_KEY`` to enable a specific test secure partition to
-retrieve initial attestation public key for initial attestation test in runtime.
-``ATTEST_TEST_GET_PUBLIC_KEY`` shall be selected only when the initial
-attestation public key can only be retrieved in runtime.
-By default, ``ATTEST_TEST_GET_PUBLIC_KEY`` is ``OFF``.
-
 iat-verifier
 ============
 
 There is another possibility to verify the attestation token. This addresses
 the off-device testing when the token is already retrieved from the device and
 verification is done on the requester side. There is a Python script for this
-purpose in ``tools/iat-verifier``. It does the same checking as the
-attestation test suite. The following steps describe how to simulate an
-off-device token verification on a host computer. It is described how to
-retrieve an initial attestation token when TF-M code is executed on FVP
-and how to use the iat_verifier script to check the token. This example assumes
+purpose in the `tf-m-tools`_ repo called `iat-verifier`_. It does the same
+checking as the attestation test suite. The following steps describe how to
+simulate an off-device token verification on a host computer. It is described
+how to retrieve an initial attestation token when TF-M code is executed on FVP
+and how to use the iat-verifier script to check the token. This example assumes
 that user has license for DS-5 and FVP models:
 
+.. _tf-m-tools: https://git.trustedfirmware.org/TF-M/tf-m-tools.git
+
+.. _iat-verifier: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/
+  iat-verifier
+
  - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
    for MPS2 AN521 platform. More info in
-   :doc:`tfm_build_instruction </docs/technical_references/instructions/tfm_build_instruction>`.
+   :doc:`tfm_build_instruction </technical_references/instructions/tfm_build_instruction>`.
  - Lunch FVP model in DS-5. More info in
-   :doc:`Run TF-M examples on Arm platforms </docs/technical_references/instructions/run_tfm_examples_on_arm_platforms>`.
- - Set a breakpoint in ``test/suites/attestation/attest_token_test.c``
+   :doc:`Run TF-M examples on Arm platforms </technical_references/instructions/run_tfm_examples_on_arm_platforms>`.
+ - Set a breakpoint in ``test/secure_fw/suites/attestation/attest_token_test.c``
    in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned,
    i.e. on line 859. Execute the code in the model until the breakpoint hits
    second time. At this point the console prints the test case name:
@@ -661,9 +658,12 @@ that user has license for DS-5 and FVP models:
    - For symmetric initial attestation
      ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key <PATH>/iat_hmac_02.cbor``
 
- - Documentation of the iat-verifier can be found
-   :doc:`here </tools/iat-verifier/README>`.
+ - Documentation of the iat-verifier can be found in the
+   `tf-m-tools-iat-verifer-readme`_ .
+
+.. _tf-m-tools-iat-verifer-readme: https://git.trustedfirmware.org/TF-M/
+  tf-m-tools.git/tree/iat-verifier/README.rst
 
 --------------
 
-*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*

docs/integration_guide/services/tfm_ps_integration_guide.rst

@@ -7,17 +7,17 @@ Introduction
 ************
 TF-M Protected Storage (PS) service implements PSA Protected Storage APIs.
 
-The service is backed by hardware isolation of the flash access domain and, in
-the current version, relies on hardware to isolate the flash area from
-non-secure access. In absence of hardware level isolation, the secrecy and
-integrity of data is still maintained.
+The service is usually backed by hardware isolation of the flash
+access domain and, in the current version, relies on hardware to
+isolate the flash area from non-secure access. In absence of hardware
+isolation, the secrecy and integrity of data is still maintained.
 
 The PS service implements an AES-GCM based AEAD encryption policy, as a
 reference, to protect data integrity and authenticity.
 
-PS reuses the non-hierarchical filesystem provided by the TF-M Internal Trusted
-Storage service to store encrypted, authenticated objects on the external flash
-device.
+The PS reuses the non-hierarchical filesystem provided by the TF-M
+Internal Trusted Storage service to store encrypted, authenticated
+objects.
 
 The design addresses the following high level requirements as well:
 
@@ -45,20 +45,18 @@ The design addresses the following high level requirements as well:
 ******************************
 Current PS Service Limitations
 ******************************
-- **Fragmentation** - The current design does not support fragmentation, as an
-  asset is stored in a contiguous space in a block. This means that the maximum
-  asset size can only be up-to a block size. Detailed information about the
-  maximum asset size can be found in the section `Maximum asset size` below.
-  Each block can potentially store multiple assets.
-  A delete operation implicitly moves all the assets towards the top of the block
-  to avoid fragmentation within block. However, this may also result in
-  unutilized space at the end of each block.
-
 - **Asset size limitation** - An asset is stored in a contiguous space in a
   block/sector. Hence, the maximum asset size can be up-to the size of the
   data block/sector. Detailed information about the maximum asset size can be
   found in the section `Maximum asset size` below.
 
+- **Fragmentation** - The current design does not support fragmentation, as an
+  asset is stored in a contiguous space in a block.
+  Each block can potentially store multiple assets.
+  A delete operation implicitly moves all the assets towards the top of the block
+  to avoid fragmentation within block. However, this may also result in
+  unutilized space at the end of each block.
+
 - **Non-hierarchical storage model** - The current design uses a
   non-hierarchical storage model, as a filesystem, where all the assets are
   managed by a linearly indexed list of metadata. This model locates the
@@ -146,19 +144,19 @@ Core Files
 
 Flash Filesystem and Flash Interfaces
 =====================================
-The PS service reuses the non-hierarchical filesystem and flash interfaces
-provided by the TF-M Internal Trusted Storage service. It stores encrypted,
-authenticated objects on the external flash device by making service calls to
-the ITS service. When the ITS service receives requests from the PS partition,
-it handles the request by using a separate filesystem context initialised to use
-the external flash device.
+The PS service reuses the non-hierarchical filesystem and flash
+interfaces provided by the TF-M Internal Trusted Storage service. It
+stores encrypted, authenticated objects by making service calls to the
+ITS service. When the ITS service receives requests from the PS
+partition, it handles the request by using a separate filesystem
+context.
 
 The ITS filesystem and flash interfaces and their implementation can be found in
 ``secure_fw/partitions/internal_trusted_storage/flash_fs`` and
 ``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More
 information about the filesystem and flash interfaces can be found in the
 :doc:`ITS integration guide
-</docs/integration_guide/services/tfm_its_integration_guide>`.
+</integration_guide/services/tfm_its_integration_guide>`.
 
 The ITS service implementation in
 ``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``,
@@ -293,14 +291,14 @@ TF-M core tracks the current client IDs running in the secure or non-secure
 processing environment. It provides a dedicated API to retrieve the client ID
 which performs the service request.
 
-:doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`
+:doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`
 provides further details on how client identification works.
 
 PS service uses that TF-M core API to retrieve the client ID and associate it
 as the owner of an asset. Only the owner can read, write or delete that asset
 based on the creation flags.
 
-The :doc:`integration guide </docs/integration_guide/tfm_integration_guide>`
+The :doc:`integration guide </integration_guide/index>`
 provides further details of non-secure implementation requirements for TF-M.
 
 Cryptographic Interface
@@ -371,8 +369,8 @@ definitions is:
   object table is allocated statically as PS does not use dynamic memory
   allocation.
 - ``PS_TEST_NV_COUNTERS``- this flag enables the virtual implementation of the
-  PS NV counters interface in ``test/suites/ps/secure/nv_counters`` of the
-  ``tf-m-tests`` repo, which emulates NV counters in
+  PS NV counters interface in ``test/secure_fw/suites/ps/secure/nv_counters`` of
+  the ``tf-m-tests`` repo, which emulates NV counters in
   RAM, and disables the hardware implementation of NV counters provided by
   the secure service. This flag is enabled by default, but has no effect when
   the secure regression test is disabled. This flag can be
@@ -388,5 +386,5 @@ definitions is:
 
 --------------
 
-*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
 *Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*

docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst

@@ -9,7 +9,7 @@ TF-M PSA Proxy partition is responsible for forwarding all the PSA RoT messages
 to a Secure Enclave, this way virtually providing all the PSA RoT services.
 Proxy can only be used in IPC model, for context and design details please
 check the
-:doc:`Secure Enclave design document </docs/technical_references/design_docs/secure_enclave_solution>`.
+:doc:`Secure Enclave design document </technical_references/design_docs/secure_enclave_solution>`.
 
 Currently to forward the PSA Client call parameters Proxy must read them with
 ``psa_read`` into a memory area shared with the Secure Enclave. (Similarily

docs/integration_guide/services/tfm_secure_partition_addition.rst

@@ -13,7 +13,7 @@ This document uses the following terms and abbreviations.
    ================== ==================================
     **Term**          **Meaning**
    ================== ==================================
-   FF                 Firmware Framework
+   FF-M               Firmware Framework for M
    ID                 Identifier
    IPC                Interprocess communication
    IPC model          The secure IPC framework
@@ -22,6 +22,8 @@ This document uses the following terms and abbreviations.
    MMIO               Memory Mapped I/O
    PSA                Platform Security Architecture
    RoT                Root of Trust
+   SFN                Secure Function
+   SFN model          Secure Function model
    SID                RoT Service ID
    SP                 Secure Partition
    SPM                Secure Partition Manager
@@ -45,11 +47,12 @@ focuses on the configuration, manifest, implement rules. The actual
 source-level implementation is not included in this document.
 
 .. Note::
-   If not otherwise specified, the steps are identical for library and IPC
+   If not otherwise specified, the steps are identical for Library, IPC and SFN
    model.
 
-   The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to
-   `PSA Firmware Framework specification`_ for details.
+   The IPC and SFN model conforms to the *PSA Firmware Framework for M (FF-M) v
+   1.1* changes. Refer to `PSA Firmware Framework specification`_ and
+   `Firmware Framework for M 1.1 Extensions`_ for details.
 
 *******
 Process
@@ -63,12 +66,12 @@ The main steps to add a secure partition are as follows:
 
 Add source folder
 =================
-Add a source folder under ``<TF-M base folder>/secure_fw/partitions`` for the new
-secure partition (Let's take EXAMPLE as the folder name):
+Add a source folder under ``<TF-M base folder>/secure_fw/partitions`` for the
+new secure partition (Let's take ``example`` as the folder name):
 
 This folder should include those parts:
 
-- Manifest file: EXAMPLE.yaml
+- Manifest file
 - CMake configuration files
 - Source code files
 
@@ -89,25 +92,32 @@ allocate resources within the SPE. The manifest includes the following:
    The current manifest format in TF-M is "yaml" which is different from the
    requirement of PSA FF.
 
-Here is a manifest reference example for the IPC model, please refer to
-`Library model support`_ for the library extend:
+Here is a manifest reference example for the IPC model:
+
+.. Note::
+    To use SFN model, the user needs to replace ``"model": "IPC"`` to
+    ``"model": "SFN"``. The user also needs to remove the attribute
+    ``"entry_point"``, and optionally replace it with ``"entry_init"``.
 
 .. code-block:: yaml
 
   {
-    "psa_framework_version": 1.0,
+    "psa_framework_version": 1.1,
     "name": "TFM_SP_EXAMPLE",
-    "type": "PSA-ROT",
-    "priority": "HIGH",
-    "entry_point": "example_main",
+    "type": "APPLICATION-ROT",
+    "priority": "NORMAL",
+    "model": "IPC",
+    "entry_point": "tfm_example_main",
     "stack_size": "0x0200",
     "services" : [
       {
         "name": "ROT_A",
-        "sid": "0x0000F000",
+        "sid": "0x000000E0",
         "non_secure_clients": true,
+        "connection_based": true,
         "version": 1,
         "version_policy": "STRICT"
+        "mm_iovec": "disable"
       }
     ],
     "mmio_regions": [
@@ -119,23 +129,23 @@ Here is a manifest reference example for the IPC model, please refer to
     "irqs": [
       {
         "source": "TFM_A_IRQ",
-        "signal": "SPM_CORE_A_IRQ",
+        "name": "A_IRQ",
+        "handling": "SLIH"
       }
-    ],
-    "linker_pattern": {
-      "object_list": [
-        "*EXAMPLE.*"
-      ]
-    }
+    ]
+    "dependencies": [
+      "TFM_CRYPTO",
+      "TFM_INTERNAL_TRUSTED_STORAGE_SERVICE"
+    ]
   }
 
 Secure Partition ID Distribution
 --------------------------------
 Every Secure Partition has an identifier (ID). TF-M will generate a header file
 that includes definitions of the Secure Partition IDs. The header file is
-``<TF-M base folder>/interface/include/psa_manifest/pid.h``. Each definition
-uses the ``name`` attribute in the manifest as its name and the value is
-allocated by SPM.
+``<TF-M build folder>generated/interface/include/psa_manifest/pid.h``. Each
+definition uses the ``name`` attribute in the manifest as its name and the
+value is allocated by SPM.
 
 The Partition ID can be set to a fixed value or omitted to be auto allocated.
 
@@ -143,8 +153,23 @@ The Partition ID can be set to a fixed value or omitted to be auto allocated.
 
    #define name id-value
 
-Please refer to ``<TF-M base folder>/tools/tfm_manifest_list.yaml`` for the PID
-allocations.
+.. table:: PID table
+   :widths: auto
+
+   ==================================== ======================
+   **Secure Partitions**                **PID Range**
+   ==================================== ======================
+   TF-M Internal Partitions             0 - 255
+   PSA and user Partitions              256 - 2999
+   TF-M test Partitions                 3000 - 4999
+   Firmware Framework test Partitions   5000 - 5999
+   Reserved                             6000 -
+   ==================================== ======================
+
+Please refer to ``<TF-M base folder>/tools/tfm_manifest_list.yaml``,
+``<TF-M test repo>/test/secure_fw/tfm_test_manifest_list.yaml`` and
+``<TF-M base folder>/tools/tfm_psa_ff_test_manifest_list.yaml`` for the detailed
+PID allocations.
 
 About where to add the definition, please refer to the chapter `Add
 configuration`_.
@@ -162,7 +187,7 @@ Here is the RoT Service ID table used in TF-M.
    :widths: auto
 
    =========================== ====================== ========================
-   **Services**                **Vendor ID(20 bits)** **Function ID(12 bits)**
+   **Partitions**              **Vendor ID(20 bits)** **Function ID(12 bits)**
    =========================== ====================== ========================
    audit_logging               0x00000                0x000-0x01F
    initial_attestation         0x00000                0x020-0x03F
@@ -171,7 +196,7 @@ Here is the RoT Service ID table used in TF-M.
    internal_trusted_storage    0x00000                0x070-0x07F
    crypto                      0x00000                0x080-0x09F
    firmware_update             0x00000                0x0A0-0x0BF
-   test_secure_service         0x0000F                0x000-0x01F
+   tfm_secure_client           0x0000F                0x000-0x01F
    core_test                   0x0000F                0x020-0x03F
    core_test_2                 0x0000F                0x040-0x05F
    tfm_ipc_client              0x0000F                0x060-0x07F
@@ -179,14 +204,19 @@ Here is the RoT Service ID table used in TF-M.
    tfm_slih_test_service       0x0000F                0x0A0-0x0AF
    tfm_flih_test_service       0x0000F                0x0B0-0x0BF
    tfm_ps_test_service         0x0000F                0x0C0-0x0DF
+   tfm_secure_client_2         0x0000F                0x0E0-0x0FF
+   tfm_sfn_test_service_1      0x0000F                0x100-0x11F
+   tfm_sfn_test_service_2      0x0000F                0x120-0x13F
+   tfm_attest_test_service     0x0000F                0x140-0x15F
    =========================== ====================== ========================
 
 RoT Service Stateless Handle Distribution
 -----------------------------------------
-A RoT Service may include stateless services. They are distinguished and
+A Secure partition may include stateless services. They are distinguished and
 referenced by stateless handles. In manifest, a ``stateless_handle`` attribute
-is set for indexing stateless services. The valid range is [1, 32] in current
-implementation and may extend.
+is set for indexing stateless services. It must be either ``"auto"`` or a
+number in the range [1, 32] in current implementation and may extend. Also the
+``connection-based`` attribute must be set to ``false`` for stateless services.
 
 Here is the stateless handle allocation for partitions in TF-M. Partitions not
 listed are not applied to stateless mechanism yet.
@@ -226,24 +256,19 @@ TF-M uses the below structure to indicate a peripheral memory.
    implementations are using. Other peripherals that need different information
    to create isolation need to define a different structure with the same name.
 
-Here is a example for it:
+Here is an example for it:
 
 .. code-block:: c
 
    struct platform_data_t tfm_peripheral_A;
    #define TFM_PERIPHERAL_A                 (&tfm_peripheral_A)
 
-linker_pattern
---------------
-``linker_pattern`` is a legacy region which contains the minimum information
-required to link a Secure Partition’s compiled static objects. Now, it is
-required as 'IMPLEMENTATION DEFINED' in PSA FF 1.0.0.
 
 Library model support
 ---------------------
 For the library model, the user needs to add a ``secure_functions`` item. The
 main difference between ``secure_function`` and ``services`` is the extra
-``signal`` key for secure function entry.
+``signal`` key for secure function entry. This is not required in FF-M v1.0.
 
 The ``signal`` must be the upper case of the secure function name.
 
@@ -266,7 +291,14 @@ partition:
 
 Add CMake configure files
 -------------------------
-- CMakeLists.txt, which is the compilation configuration for this module.
+- ``<TF-M base folder>/secure_fw/partitions/example/CMakeLists.txt``, which is
+  the compilation configuration for this module. Add library
+  ``tfm_app_rot_partition_example`` and associated source files.
+
+Here is a reference example for `CMakeLists.txt`_
+
+.. _CMakeLists.txt: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/
+  example_partition/CMakeLists.txt
 
 .. Note::
    The secure partition must be built as a standalone static library, and the
@@ -276,14 +308,19 @@ Add CMake configure files
    - ``tfm_app_rot_partition*`` in case of an Application RoT partition
 
 The current CMake configuration should also be updated, by updating
-config_default.cmake to include the definition of the newly introduced partition
-and adding the relevant subdirectoy in ``secure_fw/CMakeLists.txt``.
+``<TF-M base folder>/config/config_default.cmake``
+to include the CMake configuration variable of the newly added Secure
+Partition, e.g, TFM_PARTITION_EXAMPLE and adding the relevant
+subdirectory in ``<TF-M base folder>/secure_fw/CMakeLists.txt``, e.g.
+``add_subdirectory(partitions/example)``.
 Please refer to the source code of TF-M for more detail.
 
 Update manifest list
 --------------------
 The ``<TF-M base folder>/tools/tfm_manifest_list.yaml`` is used to collect
 necessary information of secure partition.
+The manifest tool ``tools/tfm_parse_manifest_list.py`` processes it and
+generates necessary files while building.
 
 - ``name``: The name string of the secure partition.
 - ``short_name``: should be the same as the ``name`` in the secure partition
@@ -291,54 +328,96 @@ necessary information of secure partition.
 - ``manifest``: the relative path of the manifest file to TF-M root.
   In out-of-tree secure partition, ``manifest`` can be an absolute path or the
   relative path to the current manifest list file.
-- ``conditional``: Optional. Configure control macro for this partition.
+- ``conditional``: Optional configuration to enable or disable this partition.
+  If it is not set, the Secure Partition is always enabled.
+  The value of this attribute must be a CMake variable surrounded by ``@``.
+  The value of the CMake variable must be:
+
+  - ``ON``, ``TRUE`` or ``ENABLED`` - the Partition is enabled.
+  - ``OFF``, ``FALSE`` or ``DISABLED`` - the Partition is disabled.
+  - unset - the Partition is disabled.
+
+  The build system relies on the CMake command ``configure_file()`` to replace
+  the CMake variables with the corresponding values before the manifest tool
+  processes it.
+  If you are using the manifest tool out of the CMake build system, you can also
+  set this attribute to the values allowed above to make the tool work.
+
 - ``version_major``: major version the partition manifest.
 - ``version_minor``: minor version the partition manifest.
 - ``pid``: Secure Partition ID value distributed in chapter `Secure Partition
   ID Distribution`_.
-- ``output_dir``: Optional. Secure Partition can specify a relative path to
-  ``<build_dir>/generated`` to hold the generated files.
-  It enables Secure Partition to select a generated path independent from its
-  source code path, for example in out-of-tree Secure Parition build.
+- ``output_dir``: Optional path to hold the generated files.
+  The files are generated to:
+
+  - ``<build_dir>/generated/<output_dir>``, if ``output_dir`` is relative path.
+  - ``<output_dir>``, if ``output_dir`` is absolute path.
+  - ``<build_dir>/generated/``, if ``output_dir`` is not set.
+- ``linker_pattern``: contains the information for linker to place the symbols
+  of the Secure Partition. The following patterns are supported:
+
+    - ``library_list`` - the library defined by CMake in `Add configuration`_
+      section. It must be ``*tfm_*partition_<name>.*``, the ``<name>>`` must
+      match the CMake library name.
+
+    - ``object_list`` - Any object files containing symbols belonging to the
+      Secure Partition but are not included in the Secure Partitions library.
 
 Reference configuration example:
 
 .. code-block:: yaml
 
     {
-      "name": "Example Service",
+      "name": "TFM Example Service",
       "short_name": "TFM_SP_EXAMPLE",
-      "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml",
-      "conditional": "TFM_PARTITION_EXAMPLE",
+      "manifest": "secure_fw/partitions/example/tfm_example_partition.yaml",
+      "conditional": "@TFM_PARTITION_EXAMPLE@",
+      "output_path": "partitions/example",
       "version_major": 0,
       "version_minor": 1,
-      "pid": 256
+      "pid": 290,
+      "linker_pattern": {
+        "library_list": [
+          "*tfm_*partition_example*"
+         ]
+      }
     }
 
+TF-M also supports out-of-tree Secure Partition build where you can have your
+own manifest lists.
+Please refer to `Out-of-tree Secure Partition build`_ for details.
+
 Implement the RoT services
 ==========================
 To implement RoT services, the partition needs a source file which contains the
 implementations of the services, as well as the partition entry point. The user
 can create this source file under
-``<TF-M base folder>/secure_fw/partitions/EXAMPLE/EXAMPLE.c``. The linker
-detects source files according to the pattern matching defined by the
-"linker_pattern" attribute in the ``tfm_manifest_list.yaml`` file.
+``<TF-M base folder>/secure_fw/partitions/example/tfm_example_partition.c``.
 
 As an example, the RoT service with SID **ROT_A** will be implemented.
 
-Entry point function
---------------------
-This function acts as a main() function for the partition.
-On incoming signals for service calls, the entry point function handles
-signals by calling the relevant service function.
-An example entry point is given
+Entry point for IPC Model Partitions
+------------------------------------
+This function must have a loop that repeatedly waits for input signals and
+then processes them, following the Secure Partition initialization.
 
 .. code-block:: c
 
-    void example_main(void)
+    #include "psa_manifest/tfm_example.h"
+    #include "psa/service.h"
+
+    void tfm_example_main(void)
     {
         psa_signal_t signals = 0;
 
+        /* Secure Partition initialization */
+        example_init();
+
+        /*
+         * Continually wait for one or more of the partition's RoT Service or
+         * interrupt signals to be asserted and then handle the asserted
+         * signal(s).
+         */
         while (1) {
             signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK);
             if (signals & ROT_A_SIGNAL) {
@@ -350,8 +429,25 @@ An example entry point is given
         }
     }
 
-Service implementation
-----------------------
+Entry init for SFN Model Partitions
+-----------------------------------
+In the SFN model, the Secure Partition consists of one optional initialization
+function, which is declared as the ``entry_init`` symbol as mentioned in
+section `Add manifest`_. After initialization, the entry_init function
+returns the following values:
+
+    - Return ``PSA_SUCCESS`` if initialization succeeds.
+
+    - Return ``PSA_SUCCESS`` if initialization is partially successful,
+      and you want some SFNs to receive messages. RoT Services that are
+      non-operational must respond to connection requests with
+      ``PSA_ERROR_CONNECTION_REFUSED``.
+
+    - Return an error status if the initialization failed, and no SFNs
+      within the Secure Partition must be called.
+
+Service implementation for IPC Model
+------------------------------------
 The service is implemented by the ``rot_A()`` function, which is called upon an
 incoming signal. This implementation is up to the user, however an example
 service has been included for reference. The following example sends a message
@@ -359,11 +455,13 @@ service has been included for reference. The following example sends a message
 
 .. code-block:: c
 
+    #include "psa_manifest/tfm_example.h"
+    #include "psa/service.h"
+
     static void rot_A(void)
     {
         const int BUFFER_LEN = 32;
         psa_msg_t msg;
-        psa_status_t r;
         int i;
         uint8_t rec_buf[BUFFER_LEN];
         uint8_t send_buf[BUFFER_LEN] = "Hello World";
@@ -371,13 +469,12 @@ service has been included for reference. The following example sends a message
         psa_get(ROT_A_SIGNAL, &msg);
         switch (msg.type) {
         case PSA_IPC_CONNECT:
-            if (service_in_use & ROT_A_SIGNAL) {
-                r = PSA_ERROR_CONNECTION_REFUSED;
-            } else {
-                service_in_use |= ROT_A_SIGNAL;
-                r = PSA_SUCCESS;
-            }
-            psa_reply(msg.handle, r);
+        case PSA_IPC_DISCONNECT:
+            /*
+             * This service does not require any setup or teardown on connect
+             * or disconnect, so just reply with success.
+             */
+            psa_reply(msg.handle, PSA_SUCCESS);
             break;
         case PSA_IPC_CALL:
             for (i = 0; i < PSA_MAX_IOVEC; i++) {
@@ -390,11 +487,6 @@ service has been included for reference. The following example sends a message
             }
             psa_reply(msg.handle, PSA_SUCCESS);
             break;
-        case PSA_IPC_DISCONNECT:
-            assert((service_in_use & ROT_A_SIGNAL) != 0);
-            service_in_use &= ~ROT_A_SIGNAL;
-            psa_reply(msg.handle, PSA_SUCCESS);
-            break;
         default:
             /* cannot get here [broken SPM] */
             psa_panic();
@@ -402,14 +494,77 @@ service has been included for reference. The following example sends a message
         }
     }
 
+Service implementation for SFN Model
+------------------------------------
+SFN model consists of a set of Secure Functions (SFN), one for each RoT
+Service. The connection, disconnection and request messages do not cause a
+Secure Partition signal to be asserted for SFN Secure Partitions. Instead,
+the Secure Function (SFN) for the RoT Service is invoked by the framework,
+with the message details provided as a parameter to the SFN. To add a secure
+function (SFN) to process messages for each RoT Service, each SFN will have
+following prototype.
+
+.. code-block:: c
+
+  psa_status_t <<name>>_sfn(const psa_msg_t *msg);
+
+A connection-based example service has been included for reference which
+sends a message "Hello World" when called.
+
+.. code-block:: c
+
+    #include "psa_manifest/tfm_example.h"
+    #include "psa/service.h"
+
+    psa_status_t rot_a_sfn(const psa_msg_t *msg)
+    {
+        const int BUFFER_LEN = 32;
+        int i;
+        uint8_t rec_buf[BUFFER_LEN];
+        uint8_t send_buf[BUFFER_LEN] = "Hello World";
+
+        switch (msg->type) {
+        case PSA_IPC_CONNECT:
+        case PSA_IPC_DISCONNECT:
+            /*
+             * This service does not require any setup or teardown on connect
+             * or disconnect, so just reply with success.
+             */
+            return PSA_SUCCESS;
+        case PSA_IPC_CALL:
+            for (i = 0; i < PSA_MAX_IOVEC; i++) {
+                if (msg->in_size[i] != 0) {
+                    psa_read(msg->handle, i, rec_buf, BUFFER_LEN);
+                }
+                if (msg.->out_size[i] != 0) {
+                    psa_write(msg->handle, i, send_buf, BUFFER_LEN);
+                }
+            }
+            return PSA_SUCCESS;
+        default:
+            /* cannot get here [broken SPM] */
+            return PSA_ERROR_PROGRAMMER_ERROR;
+        }
+    }
+
 Test connection
 ---------------
 To test that the service has been implemented correctly, the user needs to call
 it from somewhere. One option is to create a new testsuite, such as
-``<TF-M-test base folder>/test/suites/example/non_secure/example_ns_interface_testsuite.c``.
+``<TF-M-test base folder>/test/secure_fw/suites/example/non_secure/example_ns_
+interface_testsuite.c``.
+
+The process of adding test connection is explained in the specification
+:doc:`Adding TF-M Regression Test Suite </integration_guide/tfm_test_suites_addition>`
 
 .. code-block:: c
 
+    #include "psa_manifest/sid.h"
+    #include "psa/client.h"
+
+    #include "test_framework.h"
+    #include "test_log.h"
+
     static void tfm_example_test_1001(struct test_result_t *ret)
     {
         char str1[] = "str1";
@@ -565,10 +720,14 @@ Reference
 *********
 
 | `PSA Firmware Framework specification`_
+| `Firmware Framework for M 1.1 Extensions`_
 
-.. _PSA Firmware Framework specification: https://pages.arm.com/psa-
-  resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
+.. _PSA Firmware Framework specification:
+  https://www.arm.com/architecture/security-features/platform-security
+
+.. _Firmware Framework for M 1.1 Extensions: https://developer.arm.com/
+  documentation/aes0039/latest
 
 --------------
 
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*

docs/integration_guide/tfm_fpu_support.rst

@@ -3,28 +3,38 @@ Floating-Point Support
 ######################
 
 TF-M adds several configuration flags to control Floating point (FP) [1]_
-support in TF-M Secure Processing Environment (SPE).
-Non Secure Processing Environment (NSPE) is not allowed to access Floating
-Point Unit (FPU) [2]_ when FP support is enabled in SPE at current stage.
+support in TF-M Secure Processing Environment (SPE) and Non Secure Processing
+Environment (NSPE).
 
-* Support GNU Arm Embedded Toolchain [3]_.
-* Support FP Application Binary Interface (ABI) [4]_ types: software, hybird,
-  hardware.
-* Support lazy stacking on/off.
+* Support FP in SPE or NSPE.
+* Support FP Application Binary Interface (ABI) [2]_ types: software, hardware.
+  SPE and NSPE shall use the same FP ABI type.
+* Support lazy stacking enable/disable in SPE only, NSPE is not allowed to
+  enable/disable this feature.
+* Support GNU Arm Embedded Toolchain [3]_. ``GNU Arm Embedded Toolchain 10.3-
+  2021.10`` and later version shall be used to mitigate VLLDM instruction
+  security vulnerability [4]_.
 * Support Inter-Process Communication (IPC) [5]_ model in TF-M, and doesn't
   support LIBRARY or SFN model.
-* Support Armv8-M [6]_ mainline or later.
+* Support Armv8.0-M mainline.
 * Support isolation level 1,2,3.
-* Does not support use FPU in First-Level Interrupt Handling (FLIH) [7]_ at
+* Does not support use FPU in First-Level Interrupt Handling (FLIH) [6]_ at
   current stage.
 
-Please refer to Arm musca S1 [8]_ platform as a reference implementation when
+Please refer to Arm musca S1 [7]_ platform as a reference implementation when
 you enable FP support on your platforms.
 
-Secure libraries are compiled with ``COMPILER_CP_FLAG`` and linked with
-``LINKER_CP_OPTION`` for different FP ABI types. All those libraries shall be
-built with the same FP ABI type. Otherwise, linking errors may occur due to FP
-ABI type conflicts.
+============================
+FP ABI type for SPE and NSPE
+============================
+FP design in Armv8.0-M [8]_ architecture requires consistent FP ABI types
+between SPE and NSPE. Furthermore, both sides shall set up CPACR individually
+when FPU is used. Otherwise, No Coprocessor (NOCP) usage fault will be asserted
+during FP context switch between security states.
+
+Secure and non-secure libraries are compiled with ``COMPILER_CP_FLAG`` and
+linked with ``LINKER_CP_OPTION`` for different FP ABI types. All those
+libraries shall be built with ``COMPLIER_CP_FLAG``.
 
 If FP ABI types mismatch error is generated during build, pleae check whether
 the library is compiled with ``COMPILER_CP_FLAG``.
@@ -42,26 +52,27 @@ CMake configurations for FP support
 ===================================
 The following CMake configurations configure ``COMPILER_CP_FLAG`` in TF-M SPE.
 
-* ``CONFIG_TFM_SPE_FP`` are used to configure FP ABI type for secure side.
+* ``CONFIG_TFM_FP`` are used to configure FP ABI type for secure and non-secure
+  side both.
 
   +-------------------+---------------------------+
-  | CONFIG_TFM_SPE_FP | FP ABI type [2]_ [3]_     |
+  | CONFIG_TFM_FP     | FP ABI type [2]_ [3]_     |
   +===================+===========================+
-  | 0 (default)       | Software                  |
+  | soft (default)    | Software                  |
   +-------------------+---------------------------+
-  | 1                 | Hybird                    |
-  +-------------------+---------------------------+
-  | 2                 | Hardware                  |
+  | hard              | Hardware                  |
   +-------------------+---------------------------+
 
-  FP software ABI type is default for secure side in TF-M (mfloat-abi=soft).
+  FP software ABI type is default in TF-M.
 
-* ``CONFIG_TFM_LAZY_STACKING_SPE`` is used to enable/disable lazy stacking
-  feature from secure side. This feature is only valid for FP hardware or
-  hybird option.
+* ``CONFIG_TFM_LAZY_STACKING`` is used to enable/disable lazy stacking
+  feature. This feature is only valid for FP hardware ABI type.
+  NSPE is not allowed to enable/disable this feature. Let SPE decide the
+  secure/non-secure shared setting of lazy stacking to avoid the possible
+  side-path brought by flexibility.
 
   +------------------------------+---------------------------+
-  | CONFIG_TFM_LAZY_STACKING_SPE | Description               |
+  | CONFIG_TFM_LAZY_STACKING     | Description               |
   +==============================+===========================+
   | 0FF                          | Disable lazy stacking     |
   +------------------------------+---------------------------+
@@ -69,7 +80,7 @@ The following CMake configurations configure ``COMPILER_CP_FLAG`` in TF-M SPE.
   +------------------------------+---------------------------+
 
 * ``CONFIG_TFM_FP_ARCH`` specifies which FP architecture is available on the
-  target, valid for FP hardware or hybird option.
+  target, valid for FP hardware ABI type.
 
   FP architecture is processor dependent. For GNUARM compiler, example value
   are: auto, fpv5-d16, fpv5-sp-d16, etc.
@@ -86,20 +97,19 @@ Reference
 *********
 .. [1] `High-Performance Hardware Support for Floating-Point Operations <https://www.arm.com/why-arm/technologies/floating-point>`_
 
-.. [2] `Cortex-M4 Technical Reference Manual <https://developer.arm.com/documentation/ddi0439/b/Floating-Point-Unit/About-the-FPU>`_
+.. [2] `Float Point ABI <https://www.keil.com/support/man/docs/armclang_ref/armclang_ref_chr1417451577871.htm>`_
 
 .. [3] `GNU Arm Embedded Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
 
-.. [4] `Float Point ABI <https://www.keil.com/support/man/docs/armclang_ref/armclang_ref_chr1417451577871.htm>`_
+.. [4] `VLLDM instruction Security Vulnerability <https://developer.arm.com/support/arm-security-updates/vlldm-instruction-security-vulnerability>`_
 
-.. [5] :doc:`TF-M Inter-Process Communication </docs/technical_references/design_docs/tfm_psa_inter_process_communication>`
+.. [5] `Arm® Platform Security Architecture Firmware Framework 1.0 <https://armkeil.blob.core.windows.net/developer/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf>`_
 
-.. [6] `Armv8-M Architecture Reference Manual <https://developer.arm.com/documentation/ddi0553/latest>`_
+.. [6] :doc:`Secure Interrupt Integration Guide </integration_guide/tfm_secure_irq_integration_guide>`
 
-.. [7] :doc:`Secure Interrupt Integration Guide </docs/integration_guide/tfm_secure_irq_integration_guide>`
-
-.. [8] `Musca-S1 Test Chip Board <https://developer.arm.com/tools-and-software/development-boards/iot-test-chips-and-boards/musca-s1-test-chip-board>`_
+.. [7] `Musca-S1 Test Chip Board <https://developer.arm.com/tools-and-software/development-boards/iot-test-chips-and-boards/musca-s1-test-chip-board>`_
 
+.. [8] `Armv8-M Architecture Reference Manual <https://developer.arm.com/documentation/ddi0553/latest>`_
 
 --------------
 

docs/integration_guide/tfm_integration_guide.rst

@@ -1,176 +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 </docs/technical_references/instructions/tfm_build_instruction>`.
-
-********************************************************
-How to export files for building non-secure applications
-********************************************************
-Explained in the :doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>`.
-
-*************************
-How to add a new platform
-*************************
-
-:doc:`Porting TF-M to a New Hardware </docs/integration_guide/porting_TFM_to_a_new_hardware>`
-contains guidance on how to add a new platform.
-
-*******************
-Supported Platforms
-*******************
-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 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 DK (Cortex-M33 Application MCU)
-- BL5340 DVK (Cortex-M33 Application MCU)
-- Corstone-Polaris Ethos-U55 FVP (Olympus CPU plus Ethos-U55)
-
-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 DK platform can be found in:
-`nRF5340 DK product page <https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF5340-DK>`__
-
-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>`__
-
-More information about the BL5340 platform can be found in:
-`BL5340 product page <https://www.lairdconnect.com/wireless-modules/bluetooth-modules/bluetooth-5-modules/bl5340-series-multi-core-bluetooth-52-802154-nfc-modules>`__
-
-***************************
-How to integrate another OS
-***************************
-
-OS migration to Armv8-M platforms
-=================================
-To work with TF-M on Armv8-M platforms, 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.
-
-TF-M interface header files are exported in ``<install_dir>/interface/include``
-directory. For example, the Protected Storage (PS) service PSA API is declared
-in the file ``<install_dir>/interface/include/psa/protected_storage.h``.
-
-TF-M also exports a reference implementation of PSA APIs for NS clients in the
-``<install_dir>/interface/src``.
-
-On Armv8-M TrustZone based platforms, NS OS shall implement interface API
-``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
-APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
-of ``tfm_ns_interface_dispatch()``.
-TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
-Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
-``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
-See ``interface/src/tfm_ns_interface.c.example`` for more details.
-
-TF-M provides a reference implementation of NS mailbox on multi-core platforms,
-under folder ``interface/src/multi_core``.
-See :doc:`Mailbox design </docs/technical_references/design_docs/dual-cpu/mailbox_design_on_dual_core_system>`
-for TF-M multi-core mailbox design.
-
-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
-========================
-
-The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
-If SPM manages the NSID (default option), then the same NSID (-1) will be used
-for all connections from NS clients.
-For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
-used for different NS clients. See
-:doc:`Non-secure Client Extension Integration Guide </docs/integration_guide/non-secure_client_extension_integration_guide>`.
-
-*********************
-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.*

docs/integration_guide/tfm_secure_irq_integration_guide.rst

@@ -228,7 +228,7 @@ Here is an example of named region:
 The Device Drivers
 ------------------
 
-To give permissions of devices drivers to Secure Partitions, it is recommanded
+To give permissions of devices drivers to Secure Partitions, it is recommended
 to put the driver codes to the Partition's CMake library:
 
 .. code-block:: bash
@@ -262,6 +262,10 @@ is ``irq_5_init``.
 If the mannifest declares ``"source"  : "TIMER_1_IRQ"`` then the function
 name is ``timer_1_irq_init``.
 
+The function will be called by the Framework automatically during
+initialization. The function can be put in any source file that belongs to SPM,
+for example a ``tfm_interrupts.c`` added to the ``platform_s`` CMake target.
+
 The initialization of an interrupt must include:
 
 - setting the priority
@@ -328,8 +332,20 @@ TF-M provides an interrupt handling entry for Secure interrupts:
 The ``p_pt`` and ``p_ildi`` are the information passed to interrupt
 initialization functions and saved by platforms.
 
-Platforms should call this entry function in the interrupt handlers defined in
-Vector Table with the saved information for each interrupt.
+Platforms should call this entry function in the interrupt handlers held in
+Vector Table with the information saved by the interrupt initialization
+functions.
+If the information is saved as global variables, then the interrupt handlers can
+be put in the same source file that contains the initialization functions.
+
+Here is an example:
+
+.. code-block:: c
+
+  void TFM_TIMER0_IRQ_Handler(void) /* The handler in Vector Table */
+  {
+      spm_handle_interrupt(p_timer0_pt, p_tfm_timer0_irq_ldinf);
+  }
 
 ****************************
 Enabling the Interrupt Tests
@@ -380,10 +396,10 @@ References
 
 .. [2] `FF-M v1.1 Extention <https://documentation-service.arm.com/static/600067c09b9c2d1bb22cd1c5?token=>`__
 
-.. [3] https://git.trustedfirmware.org/TF-M/tf-m-tests.git/tree/test/test_services/tfm_flih_test_service
+.. [3] https://git.trustedfirmware.org/TF-M/tf-m-tests.git/tree/test/secure_fw/suites/spm/irq/service/tfm_flih_test_service
 
-.. [4] https://git.trustedfirmware.org/TF-M/tf-m-tests.git/tree/test/test_services/tfm_slih_test_service
+.. [4] https://git.trustedfirmware.org/TF-M/tf-m-tests.git/tree/test/secure_fw/suites/spm/irq/service/tfm_slih_test_service
 
 --------------
 
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*

docs/integration_guide/tfm_test_suites_addition.rst

@@ -22,23 +22,25 @@ Source structure
 TF-M tests source code are located in
 `tf-m-tests <https://git.trustedfirmware.org/TF-M/tf-m-tests.git/>`__.
 
-+----------------+-------------------------------------------------------------+
-| Folder name    | Description                                                 |
-+================+=============================================================+
-| test/config    | The CMAKE test configurations files.                        |
-+----------------+-------------------------------------------------------------+
-| test/framework | Source code for test framework code, managing test suites.  |
-+----------------+-------------------------------------------------------------+
-| test/suites    | Test suites divided into subdirectories.                    |
-+----------------+-------------------------------------------------------------+
-| test/services  | Test services divided into subdirectories.                  |
-+----------------+-------------------------------------------------------------+
++---------------------------------------+---------------------------------------------------------------+
+| Folder name                           | Description                                                   |
++=======================================+===============================================================+
+| test/config                           | The CMAKE test configurations files.                          |
++---------------------------------------+---------------------------------------------------------------+
+| test/framework                        | Source code for test framework code, managing test suites.    |
++---------------------------------------+---------------------------------------------------------------+
+| test/secure_fw/suites                 | Test suites divided into subdirectories.                      |
++---------------------------------------+---------------------------------------------------------------+
+| test/secure_fw/suites/<suite>/service | Test service divided into corresponding suite subdirectories. |
++---------------------------------------+---------------------------------------------------------------+
+| test/secure_fw/common_test_services   | Common test services.                                         |
++---------------------------------------+---------------------------------------------------------------+
 
 Test configuration
 ==================
 
 A test configuration controls whether one or multiple test suites are enabled.
-The doc :doc:`TF-M Build Instructions </docs/technical_references/instructions/tfm_build_instruction>`
+The doc :doc:`TF-M Build Instructions </technical_references/instructions/tfm_build_instruction>`
 shows some test configurations which are already supported in current TF-M.
 An example usage of test configuration shows below.
 
@@ -61,10 +63,11 @@ with a test configuration in ``tf-m-tests`` repository.
 Source code
 ===========
 
-The test suite example subdirectory named ``<test_name>`` is located under the path
-``tf-m-tests/test/suites``. If the new test suite includes both non-secure and
-secure parts, the source code shall be divided shared code and specific code.
-An example test suite folder can be organized as the figure below.
+The test suite example subdirectory named ``<test_name>`` is located under the
+path ``tf-m-tests/test/secure_fw/suites``. If the new test suite includes both
+non-secure and secure parts, the source code shall be divided shared code and
+specific code. An example test suite folder can be organized as the figure
+below.
 
 .. code-block:: bash
 
@@ -143,7 +146,7 @@ Applicating test configurations
 ===============================
 
 The mission of test configurations is to control the build. They are applied
-in ``test/suites/<test_name>/CMakeLists.txt`` like the example below.
+in ``test/secure_fw/suites/<test_name>/CMakeLists.txt`` like the example below.
 
 .. code-block:: cmake
 
@@ -218,7 +221,7 @@ registered if the macro is defined.
     On most platforms non-secure tests and secure tests run on the same CPU
     core, but dual-core platform is an exception. So secure test library and
     secure sevices shall be linked together in the file
-    ``tf-m-tests/test/test_services/CMakeLists.txt``. Thus they can be built on
+    ``tf-m-tests/test/secure_fw/secure_tests.cmake``. Thus they can be built on
     secure CPU core and non-secure tests library and RTOS are built on
     non-secure CPU core.
 
@@ -245,7 +248,6 @@ into an array with structure type called ``test_t`` defined in
         TEST_FUN * const test;         /*!< Test function to call */
         const char *name;              /*!< Test name */
         const char *desc;              /*!< Test description */
-        struct test_result_t ret;      /*!< Test result */
     };
 
 For example, a new test case called ``TFM_NS_<TEST_NAME>_TEST_1001`` is created
@@ -262,7 +264,7 @@ into the array which will be quoted in function
     /* Append test cases */
     static struct test_t <test_name>_tests[] = {
         {&tfm_<test_name>_test_1001, "TFM_NS_<TEST_NAME>_TEST_1001",
-        "Example test case", {TEST_PASSED}},
+        "Example test case"},
     };
 
     /* Register test case into test suites */
@@ -293,26 +295,64 @@ Steps
 
 Adding a test service is same as adding a secure partition, generally the
 process can be referenced from the document
-:doc:`Adding Secure Partition </docs/integration_guide/services/tfm_secure_partition_addition>`
+:doc:`Adding Secure Partition </integration_guide/services/tfm_secure_partition_addition>`
 
 .. Note::
     Each test service must have resource requirements declared in a manifest
-    file, the contents of test services are the same as secure partitions,but
+    file, the contents of test services are the same as secure partitions, but
     their locations are different. Test service manifests shall be set in
-    ``tf-m-tests/test/test_services/tfm_test_manifest_list.yaml``.
+    ``tf-m-tests/test/secure_fw/tfm_test_manifest_list.yaml``.
 
-Configuration
-=============
+Test Partition Specific Manifest Attributes
+===========================================
+There are some test purpose attributes in Secure Partition manifests that are
+**NOT** compatible with FF-M.
+They should be used in Test Partitions only.
 
-If the new test service names ``tfm_<test_name>_test_service`` only supports for the
-example test, the configuration in
-``tf-m-tests/test/test_services/CMakeLists.txt`` forms like below.
+weak_dependencies
+-----------------
+A TF-M regression test Partition calls other RoT services for test. But it
+can still run other tests if some of the RoT services are disabled.
+TF-M defines a ``"weak_dependencies"`` attribute in partition manifests of
+regression test partitions to describe test service access to other RoT
+services. It *shall* be only used for TF-M regression test services.
 
-.. code-block:: cmake
+model
+-----
+A TF-M regression test Partition may support both the SFN and IPC model.
+The actual model being used follows the SPM backend enabled.
 
-    if (TEST_S_<TEST_NAME> OR TEST_NS_<TEST_NAME>)
-        add_subdirectory(tfm_<test_name>_test_service)
-    endif()
+The TF-M build system supports this by allowing Secure Partitions to set
+the ``model`` attribute to ``dual``.
+The manifest tool will then change it to the corresponding value according
+to the current backend selected.
+
+The Test Partitions use the following definitions to know what model is being
+built:
+
+- ``<<partition_name>>_MODEL_IPC``, ``1`` if IPC model is used.
+- ``<<partition_name>>_MODEL_SFN``, ``1`` if SFN model is used.
+
+Test service implementation
+===========================
+
+Test service of individual test
+-------------------------------
+
+An individual test dedicated test service should be put under the corresponding
+test folder ``test/secure_fw/suites/<test_name>``.
+
+``add_subdirectory(suites/<test_name>/<service_dir>)`` shall be added into
+``tf-m-tests/test/secure_fw/secure_tests.cmake`` to make sure that the test
+service is built with secure side configuration.
+
+Common test service
+-------------------
+
+If a new test service is required by multiple test suites, the code should be
+put under ``test/secure_fw/common_test_services``. If the new test suite relies
+on a common test service, please make sure that the build implementation of the
+test service is linked correctly, including the header files and libraries.
 
 **********************************
 Out-of-tree regression test suites
@@ -458,4 +498,4 @@ another configuration file, a new one can be ignored.
 
 --------------
 
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*

docs/introduction/index.rst

@@ -3,11 +3,7 @@ Introduction
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-    :numbered:
+    :titlesonly:
+    :hidden:
 
-    readme
-
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+.. include:: readme.rst

docs/introduction/readme.rst

@@ -37,15 +37,15 @@ the platform. TF-M is supported on several Cortex-M based
 Systems (RTOS).
 
 Terms ``TFM`` and ``TF-M`` are commonly used in documents and code and both
-refer to ``Trusted Firmware M.`` :doc:`Glossary </docs/glossary>` has the list
+refer to ``Trusted Firmware M.`` :doc:`Glossary </glossary>` has the list
 of terms and abbreviations.
 
 #######
 License
 #######
-The software is provided under a BSD-3-Clause :doc:`License </docs/contributing/lic>`.
+The software is provided under a BSD-3-Clause :doc:`License </contributing/lic>`.
 Contributions to this project are accepted under the same license with developer
-sign-off as described in the :doc:`Contributing Guidelines </docs/contributing/contributing_process>`.
+sign-off as described in the :doc:`Contributing Guidelines </contributing/contributing_process>`.
 
 This project contains code from other projects as listed below. The code from
 external projects is limited to ``app``, ``bl2``, ``lib`` and ``platform``
@@ -59,61 +59,21 @@ folders. The original license text is included in those source files.
 - The ``platform`` folder currently contains platforms support imported from
   the external project and the files may have different licenses.
 
-###############
-Getting Started
-###############
+.. include:: /platform/ext/platform_introduction.rst
 
-************
-Prerequisite
-************
-Trusted Firmware M provides a reference implementation of platform security
-architecture  reference implementation aligning with PSA Certified guidelines.
-It is assumed that the reader is familiar with specifications can be found at
-`Platform Security Architecture Resources <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>`__.
-
-The current TF-M implementation specifically targets TrustZone for ARMv8-M so a
-good understanding of the v8-M architecture is also necessary. A good place to
-get started with ARMv8-M is
-`developer.arm.com <https://developer.arm.com/architectures/cpu-architecture/m-profile>`__.
-
-**************************
-Build and run instructions
-**************************
-Trusted Firmware M source code is available on
-`git.trustedfirmware.org <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/>`__.
-
-To build & run TF-M:
-
-    - Follow the :doc:`TF-M getting started </docs/getting_started/tfm_getting_started>`
-      to set up your environment.
-    - Follow the
-      :doc:`Build instructions </docs/technical_references/instructions/tfm_build_instruction>`
-      to compile and build the TF-M source.
-    - Follow the :doc:`Run TF-M examples on Arm platforms </docs/technical_references/instructions/run_tfm_examples_on_arm_platforms>`
-      for information on running the example.
-
-To port TF-M to a another system or OS, follow the
-:doc:`OS Integration Guide </docs/integration_guide/tfm_integration_guide>`
-
-:doc:`Contributing Guidelines </docs/contributing/contributing_process>` contains guidance on how to
-contribute to this project.
-
-###################
-Platforms supported
-###################
 The document :doc:`Supported Platforms </platform/ext/index>` lists the details.
 
 #########################
 Release Notes and Process
 #########################
-The :doc:`Release Cadence and Process </docs/releases/release_process>` provides
+The :doc:`Release Cadence and Process </releases/release_process>` provides
 release cadence and process information.
 
-The :doc:`Releases </docs/releases/index>` provides details of
+The :doc:`Releases </releases/index>` provides details of
 major features of the release and platforms supported.
 
 ####################
-Feedback and support
+Feedback and Support
 ####################
 For this release, feedback is requested via email to
 `tf-m@lists.trustedfirmware.org <tf-m@lists.trustedfirmware.org>`__.

docs/platform/ext/index.rst

@@ -1,22 +1,12 @@
-Supported Platforms
-===================
+TF-M Platforms
+==============
 
 .. toctree::
-    :maxdepth: 1
-    :caption: Information
-
-    /platform/readme
-    readme
-    /platform/ext/platform_introduction.rst
-    /platform/ext/platform_deprecation.rst
-    /platform/ext/platform_provisioning.rst
-
-.. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: arm
     :glob:
 
-    target/arm/**
+    target/arm/index
 
 .. toctree::
     :maxdepth: 1
@@ -30,24 +20,24 @@ Supported Platforms
     :caption: Cypress
     :glob:
 
-    target/cypress/**
+    target/cypress/psoc64/index
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: STM
     :glob:
 
     target/stm/index
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: Nordic
     :glob:
 
     target/nordic_nrf/**
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: Laird Connectivity
     :glob:
 
@@ -60,6 +50,13 @@ Supported Platforms
 
     target/nuvoton/**
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Rules and processes
+
+    platform_deprecation.rst
+    platform_provisioning.rst
+
 --------------
 
 *Copyright (c) 2020-2021, Arm Limited. All rights reserved.*