From abf6698dd6b916de5aea971783aa80776bf296dd Mon Sep 17 00:00:00 2001
From: Summer Qin
Date: Tue, 6 Apr 2021 17:22:15 +0800
Subject: Docs: Restructure the documents
Restructure the file category to let it more friendly to users.
Signed-off-by: Summer Qin
Change-Id: I7ced0e2d700ce03423e472e0098608f3445ba169
---
docs/contributing/code_review_guide.rst | 6 +-
docs/contributing/coding_guide.rst | 4 +-
docs/contributing/contributing.rst | 80 --
docs/contributing/contributing_process.rst | 80 ++
docs/contributing/doc_guidelines.rst | 6 +-
docs/contributing/index.rst | 8 +-
docs/contributing/maintainers.rst | 4 +-
docs/contributing/platform_deprecation.rst | 68 -
docs/contributing/release_process.rst | 42 -
docs/contributing/tfm_design_proposal_process.rst | 10 +-
docs/design_documents/code_sharing.rst | 368 -----
.../dual-cpu/booting_a_dual_core_system.rst | 136 --
...e_between_nspe_and_spe_in_dual_core_systems.rst | 767 ----------
.../dual-cpu/dual_core_mailbox_arch.png | Bin 31782 -> 0 bytes
docs/design_documents/dual-cpu/index.rst | 12 -
.../mailbox_design_on_dual_core_system.rst | 1475 --------------------
.../dual-cpu/tfm_multi_core_access_check.rst | 513 -------
docs/design_documents/enum_implicit_casting.rst | 190 ---
docs/design_documents/ff_isolation.rst | 401 ------
.../hardware_abstraction_layer.rst | 671 ---------
docs/design_documents/index.rst | 15 -
docs/design_documents/index.rst.in | 30 -
docs/design_documents/media/hal_structure.png | Bin 32736 -> 0 bytes
.../attest_token_finish.png | Bin 14947 -> 0 bytes
.../attest_token_start.png | Bin 30230 -> 0 bytes
.../symmetric_initial_attest/ia_service_flow.png | Bin 50354 -> 0 bytes
.../media/symmetric_initial_attest/iat_decode.png | Bin 40309 -> 0 bytes
.../symmetric_initial_attest/overall_diagram.png | Bin 14536 -> 0 bytes
docs/design_documents/media/tfm_crypto_design.png | Bin 32529 -> 0 bytes
docs/design_documents/profiles/index.rst | 12 -
.../profiles/tfm_profile_large.rst | 459 ------
.../profiles/tfm_profile_medium.rst | 477 -------
.../profiles/tfm_profile_small.rst | 645 ---------
docs/design_documents/ps_key_management.rst | 183 ---
.../secure_boot_hw_key_integration.rst | 166 ---
.../secure_boot_rollback_protection.rst | 203 ---
docs/design_documents/secure_enclave_solution.rst | 122 --
docs/design_documents/source_structure.rst | 165 ---
docs/design_documents/symmetric_initial_attest.rst | 601 --------
.../tfm_code_generation_with_jinja2.rst | 77 -
.../tfm_cooperative_scheduling_rules.rst | 211 ---
docs/design_documents/tfm_crypto_design.rst | 198 ---
docs/design_documents/tfm_fwu_service.rst | 313 -----
docs/design_documents/tfm_its_512_flash.rst | 104 --
docs/design_documents/tfm_its_service.rst | 281 ----
.../tfm_log_system_design_document.rst | 209 ---
.../tfm_non-secure_interrupt_handling.rst | 318 -----
.../tfm_non_secure_client_management.rst | 388 -----
.../tfm_partition_and_service_design_document.rst | 150 --
.../tfm_physical_attack_mitigation.rst | 626 ---------
.../tfm_psa_inter_process_communication.rst | 234 ----
.../tfm_secure_partition_interrupt_handling.rst | 234 ----
.../tfm_secure_partition_runtime_library.rst | 361 -----
.../tfm_uniform_secure_service_signature.rst | 114 --
docs/getting_started/index.rst | 9 +-
docs/getting_started/os_migration_guide_armv8m.rst | 42 -
docs/getting_started/tfm_build_instruction.rst | 4 +-
docs/getting_started/tfm_integration_guide.rst | 180 ---
.../tfm_ns_client_identification.rst | 43 -
docs/getting_started/tfm_secure_boot.rst | 808 -----------
docs/getting_started/tfm_secure_irq_handling.rst | 182 ---
docs/getting_started/tfm_user_guide.rst | 8 +-
docs/glossary.rst | 165 +++
docs/index.rst | 58 +-
docs/integration_guide/index.rst | 12 +
.../os_migration_guide_armv8m.rst | 42 +
.../core_test_services_integration_guide.rst | 114 ++
docs/integration_guide/services/index.rst | 12 +
.../services/tfm_attestation_integration_guide.rst | 671 +++++++++
.../services/tfm_audit_integration_guide.rst | 134 ++
.../services/tfm_crypto_integration_guide.rst | 118 ++
.../services/tfm_its_integration_guide.rst | 318 +++++
.../services/tfm_platform_integration_guide.rst | 113 ++
.../services/tfm_ps_integration_guide.rst | 392 ++++++
.../services/tfm_psa_proxy_integration_guide.rst | 83 ++
.../services/tfm_secure_partition_addition.rst | 467 +++++++
docs/integration_guide/tfm_integration_guide.rst | 180 +++
docs/introduction/index.rst | 3 +-
docs/introduction/readme.rst | 20 +-
docs/reference/changelog.rst | 15 -
docs/reference/glossary.rst | 165 ---
docs/reference/index.rst | 16 -
docs/reference/releases/1.0.rst | 144 --
docs/reference/releases/1.1.rst | 126 --
docs/reference/releases/1.2.0.rst | 142 --
docs/reference/releases/1.3.0.rst | 173 ---
docs/reference/releases/index.rst | 12 -
docs/reference/security.rst | 65 -
docs/reference/security_advisories/index.rst | 12 -
.../stack_seal_vulnerability.rst | 113 --
.../svc_caller_sp_fetching_vulnerability.rst | 125 --
.../core_test_services_integration_guide.rst | 114 --
docs/reference/services/index.rst | 12 -
.../services/tfm_attestation_integration_guide.rst | 671 ---------
.../services/tfm_audit_integration_guide.rst | 134 --
.../services/tfm_crypto_integration_guide.rst | 118 --
.../services/tfm_its_integration_guide.rst | 318 -----
.../services/tfm_platform_integration_guide.rst | 113 --
.../services/tfm_ps_integration_guide.rst | 392 ------
.../services/tfm_psa_proxy_integration_guide.rst | 83 --
.../services/tfm_secure_partition_addition.rst | 467 -------
docs/releases/1.0.rst | 144 ++
docs/releases/1.1.rst | 126 ++
docs/releases/1.2.0.rst | 142 ++
docs/releases/1.3.0.rst | 173 +++
docs/releases/index.rst | 12 +
docs/releases/release_process.rst | 42 +
docs/security/index.rst | 12 +
docs/security/security.rst | 65 +
docs/security/security_advisories/index.rst | 12 +
.../stack_seal_vulnerability.rst | 113 ++
.../svc_caller_sp_fetching_vulnerability.rst | 125 ++
docs/security/threat_models/TF-M-block-diagram.png | Bin 0 -> 124526 bytes
.../threat_models/generic_threat_model.rst | 1130 +++++++++++++++
docs/security/threat_models/index.rst | 12 +
docs/security/threat_models/overall-DFD.png | Bin 0 -> 17954 bytes
docs/technical_references/code_sharing.rst | 368 +++++
.../dual-cpu/booting_a_dual_core_system.rst | 136 ++
...e_between_nspe_and_spe_in_dual_core_systems.rst | 767 ++++++++++
.../dual-cpu/dual_core_mailbox_arch.png | Bin 0 -> 31782 bytes
docs/technical_references/dual-cpu/index.rst | 12 +
.../mailbox_design_on_dual_core_system.rst | 1475 ++++++++++++++++++++
.../dual-cpu/tfm_multi_core_access_check.rst | 513 +++++++
.../technical_references/enum_implicit_casting.rst | 190 +++
docs/technical_references/ff_isolation.rst | 401 ++++++
.../hardware_abstraction_layer.rst | 671 +++++++++
docs/technical_references/index.rst | 15 +
docs/technical_references/index.rst.in | 30 +
docs/technical_references/media/hal_structure.png | Bin 0 -> 32736 bytes
.../attest_token_finish.png | Bin 0 -> 14947 bytes
.../attest_token_start.png | Bin 0 -> 30230 bytes
.../symmetric_initial_attest/ia_service_flow.png | Bin 0 -> 50354 bytes
.../media/symmetric_initial_attest/iat_decode.png | Bin 0 -> 40309 bytes
.../symmetric_initial_attest/overall_diagram.png | Bin 0 -> 14536 bytes
.../media/tfm_crypto_design.png | Bin 0 -> 32529 bytes
docs/technical_references/profiles/index.rst | 12 +
.../profiles/tfm_profile_large.rst | 459 ++++++
.../profiles/tfm_profile_medium.rst | 477 +++++++
.../profiles/tfm_profile_small.rst | 645 +++++++++
docs/technical_references/ps_key_management.rst | 183 +++
.../secure_boot_hw_key_integration.rst | 166 +++
.../secure_boot_rollback_protection.rst | 203 +++
.../secure_enclave_solution.rst | 122 ++
docs/technical_references/source_structure.rst | 165 +++
.../symmetric_initial_attest.rst | 601 ++++++++
.../tfm_code_generation_with_jinja2.rst | 77 +
.../tfm_cooperative_scheduling_rules.rst | 211 +++
docs/technical_references/tfm_crypto_design.rst | 198 +++
docs/technical_references/tfm_fwu_service.rst | 313 +++++
docs/technical_references/tfm_its_512_flash.rst | 104 ++
docs/technical_references/tfm_its_service.rst | 281 ++++
.../tfm_log_system_design_document.rst | 209 +++
.../tfm_non-secure_interrupt_handling.rst | 318 +++++
.../tfm_non_secure_client_management.rst | 388 +++++
.../tfm_ns_client_identification.rst | 43 +
.../tfm_partition_and_service_design_document.rst | 150 ++
.../tfm_physical_attack_mitigation.rst | 626 +++++++++
.../tfm_psa_inter_process_communication.rst | 234 ++++
docs/technical_references/tfm_secure_boot.rst | 808 +++++++++++
.../tfm_secure_irq_handling.rst | 182 +++
.../tfm_secure_partition_interrupt_handling.rst | 234 ++++
.../tfm_secure_partition_runtime_library.rst | 361 +++++
.../tfm_uniform_secure_service_signature.rst | 114 ++
docs/threat_models/TF-M-block-diagram.png | Bin 124526 -> 0 bytes
docs/threat_models/generic_threat_model.rst | 1130 ---------------
docs/threat_models/index.rst | 12 -
docs/threat_models/overall-DFD.png | Bin 17954 -> 0 bytes
platform/ext/index.rst | 10 +-
platform/ext/platform_deprecation.rst | 68 +
.../ext/target/musca_b1/secure_enclave/readme.rst | 4 +-
readme.rst | 2 +-
171 files changed, 17618 insertions(+), 17623 deletions(-)
delete mode 100644 docs/contributing/contributing.rst
create mode 100644 docs/contributing/contributing_process.rst
delete mode 100644 docs/contributing/platform_deprecation.rst
delete mode 100644 docs/contributing/release_process.rst
delete mode 100644 docs/design_documents/code_sharing.rst
delete mode 100644 docs/design_documents/dual-cpu/booting_a_dual_core_system.rst
delete mode 100644 docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
delete mode 100644 docs/design_documents/dual-cpu/dual_core_mailbox_arch.png
delete mode 100644 docs/design_documents/dual-cpu/index.rst
delete mode 100644 docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
delete mode 100644 docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst
delete mode 100644 docs/design_documents/enum_implicit_casting.rst
delete mode 100644 docs/design_documents/ff_isolation.rst
delete mode 100644 docs/design_documents/hardware_abstraction_layer.rst
delete mode 100644 docs/design_documents/index.rst
delete mode 100644 docs/design_documents/index.rst.in
delete mode 100644 docs/design_documents/media/hal_structure.png
delete mode 100644 docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png
delete mode 100644 docs/design_documents/media/symmetric_initial_attest/attest_token_start.png
delete mode 100644 docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png
delete mode 100644 docs/design_documents/media/symmetric_initial_attest/iat_decode.png
delete mode 100644 docs/design_documents/media/symmetric_initial_attest/overall_diagram.png
delete mode 100644 docs/design_documents/media/tfm_crypto_design.png
delete mode 100644 docs/design_documents/profiles/index.rst
delete mode 100644 docs/design_documents/profiles/tfm_profile_large.rst
delete mode 100644 docs/design_documents/profiles/tfm_profile_medium.rst
delete mode 100644 docs/design_documents/profiles/tfm_profile_small.rst
delete mode 100644 docs/design_documents/ps_key_management.rst
delete mode 100644 docs/design_documents/secure_boot_hw_key_integration.rst
delete mode 100644 docs/design_documents/secure_boot_rollback_protection.rst
delete mode 100644 docs/design_documents/secure_enclave_solution.rst
delete mode 100644 docs/design_documents/source_structure.rst
delete mode 100644 docs/design_documents/symmetric_initial_attest.rst
delete mode 100644 docs/design_documents/tfm_code_generation_with_jinja2.rst
delete mode 100644 docs/design_documents/tfm_cooperative_scheduling_rules.rst
delete mode 100644 docs/design_documents/tfm_crypto_design.rst
delete mode 100644 docs/design_documents/tfm_fwu_service.rst
delete mode 100644 docs/design_documents/tfm_its_512_flash.rst
delete mode 100644 docs/design_documents/tfm_its_service.rst
delete mode 100644 docs/design_documents/tfm_log_system_design_document.rst
delete mode 100644 docs/design_documents/tfm_non-secure_interrupt_handling.rst
delete mode 100644 docs/design_documents/tfm_non_secure_client_management.rst
delete mode 100644 docs/design_documents/tfm_partition_and_service_design_document.rst
delete mode 100644 docs/design_documents/tfm_physical_attack_mitigation.rst
delete mode 100644 docs/design_documents/tfm_psa_inter_process_communication.rst
delete mode 100644 docs/design_documents/tfm_secure_partition_interrupt_handling.rst
delete mode 100644 docs/design_documents/tfm_secure_partition_runtime_library.rst
delete mode 100644 docs/design_documents/tfm_uniform_secure_service_signature.rst
delete mode 100644 docs/getting_started/os_migration_guide_armv8m.rst
delete mode 100644 docs/getting_started/tfm_integration_guide.rst
delete mode 100644 docs/getting_started/tfm_ns_client_identification.rst
delete mode 100644 docs/getting_started/tfm_secure_boot.rst
delete mode 100644 docs/getting_started/tfm_secure_irq_handling.rst
create mode 100644 docs/glossary.rst
create mode 100644 docs/integration_guide/index.rst
create mode 100644 docs/integration_guide/os_migration_guide_armv8m.rst
create mode 100644 docs/integration_guide/services/core_test_services_integration_guide.rst
create mode 100644 docs/integration_guide/services/index.rst
create mode 100644 docs/integration_guide/services/tfm_attestation_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_audit_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_crypto_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_its_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_platform_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_ps_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst
create mode 100644 docs/integration_guide/services/tfm_secure_partition_addition.rst
create mode 100644 docs/integration_guide/tfm_integration_guide.rst
delete mode 100644 docs/reference/changelog.rst
delete mode 100644 docs/reference/glossary.rst
delete mode 100644 docs/reference/index.rst
delete mode 100644 docs/reference/releases/1.0.rst
delete mode 100644 docs/reference/releases/1.1.rst
delete mode 100644 docs/reference/releases/1.2.0.rst
delete mode 100644 docs/reference/releases/1.3.0.rst
delete mode 100644 docs/reference/releases/index.rst
delete mode 100644 docs/reference/security.rst
delete mode 100644 docs/reference/security_advisories/index.rst
delete mode 100644 docs/reference/security_advisories/stack_seal_vulnerability.rst
delete mode 100644 docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst
delete mode 100644 docs/reference/services/core_test_services_integration_guide.rst
delete mode 100644 docs/reference/services/index.rst
delete mode 100644 docs/reference/services/tfm_attestation_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_audit_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_crypto_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_its_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_platform_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_ps_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_psa_proxy_integration_guide.rst
delete mode 100644 docs/reference/services/tfm_secure_partition_addition.rst
create mode 100644 docs/releases/1.0.rst
create mode 100644 docs/releases/1.1.rst
create mode 100644 docs/releases/1.2.0.rst
create mode 100644 docs/releases/1.3.0.rst
create mode 100644 docs/releases/index.rst
create mode 100644 docs/releases/release_process.rst
create mode 100644 docs/security/index.rst
create mode 100644 docs/security/security.rst
create mode 100644 docs/security/security_advisories/index.rst
create mode 100644 docs/security/security_advisories/stack_seal_vulnerability.rst
create mode 100644 docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst
create mode 100644 docs/security/threat_models/TF-M-block-diagram.png
create mode 100644 docs/security/threat_models/generic_threat_model.rst
create mode 100644 docs/security/threat_models/index.rst
create mode 100644 docs/security/threat_models/overall-DFD.png
create mode 100644 docs/technical_references/code_sharing.rst
create mode 100644 docs/technical_references/dual-cpu/booting_a_dual_core_system.rst
create mode 100644 docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
create mode 100644 docs/technical_references/dual-cpu/dual_core_mailbox_arch.png
create mode 100644 docs/technical_references/dual-cpu/index.rst
create mode 100644 docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst
create mode 100644 docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst
create mode 100644 docs/technical_references/enum_implicit_casting.rst
create mode 100644 docs/technical_references/ff_isolation.rst
create mode 100644 docs/technical_references/hardware_abstraction_layer.rst
create mode 100644 docs/technical_references/index.rst
create mode 100644 docs/technical_references/index.rst.in
create mode 100644 docs/technical_references/media/hal_structure.png
create mode 100644 docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png
create mode 100644 docs/technical_references/media/symmetric_initial_attest/attest_token_start.png
create mode 100644 docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png
create mode 100644 docs/technical_references/media/symmetric_initial_attest/iat_decode.png
create mode 100644 docs/technical_references/media/symmetric_initial_attest/overall_diagram.png
create mode 100644 docs/technical_references/media/tfm_crypto_design.png
create mode 100644 docs/technical_references/profiles/index.rst
create mode 100644 docs/technical_references/profiles/tfm_profile_large.rst
create mode 100644 docs/technical_references/profiles/tfm_profile_medium.rst
create mode 100644 docs/technical_references/profiles/tfm_profile_small.rst
create mode 100644 docs/technical_references/ps_key_management.rst
create mode 100644 docs/technical_references/secure_boot_hw_key_integration.rst
create mode 100644 docs/technical_references/secure_boot_rollback_protection.rst
create mode 100644 docs/technical_references/secure_enclave_solution.rst
create mode 100644 docs/technical_references/source_structure.rst
create mode 100644 docs/technical_references/symmetric_initial_attest.rst
create mode 100644 docs/technical_references/tfm_code_generation_with_jinja2.rst
create mode 100644 docs/technical_references/tfm_cooperative_scheduling_rules.rst
create mode 100644 docs/technical_references/tfm_crypto_design.rst
create mode 100644 docs/technical_references/tfm_fwu_service.rst
create mode 100644 docs/technical_references/tfm_its_512_flash.rst
create mode 100644 docs/technical_references/tfm_its_service.rst
create mode 100644 docs/technical_references/tfm_log_system_design_document.rst
create mode 100644 docs/technical_references/tfm_non-secure_interrupt_handling.rst
create mode 100644 docs/technical_references/tfm_non_secure_client_management.rst
create mode 100644 docs/technical_references/tfm_ns_client_identification.rst
create mode 100644 docs/technical_references/tfm_partition_and_service_design_document.rst
create mode 100644 docs/technical_references/tfm_physical_attack_mitigation.rst
create mode 100644 docs/technical_references/tfm_psa_inter_process_communication.rst
create mode 100644 docs/technical_references/tfm_secure_boot.rst
create mode 100644 docs/technical_references/tfm_secure_irq_handling.rst
create mode 100644 docs/technical_references/tfm_secure_partition_interrupt_handling.rst
create mode 100644 docs/technical_references/tfm_secure_partition_runtime_library.rst
create mode 100644 docs/technical_references/tfm_uniform_secure_service_signature.rst
delete mode 100644 docs/threat_models/TF-M-block-diagram.png
delete mode 100644 docs/threat_models/generic_threat_model.rst
delete mode 100644 docs/threat_models/index.rst
delete mode 100644 docs/threat_models/overall-DFD.png
create mode 100644 platform/ext/platform_deprecation.rst
diff --git a/docs/contributing/code_review_guide.rst b/docs/contributing/code_review_guide.rst
index 8bbf33aa2b..e9ed9699f4 100644
--- a/docs/contributing/code_review_guide.rst
+++ b/docs/contributing/code_review_guide.rst
@@ -13,9 +13,9 @@ List of the guidelines
**********************
The prerequisites before going to the review stage:
-- Read the :doc:`Contributing Guidelines `
+- Read the :doc:`Contributing Process `
to know basic concepts.
-- Read the :doc:`Source Structure `
+- Read the :doc:`Source Structure `
for structure related reference.
The review guidelines consist of these items:
@@ -234,4 +234,4 @@ SPRTL secure-fw/partitions/lib/sprt/*
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/coding_guide.rst b/docs/contributing/coding_guide.rst
index 099d3b3fc1..f208fc0944 100644
--- a/docs/contributing/coding_guide.rst
+++ b/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 `
+As implied in the :doc:`contributing guide `
maintainers have the right to decide on what's acceptable in case of any
divergence.
@@ -76,4 +76,4 @@ List of rules
--------------
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst
deleted file mode 100644
index 9c80cab957..0000000000
--- a/docs/contributing/contributing.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-Contributing
-============
-
-Contributions to the TF-M project need to follow the process below.
-
-.. Note::
-
- Please contact :doc:`maintainers ` for any
- questions.
-
-- Subscribe to `TF-M development
- `_ if not subscribed
- already.
-- Refer to the `Roadmap
- `_ or send a mail to
- the tf-m@lists.trustedfirmware.org to check if this work is already
- planned/progresses elsewhere.
-- Create a task in `Phabricator
- `_, 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 `
- 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
- `_.
- - Follow the :doc:`SW Requirements `,
- :doc:`Build Instructions ` and
- :doc:`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 `, Developer
- Certificate of Origin, so you must add following fields to your
- commit description:
-
- .. code-block:: text
-
- Author: Full Name
- Signed-off-by: Full Name
-
- .. Note::
-
- Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
-
- - You must add a `Change-Id
- ` to
- the commit message, which can be generated any way you like (e.g. from the
- SHA of the commit), or use the commit hook.
- - Create a user in the `TF-M Gerrit `,
- then add `SSH keys or HTTP credentials
- `.
- - Submit your patch for review.
-
- .. code-block:: shell
-
- git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master
-
- or
-
- .. code-block:: shell
-
- git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master
-
-- Add relevant :doc:`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
- necessary.
-- Once the change is approved by maintainers, the patch will be merged by the
- maintainer.
-- Mark the task as 'resolved' after patch is merged.
-
---------------
-
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/contributing_process.rst b/docs/contributing/contributing_process.rst
new file mode 100644
index 0000000000..b017c638a9
--- /dev/null
+++ b/docs/contributing/contributing_process.rst
@@ -0,0 +1,80 @@
+Contributing Process
+====================
+
+Contributions to the TF-M project need to follow the process below.
+
+.. Note::
+
+ Please contact :doc:`maintainers ` for any
+ questions.
+
+- Subscribe to `TF-M development
+ `_ if not subscribed
+ already.
+- Refer to the `Roadmap
+ `_ or send a mail to
+ the tf-m@lists.trustedfirmware.org to check if this work is already
+ planned/progresses elsewhere.
+- Create a task in `Phabricator
+ `_, 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 `
+ 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
+ `_.
+ - Follow the :doc:`SW Requirements `,
+ :doc:`Build Instructions ` and
+ :doc:`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 `, Developer
+ Certificate of Origin, so you must add following fields to your
+ commit description:
+
+ .. code-block:: text
+
+ Author: Full Name
+ Signed-off-by: Full Name
+
+ .. Note::
+
+ Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
+
+ - You must add a `Change-Id
+ ` to
+ the commit message, which can be generated any way you like (e.g. from the
+ SHA of the commit), or use the commit hook.
+ - Create a user in the `TF-M Gerrit `,
+ then add `SSH keys or HTTP credentials
+ `.
+ - Submit your patch for review.
+
+ .. code-block:: shell
+
+ git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master
+
+ or
+
+ .. code-block:: shell
+
+ git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master
+
+- Add relevant :doc:`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
+ necessary.
+- Once the change is approved by maintainers, the patch will be merged by the
+ maintainer.
+- Mark the task as 'resolved' after patch is merged.
+
+--------------
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst
index e217dde571..41f4e05c98 100644
--- a/docs/contributing/doc_guidelines.rst
+++ b/docs/contributing/doc_guidelines.rst
@@ -187,7 +187,7 @@ 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_sw_requirement` and
-:doc:`/docs/reference/releases/1.0`
+:doc:`/docs/releases/1.0`
External Links
@@ -260,7 +260,7 @@ Glossary term
=============
For technical terms and abbreviations, the recommended guidance is to add an
-entry to the :doc:`/docs/reference/glossary` and refer to it, using the `term:`
+entry to the :doc:`/docs/glossary` and refer to it, using the `term:`
directive
@@ -297,4 +297,4 @@ References
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index 7b921f25dc..e5f9c66be6 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -1,15 +1,13 @@
-Contributing
-============
+Contribution Guidelines
+=======================
.. toctree::
:maxdepth: 1
- :caption: Contents
:glob:
*
- Security Center
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/maintainers.rst b/docs/contributing/maintainers.rst
index aeced913bd..ced48d167a 100644
--- a/docs/contributing/maintainers.rst
+++ b/docs/contributing/maintainers.rst
@@ -111,8 +111,8 @@ Michel JAOUEN
:github: `jamike `__
-Infineon/Cypress Platform:
-~~~~~~~~~~~~~~~~~
+Infineon/Cypress Platforms
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Chris Brand
:email: `Chris Brand@cypress.com `__
diff --git a/docs/contributing/platform_deprecation.rst b/docs/contributing/platform_deprecation.rst
deleted file mode 100644
index 5d7a3de987..0000000000
--- a/docs/contributing/platform_deprecation.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-################################
-Platform deprecation and removal
-################################
-
-********************************************
-Process for Platform deprecation and removal
-********************************************
-
-A platform may need to be removed from upstream code due to lack of community
-interest or it may have reached end of life. The below section calls out the
-process for removing platform support from TF-M.
-
- 1. An email to the TF-M mailing list proposing the removal of the platform.
-
- 2. The merit of the proposal will be considered by the maintainers for a
- period of 4 weeks and community can express their opinion on the same
- during this time window. The platform owner can veto the proposal and
- incase of multiple platform owners with differing opinion or community
- having interest in the platform, then the project maintainer can work
- with the platform owner and use their discretion to decide on the
- proposal.
-
- 3. Once a decision is made to remove the platform, the platform is
- considered to be in `deprecated` state as per platform support lifecyle
- defined here: "https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/".
- The platform will be marked as deprecated and the TF-M version after
- which it will be removed will also be mentioned. Suitable build time
- or runtime messages needs to be incorporated to the platform to warn
- about the `deprecation`.
-
- 4. The project should strive to keep the `deprecated` platforms
- building/running till the removal. This relies on platform owners being
- still actively involved with the project and maintaining the platform.
-
- 5. Although this will be the usual process for platform deprecation and
- eventual removal, the process still leaves room for the platform
- deprecation to be cancelled after it has been marked as `deprecated`
- due to evolving project and market requirements. This is left to
- consensus between project maintainers and platform owner/s.
-
- 6. Once a platform has been removed, it can be added back in future and
- this would follow the same guidelines as for a new platform contribution.
-
-****************************
-List of Deprecated Platforms
-****************************
-
-The below list calls out platforms marked for deprecation according to the
-above process and the platform will be removed soon after the mentioned
-release.
-
-+--------------------------------------+-----------+---------------------------+
-| Deprecated Platform | Removed | Comments |
-| | after | |
-| | release | |
-+======================================+===========+===========================+
-| mps2/an539 | v1.2.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-| mps2/sse-200_aws | v1.3.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-| musca_a | v1.3.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-| nordic_nrf/nrf5340pdk_nrf5340_cpuapp | v1.3.0 | N.A |
-+--------------------------------------+-----------+---------------------------+
-
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/release_process.rst b/docs/contributing/release_process.rst
deleted file mode 100644
index 8b6d1965b1..0000000000
--- a/docs/contributing/release_process.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-Release Cadence and Process
-===========================
-
-Project Release Cadence
------------------------
-
-The project currently aims to do a release once every 4 months which will be
-tagged on the master branch. There will be a code freeze (stop merging
-non-essential changes) up to 3 weeks prior to the target release date. The
-release candidates will start appearing after this and only bug fixes or
-updates required for the release will be merged. The maintainers are free
-to use their judgement on what changes are essential for the release.
-
-The release testing will be performed on release candidates and depending on
-issues found, additional release candidates may be created to fix the issues.
-
-::
-
- |<------------4 months----------->|
- |<--upto 3 weeks-->| |<--upto 3 weeks-->|
- +----------------------------------------------------- ----------> time
- | | | |
- code freeze ver w.x code freeze ver y.z
-
-Although this document specifies the release cadence, this does not preclude
-an adhoc release for specific project requirements.
-
-Release Version Scheme
-----------------------
-
-Trusted Firmware-M uses a semantic versioning scheme. A version number is
-compiled as a dot separated set of numbers:
-
-**TF-Mv..**
-
-- : Major release version for significant feature and API changes.
-- : Minor release version for incremental features and API changes.
-- : Used only for backporting **critical bug fix/security patches**.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst
index 0be4d04e75..fcc2be9d74 100644
--- a/docs/contributing/tfm_design_proposal_process.rst
+++ b/docs/contributing/tfm_design_proposal_process.rst
@@ -49,7 +49,7 @@ Example document fragment::
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/design_documents`` directory.
+documents shall be put to the ``docs/technical_references`` directory.
.. important::
- 'Author' and 'Organization' can be *OPTIONAL* but at least one of them is
@@ -78,7 +78,7 @@ 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/design_documents`` directory and create a pull request.
+ ``docs/technical_references`` directory and create a pull request.
- Start an e-mail thread on the
`TF-M mailing list `_ for discussing
the proposal.
@@ -98,8 +98,8 @@ Process steps
.. uml::
@startuml
- !define DRAFT_DIR **docs/design_documents/**
- !define REJECTED_DIR **docs/design_documents/rejected/**
+ !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
@@ -153,4 +153,4 @@ Process steps
--------------
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/code_sharing.rst b/docs/design_documents/code_sharing.rst
deleted file mode 100644
index 45aec7e01f..0000000000
--- a/docs/design_documents/code_sharing.rst
+++ /dev/null
@@ -1,368 +0,0 @@
-######################################################
-Code sharing between independently linked XIP binaries
-######################################################
-
-:Authors: Tamas Ban
-:Organization: Arm Limited
-:Contact: tamas.ban@arm.com
-:Status: Draft
-
-**********
-Motivation
-**********
-Cortex-M devices are usually constrained in terms of flash and RAM. Therefore,
-it is often challenging to fit bigger projects in the available memory. The PSA
-specifications require a device to both have a secure boot process in place at
-device boot-up time, and to have a partition in the SPE which provides
-cryptographic services at runtime. These two entities have some overlapping
-functionality. Some cryptographic primitives (e.g. hash calculation and digital
-signature verification) are required both in the bootloader and the runtime
-environment. In the current TF-M code base, both firmware components use the
-mbed-crypto library to implement these requirements. During the build process,
-the mbed-crpyto library is built twice, with different configurations (the
-bootloader requires less functionality) and then linked to the corresponding
-firmware component. As a result of this workflow, the same code is placed in the
-flash twice. For example, the code for the SHA-256 algorithm is included in
-MCUboot, but the exact same code is duplicated in the SPE cryptography
-partition. In most cases, there is no memory isolation between the bootloader
-and the SPE, because both are part of the PRoT code and run in the secure
-domain. So, in theory, the code of the common cryptographic algorithms could be
-reused among these firmware components. This could result in a big reduction in
-code footprint, because the cryptographic algorithms are usually flash hungry.
-Code size reduction can be a good opportunity for very constrained devices,
-which might need to use TF-M Profile Small anyway.
-
-*******************
-Technical challenge
-*******************
-Code sharing in a regular OS environment is easily achievable with dynamically
-linked libraries. However, this is not the case in Cortex-M systems where
-applications might run bare-metal, or on top of an RTOS, which usually lacks
-dynamic loading functionality. One major challenge to be solved in the Cortex-M
-space is how to share code between independently linked XIP applications that
-are tied to a certain memory address range to be executable and have absolute
-function and global data memory addresses. In this case, the code is not
-relocatable, and in most cases, there is no loader functionality in the system
-that can perform code relocation. Also, the lack of an MMU makes the address
-space flat, constant and not reconfigurable at runtime by privileged code.
-
-One other difficulty is that the bootloader and the runtime use the same RAM
-area during execution. The runtime firmware is executed strictly after the
-bootloader, so normally, it can reuse the whole secure RAM area, as it would be
-the exclusive user. No attention needs to be paid as to where global data is
-placed by the linker. The bootloader does not need to retain its state. The low
-level startup of the runtime firmware can freely overwrite the RAM with its data
-without corrupting bootloader functionality. However, with code sharing between
-bootloader and runtime firmware, these statements are no longer true. Global
-variables used by the shared code must either retain their value or must be
-reinitialised during low level startup of the runtime firmware. The startup code
-is not allowed to overwrite the shared global variables with arbitrary data. The
-following design proposal provides a solution to these challenges.
-
-**************
-Design concept
-**************
-The bootloader is sometimes implemented as ROM code (BL1) or stored in a region
-of the flash which is lockable, to prevent tampering. In a secure system, the
-bootloader is immutable code and thus implements a part of the Root of Trust
-anchor in the device, which is trusted implicitly. The shared code is primarily
-part of the bootloader, and is reused by the runtime SPE firmware at a later
-stage. Not all of the bootloader code is reused by the runtime SPE, only some
-cryptographic functions.
-
-Simplified steps of building with code sharing enabled:
-
- - Complete the bootloader build process to have a final image that contains
- the absolute addresses of the shared functions, and the global variables
- used by these functions.
- - Extract the addresses of the functions and related global variables that are
- intended to be shared from the bootloader executable.
- - When building runtime firmware, provide the absolute addresses of the shared
- symbols to the linker, so that it can pick them up, instead of instantiating
- them again.
-
-The execution flow looks like this:
-
-.. code-block:: bash
-
- SPE MCUboot func1() MCUboot func2() MCUboot func3()
- |
- | Hash()
- |------------->|
- |----------------->|
- |
- Return |
- Return |<-----------------|
- |<-------------|
- |
- |
- |----------------------------------------------------->|
- |
- Function pointer in shared global data() |
- |<-----------------------------------------------------|
- |
- | Return
- |----------------------------------------------------->|
- |
- Return |
- |<-----------------------------------------------------|
- |
- |
-
-The execution flow usually returns from a shared function back to the SPE with
-an ordinary function return. So usually, once a shared function is called in the
-call path, all further functions in the call chain will be shared as well.
-However, this is not always the case, as it is possible for a shared function to
-call a non-shared function in SPE code through a global function pointer.
-
-For shared global variables, a dedicated data section must be allocated in the
-linker configuration file. This area must have the same memory address in both
-MCUboot's and the SPE's linker files, to ensure the integrity of the variables.
-For simplicity's sake, this section is placed at the very beginning of the RAM
-area. Also, the RAM wiping functionality at the end of the secure boot flow
-(that is intended to remove any possible secrets from the RAM) must not clear
-this area. Furthermore, it must be ensured that the linker places shared globals
-into this data section. There are two way to achieve this:
-
- - Put a filter pattern in the section body that matches the shared global
- variables.
- - Mark the global variables in the source code with special attribute
- `__attribute__((section()))`
-
-RAM memory layout in MCUboot with code sharing enabled:
-
-.. code-block:: bash
-
- +------------------+
- | Shared symbols |
- +------------------+
- | Shared boot data |
- +------------------+
- | Data |
- +------------------+
- | Stack (MSP) |
- +------------------+
- | Heap |
- +------------------+
-
-RAM memory layout in SPE with code sharing enabled:
-
-.. code-block:: bash
-
- +-------------------+
- | Shared symbols |
- +-------------------+
- | Shared boot data |
- +-------------------+
- | Stack (MSP) |
- +-------------------+
- | Stack (PSP) |
- +-------------------+
- | Partition X Data |
- +-------------------+
- | Partition X Stack |
- +-------------------+
- .
- .
- .
- +-------------------+
- | Partition Z Data |
- +-------------------+
- | Partition Z Stack |
- +-------------------+
- | PRoT Data |
- +-------------------+
- | Heap |
- +-------------------+
-
-Patching mbedTLS
-================
-In order to share some global function pointers from mbed-crypto that are
-related to dynamic memory allocation, their scope must be extended from private
-to global. This is needed because some compiler toolchain only extract the
-addresses of public functions and global variables, and extraction of addresses
-is a requirement to share them among binaries. Therefore, a short patch was
-created for the mbed-crypto library, which "globalises" these function pointers:
-
-`lib/ext/mbedcrypto/0005-Enable-crypto-code-sharing-between-independent-binar.patch`
-
-The patch need to manually applied in the mbedtls repo, if code sharing is
-enabled. The patch has no effect on the functional behaviour of the
-cryptographic library, it only extends the scope of some variables.
-
-*************
-Tools support
-*************
-All the currently supported compilers provide a way to achieve the above
-objectives. However, there is no standard way, which means that the code sharing
-functionality must be implemented on a per compiler basis. The following steps
-are needed:
-
- - Extraction of the addresses of all global symbols.
- - The filtering out of the addresses of symbols that aren't shared. The goal is
- to not need to list all the shared symbols by name. Only a simple pattern
- has to be provided, which matches the beginning of the symbol's name.
- Matching symbols will be shared. Examples are in :
- `bl2/src/shared_symbol_template.txt`
- - Provision of the addresses of shared symbols to the linker during the SPE
- build process.
- - The resolution of symbol collisions during SPE linking. Because mbed-crypto
- is linked to both firmware components as a static library, the external
- shared symbols will conflict with the same symbols found within it. In order
- to prioritize the external symbol, the symbol with the same name in
- mbed-crypto must be marked as weak in the symbol table.
-
-The above functionalities are implemented in the toolchain specific CMake files:
-
- - `toolchain_ARMCLANG.cmake`
- - `toolchain_GNUARM.cmake`
-
-By the following two functions:
-
- - `compiler_create_shared_code()`: Extract and filter shared symbol addresses
- from MCUboot.
- - `compiler_link_shared_code()`: Link shared code to the SPE and resolve symbol
- conflict issues.
-
-ARMCLANG
-========
-The toolchain specific steps are:
-
- - Extract all symbols from MCUboot: add `-symdefs` to the compiler command line
- - Filter shared symbols: call CMake script `FilterSharedSymbols.cmake`
- - Weaken duplicated (shared) symbols in the mbed-crypto static library that are
- linked to the SPE: `arm-none-eabi-objcopy`
- - Link shared code to SPE: Add the filtered output of `-symdefs` to the SPE
- source file list.
-
-GNUARM
-======
-The toolchain specific steps are:
-
- - Extract all symbols from MCUboot: `arm-none-eabi-nm`
- - Filter shared symbols: call CMake script: `FilterSharedSymbols.cmake`
- - Strip unshared code from MCUboot: `arm-none-eabi-strip`
- - Weaken duplicated (shared) symbols in the mbed-crypto static library that are
- linked to the SPE: `arm-none-eabi-objcopy`
- - Link shared code to SPE: Add `-Wl -R ` to the
- compiler command line
-
-IAR
-===
-Functionality currently not implemented, but the toolchain supports doing it.
-
-**************************
-Memory footprint reduction
-**************************
-Build type: MinSizeRel
-Platform: mps2/an521
-Version: TF-Mv1.2.0 + code sharing patches
-MCUboot image encryption support is disabled.
-
-+------------------+-------------------+-------------------+-------------------+
-| | ConfigDefault | ConfigProfile-M | ConfigProfile-S |
-+------------------+----------+--------+----------+--------+----------+--------+
-| | ARMCLANG | GNUARM | ARMCLANG | GNUARM | ARMCLANG | GNUARM |
-+------------------+----------+--------+----------+--------+----------+--------+
-| CODE_SHARING=OFF | 122268 | 124572 | 75936 | 75996 | 50336 | 50224 |
-+------------------+----------+--------+----------+--------+----------+--------+
-| CODE_SHARING=ON | 113264 | 115500 | 70400 | 70336 | 48840 | 48988 |
-+------------------+----------+--------+----------+--------+----------+--------+
-| Difference | 9004 | 9072 | 5536 | 5660 | 1496 | 1236 |
-+------------------+----------+--------+----------+--------+----------+--------+
-
-If MCUboot image encryption support is enabled then saving could be up to
-~13-15KB.
-
-.. Note::
-
- Code sharing on Musca-B1 was tested only with SW only crypto, so crypto
- hardware acceleration must be turned off: -DCRYPTO_HW_ACCELERATOR=OFF
-
-
-*************************
-Useability considerations
-*************************
-Functions that only use local variables can be shared easily. However, functions
-that rely on global variables are a bit tricky. They can still be shared, but
-all global variables must be placed in the shared symbol section, to prevent
-overwriting and to enable the retention of their values.
-
-Some global variables might need to be reinitialised to their original values by
-runtime firmware, if they have been used by the bootloader, but need to have
-their original value when runtime firmware starts to use them. If so, the
-reinitialising functionality must be implemented explicitly, because the low
-level startup code in the SPE does not initialise the shared variables, which
-means they retain their value after MCUboot stops running.
-
-If a bug is discovered in the shared code, it cannot be fixed with a firmware
-upgrade, if the bootloader code is immutable. If this is the case, disabling
-code sharing might be a solution, as the new runtime firmware could contain the
-fixed code instead of relying on the unfixed shared code. However, this would
-increase code footprint.
-
-API backward compatibility also can be an issue. If the API has changed in newer
-version of the shared code. Then new code cannot rely on the shared version.
-The changed code and all the other shared code where it is referenced from must
-be ignored and the updated version of the functions must be compiled in the
-SPE binary. The mbedTLS library is API compatible with its current version
-(``v2.24.0``) since the ``mbedtls-2.7.0 release`` (2018-02-03).
-
-To minimise the risk of incompatibility, use the same compiler flags to build
-both firmware components.
-
-The artifacts of the shared code extraction steps must be preserved so as to
-remain available if new SPE firmware (that relies on shared code) is built and
-released. Those files are necessary to know the address of shared symbols when
-linking the SPE.
-
-************************
-How to use code sharing?
-************************
-Considering the above, code sharing is an optional feature, which is disabled
-by default. It can be enabled from the command line with a compile time switch:
-
- - `TFM_CODE_SHARING`: Set to `ON` to enable code sharing.
-
-With the default settings, only the common part of the mbed-crypto library is
-shared, between MCUboot and the SPE. However, there might be other device
-specific code (e.g. device drivers) that could be shared. The shared
-cryptography code consists mainly of the SHA-256 algorithm, the `bignum` library
-and some RSA related functions. If image encryption support is enabled in
-MCUboot, then AES algorithms can be shared as well.
-
-Sharing code between the SPE and an external project is possible, even if
-MCUboot isn't used as the bootloader. For example, a custom bootloader can also
-be built in such a way as to create the necessary artifacts to share some of its
-code with the SPE. The same artifacts must be created like the case of MCUboot:
-
- - `shared_symbols_name.txt`: Contains the name of the shared symbols. Used by
- the script that prevents symbol collision.
- - `shared_symbols_address.txt`: Contains the type, address and name of shared
- symbols. Used by the linker when linking runtime SPE.
- - `shared_code.axf`: GNUARM specific. The stripped version of the firmware
- component, only contains the shared code. It is used by the linker when
- linking the SPE.
-
-.. Note::
-
- The artifacts of the shared code extraction steps must be preserved to be
- able to link them to any future SPE version.
-
-When an external project is sharing code with the SPE, the `SHARED_CODE_PATH`
-compile time switch must be set to the path of the artifacts mentioned above.
-
-********************
-Further improvements
-********************
-This design focuses only on sharing the cryptography code. However, other code
-could be shared as well. Some possibilities:
-
-- Flash driver
-- Serial driver
-- Image metadata parsing code
-- etc.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst b/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst
deleted file mode 100644
index 0a88ab3674..0000000000
--- a/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst
+++ /dev/null
@@ -1,136 +0,0 @@
-##########################
-Booting a Dual-Core System
-##########################
-
-:Authors: Chris Brand
-:Organization: Cypress Semiconductor Corporation
-:Contact: chris.brand@cypress.com
-:Status: Accepted
-
-*******************
-System Architecture
-*******************
-There are many possibly ways to design a dual core system. Some important
-considerations from a boot perspective are:
-
-- Which core has access to which areas of Flash?
-
- - It is possible that the secure core has no access to the Flash from which
- the non-secure core will boot, in which case the non-secure core will
- presumably have a separate root of trust and perform its own integrity
- checks on boot.
-
-- How does the non-secure core behave on power-up? Is it held in reset,
- does it jump to a set address, …?
-
-- What are the performance characteristics of the two core?
-
- - There could be a great disparity in performance
-
-**********************
-TF-M Twin Core Booting
-**********************
-In an effort to make the problem manageable, as well as to provide a system
-with good performance, that is flexible enough to work for a variety of dual
-core systems, the following design decisions have been made:
-
-- TF-M will (for now) only support systems where the secure core has full
- access to the Flash that the non-secure core will boot from
-
- - This keeps the boot flow as close as possible to the single core design,
- with the secure core responsible for maintaining the chain of trust for
- the entire system, and for upgrade of the entire system
-
-- The secure code will make a platform-specific call immediately after setting
- up hardware protection to (potentially) start the non-secure core running
-
- - This is the earliest point at which it is safe to allow the non-secure
- code to start running, so starting it here ensures system integrity while
- also giving the non-secure code the maximum amount of time to perform its
- initialization
-
- - Note that this is after the bootloader has validated the non-secure image,
- which is the other key part to maintain security
-
- - This also means that only tfm_s and tfm_ns have to change, and not mcuboot
-
-- Both the secure and non-secure code will make platform-specific calls to
- establish a synchronization point. This will be after both sides have done
- any initialization that is required, including setting up inter-core
- communications. On a single core system, this would be the point at which the
- secure code jumps to the non-secure code, and at the very start of the
- non-secure code.
-
-- After completing initialization on the secure core (at the point where on a
- single core system, it would jump to the non-secure code), the main thread on
- the secure core will be allowed to die
-
- - The scheduler has been started at this point, and an idle thread exists.
- Any additional work that is only required in the dual core case will be
- interrupt-driven.
-
-- Because both cores may be booting in parallel, executing different
- initialization code, at different speeds, the design must be resilient if
- either core attempts to communicate with the other before the latter is ready.
- For example, the client (non-secure) side of the IPC mechanism must be able
- to handle the situation where it has to wait for the server (secure) side to
- finish setting up the IPC mechanism.
-
- - This relates to the synchronization calls mentioned above. It means that
- those calls cannot utilise the IPC mechanism, but must instead use some
- platform-specific mechanism to establish this synchronization. This could
- be as simple as setting aside a small area of shared memory and having
- both sides set a “ready” flag, but may well also involve the use of
- interrupts.
-
- - This also means that the synchronization call must take place after the
- IPC mechanism has been set up but before any attempt (by either side) to
- use it.
-
-*************
-API Additions
-*************
-Three new HAL functions are required:
-
-.. code-block:: c
-
- void tfm_spm_hal_boot_ns_cpu(uintptr_t start_addr);
-
-- Called on the secure core from ``tfm_core_init()`` after hardware protections
- have been configured.
-
-- Performs the necessary actions to start the non-secure core running the code
- at the specified address.
-
-.. code-block:: c
-
- void tfm_spm_hal_wait_for_ns_cpu_ready(void);
-
-- Called on the secure core from the end of ``tfm_core_init()`` where on a
- single core system the secure code calls into the non-secure code.
-
-- Flags that the secure core has completed its initialization, including setting
- up the IPC mechanism.
-
-- Waits, if necessary, for the non-secure core to flag that it has completed its
- initialisation
-
-.. code-block:: c
-
- void tfm_ns_wait_for_s_cpu_ready(void);
-
-- Called on the non-secure core from ``main()`` after the dual-core-specific
- initialization (on a single core system, this would be the start of the
- non-secure code), before the first use of the IPC mechanism.
-
-- Flags that the non-secure side has completed its initialization.
-
-- Waits, if necessary, for the secure core to flag that it has completed its
- initialization.
-
-For all three, an empty implementation will be provided with a weak symbol so
-that platforms only have to provide the new functions if they are required.
-
----------------
-
-Copyright (c) 2019 Cypress Semiconductor Corporation
diff --git a/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
deleted file mode 100644
index 2bb3762aee..0000000000
--- a/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
+++ /dev/null
@@ -1,767 +0,0 @@
-################################################################
-Communication Prototype Between NSPE And SPE In Dual Core System
-################################################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-This document proposes a generic prototype of the communication between NSPE
-(Non-secure Processing Environment) and SPE (Secure Processing Environment) in
-TF-M on a dual core system.
-
-The dual core system should satisfy the following requirements
-
-- NSPE and SPE are properly isolated and protected following PSA
-- An Arm M-profile core locates in SPE and acts as the Secure core
-- An Inter-Processor Communication hardware module in system for communication
- between NSPE core and SPE core
-- TF-M runs on the Secure core with platform specific drivers support.
-
-Scope
-=====
-
-This design document focuses on the dual core communication design inside TF-M.
-Some changes to TF-M core/Secure Partition Manager (SPM) are listed to support
-the dual core communication. This document only discuss about the implementation
-in TF-M Inter-Process Communication (IPC) model.
-The TF-M non-secure interface library depends on mailbox and NS RTOS
-implementation. The related changes to TF-M non-secure interface library are not
-discussed in detail in this document.
-
-Some requirements to mailbox functionalities are defined in this document. The
-detailed mailbox design or implementations is not specified in this document.
-Please refer to mailbox dedicate document [1]_.
-
-Organization of the document
-============================
-
-- `Overall workflow in dual core communication`_ provides an overall workflow of
- dual core communication between NSPE and SPE.
-- `Requirements on mailbox communication`_ lists general requirements of
- mailbox, from the perspective of dual core communication.
-- `PSA client call handling flow in TF-M`_ discusses about the detailed sequence
- and key modules of handling PSA client call in TF-M.
-- `Summary of changes to TF-M core/SPM`_ summarizes the potential changes to
- TF-M core/SPM to support dual core communication.
-
-*******************************************
-Overall workflow in dual core communication
-*******************************************
-
-The overall workflow in dual-core scenario can be described as follows
-
-1. Non-secure application calls TF-M non-secure interface library to request
- Secure service. The TF-M non-secure interface library translates the Secure
- service into PSA Client calls.
-2. TF-M non-secure interface library notifies TF-M of the PSA client call
- request, via mailbox. Proper generic mailbox APIs in HAL should be defined
- so that TF-M non-secure interface library can co-work with diverse platform
- specific Inter-Processor Communication implementations.
-3. Inter-Processor Communication interrupt handler and mailbox handling in TF-M
- deal with the inbound mailbox event(s) and deliver the PSA client call
- request to TF-M SPM.
-4. TF-M SPM processes the PSA client call request. The PSA client call is
- eventually handled in target Secure Partition or corresponding handler.
-5. After the PSA Client call is completed, the return value is returned to NSPE
- via mailbox.
-6. TF-M non-secure interface library fetches return value from mailbox.
-7. The return value is returned to non-secure application.
-
-The interfaces between NSPE app and TF-M NSPE interface library are unchanged
-so the underlying platform specific details are transparent to NSPE
-application.
-
-Step 3 ~ step 5 are covered in `PSA client call handling flow in TF-M`_ in
-detail.
-
-*************************************
-Requirements on mailbox communication
-*************************************
-
-The communication between NSPE and SPE relies on mailbox communication
-implementation. The mailbox functionalities are eventually implemented by
-platform specific Inter-Processor Communication drivers.
-This section lists some general requirements on mailbox communication between
-NSPE and SPE.
-
-Data transferred between NPSE and SPE
-=====================================
-
-A mailbox message should contain the information and parameters of a PSA client
-call. After SPE is notified by a mailbox event, SPE fetches the parameters from
-NSPE for PSA Client call processing.
-The mailbox design document [1]_ defines the structure of the mailbox message.
-
-The information and parameters of PSA Client call in the mailbox message include
-
-- PSA Client API
-
-- Parameters required in PSA Client call. The parameters can include the
- following, according to PSA client call type
-
- - Service ID (SID)
- - Handle
- - Request type
- - Input vectors and the lengths
- - Output vectors and the lengths
- - Requested version of secure service
-
-- NSPE Client ID. Optional. The NSPE Client ID is required when NSPE RTOS
- enforces non-secure task isolation.
-
-The mailbox implementation may define additional members in mailbox message to
-accomplish mailbox communication between NSPE and SPE.
-
-When the PSA Client call is completed in TF-M, the return result, such as
-PSA_SUCCESS or a handle, should be returned from SPE to NSPE via mailbox.
-
-Mailbox synchronization between NSPE and SPE
-============================================
-
-Synchronization and protection between NSPE and SPE accesses to shared mailbox
-objects and variables should be implemented.
-
-When a core accesses shared mailbox objects or variables, proper mechanisms
-should protect concurrent operations from the other core.
-
-Support of multiple ongoing NS PSA client calls (informative)
-=============================================================
-
-If the support of multiple ongoing NS PSA client calls in TF-M is required
-in dual-core systems, an optional queue can be maintained in TF-M core to store
-multiple mailbox objects received from NSPE.
-To identify NS PSA client calls, additional fields can be added in TF-M SPM
-objects to store the NS PSA Client request identification.
-
-Note that when just a single outstanding PSA client call is allowed, multiple
-NSPE OS threads can run concurrently and call PSA client functions. The first
-PSA client call will be processed first, and any other OS threads will be
-blocked from submitting PSA client calls until the first is completed.
-
-*************************************
-PSA client call handling flow in TF-M
-*************************************
-
-This section provides more details about the flow of PSA client call handing in
-TF-M.
-
-The sequence of handling PSA Client call request in TF-M is listed as below
-
-1. Platform specific Inter-Processor Communication interrupt handler is
- triggered after the mailbox event is asserted by NSPE. The interrupt handler
- should assert a PendSV.
-2. In the top half of PendSV handler, the scheduler selects the next thread to
- run and executes normal context switch if necessary.
-3. In the bottom half of PendSV handler, mailbox handling deals with the mailbox
- message(s) which contain(s) the PSA client call information and parameters.
- Then the PSA client call request is dispatched to dedicated PSA client call
- handler in TF-M SPM.
-4. After the PSA client call is completed, the return value is transmitted to
- NSPE via mailbox.
-
-Several key modules in the whole process are covered in detail in following
-sections.
-
-- `Inter-Processor Communication interrupt handler`_ discusses about the
- Inter-Processor Communication interrupt handler
-- `TF-M Remote Procedure Call (RPC) layer`_ introduces TF-M Remote Procedure
- Call layer to support dual-core communication.
-- `PendSV handler`_ specifies the mailbox tasks in PendSV handler.
-- `Return value replying routine in TF-M`_ proposes the routine to reply the
- return value to NSPE.
-
-Inter-Processor Communication interrupt handler
-===============================================
-
-Platform specific driver should implement the Inter-Processor Communication
-interrupt handler to deal with the Inter-Processor Communication interrupt
-asserted by NSPE.
-The platform specific interrupt handler should complete the interrupt
-operations, such as interrupt EOI or acknowledge.
-
-The interrupt handler should call SPE mailbox API(s) to deal with the inbound
-mailbox event. The SPE mailbox may assert a PendSV.
-
-Platform specific driver should put Inter-Processor Communication interrupt into
-a proper exception priority, according to system and application requirements.
-The proper priority setting should guarantee that
-
-- TF-M can respond to a PSA client call request in time according to system and
- application requirements.
-- Other exceptions, which are more latency sensitive or require higher
- priorities, are not blocked by Inter-Processor Communication interrupt ISR.
-
-The exception priority setting is IMPLEMENTATION DEFINED.
-
-TF-M Remote Procedure Call (RPC) layer
-======================================
-
-This design brings up a concept of Remote Procedure Call layer in TF-M.
-
-The RPC layer sits between TF-M SPM and mailbox implementation. The purpose of
-RPC layer is to decouple mailbox implementation and TF-M SPM and enhance the
-generality of entire dual-core communication.
-
-The RPC layer provides a set of APIs to TF-M SPM to handle and reply PSA client
-call from NSPE in dual-core scenario. Please refer to
-`TF-M RPC definitions to TF-M SPM`_ for API details.
-It hides the details of specific mailbox implementation from TF-M SPM. It avoids
-modifying TF-M SPM to fit mailbox development and changes.
-It can keep a unified PSA client call process in TF-M SPM in both single
-Armv8-M scenario and dual core scenario.
-
-The RPC layer defines a set callback functions for mailbox implementation to
-hook its specific mailbox operations. When TF-M SPM invokes RPC APIs to deal
-with NSPE PSA client call, RPC layer eventually calls the callbacks to execute
-mailbox operations.
-RPC layer also defines a set of PSA client call handler APIs for mailbox
-implementation. RPC specific client call handlers parse the PSA client call
-parameters and invoke common TF-M PSA client call handlers. Please refer to
-`TF-M RPC definitions for mailbox`_ for the details.
-
-PendSV handler
-==============
-
-The mailbox handling should be added to PendSV handler in current TF-M single
-Armv8-M implementation in IPC model. Mailbox handling processes the inbound
-mailbox event(s) in the bottom half of PendSV handler. The top half of PendSV
-contains the original scheduling.
-
-Mailbox handling must be executed after the original scheduling to make sure
-that the status of sleeping secure service has been updated in scheduling when
-mailbox handling triggers the sleeping secure service.
-
-A compile flag can be defined to disable mailbox handling in PendSV handler in
-single Armv8-M scenario during building.
-
-This section only discusses about the mailbox handling in the bottom half of
-PendSV handler. The TF-M scheduling and context switch should keep unchanged as
-current single Armv8-M implementation.
-
-Mailbox handling in bottom half of PendSV handler
--------------------------------------------------
-
-PendSV handler should call RPC API ``tfm_rpc_client_call_handler()`` to check
-and handle PSA client call request from NSPE. ``tfm_rpc_client_call_handler()``
-invokes request handling callback function to eventually execute specific
-mailbox message handling operations. The mailbox APIs are defined in mailbox
-design document [1]_.
-
-The handling process in mailbox operation consists of the following steps.
-
-1. SPE mailbox fetches the PSA client call parameters from NSPE mailbox.
- Proper protection and synchronization should be implemented in mailbox to
- guarantee that the operations are not interfered by NSPE mailbox operations
- or Inter-Processor Communication interrupt handler.
- If a queue is maintained inside TF-M core, SPE mailbox can fetch multiple
- PSA client calls together into the queue, to save the time of synchronization
- between two cores.
-
-2. SPE mailbox parses the PSA client call paramters copied from NSPE, including
- the PSA client call type.
-
-3. The PSA client call request is dispatched to the dedicated TF-M RPC PSA
- client call handler. The PSA client call request is processed in the
- corresponding handler.
-
- - For ``psa_framework_version()`` and ``psa_version()``, the PSA client call
- can be completed in the handlers ``tfm_rpc_psa_framework_version()`` and
- ``tfm_rpc_psa_version()`` respectively.
-
- - For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the handlers
- ``tfm_rpc_psa_connect()``, ``tfm_rpc_psa_call()`` and
- ``tfm_rpc_psa_close()`` create the PSA message and trigger target Secure
- partition respectively. The target Secure partition will be woken up to
- handle the PSA message.
-
-The dual-core scenario and single Armv8-M scenario in TF-M IPC implementation
-should share the same PSA client call routines inside TF-M SPM. The current
-handler definitions can be adjusted to be more generic for dual-core scenario
-and single Armv8-M implementation. Please refer to
-`Summary of changes to TF-M core/SPM`_ for details.
-
-If there are multiple NSPE PSA client call requests pending, SPE mailbox can
-process mailbox messages one by one.
-
-Implementation details in PendSV handler
-----------------------------------------
-
-Some more details should be taken care of in actual implementation.
-
-- PendSV priority should be configured as low enough, to prevent blocking or
- preempting other latency sensitive interrupts.
-- All the mailbox implementations inside PendSV handler must not directly
- execute context switch.
-- To simplify the interrupt handling inside TF-M, the mailbox handling
- implementation inside PendSV handle should avoid triggering additional
- Inter-Processor Communication interrupts in TF-M, unless it is explicitly
- required in mailbox design.
-- If Inter-Processor Communication interrupt handler and PendSV handler access
- shared mailbox objects, proper protection and synchronization should be
- implemented in both handlers. For example, the Inter-Processor Communication
- interrupt can be temporarily disabled on secure core while PendSV handler
- accesses mailbox objects in TF-M.
-
-Return value replying routine in TF-M
-=====================================
-
-Diverse PSA client calls can be implemented with different return value replying
-routines.
-
-- `Replying routine for psa_framework_version() and psa_version()`_ describes
- the routine for ``psa_framework_version()`` and ``psa_version()``.
-- `Replying routine for psa_connect(), psa_call() and psa_close()`_ describes
- the routine for ``psa_connect()``, ``psa_call()`` and ``psa_close()``.
-
-Replying routine for psa_framework_version() and psa_version()
---------------------------------------------------------------
-
-For ``psa_framework_version()`` and ``psa_version()``, the return value can be
-directly returned from the dedicated TF-M RPC PSA client call handlers.
-Therefore, the return value can be directly replied in mailbox handling process.
-
-A compile flag should be defined to enable replying routine via mailbox in
-dual-core scenario during building.
-
-The mailbox reply functions must not trigger context switch inside PendSV
-handler.
-
-Replying routine for psa_connect(), psa_call() and psa_close()
---------------------------------------------------------------
-
-For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the PSA client call
-is completed in the target Secure Partition. The target Secure Partition calls
-``psa_reply()`` to reply the return value to TF-M SPM. In the SVC handler of
-``psa_reply()`` in TF-M SPM, TF-M SPM should call TF-M RPC API
-``tfm_rpc_client_call_reply()`` to return the value to NSPE via mailbox.
-``tfm_rpc_client_call_reply()`` invokes reply callbacks to execute specific
-mailbox reply operations. The mailbox reply functions must not trigger context
-switch inside SVC handler.
-
-If an error occurs in the handlers, the TF-M RPC handlers,
-``tfm_rpc_psa_call()``, ``tfm_rpc_psa_connect()`` and ``tfm_rpc_psa_close()``,
-may terminate and return the error, without triggering the target Secure
-Partition. The mailbox implementation should return THE error code to NSPE.
-
-A compile flag should be defined to enable replying routine via mailbox in
-dual-core scenario during building.
-
-***********************************
-Summary of changes to TF-M core/SPM
-***********************************
-
-This section discusses the general changes related to NSPE and SPE
-communication to current TF-M core/SPM implementations.
-
-The detailed mailbox implementations are not covered in this section. Please
-refer to mailbox dedicated document [1]_.
-The platform specific implementations are also not covered in this section,
-including the Inter-Processor Communication interrupt or its interrupt handler.
-
-Common PSA client call handlers
-===============================
-
-Common PSA client call handlers should be extracted from current PSA client
-call handlers implementation in TF-M.
-Common PSA client call handlers are shared by both TF-M RPC layer in dual-core
-scenario and SVCall handlers in single Armv8-M scenario.
-
-TF-M RPC layer
-==============
-
-This section describes the TF-M RPC data types and APIs.
-
-- `TF-M RPC definitions to TF-M SPM`_ lists the data types and APIs to be
- invoked by TF-M SPM.
-- `TF-M RPC definitions for mailbox`_ lists the data types and APIs to be
- referred by mailbox implementation
-
-TF-M RPC definitions to TF-M SPM
---------------------------------
-
-TFM_RPC_SUCCESS
-^^^^^^^^^^^^^^^
-
-``TFM_RPC_SUCCESS`` is a general return value to indicate that the RPC operation
-succeeds.
-
-.. code-block:: c
-
- #define TFM_RPC_SUCCESS (0)
-
-TFM_RPC_INVAL_PARAM
-^^^^^^^^^^^^^^^^^^^
-
-``TFM_RPC_INVAL_PARAM`` is a return value to indicate that the input parameters
-are invalid.
-
-.. code-block:: c
-
- #define TFM_RPC_INVAL_PARAM (INT32_MIN + 1)
-
-TFM_RPC_CONFLICT_CALLBACK
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Currently one and only one mailbox implementation is supported in dual core
-communication. This flag indicates that callback functions from one mailbox
-implementation are already registered and no more implementations are accepted.
-
-.. code-block:: c
-
- #define TFM_RPC_CONFLICT_CALLBACK (INT32_MIN + 2)
-
-``tfm_rpc_client_call_handler()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M PendSV handler calls this function to handle NSPE PSA client call request.
-
-.. code-block:: c
-
- void tfm_rpc_client_call_handler(void);
-
-Usage
-~~~~~
-
-``tfm_rpc_client_call_handler()`` invokes callback function ``handle_req()`` to
-execute specific mailbox handling.
-Please note that ``tfm_rpc_client_call_handler()`` doesn't return the status of
-underlying mailbox handling.
-
-``tfm_rpc_client_call_reply()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M ``psa_reply()`` handler calls this function to reply PSA client call return
-result to NSPE.
-
-.. code-block:: c
-
- void tfm_rpc_client_call_reply(const void *owner, int32_t ret);
-
-Parameters
-~~~~~~~~~~
-
-+-----------+--------------------------------------------------------------+
-| ``owner`` | A handle to identify the owner of the PSA client call return |
-| | value. |
-+-----------+--------------------------------------------------------------+
-| ``ret`` | PSA client call return result value. |
-+-----------+--------------------------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_client_call_reply()`` invokes callback function ``reply()`` to execute
-specific mailbox reply.
-Please note that ``tfm_rpc_client_call_reply()`` doesn't return the status of
-underlying mailbox reply process.
-
-``tfm_rpc_set_caller_data()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function sets the private data of the NS caller in TF-M message to identify
-the caller after PSA client call is completed.
-
-.. code-block:: c
-
- void tfm_rpc_set_caller_data(struct tfm_msg_body_t *msg, int32_t client_id);
-
-Parameters
-~~~~~~~~~~
-
-+---------------+-----------------------------------------------------+
-| ``msg`` | TF-M message to be set with NS caller private data. |
-+---------------+-----------------------------------------------------+
-| ``client_id`` | The client ID of the NS caller. |
-+---------------+-----------------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_set_caller_data()`` invokes callback function ``get_caller_data()`` to
-fetch the private data of caller of PSA client call and set it into TF-M message
-structure.
-
-TF-M RPC definitions for mailbox
---------------------------------
-
-PSA client call parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This data structure holds the parameters used in a PSA client call. The
-parameters are passed from non-secure core to secure core via mailbox.
-
-.. code-block:: c
-
- struct client_call_params_t {
- uint32_t sid;
- psa_handle_t handle;
- int32_t type;
- const psa_invec *in_vec;
- size_t in_len;
- psa_outvec *out_vec;
- size_t out_len;
- uint32_t version;
- };
-
-Mailbox operations callbacks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This structures contains the callback functions for specific mailbox operations.
-
-.. code-block:: c
-
- struct tfm_rpc_ops_t {
- void (*handle_req)(void);
- void (*reply)(const void *owner, int32_t ret);
- const void * (*get_caller_data)(int32_t client_id);
- };
-
-``tfm_rpc_register_ops()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function registers underlying mailbox operations into TF-M RPC callbacks.
-
-.. code-block:: c
-
- int32_t tfm_rpc_register_ops(const struct tfm_rpc_ops_t *ops_ptr);
-
-Parameters
-~~~~~~~~~~
-
-+-------------+----------------------------------------------+
-| ``ops_ptr`` | Pointer to the specific operation structure. |
-+-------------+----------------------------------------------+
-
-Return
-~~~~~~
-
-+----------------------+-----------------------------------------+
-| ``TFM_RPC_SUCCESS`` | Operations are successfully registered. |
-+----------------------+-----------------------------------------+
-| ``Other error code`` | Fail to register operations. |
-+----------------------+-----------------------------------------+
-
-Usage
-~~~~~
-
-Mailbox should register TF-M RPC callbacks during mailbox initialization, before
-enabling secure services for NSPE.
-
-Currently one and only one underlying mailbox communication implementation is
-allowed in runtime.
-
-``tfm_rpc_unregister_ops()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function unregisters underlying mailbox operations from TF-M RPC callbacks.
-
-.. code-block:: c
-
- void tfm_rpc_unregister_ops(void);
-
-Usage
-~~~~~
-
-Currently one and only one underlying mailbox communication implementation is
-allowed in runtime.
-
-``tfm_rpc_psa_framework_version()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M RPC handler for psa_framework_version().
-
-.. code-block:: c
-
- uint32_t tfm_rpc_psa_framework_version(void);
-
-Return
-~~~~~~
-
-+-------------+---------------------------------------------------------+
-| ``version`` | The version of the PSA Framework implementation that is |
-| | providing the runtime services. |
-+-------------+---------------------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_psa_framework_version()`` invokes common ``psa_framework_version()``
-handler in TF-M.
-
-``tfm_rpc_psa_version()``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M RPC handler for psa_version().
-
-.. code-block:: c
-
- uint32_t tfm_rpc_psa_version(const struct client_call_params_t *params,
- bool ns_caller);
-
-Parameters
-~~~~~~~~~~
-
-+---------------+-----------------------------------+
-| ``params`` | Base address of parameters. |
-+---------------+-----------------------------------+
-| ``ns_caller`` | Whether the caller is non-secure. |
-+---------------+-----------------------------------+
-
-Return
-~~~~~~
-
-+----------------------+------------------------------------------------------+
-| ``PSA_VERSION_NONE`` | The RoT Service is not implemented, or the caller is |
-| | not permitted to access the service. |
-+----------------------+------------------------------------------------------+
-| ``> 0`` | The minor version of the implemented RoT Service. |
-+----------------------+------------------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_psa_version()`` invokes common ``psa_version()`` handler in TF-M.
-The parameters in params should be prepared before calling
-``tfm_rpc_psa_version()``.
-
-``tfm_rpc_psa_connect()``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M RPC handler for ``psa_connect()``.
-
-.. code-block:: c
-
- psa_status_t tfm_rpc_psa_connect(const struct client_call_params_t *params,
- bool ns_caller);
-
-Parameters
-~~~~~~~~~~
-
-+---------------+-----------------------------------+
-| ``params`` | Base address of parameters. |
-+---------------+-----------------------------------+
-| ``ns_caller`` | Whether the caller is non-secure. |
-+---------------+-----------------------------------+
-
-Return
-~~~~~~
-
-+-------------------------+---------------------------------------------------+
-| ``PSA_SUCCESS`` | Success. |
-+-------------------------+---------------------------------------------------+
-| ``PSA_CONNECTION_BUSY`` | The SPM cannot make the connection at the moment. |
-+-------------------------+---------------------------------------------------+
-| ``Does not return`` | The RoT Service ID and version are not supported, |
-| | or the caller is not permitted to access the |
-| | service. |
-+-------------------------+---------------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_psa_connect()`` invokes common ``psa_connect()`` handler in TF-M.
-The parameters in params should be prepared before calling
-``tfm_rpc_psa_connect()``.
-
-``tfm_rpc_psa_call()``
-^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M RPC handler for ``psa_call()``.
-
-.. code-block:: c
-
- psa_status_t tfm_rpc_psa_call(const struct client_call_params_t *params,
- bool ns_caller);
-
-Parameters
-~~~~~~~~~~
-
-+---------------+-----------------------------------+
-| ``params`` | Base address of parameters. |
-+---------------+-----------------------------------+
-| ``ns_caller`` | Whether the caller is non-secure. |
-+---------------+-----------------------------------+
-
-Return
-~~~~~~
-
-+---------------------+---------------------------------------------+
-| ``PSA_SUCCESS`` | Success. |
-+---------------------+---------------------------------------------+
-| ``Does not return`` | The call is invalid, or invalid parameters. |
-+---------------------+---------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_psa_call()`` invokes common ``psa_call()`` handler in TF-M.
-The parameters in params should be prepared before calling
-``tfm_rpc_psa_call()``.
-
-``tfm_rpc_psa_close()``
-^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M RPC ``psa_close()`` handler
-
-.. code-block:: c
-
- void tfm_rpc_psa_close(const struct client_call_params_t *params,
- bool ns_caller);
-
-Parameters
-~~~~~~~~~~
-
-+---------------+-----------------------------------+
-| ``params`` | Base address of parameters. |
-+---------------+-----------------------------------+
-| ``ns_caller`` | Whether the caller is non-secure. |
-+---------------+-----------------------------------+
-
-Return
-~~~~~~
-
-+---------------------+---------------------------------------------+
-| ``void`` | Success. |
-+---------------------+---------------------------------------------+
-| ``Does not return`` | The call is invalid, or invalid parameters. |
-+---------------------+---------------------------------------------+
-
-Usage
-~~~~~
-
-``tfm_rpc_psa_close()`` invokes common ``psa_close()`` handler in TF-M.
-The parameters in params should be prepared before calling
-``tfm_rpc_psa_close()``.
-
-Other modifications
-===================
-
-The following mandatory changes are also required.
-
-- One or more compile flag(s) should be defined to select corresponding
- execution routines in dual-core scenario or single Armv8-M scenario during
- building.
-- PendSV priority should be configured in TF-M initialization.
-
-Some optional changes or optimizations are listed below.
-
-- The PSA client call handlers of ``psa_connect()``, ``psa_call()`` and
- ``psa_close()`` can be optimized to skip asserting PendSV in dual-core
- scenario.
-
-*********
-Reference
-*********
-
-.. [1] :doc:`Mailbox Design in TF-M on Dual-core System <./mailbox_design_on_dual_core_system>`
-
-----------------
-
-*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.*
-
-*Copyright (c) 2020 Cypress Semiconductor Corporation.*
diff --git a/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png b/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png
deleted file mode 100644
index 79f5654465..0000000000
Binary files a/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png and /dev/null differ
diff --git a/docs/design_documents/dual-cpu/index.rst b/docs/design_documents/dual-cpu/index.rst
deleted file mode 100644
index f302748333..0000000000
--- a/docs/design_documents/dual-cpu/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Dual-CPU
-========
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst b/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
deleted file mode 100644
index 60ac467d0f..0000000000
--- a/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
+++ /dev/null
@@ -1,1475 +0,0 @@
-##########################################
-Mailbox Design in TF-M on Dual-core System
-##########################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-This document proposes a generic design of the mailbox communication for Trusted
-Firmware-M (TF-M) on a dual-core system. The mailbox functionalities transfer
-PSA Client requests and results between Non-secure Processing Environment (NSPE)
-and Secure Processing Environment (SPE).
-
-The dual-core system should satisfy the following requirements
-
-- NSPE and SPE are properly isolated and protected following PSA specifications.
-- An Arm M-profile core locates in SPE and acts as the Secure core.
-- TF-M runs on the Secure core with platform specific drivers support.
-- Inter-Processor Communication hardware module in system for communication
- between Secure core and Non-secure core. Mailbox communication calls the
- Inter-Processor Communication to transfer notifications.
-- Non-secure memory shared by NSPE and SPE.
-
-Scope
-=====
-
-This design document focuses on the mailbox functionalities in NSPE and SPE on a
-dual-core system. The mailbox functionalities include the initialization of
-mailbox in NSPE and SPE, and the transfer of PSA Client requests and replies
-between NSPE and SPE.
-
-Data types and mailbox APIs are defined in this document.
-
-Some details of interactions between mailbox and other modules are specified in
-other documents.
-Communication prototype design [1]_ defines a general communication prototype
-between NSPE and SPE on a dual-core system. It describes how TF-M interacts with
-mailbox functionalities and the general requirements on mailbox.
-Dual-core booting sequence [2]_ describes a synchronization step of mailbox
-between NSPE and SPE during system booting.
-
-Organization of the document
-============================
-
-- `Mailbox architecture`_ provides an overview on the mailbox architecture.
-- `Mailbox communication for PSA Client calls`_ discusses about the mailbox
- communication for PSA Client calls.
-- `Mailbox initialization`_ introduces the initialization of mailbox.
-- `Mailbox APIs and data structures`_ lists mailbox data types and APIs.
-
-********************
-Mailbox architecture
-********************
-
-The mailbox consists of two parts sitting in NSPE and SPE respectively.
-NSPE mailbox provides mailbox functionalities in NSPE and SPE mailbox provides
-mailbox functionalities in TF-M in SPE.
-
-PSA Client APIs called in NSPE are implemented by NSPE mailbox functions on
-dual-core systems, to send PSA Client request and receive the result. The
-implementation can vary in diverse NSPE OSs or use cases.
-
-TF-M provides a reference implementation of NSPE mailbox. The NSPE mailbox
-delivers the PSA Client requests to SPE mailbox. After the PSA Client result is
-replied from SPE, NSPE mailbox fetches the result and returns it to PSA Client
-APIs.
-
-NSPE mailbox objects are managed by NSPE mailbox in non-secure memory to hold
-PSA Client call parameters, return result and other mailbox data.
-NSPE mailbox relies on platform specific Inter-Process Communication to process
-notifications between NSPE and SPE.
-
-The SPE mailbox in TF-M receives PSA Client requests from NSPE mailbox. It
-parses the requests and invokes TF-M Remote Procedure Call (RPC) layer.
-RPC layer delivers the requests to TF-M core/Secure Partition Manager (SPM).
-After the PSA Client call is completed, TF-M core/SPM invokes RPC layer to
-return results to NSPE, via SPE mailbox.
-SPE mailbox objects are managed by SPE mailbox in secure memory.
-SPE mailbox relies on platform specific Inter-Process Communication to process
-notifications between SPE and NSPE.
-
-The architecture is showed in following figure.
-
-.. figure:: dual_core_mailbox_arch.png
-
-******************************************
-Mailbox communication for PSA Client calls
-******************************************
-
-This section describes the transfer of PSA Client request and reply between NSPE
-and SPE via mailbox.
-
-Mailbox objects
-===============
-
-This section lists the mailbox objects required in NSPE and SPE.
-
-NSPE mailbox objects are managed by NSPE mailbox in non-secure memory. But NSPE
-mailbox objects can be accessed by both NSPE mailbox and SPE mailbox.
-
-SPE mailbox objects are managed by SPE mailbox in secure memory. SPE mailbox
-objects should be protected from NSPE accesses by system specific isolation.
-
-NSPE Mailbox queue
-------------------
-
-NSPE mailbox maintains a mailbox queue in non-secure memory. Please refer to the
-structure definition in `NSPE mailbox queue structure`_.
-
-NSPE mailbox queue contains one or more slots. The number of slots should be
-aligned with that in SPE mailbox queue.
-
-Each slot in NSPE mailbox queue consists of a pair of a mailbox message
-structure and a mailbox reply structure. Each slot might contain additional
-fields, such as identification of non-secure task which initiates the PSA Client
-request. Each slot serves a PSA Client call from non-secure task.
-
-The parameters of PSA Client request are hosted in the mailbox message inside
-the slot. `Mailbox messages`_ describes the details of mailbox message.
-
-The mailbox reply structure is used to receive the PSA Client result from SPE.
-`Mailbox replies`_ describes the details of mailbox reply.
-
-Mailbox messages
-----------------
-
-A mailbox message contains the parameters of a PSA Client request from a
-non-secure task. Please refer to the structure definition in
-`Mailbox message structure`_.
-
-Inside PSA Client API implementation, NSPE mailbox selects an empty mailbox
-queue slot for the PSA Client request. The parameters of that PSA Client request
-are organized into the mailbox message belonging to the selected slot.
-SPE mailbox will parse those parameters from the mailbox message.
-
-More fields can be defined in mailbox message to transfer additional information
-from NSPE to SPE for processing in TF-M.
-
-Mailbox replies
----------------
-
-A mailbox reply structure in non-secure memory receives the PSA Client result
-replied from SPE mailbox. Please refer to the structure definition in
-`Mailbox reply structure`_.
-
-SPE Mailbox queue
------------------
-
-SPE mailbox maintains a mailbox queue to store SPE mailbox objects.
-Please refer to the structure definition in `SPE mailbox queue structure`_.
-
-SPE mailbox queue contains one or more slots. The number of slots should be
-aligned with that in NSPE mailbox queue. After SPE is notified that a PSA Client
-request is pending, SPE mailbox can assign an empty slot, copy the corresponding
-PSA Client call parameters from non-secure memory to that slot and parse the
-parameters.
-
-Each slot in SPE mailbox queue can contain the following fields
-
-- An optional field to hold mailbox message content copied from non-secure
- memory.
-- Index of NSPE mailbox queue slot containing the mailbox message.
-- A handle to the mailbox message. Optional. Identify the owner slot of PSA
- Client result when multiple mailbox messages are under processing.
-
-More fields can be defined in the slot structure to support mailbox processing
-in SPE.
-
-Overall workflow
-================
-
-The overall workflow of transferring PSA Client requests and results between
-NSPE and SPE via mailbox is shown below.
-
-#. Non-secure task initiates a service request by calling PSA Developer APIs,
- which eventually invoke PSA Client APIs.
- PSA Client APIs call NSPE mailbox functions to transmit PSA Client call to
- SPE.
-
-#. NSPE mailbox assigns an empty slot from NSPE mailbox queue for that PSA
- client call.
-
-#. NSPE mailbox prepares the parameters of PSA Client call in the dedicated
- mailbox message inside the assigned slot.
-
-#. After the mailbox message is ready, NSPE mailbox invokes platform specific
- Inter-Processor Communication driver to notify SPE.
- The notification mechanism of Inter-Processor Communication is platform
- specific.
-
-#. After the notification is completed, non-secure task waits for the reply from
- SPE.
-
-#. Platform specific Inter-Processor Communication interrupt for mailbox is
- asserted in SPE. The interrupt handler activates SPE mailbox to process the
- request(s).
-
-#. During mailbox processing in TF-M, the handling routine can include the
- following steps:
-
- #. SPE mailbox checks and validates NSPE mailbox queue status.
- #. SPE mailbox fetches PSA Client call parameters from NSPE mailbox queue.
- #. SPE mailbox parses the parameters.
- #. SPE mailbox invokes the TF-M RPC APIs to deliver the PSA Client
- request to TF-M SPM.
- #. The PSA Client call is handled in TF-M SPM and target Secure Partition if
- necessary.
-
- If multiple ongoing mailbox messages are pending in the SPE, SPE mailbox can
- process mailbox messages one by one.
-
-#. After the PSA Client call is completed, TF-M RPC layer notifies SPE mailbox
- to reply PSA Client result to NSPE.
-
-#. SPE mailbox writes the PSA Client result to the dedicated mailbox reply
- structure in non-secure memory. The related SPE mailbox objects should be
- invalidated or cleaned.
-
-#. SPE mailbox notifies NSPE by invoking Inter-Processor Communication driver to
- send a notification to NSPE.
- The notification mechanism of Inter-Processor Communication is platform
- specific.
-
-#. NSPE mailbox is activated to handle the PSA Client result in the mailbox
- reply structure. Related mailbox objects should be invalidated or cleaned by
- NSPE mailbox after the return results is extracted out.
-
-#. NSPE mailbox returns the result to PSA Client API implementation.
- The result is eventually returned to the non-secure task.
-
-The following sections discuss more details of key steps in above sequence.
-
-Mailbox notifications between NSPE and SPE
-==========================================
-
-As shown in `Overall workflow`_, NSPE mailbox asserts mailbox notification to
-trigger SPE to handle PSA Client request. SPE mailbox asserts mailbox
-notification to notify NSPE that PSA Client result is written. The notification
-implementation is based on platform specific Inter-Processor Communication.
-
-It is recommended to assign one independent set of Inter-Processor Communication
-channel to each notification routine respectively, to implement a *full-duplex*
-notification mechanism between NSPE and SPE.
-If both notification routines share the same Inter-Processor Communication
-channel, proper synchronization should be implemented to prevent conflicts
-between two notification routines.
-
-In SPE, the Inter-Processor Communication interrupt handler should deal with the
-incoming notification from NSPE and activate the subsequent mailbox handling in
-SPE. Communication prototype design [1]_ defines the behavior of Inter-Processor
-Communication interrupt handler.
-
-NSPE can implement an interrupt handler or a polling of notification status to
-handle Inter-Processor Communication notification from SPE.
-
-Implement PSA Client API with NSPE Mailbox
-==========================================
-
-PSA Client APIs are implemented with NSPE mailbox API
-``tfm_ns_mailbox_client_call()``.
-
-The pseudo code below shows a reference implementation of
-``psa_framework_version()``.
-
-.. code-block:: c
-
- uint32_t psa_framework_version(void)
- {
- ...
- int32_t ret;
-
- ret = tfm_ns_mailbox_client_call(...);
- if (ret != MAILBOX_SUCCESS) {
- version = PSA_VERSION_NONE;
- }
-
- ...
- }
-
-``tfm_ns_mailbox_client_call()`` implementation can vary according to usage
-scenario. TF-M reference implementation provides implementations for NS OS and
-NS bare metal environment respectively. Refer to
-`TF-M reference implementation of NSPE mailbox`_ for details.
-
-As PSA Firmware Framework-M (FF-M) requests, a PSA Client API function should be
-blocked until the result is returned. To comply with FF-M, NSPE mailbox requires
-proper mechanism(s) to keep current caller waiting for PSA Client result or an
-empty mailbox queue slot.
-
-.. note::
-
- ``tfm_ns_mailbox_client_call()`` may trap the current exception in sleep and
- therefore it must not be called in interrupt service routine.
-
-Refer to `Mailbox APIs and data structures`_ for details of
-``tfm_ns_mailbox_client_call()``.
-
-TF-M reference implementation of NSPE mailbox
-=============================================
-
-TF-M NS interface provides a reference implementation of NS mailbox.
-
-This reference implementation defines several NS mailbox HAL APIs. Please refer
-to `NSPE mailbox HAL APIs`_ for details.
-
-Integration with NSPE
----------------------
-
-TF-M reference implementation provides several mailbox build flags to control
-the integration with NS software.
-
- .. _mailbox_os_flag:
-
- - ``TFM_MULTI_CORE_NS_OS``
-
- When integrating NS mailbox with NS OS, such as NS RTOS, that flag can be
- selected to enable NS OS support in NS mailbox, such as thread management
- to fulfill thread wait and wake-up.
- Please refer to `NSPE mailbox RTOS abstraction APIs`_ for NS OS support
- details.
-
- With NS OS support, multiple outstanding PSA Client calls can be supported
- in NS mailbox when number of mailbox queue slots configured in
- ``NUM_MAILBOX_QUEUE_SLOT`` is greater than 1.
-
- If ``TFM_MULTI_CORE_NS_OS`` is enabled, when a NS client starts a PSA Client
- call:
-
- - ``tfm_ns_mailbox_client_call()`` selects an empty NSPE mailbox queue slot
- to organize received PSA client call parameters into a mailbox message.
-
- - Then it sends those parameters to SPE mailbox and waits for results from
- SPE. During waiting for the result, the NS client thread may be switched
- out by NS OS scheduler.
-
- - When the result arrives, the NS client thread will be woken up inside
- NS mailbox interrupt handler.
-
- - The result is then written back to NS client finally.
-
- When that flag is disabled, NS mailbox runs as being integrated with NS bare
- metal environment. NS mailbox simply loops mailbox message status while
- waiting for results.
-
- .. _mailbox_os_thread_flag:
-
- - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD``
-
- When ``TFM_MULTI_CORE_NS_OS`` is enabled, this flag can be selected to
- enable another NS mailbox thread model which relies on a NS mailbox
- dedicated thread.
-
- - It requires NS OS to create a dedicated thread to perform NS mailbox
- functionalities. This dedicated thread invokes
- ``tfm_ns_mailbox_thread_runner()`` to handle PSA Client calls.
- ``tfm_ns_mailbox_thread_runner()`` constructs mailbox messages and sends
- them to SPE mailbox.
-
- - ``tfm_ns_mailbox_client_call()`` sends PSA Client calls to the dedicated
- mailbox thread. It doesn't directly deal with mailbox messages.
-
- - It also relies on NS OS to provide thread management and inter-thread
- communication. Please refer to `NSPE mailbox RTOS abstraction APIs`_ for
- details.
-
- - It also requires dual-cpu platform to implement NS Inter-Processor
- Communication interrupts. The interrupt handler invokes
- ``tfm_ns_mailbox_wake_reply_owner_isr()`` to deal with PSA Client call
- replies and notify the waiting threads.
-
-Multiple outstanding PSA Client call feature
---------------------------------------------
-
-Multiple outstanding PSA Client call feature can enable dual-cpu platform to
-issue multiple PSA Client calls in NS OS and those PSA Client calls can be
-served simultaneously.
-
-Without this feature, only a single PSA Client call can be issued and served.
-A new PSA Client call cannot be started until the previous one is completed.
-
-When multiple outstanding PSA Client call feature is enabled, while a NS
-application is waiting for its PSA Client result, another NS application can be
-switched in by NS OS to prepare another PSA Client call or deal with its PSA
-client result. It can decrease the CPU idle time of waiting for PSA Client call
-completion.
-
-If multiple NS applications request secure services in NS OS, it is recommended
-to enable this feature.
-
-To implement this feature in NS OS:
-
- - Platform should set the number of mailbox queue slots in
- ``NUM_MAILBOX_QUEUE_SLOT`` in platform's ``config.cmake``.
- It will use more data area with multiple mailbox queue slots.
-
- NSPE and SPE share the same ``NUM_MAILBOX_QUEUE_SLOT`` value.
-
- - Enable ``TFM_MULTI_CORE_NS_OS``
-
- For more details, refer to
- :ref:`TFM_MULTI_CORE_NS_OS`.
-
- ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` can be enabled to select another NS
- mailbox working model.
- See :ref:`TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD` for
- details.
-
-Critical section protection between cores
-=========================================
-
-Proper protection should be implemented to protect the critical accesses to
-shared mailbox resources. The critical sections can include atomic reading and
-modifying NSPE mailbox queue status, slot status and other critical operations.
-
-The implementation should protect a critical access to those shared mailbox
-resource from corruptions caused by accesses from the peer core. SPE mailbox
-also accesses NSPE mailbox queue. Therefore, it is essential to implement
-synchronization or protection on NSPE mailbox queue between Secure core and
-Non-secure core. NSPE mailbox and SPE mailbox define corresponding critical
-section protection APIs respectively. The implementation of those APIs can be
-platform specific. Please see more details in `NSPE mailbox APIs`_ and
-`SPE mailbox APIs`_.
-
-It is recommended to rely on both hardware and software to implement the
-synchronization and protection.
-
-Protection of local mailbox objects can be implemented as static functions
-inside NSPE mailbox and SPE mailbox.
-
-Mailbox handling in TF-M
-========================
-
-According to communication prototype design [1]_, mailbox implementation should
-invoke ``tfm_rpc_register_ops()`` to hook its operations to TF-M RPC module
-callbacks during initialization. Mailbox message handling should call TF-M RPC
-PSA Client call handlers to deliver PSA Client request to TF-M SPM.
-
-If multiple outstanding NS PSA Client calls should be supported, TF-M SPM can
-store the mailbox message handle in a specific field in PSA message structure to
-identify the mailbox message, while creating a PSA message. While replying the
-PSA Client result, TF-M SPM can extract the mailbox message handle from PSA
-message and pass it back to mailbox reply function. SPE mailbox can identify
-which mailbox message is completed according to the handle and write the result
-to corresponding NSPE mailbox queue slot.
-
-Platform specific Inter-Processor Communication interrupt handler in SPE should
-call ``tfm_mailbox_msg_irq_handler()`` to notify SPE mailbox to deal with
-received PSA Client call(s) from NSPE. ``tfm_mailbox_msg_irq_handler()`` will
-assert PendSV. Please refer to `tfm_mailbox_msg_irq_handler()`_ for details.
-
-**********************
-Mailbox initialization
-**********************
-
-It should be guaranteed that NSPE mailbox should not initiate PSA Client request
-until SPE mailbox initialization completes.
-Refer to dual-core booting sequence [2]_ for more details on the synchronization
-between NSPE and SPE during booting.
-
-In current design, the base address of NSPE mailbox queue should be pre-defined
-and shared between NSPE mailbox and SPE mailbox.
-
-SPE mailbox initialization
-==========================
-
-The SPE mailbox queue memory should be allocated before calling
-``tfm_mailbox_init()``. ``tfm_mailbox_init()`` initializes the memory and
-variables.
-``tfm_mailbox_init()`` calls ``tfm_mailbox_hal_init()`` to perform platform
-specific initialization. The base address of NSPE mailbox queue can be
-received via ``tfm_mailbox_hal_init()``.
-
-SPE mailbox dedicated Inter-Processor Communication initialization can also be
-enabled during SPE mailbox initialization.
-
-After SPE mailbox initialization completes, SPE notifies NSPE that SPE mailbox
-functionalities are ready.
-
-NSPE mailbox initialization
-===========================
-
-The NSPE mailbox queue memory should be allocated before calling
-``tfm_ns_mailbox_init()``. ``tfm_ns_mailbox_init()`` initializes the memory and
-variables.
-``tfm_ns_mailbox_init()`` calls ``tfm_ns_mailbox_hal_init()`` to perform
-platform specific initialization. The base address of NSPE mailbox queue can be
-passed to SPE mailbox via ``tfm_ns_mailbox_hal_init()``.
-
-NSPE mailbox dedicated Inter-Processor Communication initialization can also be
-enabled during NSPE mailbox initialization.
-
-********************************
-Mailbox APIs and data structures
-********************************
-
-Data types
-==========
-
-Constants
----------
-
-``MAILBOX_SUCCESS``
-^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_SUCCESS`` is a generic return value to indicate success of mailbox
-operation.
-
-.. code-block:: c
-
- #define MAILBOX_SUCCESS (0)
-
-``MAILBOX_QUEUE_FULL``
-^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_QUEUE_FULL`` is a return value from mailbox function if mailbox queue
-is full.
-
-.. code-block:: c
-
- #define MAILBOX_QUEUE_FULL (INT32_MIN + 1)
-
-``MAILBOX_INVAL_PARAMS``
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_INVAL_PARAMS`` is a return value from mailbox function if any
-parameter is invalid.
-
-.. code-block:: c
-
- #define MAILBOX_INVAL_PARAMS (INT32_MIN + 2)
-
-``MAILBOX_NO_PERMS``
-^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_NO_PERMS`` is a return value from mailbox function if the caller
-doesn't own a proper permission to execute the operation.
-
-.. code-block:: c
-
- #define MAILBOX_NO_PERMS (INT32_MIN + 3)
-
-``MAILBOX_NO_PEND_EVENT``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_NO_PEND_EVENT`` is a return value from mailbox function if the
-expected event doesn't occur yet.
-
-.. code-block:: c
-
- #define MAILBOX_NO_PEND_EVENT (INT32_MIN + 4)
-
-``MAILBOX_CHAN_BUSY``
-^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_CHAN_BUSY`` is a return value from mailbox function if the underlying
-Inter-Processor Communication resource is busy.
-
-.. code-block:: c
-
- #define MAILBOX_CHAN_BUSY (INT32_MIN + 5)
-
-``MAILBOX_CALLBACK_REG_ERROR``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_CALLBACK_REG_ERROR`` is a return value from mailbox function if the
-registration of mailbox callback functions failed.
-
-.. code-block:: c
-
- #define MAILBOX_CALLBACK_REG_ERROR (INT32_MIN + 6)
-
-``MAILBOX_INIT_ERROR``
-^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_INIT_ERROR`` is a return value from mailbox function if the mailbox
-initialization failed.
-
-.. code-block:: c
-
- #define MAILBOX_INIT_ERROR (INT32_MIN + 7)
-
-``MAILBOX_GENERIC_ERROR``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``MAILBOX_GENERIC_ERROR`` indicates mailbox generic errors which cannot be
-indicated by the codes above.
-
-.. code-block:: c
-
- #define MAILBOX_GENERIC_ERROR (INT32_MIN + 8)
-
-PSA Client API types
-^^^^^^^^^^^^^^^^^^^^
-
-The following constants define the PSA Client API type values shared between
-NSPE and SPE
-
-.. code-block:: c
-
- #define MAILBOX_PSA_FRAMEWORK_VERSION (0x1)
- #define MAILBOX_PSA_VERSION (0x2)
- #define MAILBOX_PSA_CONNECT (0x3)
- #define MAILBOX_PSA_CALL (0x4)
- #define MAILBOX_PSA_CLOSE (0x5)
-
-Mailbox message structure
--------------------------
-
-``psa_client_params_t`` lists the parameters passed from NSPE to SPE required by
-a PSA Client call.
-
-.. code-block:: c
-
- struct psa_client_params_t {
- union {
- struct {
- uint32_t sid;
- } psa_version_params;
-
- struct {
- uint32_t sid;
- uint32_t minor_version;
- } psa_connect_params;
-
- struct {
- psa_handle_t handle;
- int32_t type;
- const psa_invec *in_vec;
- size_t in_len;
- psa_outvec *out_vec;
- size_t out_len;
- } psa_call_params;
-
- struct {
- psa_handle_t handle;
- } psa_close_params;
- };
- };
-
-The following structure describe a mailbox message and its members.
-
-- ``call_type`` indicates the PSA Client API type.
-- ``params`` stores the PSA Client call parameters.
-- ``client_id`` records the client ID of the non-secure client. Optional.
- It is used to identify the non-secure tasks in TF-M when NSPE OS enforces
- non-secure task isolation.
-
-.. code-block:: c
-
- struct mailbox_msg_t {
- uint32_t call_type;
- struct psa_client_params_t params;
-
- int32_t client_id;
- };
-
-Mailbox reply structure
------------------------
-
-This structure describes a mailbox reply structure, which is managed by NSPE
-mailbox in non-secure memory.
-
-.. code-block:: c
-
- struct mailbox_reply_t {
- int32_t return_val;
- const void *owner;
- int32_t *reply;
- uint8_t *woken_flag;
- };
-
-Mailbox queue status bitmask
-----------------------------
-
-``mailbox_queue_status_t`` defines a bitmask to indicate a status of slots in
-mailbox queues.
-
-.. code-block:: c
-
- typedef uint32_t mailbox_queue_status_t;
-
-NSPE mailbox queue structure
-----------------------------
-
-``ns_mailbox_slot_t`` defines a non-secure mailbox queue slot.
-
-.. code-block:: c
-
- /* A single slot structure in NSPE mailbox queue */
- struct ns_mailbox_slot_t {
- struct mailbox_msg_t msg;
- struct mailbox_reply_t reply;
- };
-
-``ns_mailbox_queue_t`` describes the NSPE mailbox queue and its members in
-non-secure memory.
-
-- ``empty_slots`` is the bitmask of empty slots.
-- ``pend_slots`` is the bitmask of slots whose PSA Client call is not replied
- yet.
-- ``replied_slots`` is the bitmask of slots whose PSA Client result is returned
- but not extracted yet.
-- ``queue`` is the NSPE mailbox queue of slots.
-- ``is_full`` indicates whether NS mailbox queue is full.
-
-.. code-block:: c
-
- struct ns_mailbox_queue_t {
- mailbox_queue_status_t empty_slots;
- mailbox_queue_status_t pend_slots;
- mailbox_queue_status_t replied_slots;
-
- struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];
-
- bool is_full;
- };
-
-SPE mailbox queue structure
----------------------------
-
-``secure_mailbox_slot_t`` defines a single slot structure in SPE mailbox queue.
-
-- ``ns_slot_idx`` records the index of NSPE mailbox slot containing the mailbox
- message under processing. SPE mailbox determines the reply structure address
- according to this index.
-- ``msg_handle`` contains the handle to the mailbox message under processing.
- The handle can be delivered to TF-M SPM while creating PSA message to identify
- the mailbox message.
-
-.. code-block:: c
-
- /* A handle to a mailbox message in use */
- typedef int32_t mailbox_msg_handle_t;
-
- struct secure_mailbox_slot_t {
- uint8_t ns_slot_idx;
- mailbox_msg_handle_t msg_handle;
- };
-
-``secure_mailbox_queue_t`` describes the SPE mailbox queue in secure memory.
-
-- ``empty_slots`` is the bitmask of empty slots.
-- ``queue`` is the SPE mailbox queue of slots.
-- ``ns_queue`` stores the address of NSPE mailbox queue structure.
-- ``cur_proc_slot_idx`` indicates the index of mailbox queue slot currently
- under processing.
-
-.. code-block:: c
-
- struct secure_mailbox_queue_t {
- mailbox_queue_status_t empty_slots;
-
- struct secure_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];
- /* Base address of NSPE mailbox queue in non-secure memory */
- struct ns_mailbox_queue_t *ns_queue;
- uint8_t cur_proc_slot_idx;
- };
-
-NSPE mailbox APIs
-=================
-
-NSPE mailbox interface APIs
----------------------------
-
-APIs defined in this section are called by NS software and PSA Client APIs
-implementations.
-
-``tfm_ns_mailbox_init()``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function initializes NSPE mailbox.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue);
-
-**Parameters**
-
-+-----------+-----------------------------------------+
-| ``queue`` | The base address of NSPE mailbox queue. |
-+-----------+-----------------------------------------+
-
-**Return**
-
-+---------------------+------------------------------------------+
-| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
-+---------------------+------------------------------------------+
-| Other return codes | Initialization fails with an error code. |
-+---------------------+------------------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_init()`` invokes ``tfm_ns_mailbox_hal_init()`` to complete
-platform specific mailbox and Inter-Processor Communication initialization.
-The non-secure memory area for NSPE mailbox queue structure should be statically
-or dynamically pre-allocated before calling ``tfm_ns_mailbox_init()``.
-
-``tfm_ns_mailbox_client_call()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function sends the PSA Client request to SPE, waits and fetches PSA Client
-result.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_client_call(uint32_t call_type,
- const struct psa_client_params_t *params,
- int32_t client_id,
- int32_t *reply);
-
-**Parameters**
-
-+---------------+--------------------------------------------------+
-| ``call_type`` | Type of PSA Client call |
-+---------------+--------------------------------------------------+
-| ``params`` | Address of PSA Client call parameters structure. |
-+---------------+--------------------------------------------------+
-| ``client_id`` | ID of non-secure task. |
-+---------------+--------------------------------------------------+
-| ``reply`` | The NS client task private buffer written with |
-| | PSA Client result |
-+---------------+--------------------------------------------------+
-
-**Return**
-
-+---------------------+--------------------------------------------+
-| ``MAILBOX_SUCCESS`` | PSA Client call is completed successfully. |
-+---------------------+--------------------------------------------+
-| Other return code | Operation failed with an error code. |
-+---------------------+--------------------------------------------+
-
-**Usage**
-
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
-``tfm_ns_mailbox_client_call()`` will forward PSA Client calls to the dedicated
-mailbox thread via NS OS message queue.
-Otherwise, ``tfm_ns_mailbox_client_call()`` directly deals with PSA Client calls
-and perform NS mailbox functionalities.
-
-``tfm_ns_mailbox_thread_runner()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function handles PSA Client call inside a dedicated NS mailbox thread.
-It constructs mailbox messages and transmits them to SPE mailbox.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_thread_runner(void *args);
-
-**Parameters**
-
-+----------+-------------------------------------------------------------+
-| ``args`` | The pointer to the structure of PSA Client call parameters. |
-+----------+-------------------------------------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_thread_runner()`` should be executed inside the dedicated
-mailbox thread.
-
-.. note::
-
- ``tfm_ns_mailbox_thread_runner()`` is implemented as an empty function when
- ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled.
-
-``tfm_ns_mailbox_wake_reply_owner_isr()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function wakes up the owner task(s) of the returned PSA Client result(s).
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_wake_reply_owner_isr(void);
-
-**Return**
-
-+---------------------------+--------------------------------------------+
-| ``MAILBOX_SUCCESS`` | The tasks of replied mailbox messages were |
-| | found and wake-up signals were sent. |
-+---------------------------+--------------------------------------------+
-| ``MAILBOX_NO_PEND_EVENT`` | No replied mailbox message is found. |
-+---------------------------+--------------------------------------------+
-| Other return codes | Operation failed with an error code |
-+---------------------------+--------------------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_wake_reply_owner_isr()`` should be called from platform
-specific Inter-Processor Communication interrupt handler.
-
-.. note::
-
- ``tfm_ns_mailbox_wake_reply_owner_isr()`` is implemented as a dummy function
- when ``TFM_MULTI_CORE_NS_OS`` is disabled.
-
-NSPE mailbox HAL APIs
----------------------
-
-The HAL APIs defined in this section should be implemented by platform-specific
-implementation.
-
-This section describes a *reference design* of NSPE mailbox HAL APIs. Developers
-can define and implement different APIs.
-
-``tfm_ns_mailbox_hal_init()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function executes platform-specific NSPE mailbox initialization.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);
-
-**Parameters**
-
-+-----------+-----------------------------------------+
-| ``queue`` | The base address of NSPE mailbox queue. |
-+-----------+-----------------------------------------+
-
-**Return**
-
-+---------------------+------------------------------------------+
-| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
-+---------------------+------------------------------------------+
-| Other return codes | Initialization fails with an error code. |
-+---------------------+------------------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_hal_init()`` performs platform specific mailbox and
-Inter-Processor Communication initialization. ``tfm_ns_mailbox_hal_init()`` can
-also share the address of NSPE mailbox queue with SPE mailbox via platform
-specific implementation.
-
-``tfm_ns_mailbox_hal_notify_peer()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function invokes platform specific Inter-Processor Communication drivers to
-send notification to SPE.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_hal_notify_peer(void);
-
-**Return**
-
-+---------------------+---------------------------------------+
-| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
-+---------------------+---------------------------------------+
-| Other return codes | Operation fails with an error code. |
-+---------------------+---------------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_hal_notify_peer()`` should be implemented by platform specific
-Inter-Processor Communication drivers.
-
-``tfm_ns_mailbox_hal_notify_peer()`` should not be exported outside NSPE
-mailbox.
-
-``tfm_ns_mailbox_hal_enter_critical()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function enters the critical section of NSPE mailbox queue access.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_hal_enter_critical(void);
-
-**Usage**
-
-NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical()`` before entering
-critical section of NSPE mailbox queue.
-``tfm_ns_mailbox_hal_enter_critical()`` implementation is platform specific.
-
-``tfm_ns_mailbox_hal_enter_critical()`` should not be called in any interrupt
-service routine.
-
-``tfm_ns_mailbox_hal_exit_critical()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function exits the critical section of NSPE mailbox queue access.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_hal_exit_critical(void);
-
-**Usage**
-
-NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical()`` after exiting
-critical section of NSPE mailbox queue.
-``tfm_ns_mailbox_hal_exit_critical()`` implementation is platform specific.
-
-``tfm_ns_mailbox_hal_exit_critical()`` should not be called in any interrupt
-service routine.
-
-``tfm_ns_mailbox_hal_enter_critical_isr()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function enters the critical section of NSPE mailbox queue access in an
-IRQ handler.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_hal_enter_critical(void);
-
-**Usage**
-
-NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical_isr()`` before entering
-critical section of NSPE mailbox queue in an IRQ handler.
-``tfm_ns_mailbox_hal_enter_critical_isr()`` implementation is platform specific.
-
-``tfm_ns_mailbox_hal_exit_critical_isr()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function exits the critical section of NSPE mailbox queue access in an IRQ
-handler
-
-.. code-block:: c
-
- void tfm_ns_mailbox_hal_exit_critical_isr(void);
-
-**Usage**
-
-NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical_isr()`` after exiting
-critical section of NSPE mailbox queue in an IRQ handler.
-``tfm_ns_mailbox_hal_exit_critical_isr()`` implementation is platform specific.
-
-NSPE mailbox RTOS abstraction APIs
-----------------------------------
-
-The APIs defined in this section should be implemented by RTOS-specific
-implementation when ``TFM_MULTI_CORE_NS_OS`` is enabled.
-
-.. note::
-
- If ``TFM_MULTI_CORE_NS_OS`` is set to ``OFF``, the following APIs are defined
- as dummy functions or empty functions.
-
-``tfm_ns_mailbox_os_lock_init()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function initializes the multi-core lock for synchronizing PSA client
-call(s). The actual implementation depends on the non-secure use scenario.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_os_lock_init(void);
-
-**Return**
-
-+---------------------------+---------------------------+
-| ``MAILBOX_SUCCESS`` | Initialization succeeded. |
-+---------------------------+---------------------------+
-| ``MAILBOX_GENERIC_ERROR`` | Initialization failed. |
-+---------------------------+---------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_init()`` invokes this function to initialize the lock.
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
-``tfm_ns_mailbox_os_lock_init()`` is defined as a dummy one.
-
-``tfm_ns_mailbox_os_lock_acquire()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function acquires the multi-core lock for synchronizing PSA client call(s).
-The actual implementation depends on the non-secure use scenario.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_os_lock_acquire(void);
-
-**Return**
-
-+---------------------------+--------------------------------+
-| ``MAILBOX_SUCCESS`` | Succeeded to acquire the lock. |
-+---------------------------+--------------------------------+
-| ``MAILBOX_GENERIC_ERROR`` | Failed to acquire the lock. |
-+---------------------------+--------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_client_call()`` invokes this function to acquire the lock when
-``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
-``tfm_ns_mailbox_os_lock_acquire()`` is defined as a dummy one.
-
-``tfm_ns_mailbox_os_lock_release()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function releases the multi-core lock for synchronizing PSA client call(s).
-The actual implementation depends on the non-secure use scenario.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_os_lock_release(void);
-
-**Return**
-
-+---------------------------+--------------------------------+
-| ``MAILBOX_SUCCESS`` | Succeeded to release the lock. |
-+---------------------------+--------------------------------+
-| ``MAILBOX_GENERIC_ERROR`` | Failed to release the lock. |
-+---------------------------+--------------------------------+
-
-**Usage**
-
-``tfm_ns_mailbox_client_call()`` invokes this function to release the lock when
-``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
-``tfm_ns_mailbox_os_lock_release()`` is defined as a dummy one.
-
-``tfm_ns_mailbox_os_get_task_handle()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function gets the handle of the current non-secure task executing mailbox
-functionalities.
-
-.. code-block:: c
-
- void *tfm_ns_mailbox_os_get_task_handle(void);
-
-**Return**
-
-+-------------+-----------------------------------------------------------+
-| Task handle | The non-secure task handle waiting for PSA Client result. |
-+-------------+-----------------------------------------------------------+
-
-``tfm_ns_mailbox_os_wait_reply()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function performs use scenario and NS OS specific waiting mechanism to wait
-for the reply of the specified mailbox message to be returned from SPE.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_os_wait_reply(void);
-
-**Usage**
-
-The PSA Client API implementations call ``tfm_ns_mailbox_os_wait_reply()`` to
-fall into sleep to wait for PSA Client result.
-
-``tfm_ns_mailbox_os_wake_task_isr()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function wakes up the dedicated task which is waiting for PSA Client
-result, via RTOS-specific wake-up mechanism.
-
-.. code-block:: c
-
- void tfm_ns_mailbox_hal_wait_reply(const void *task_handle);
-
-**Parameters**
-
-+-----------------+----------------------------------------+
-| ``task_handle`` | The handle to the task to be woken up. |
-+-----------------+----------------------------------------+
-
-``tfm_ns_mailbox_os_mq_create()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function creates and initializes a NS OS message queue.
-
-.. code-block:: c
-
- void *tfm_ns_mailbox_os_mq_create(ize_t msg_size, uint8_t msg_count);
-
-**Parameters**
-
-+---------------+------------------------------------------+
-| ``msg_size`` | The maximum message size in bytes. |
-+---------------+------------------------------------------+
-| ``msg_count`` | The maximum number of messages in queue. |
-+---------------+------------------------------------------+
-
-**Return**
-
-+----------------------+-----------------------------------------------------+
-| message queue handle | The handle of the message queue created, or NULL in |
-| | case of error. |
-+----------------------+-----------------------------------------------------+
-
-**Usage**
-
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
-``tfm_ns_mailbox_os_mq_create()`` is defined as a dummy one.
-
-``tfm_ns_mailbox_os_mq_send()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function sends PSA Client call request via NS OS message queue.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_os_mq_send(void *mq_handle,
- const void *msg_ptr);
-
-**Parameters**
-
-+---------------+----------------------------------------+
-| ``mq_handle`` | The handle of message queue. |
-+---------------+----------------------------------------+
-| ``msg_ptr`` | The pointer to the message to be sent. |
-+---------------+----------------------------------------+
-
-**Return**
-
-+---------------------+-------------------------------------+
-| ``MAILBOX_SUCCESS`` | The message is successfully sent. |
-+---------------------+-------------------------------------+
-| Other return code | Operation fails with an error code. |
-+---------------------+-------------------------------------+
-
-**Usage**
-
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
-``tfm_ns_mailbox_os_mq_send()`` is defined as a dummy one.
-
-``tfm_ns_mailbox_os_mq_receive()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function receives PSA Client call requests via NS OS message queue.
-
-.. code-block:: c
-
- int32_t tfm_ns_mailbox_os_mq_receive(void *mq_handle,
- void *msg_ptr);
-
-**Parameters**
-
-+---------------+---------------------------------------------------+
-| ``mq_handle`` | The handle of message queue. |
-+---------------+---------------------------------------------------+
-| ``msg_ptr`` | The pointer to buffer for message to be received. |
-+---------------+---------------------------------------------------+
-
-**Return**
-
-+---------------------+-------------------------------------+
-| ``MAILBOX_SUCCESS`` | A message is successfully received. |
-+---------------------+-------------------------------------+
-| Other return code | Operation fails with an error code. |
-+---------------------+-------------------------------------+
-
-**Usage**
-
-The buffer size must be large enough to contain the request whose size is set
-in ``msg_size `` in ``tfm_ns_mailbox_os_mq_create()``.
-
-If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
-``tfm_ns_mailbox_os_mq_receive()`` is defined as a dummy one.
-
-.. note::
-
- The function caller should be blocked until a PSA Client call request is
- received from message queue, unless a fatal error occurs.
-
-SPE mailbox APIs
-================
-
-SPE mailbox interface APIs
---------------------------
-
-The APIs defined in this section are called in TF-M routines and platform
-specific secure interrupt handler.
-
-``tfm_mailbox_handle_msg()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function completes the handling of mailbox messages from NSPE.
-
-.. code-block:: c
-
- int32_t tfm_mailbox_handle_msg(void);
-
-**Return**
-
-+---------------------+---------------------------------------+
-| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
-+---------------------+---------------------------------------+
-| Other return codes | Operation fails with an error code. |
-+---------------------+---------------------------------------+
-
-**Usage**
-
-``tfm_mailbox_handle_msg()`` is registered to RPC callback function
-``handle_req``.
-
-``tfm_mailbox_handle_msg()`` executes the following tasks:
-
-- Check NSPE mailbox queue status.
-- Copy mailbox message(s) from NSPE. Optional.
-- Checks and validations if necessary
-- Parse mailbox message
-- Call TF-M RPC APIs to pass PSA Client request to TF-M SPM.
-
-``tfm_mailbox_reply_msg()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function replies the PSA Client result to NSPE.
-
-.. code-block:: c
-
- int32_t tfm_mailbox_reply_msg(mailbox_msg_handle_t handle, int32_t reply);
-
-**Parameters**
-
-+------------+-----------------------------------------------------------------+
-| ``handle`` | The handle to mailbox message related to the PSA Client result. |
-+------------+-----------------------------------------------------------------+
-| ``reply`` | The PSA Client result value to be replied. |
-+------------+-----------------------------------------------------------------+
-
-**Return**
-
-+---------------------+---------------------------------------+
-| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
-+---------------------+---------------------------------------+
-| Other return codes | Operation fails with an error code. |
-+---------------------+---------------------------------------+
-
-**Usage**
-
-``tfm_mailbox_reply_msg()`` is registered to RPC callback ``reply``.
-It is invoked inside handler of ``psa_reply()`` to return the PSA Client result
-to NSPE.
-
-``handle`` determines which mailbox message in SPE mailbox queue contains the
-PSA Client call. If ``handle`` is set as ``MAILBOX_MSG_NULL_HANDLE``, the return
-result is replied to the mailbox message in the first SPE mailbox queue slot.
-
-``tfm_mailbox_init()``
-^^^^^^^^^^^^^^^^^^^^^^
-
-This function initializes SPE mailbox.
-
-.. code-block:: c
-
- int32_t tfm_mailbox_init(void);
-
-**Return**
-
-+---------------------+-------------------------------------------+
-| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
-+---------------------+-------------------------------------------+
-| Other return codes | Initialization failed with an error code. |
-+---------------------+-------------------------------------------+
-
-**Usage**
-
-``tfm_mailbox_init()`` invokes ``tfm_mailbox_hal_init()`` to execute platform
-specific initialization.
-
-``tfm_mailbox_msg_irq_handler()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A general IRQ handler to deal with notification from NSPE mailbox.
-
-.. code-block:: c
-
- void tfm_mailbox_msg_irq_handler(void);
-
-**Usage**
-
-``tfm_mailbox_msg_irq_handler()`` is called in platform-specific Inter-Processor
-Communication interrupt handler when a notification from NSPE mailbox arrives.
-
-SPE mailbox HAL APIs
---------------------
-
-``tfm_mailbox_hal_notify_peer()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function invokes platform specific Inter-Processor Communication drivers to
-send notification to NSPE.
-
-.. code-block:: c
-
- int32_t tfm_mailbox_hal_notify_peer(void);
-
-**Return**
-
-+---------------------+---------------------------------------+
-| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
-+---------------------+---------------------------------------+
-| Other return codes | Operation fails with an error code. |
-+---------------------+---------------------------------------+
-
-**Usage**
-
-``tfm_mailbox_hal_notify_peer()`` should be implemented by platform specific
-Inter-Processor Communication drivers.
-
-``tfm_mailbox_hal_notify_peer()`` should not be exported outside SPE mailbox.
-
-
-``tfm_mailbox_hal_init()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function is implemented by platform support in TF-M. It completes platform
-specific mailbox initialization, including receiving the the address of NSPE
-mailbox queue and Inter-Processor Communication initialization.
-
-.. code-block:: c
-
- int32_t tfm_mailbox_hal_init(struct secure_mailbox_queue_t *s_queue);
-
-**Parameters**
-
-+-------------+----------------------------------------+
-| ``s_queue`` | The base address of SPE mailbox queue. |
-+-------------+----------------------------------------+
-
-**Return**
-
-+---------------------+-------------------------------------------+
-| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
-+---------------------+-------------------------------------------+
-| Other return codes | Initialization failed with an error code. |
-+---------------------+-------------------------------------------+
-
-``tfm_mailbox_hal_enter_critical()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function enters the critical section of NSPE mailbox queue access in SPE.
-
-.. code-block:: c
-
- void tfm_mailbox_hal_enter_critical(void);
-
-**Usage**
-
-SPE mailbox invokes ``tfm_mailbox_hal_enter_critical()`` before entering
-critical section of NSPE mailbox queue.
-``tfm_mailbox_hal_enter_critical()`` implementation is platform specific.
-
-``tfm_mailbox_hal_enter_critical()`` can be called in an interrupt service
-routine.
-
-``tfm_mailbox_hal_exit_critical()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This function exits from the critical section of NSPE mailbox queue access in
-SPE.
-
-.. code-block:: c
-
- void tfm_mailbox_hal_exit_critical(void);
-
-**Usage**
-
-SPE mailbox invokes ``tfm_mailbox_hal_exit_critical()`` when exiting from
-critical section of NSPE mailbox queue.
-``tfm_mailbox_hal_exit_critical()`` implementation is platform specific.
-
-``tfm_mailbox_hal_exit_critical()`` can be called in an interrupt service
-routine.
-
-*********
-Reference
-*********
-
-.. [1] :doc:`Communication prototype between NSPE and SPE in Dual-core systems <./communication_prototype_between_nspe_and_spe_in_dual_core_systems>`
-
-.. [2] :doc:`Booting a Dual-core system `
-
---------------------
-
-*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.*
diff --git a/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst b/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst
deleted file mode 100644
index 9ea9afdfe2..0000000000
--- a/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst
+++ /dev/null
@@ -1,513 +0,0 @@
-################################################################
-Memory Access Check of Trusted Firmware-M in Multi-Core Topology
-################################################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-:Status: Accepted
-
-************
-Introduction
-************
-
-TF-M memory access check functions ``tfm_core_has_read_access_to_region()`` and
-``tfm_core_has_write_access_to_region()`` check whether an access has proper
-permission to read or write the target memory region.
-
-On single Armv8-M core platform, TF-M memory access check implementation relies
-on `Armv8-M Security Extension`_ (CMSE) intrinsic
-``cmse_check_address_range()``.
-The secure core may not implement CMSE on multi-core platforms. Even if CMSE is
-implemented on a multi-core platform, additional check on system-level security
-and memory access management units are still necessary since CMSE intrinsics and
-TT instructions are only aware of MPU/SAU/IDAU inside the core.
-
-As a result, TF-M in multi-core topology requires a dedicated access check
-process which can work without CMSE support. This document discuss about the
-design of the memory access check in multi-core topology.
-
-.. _Armv8-M Security Extension: https://developer.arm.com/architectures/cpu-architecture/m-profile/docs/100720/0100/secure-software-guidelines/armv8m-security-extension
-
-**************
-Overall Design
-**************
-
-Memory Access Check Policy
-==========================
-
-The policies vary in diverse Isolation Levels.
-
-When TF-M works in Isolation Level 1, the access check in multi-core topology
-checks
-
-- Memory region is valid according to system settings
-- Non-secure client call request should not access secure memory.
-- Secure services should not directly access non-secure memory. According to PSA
- Firmware Framework, Secure services should call Secure Partition APIs to ask
- TF-M SPM to fetch non-secure input/output buffer for them.
-- Whether read/write attribute match between access and memory region
-
-When TF-M works in Isolation Level 2, the access check in multi-core topology
-checks:
-
-- Memory region is valid according to system settings
-- Non-secure client call request should not access secure memory.
-- Secure services should not directly access non-secure memory. According to PSA
- Firmware Framework, Secure services should call Secure Partition APIs to ask
- TF-M SPM to fetch non-secure input/outputs buffer for them.
-- Whether read/write attribute match between access and memory region
-- Unprivileged secure access should not access privileged secure memory region
-
-The check policy in Isolation Level 3 will be defined according to TF-M future
-implementation.
-
-The above policies will be adjusted according to TF-M implementation and PSA
-specs.
-
-General Check Process in TF-M Core
-==================================
-
-In multi-core topology, ``tfm_core_has_read_access_to_region()`` and
-``tfm_core_has_write_access_to_region()`` are still invoked to keep an uniform
-interface to TF-M Core/SPM.
-
-Multi-core topology specific implementations of
-``tfm_core_has_read_access_to_region()`` and
-``tfm_core_has_write_access_to_region()`` are similar to those in single Armv8-M
-scenario.
-Both functions set corresponding flags according to the parameters and
-invoke static function ``has_access_to_region()`` to execute the check process.
-Both implementations should be placed in multi-core topology specific files
-separated from single Armv8-M access check.
-
-A reference code of ``tfm_core_has_read_access_to_region()`` implementation is
-shown below.
-
-.. code-block:: c
-
- int32_t tfm_core_has_read_access_to_region(const void *p, size_t s,
- bool ns_caller,
- uint32_t privileged)
- {
- uint8_t flags = MEM_CHECK_MPU_READ;
-
- if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) {
- flags |= MEM_CHECK_MPU_UNPRIV;
- }
-
- if (ns_caller) {
- flags |= MEM_CHECK_NONSECURE;
- }
-
- return has_access_to_region(p, s, flags);
- }
-
-
-A reference code of ``tfm_core_has_write_access_to_region()`` implementation is
-shown below.
-
-.. code-block:: c
-
- int32_t tfm_core_has_write_access_to_region(void *p, size_t s,
- bool ns_caller,
- uint32_t privileged)
- {
- uint8_t flags = MEM_CHECK_MPU_READWRITE;
-
- if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) {
- flags |= MEM_CHECK_MPU_UNPRIV;
- }
-
- if (ns_caller) {
- flags |= MEM_CHECK_NONSECURE;
- }
-
- return has_access_to_region(p, s, flags);
- }
-
-
-The flags ``MEM_CHECK_MPU_READ``, ``MEM_CHECK_MPU_UNPRIV``,
-``MEM_CHECK_MPU_READWRITE`` and ``MEM_CHECK_NONSECURE`` above will be described
-in the section `Access Permission Flags`_.
-
-The prototype of static function ``has_access_to_region()`` follows that in
-single Armv8-M. The multi-core topology specific ``has_access_to_region()``
-executes a general process to check if the access can access the target region.
-
-During the check process, ``has_access_to_region()`` invokes three HAL APIs
-``tfm_spm_hal_get_mem_security_attr()``, ``tfm_spm_hal_get_ns_access_attr()``
-and ``tfm_spm_hal_get_secure_access_attr()`` to retrieve the attributes of
-target memory region. ``has_access_to_region()`` compares the access permission
-with memory region attributes and determines whether the access is allowed to
-access the region according to policy described in `Memory Access Check Policy`_
-above.
-
-| ``tfm_spm_hal_get_mem_security_attr()`` retrieves the security attributes of
- the target memory region.
-| ``tfm_spm_hal_get_secure_access_attr()`` retrieves secure access attributes of
- the target memory region.
-| ``tfm_spm_hal_get_ns_access_attr()`` retrieves non-secure access attributes of
- the target memory region.
-| All three functions are implemented by multi-core platform support. The
- definitions are specified in the section `HAL APIs`_ below.
-
-The pseudo code of ``has_access_to_region()`` is shown below.
-
-.. code-block:: c
- :linenos:
- :emphasize-lines: 19,36,46
-
- static int32_t has_access_to_region(const void *p, size_t s, uint8_t flags)
- {
- struct security_attr_info_t security_attr;
- struct mem_attr_info_t mem_attr;
-
- /* The memory access check should be executed inside TF-M PSA RoT */
- if (not in privileged level) {
- abort;
- }
-
- if (memory region exceeds memory space limitation) {
- return TFM_ERROR_GENERIC;
- }
-
- /* Set initial value */
- security_attr_init(&security_attr);
-
- /* Retrieve security attributes of memory region */
- tfm_spm_hal_get_mem_security_attr(p, s, &security_attr);
-
- if (!security_attr.is_valid) {
- /* Invalid memory region */
- return TFM_ERROR_GENERIC;
- }
-
- /* Compare according to current Isolation Level */
- if (Parameter flags mismatch security attributes) {
- return TFM_ERROR_GENERIC;
- }
-
- /* Set initial value */
- mem_attr_init(&mem_attr);
-
- if (security_attr.is_secure) {
- /* Retrieve access attributes of secure memory region */
- tfm_spm_hal_get_secure_access_attr(p, s, &mem_attr);
-
- if (Not in Isolation Level 1) {
- /* Secure MPU must be enabled in Isolation Level 2 and 3 */
- if (!mem_attr->is_mpu_enabled) {
- abort;
- }
- }
- } else {
- /* Retrieve access attributes of non-secure memory region. */
- tfm_spm_hal_get_ns_access_attr(p, s, &mem_attr);
- }
-
- if (!mem_attr.is_valid) {
- /* Invalid memory region */
- return TFM_ERROR_GENERIC;
- }
-
- /*
- * Compare according to current Isolation Level and non-secure/secure
- * access.
- */
- if (access flags matches MPU attributes) {
- return TFM_SUCCESS;
- }
-
- return TFM_ERROR_GENERIC;
- }
-
-.. note::
- It cannot be guaranteed that TF-M provides a comprehensive memory access
- check on non-secure memory for NSPE client call If non-secure memory
- protection or isolation is required in a multi-core system, NSPE software
- should implement and execute the check functionalities in NSPE, rather than
- relying on TF-M access check.
-
- For example, all the access from NSPE client calls to non-secure memory are
- classified as unprivileged in current TF-M implementation. Multi-core access
- check may skip the privileged/unprivileged permission check for non-secure
- access.
-
- If a multi-core system enforces the privileged/unprivileged isolation and
- protection of non-secure area, NSPE software should execute the corresponding
- check functionalities before submitting the NSPE client call request to SPE.
-
-
-*******************
-Data Types and APIs
-*******************
-
-Data Types
-==========
-
-Access Permission Flags
------------------------
-
-The following flags are defined to indicate the access permission attributes.
-Each flag is mapped to the corresponding CMSE macro. Please refer to
-`ARMv8-M Security Extensions: Requirements on Development Tools
-`_
-for details of each CMSE macro.
-
-``MEM_CHECK_MPU_READWRITE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Mapped to CMSE macro ``CMSE_MPU_READWRITE`` to indicate that the access requires
-both read and write permission to the target memory region.
-
-.. code-block:: c
-
- #define MEM_CHECK_MPU_READWRITE (1 << 0x0)
-
-
-``MEM_CHECK_MPU_UNPRIV``
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Mapped to CMSE macro ``CMSE_MPU_UNPRIV`` to indicate that it is an unprivileged
-access.
-
-.. code-block:: c
-
- #define MEM_CHECK_MPU_UNPRIV (1 << 0x2)
-
-
-``MEM_CHECK_MPU_READ``
-^^^^^^^^^^^^^^^^^^^^^^
-
-Mapped to CMSE macro ``CMSE_MPU_READ``. It indicates that it is a read-only
-access to target memory region.
-
-.. code-block:: c
-
- #define MEM_CHECK_MPU_READ (1 << 0x3)
-
-
-``MEM_CHECK_NONSECURE``
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Mapped to CSME macro ``CMSE_NONSECURE`` to indicate that it is a access from
-non-secure client call request.
-If this flag is unset, it indicates the access is required from SPE.
-
-.. code-block:: c
-
- #define MEM_CHECK_AU_NONSECURE (1 << 0x1)
- #define MEM_CHECK_MPU_NONSECURE (1 << 0x4)
- #define MEM_CHECK_NONSECURE (MEM_CHECK_AU_NONSECURE | \
- MEM_CHECK_MPU_NONSECURE)
-
-
-Security Attributes Information
--------------------------------
-
-The structure ``security_attr_info_t`` contains the security attributes
-information of the target memory region.
-``tfm_spm_hal_get_mem_security_attr()`` implementation should fill the structure
-fields according to the platform specific secure isolation setting.
-
-.. code-block:: c
-
- struct security_attr_info_t {
- bool is_valid;
- bool is_secure;
- };
-
-| ``is_valid`` indicates whether the target memory region is valid according to
- platform resource assignment and security isolation configurations.
-| ``is_secure`` indicates the target memory region is secure or non-secure. The
- value is only valid when ``is_valid`` is ``true``.
-
-
-Memory Attributes Information
------------------------------
-
-The structure ``mem_attr_info_t`` contains the memory access attributes
-information of the target memory region.
-``tfm_spm_hal_get_secure_access_attr()`` and
-``tfm_spm_hal_get_ns_access_attr()`` implementations should fill the structure
-fields according to the memory protection settings.
-
-.. code-block:: c
-
- struct mem_attr_info_t {
- bool is_mpu_enabled;
- bool is_valid;
- bool is_xn;
- bool is_priv_rd_allow;
- bool is_priv_wr_allow;
- bool is_unpriv_rd_allow;
- bool is_unpriv_wr_allow;
- };
-
-| ``is_mpu_enabled`` indicates whether the MPU and other management unit are
- enabled and work normally.
-| ``is_valid`` indicates whether the target memory region is valid according to
- platform resource assignment and memory protection configurations.
-| ``is_xn`` indicates whether the target memory region is Execute Never. This
- field is only valid when ``is_valid`` is ``true``.
-| ``is_priv_rd_allow`` and ``is_priv_wr_allow`` indicates whether the target
- memory region allows privileged read/write. Both the fields are valid only
- when ``is_valid`` is ``true``.
-| ``is_unpriv_rd_allow`` and ``is_unpriv_wr_allow`` indicates whether the target
- memory region allows unprivileged read/write. Both the fields are valid only
- when ``is_valid`` is ``true``.
-
-
-HAL APIs
-========
-
-``tfm_spm_hal_get_mem_security_attr()``
----------------------------------------
-
-``tfm_spm_hal_get_mem_security_attr()`` retrieves the current active security
-configuration information and fills the ``security_attr_info_t``.
-
-.. code-block:: c
-
- void tfm_spm_hal_get_mem_security_attr(const void *p, size_t s,
- struct security_attr_info_t *p_attr);
-
-+--------------------------------------------------------------------+
-|**Paramters** |
-+-------------+------------------------------------------------------+
-|``p`` |Base address of the target memory region |
-+-------------+------------------------------------------------------+
-|``s`` |Size of the target memory region |
-+-------------+------------------------------------------------------+
-|``p_attr`` |Pointer to the ``security_attr_info_t`` to be filled |
-+-------------+------------------------------------------------------+
-|**Return** |
-+-------------+------------------------------------------------------+
-|``void`` |None |
-+-------------+------------------------------------------------------+
-
-The implementation should be decoupled from TF-M current isolation level or
-access check policy.
-
-All the fields in ``security_attr_info_t`` should be explicitly set in
-``tfm_spm_hal_get_mem_security_attr()``.
-
-If the target memory region crosses boundaries of different security regions or
-levels in security isolation configuration,
-``tfm_spm_hal_get_mem_security_attr()`` should determine whether the memory
-region violates current security isolation.
-It is recommended to mark the target memory region as invalid in such case, even
-if the adjoining regions or levels may have the same security configuration.
-
-If the target memory region is not explicitly specified in memory security
-configuration, ``tfm_spm_hal_get_mem_security_attr()`` can return the following
-values according to actual use case:
-
-- Either set ``is_valid = false``
-- Or set ``is_valid = true`` and set ``is_secure`` according to platform
- specific policy.
-
-
-``tfm_spm_hal_get_secure_access_attr()``
-----------------------------------------
-
-``tfm_spm_hal_get_secure_access_attr()`` retrieves the secure memory protection
-configuration information and fills the ``mem_attr_info_t``.
-
-.. code-block:: c
-
- void tfm_spm_hal_get_secure_access_attr(const void *p, size_t s,
- struct mem_attr_info_t *p_attr);
-
-+--------------------------------------------------------------------+
-|**Paramters** |
-+-------------+------------------------------------------------------+
-|``p`` |Base address of the target memory region |
-+-------------+------------------------------------------------------+
-|``s`` |Size of the target memory region |
-+-------------+------------------------------------------------------+
-|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled |
-+-------------+------------------------------------------------------+
-|**Return** |
-+-------------+------------------------------------------------------+
-|``void`` |None |
-+-------------+------------------------------------------------------+
-
-The implementation should be decoupled from TF-M current isolation level or
-access check policy.
-
-All the fields in ``mem_attr_info_t`` should be explicitly set in
-``tfm_spm_hal_get_secure_access_attr()``, according to current active memory
-protection configuration. It is recommended to retrieve the attributes from
-secure MPU and other hardware memory protection unit(s). But the implementation
-can be simplified by checking system-level memory region layout setting.
-
-If the target memory region is not specified in current active secure memory
-protection configuration, ``tfm_spm_hal_get_secure_access_attr()`` can select
-the following values according to actual use case.
-
-- Either directly set ``is_valid`` to ``false``
-- Or set ``is_valid`` to ``true`` and set other fields according to other memory
- assignment information, such as system-level memory region layout.
-
-If secure memory protection unit(s) is *disabled* and the target memory
-region is a valid area according to platform resource assignment,
-``tfm_spm_hal_get_secure_access_attr()`` must set ``is_mpu_enabled`` to
-``false`` and set other fields according to current system-level memory region
-layout.
-
-
-``tfm_spm_hal_get_ns_access_attr()``
-------------------------------------
-
-``tfm_spm_hal_get_ns_access_attr()`` retrieves the non-secure memory protection
-configuration information and fills the ``mem_attr_info_t``.
-
-.. code-block:: c
-
- void tfm_spm_hal_get_ns_access_attr(const void *p, size_t s,
- struct mem_attr_info_t *p_attr);
-
-+--------------------------------------------------------------------+
-|**Paramters** |
-+-------------+------------------------------------------------------+
-|``p`` |Base address of the target memory region |
-+-------------+------------------------------------------------------+
-|``s`` |Size of the target memory region |
-+-------------+------------------------------------------------------+
-|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled |
-+-------------+------------------------------------------------------+
-|**Return** |
-+-------------+------------------------------------------------------+
-|``void`` |None |
-+-------------+------------------------------------------------------+
-
-The implementation should be decoupled from TF-M current isolation level or
-access check policy.
-
-Since non-secure core runs asynchronously, the non-secure MPU setting may be
-modified by NSPE OS and the attributes of the target memory region can be
-unavailable during ``tfm_spm_hal_get_ns_access_attr()`` execution in TF-M.
-When the target memory region is not specified in non-secure MPU,
-``tfm_spm_hal_get_ns_access_attr()`` can set the fields according to other
-memory setting information, such as system-level memory region layout.
-
-If non-secure memory protection unit(s) is *disabled* and the target memory
-region is a valid area according to platform resource assignment,
-``tfm_spm_hal_get_ns_access_attr()`` can set the following fields in
-``mem_attr_info_t`` to default values:
-
-- ``is_mpu_enabled = false``
-- ``is_valid = true``
-- ``is_xn = true``
-- ``is_priv_rd_allow = true``
-- ``is_unpriv_rd_allow = true``
-
-``is_priv_wr_allow`` and ``is_unpriv_wr_allow`` can be set according to current
-system-level memory region layout, such as whether it is in code section or data
-section.
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/enum_implicit_casting.rst b/docs/design_documents/enum_implicit_casting.rst
deleted file mode 100644
index 01c8ce73f0..0000000000
--- a/docs/design_documents/enum_implicit_casting.rst
+++ /dev/null
@@ -1,190 +0,0 @@
-################################################
-Fixing implicit casting for C enumeration values
-################################################
-
-:Authors: Hugues de Valon
-:Organization: Arm Limited
-:Contact: hugues.devalon@arm.com
-:Status: Accepted
-
-********
-Abstract
-********
-
-C enumerations provide a nice way to increase readability by creating new
-enumerated types but the developer should take extra care when mixing
-enumeration and integer values.
-This document investigates C enumerations safety and proposes strategies on how
-to fix the implicit casting of the enumeration values of TF-M with other types.
-
-**************************
-C99 Standard point of view
-**************************
-
-In TF-M many implicit casts are done between integer types (``uint32_t``,
-``int32_t``, ``size_t``, etc), enumerated types (``enum foobar``) and
-enumeration constants (``FOOBAR_ENUM_1``).
-
-According to the C99 standard [1]_:
-
- **§6.2.5, 16**:
- An enumeration comprises a set of named integer constant values. Each
- distinct enumeration constitutes a different numerated type.
-
- **§6.7.2.2, 2**:
- The expression that defines the value of an enumeration constant shall be an
- integer constant expression that has a value representable as an int.
-
- **§6.7.2.2, 3**:
- The identifiers in an enumerator list are declared as constants that have
- type int and may appear wherever such are permitted.
-
- **§6.7.2.2, 4**:
- Each enumerated type shall be compatible with char, a signed integer type,
- or an unsigned integer type. The choice of type is implementation-defined,
- but shall be capable of representing the values of all the members of the
- enumeration.
-
-From these four quotes from the C99 standard [1]_, the following conclusions can
-be made:
-
-* an enumeration defines a new type and should be treated as such
-* the enumeration constants must only contains value representable as an ``int``
-* the enumeration constants have type ``int``
-* the actual type of the enumeration can be between ``char``, signed and
- unsigned ``int``. The compiler chooses the type it wants among those that can
- represent all declared constants of the enumeration.
-
-Example::
-
- enum french_cities {
- MARSEILLE,
- PARIS,
- LILLE,
- LYON
- };
-
-In that example, ``MARSEILLE``, ``PARIS``, ``LILLE`` and ``LYON`` are
-enumeration constants of type ``int`` and ``enum french_cities`` is a enumerated
-type which can be of actual type ``char``, ``unsigned int`` or ``int``
-(the compiler chooses!).
-
-For these reasons, doing an implicit cast between an enumeration and another
-type is the same as doing an implicit cast between two different types. From a
-defensive programming point of view, it should be checked that the destination
-type can represent the values from the origin type. In this specific case it
-means four things for enumerations:
-
-* it is always safe to assign an enumeration constant to an int, but might be
- better to cast to show intent.
-* when casting an enumeration constant to another type, it should be checked
- that the constant can fit into the destination type.
-* when casting from an integer type (``uint32_t``, ``int32_t``, etc) to an
- enumeration type, it should be checked that the integer's value is one of the
- enumeration constants. The comparison needs to be done on the biggest type of
- the two so that no information is lost. C integer promotion should
- automatically do that for the programmer (check §6.3.1.8, 1 for the rules).
-* when casting from an enumeration type to an integer type, it should be checked
- that the enumeration type value fits into the integer type. The value of a
- variable which has the type of an enumeration type is not limited to the
- enumeration constants of the type. An enumeration constant will always fit
- into an ``int``.
-
-*****************
-Strategies to fix
-*****************
-
-0. Replace the enumerated type with an integer type and replace the enumeration
- constant with preprocessor constants.
-1. Whenever possible, try to use matching types to avoid implicit casting.
- It happens, for example, for arithmetic operations, function calls and
- function returns. This strategy always have the lowest performance impact.
-2. When using an enumeration constant in an arithmetic operation with another
- type, verify that the constant can fit in the other type and cast it.
-3. When converting an integer to an enumeration type, use a conversion function
- to check if the integer matches an enumeration constant. To not impact
- performance too much, this function should be an inline function. If it does
- not match, use (or add) the error constant or return an error value.
-4. When converting an enumeration type to an integer, use a conversion function
- to check that the integer type can contain the enumeration value.
-
-************************
-Design proposal for TF-M
-************************
-
-In TF-M, an action will be taken for all enumerated types and enumeration
-constants that are used for implicit casting. The goal of this proposal is to
-remove all implicit casting of enumeration values in TF-M.
-
-The following enumerated types will be removed and replaced with preprocessor
-constants (strategy 0). These enumerated types are not used in TF-M
-but only the constants they declare.
-
-* ``enum spm_part_state_t``
-* ``enum spm_part_flag_mask_t``
-* ``enum tfm_partition_priority``
-
-The following enumerated types will be kept because they are used in the
-prototypes of functions and are useful for debugging. Whenever possible,
-strategy 1 will be applied to remove implicit casting related with those
-enumerations but dynamic conversions will be used if the first option would
-create too much change in the code base.
-
-* ``enum tfm_status_e``: the return type of the following functions will be
- changed to return the ``enum tfm_status_e`` type. These functions are already
- returning the enumeration constants, but implicitly casted to an integer type
- like ``int32_t``.
-
- * ``int32_t check_address_range``
- * ``int32_t has_access_to_region``
- * ``int32_t tfm_core_check_sfn_parameters``
- * ``int32_t tfm_start_partition``
- * ``int32_t tfm_return_from_partition``
- * ``int32_t tfm_check_sfn_req_integrity``
- * ``int32_t tfm_core_check_sfn_req_rules``
- * ``int32_t tfm_spm_sfn_request_handler``
- * ``int32_t tfm_spm_sfn_request_thread_mode``
-* ``enum tfm_buffer_share_region_e``: the following function prototypes will be
- changed:
-
- * ``tfm_spm_partition_set_share(uint32_t partition_idx, uint32_t share)`` -> ``tfm_spm_partition_set_share(uint32_t partition_idx, enum tfm_buffer_share_region_e share)``
-* ``enum tfm_memory_access_e``
-* ``enum attest_memory_access_t``
-* ``enum engine_cipher_mode_t``
-* ``mbedtls_cipher_type_t``
-
-The following enumerated types are used for error code values of Secure service
-calls. They should be kept as they are part of the interface and might be used
-by external parties in Non-Secure code. For the Initial Attestation service,
-the enumeration is defined in the PSA Attestation API specifications.
-
-* ``enum psa_attest_err_t``
-* ``enum psa_audit_err``
-* ``enum tfm_platform_err_t``
-
-Implicit casting related with these enumerations is happening in two locations
-of TF-M and need conversion functions in those locations, because the types can
-not be changed:
-
-* In the Non-Secure Client library, all of the Secure Service functions
- implicitly cast the ``uint32_t`` returned by ``tfm_ns_lock_dispatch`` to
- these enumerated types. Strategy 3 is needed here.
-* In all of the veneer functions, there is an implicit cast from the ``int32_t``
- value returned by the SVC request function (``tfm_core_*_request``) to these
- enumerated types. Strategy 3 is needed here as well. The implicit cast will
- eventually be removed if all of the services are using the Uniform Signatures
- Prototypes so that the veneer functions all return ``psa_status_t`` which is
- an ``int32_t``.
-
-If the interface of those services can be changed, these enumerations could be
-removed and replaced with the ``psa_status_t`` type to remove the implicit
-casting.
-
-.. [1] C99 standard: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf
-
-
---------------
-
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
-
diff --git a/docs/design_documents/ff_isolation.rst b/docs/design_documents/ff_isolation.rst
deleted file mode 100644
index b60b03eb2d..0000000000
--- a/docs/design_documents/ff_isolation.rst
+++ /dev/null
@@ -1,401 +0,0 @@
-##############
-FF-M Isolation
-##############
-
-:Organization: Arm Limited
-:Contact: tf-m@lists.trustedfirmware.org
-
-This document analyzes the isolation rules of implementing ``FF-M 1.0``
-isolation and introduces the reference implementation in TF-M, which
-complies the rules by operating the hardware and software resources.
-
-.. note::
- Reference the document :doc:`Glossary ` for terms
- and abbreviations.
-
-************
-Introduction
-************
-This chapter describes the definitions from ``FF-M`` and analyzes
-the possible implementation keypoints.
-
-Isolation Levels
-================
-There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level
-number has more isolation boundaries.
-
-The definition for Isolation Level 1:
-
-- L1.1 NPSE needs protection from nobody.
-- L1.2 SPE needs protection from NSPE.
-
-The definition for Isolation Level 2:
-
-- L2.1 NPSE needs protection from nobody.
-- L2.2 Application Root of Trust (ARoT) needs protection from NSPE.
-- L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT.
-
-The definition for Isolation Level 3:
-
-- L3.1 NPSE needs protection from nobody.
-- L3.2 Secure Partition needs protection from NSPE and other Secure Partitions.
-- L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure
- Partitions.
-
-.. important::
- The PSA RoT Services can be implemented directly within the SPM, or as RoT
- Services within one or more PSA RoT Secure Partitions. But if the PSA RoT
- Services needs to be accessed by NSPE or Application RoT of Trust Services
- must be implemented in a Secure Partitions (Please refer to chapter 2.4 -
- "RoT Services" of `PSA Firmware_Framework for M`_).
- The implementation in this design treats the PSA RoT Secure Partition in the
- PSA RoT domain to follow `L3.3` above and relax `L3.2` for PSA RoT Secure
- Partition under isolation level 3.
-
-Isolation Rules
-===============
-The essence of isolation is to protect the assets of one protection domain from
-being accessed from other domains. The isolation levels define where the
-isolation boundaries should be placed, the isolation rules define the strength
-of the isolation the boundaries should offer.
-
-.. note::
- In general, assets include not only ROM/RAM and peripherals. For the detail
- information about the memory assets and peripheral, please
- refer to `PSA Firmware_Framework for M`_.
-
-Memory Asset Class
-------------------
-There are 3 memory asset classes defined in `PSA Firmware_Framework for M`_:
-
-- Code
-- Constant data
-- Private data
-
-There are 6 isolation rules for protecting assets. Here lists the simplified
-description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the
-original description:
-
-- I1. Only Code is executable.
-- I2. Only private data is writable.
-- I3. If domain A needs protection from domain B, then Private data in domain A
- cannot be accessed by domain B.
-- I4. (Optional) If domain A needs protection from domain B, then Code and
- Constant data in domain A is not readable or executable by domain B.
-- I5. (Optional) Code in a domain is not executable by any other domain.
-- I6. (Optional) All assets in a domain are private to that domain and cannot be
- accessed by any other domain, with the following exception:
- The domain containing the SPM can only access Private data and Constant data
- assets of other domains when required to implement the PSA Firmware Framework
- API.
-
- The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply
- the isolation, while ``I4`` to ``I6`` are optional rules to enhance the
- isolation boundaries.
-
- .. important::
- There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists
- the asset types and allowed access method. Preventing executable access on
- constant data costs more hardware resources, so the requirement in the table
- about constant data can be regarded as a recommendation instead of a
- mandatory item under some hardware resource-constrained cases.
-
-Hardware Infrastructure
-=======================
-To implement a secure system, the hardware security framework (TrustZone or
-multiple-core e.g.) and their auxiliary components (SAU e.g.) are required
-to ensure the isolation between SPE and NSPE. The requirements:
-
-.. important::
- The interface between secure and non-secure states needs to be fully
- enumerated and audited to prove the integrity of the secure state
- isolation.
-
-Besides this SPE and NSPE isolation mechanism, the following analyzes the
-implementation rules to find out the hardware requirements for isolation inside
-SPE domains:
-
-- I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each
- type has the specific access rules.
-- I3: The private data access from the prevented domain needs to be blocked.
-- I4: All the assets access from the prevented domain needs to be blocked.
-- I5: Code execution from all other domains (even the domain not prevented
- from) needs to be blocked.
-- I6: All the assets access from all other domains (includes non-prevented
- domain) needs to be blocked, but, SPM is an exception, which can access the
- private data and constant data of the current domain.
-
-The above items list the requirements for memory access, here are two more
-points:
-
-- If the memory device or the peripheral are shared between multiple hosts
- (Such as multiple CPU or DMA, etc), specific hardware protection units need
- to be available for validating accesses to that device or peripheral.
-- The MMIO range for Secure Partitions is not allowed to be overlapped, which
- means each partition should have exclusive memory-mapped region if they
- require a peripheral device. The memory-mapped region is regarded as
- the private data so access to this area needs to be validated.
-
-************************
-Reference Implementation
-************************
-This chapter describes the isolation implementation inside SPE by using the
-Armv8m architecture component - Memory Protection Unit (MPU). The MPU can
-isolate CPU execution and data access.
-
-.. note::
- Previous version M-profile architecture MPU setting is similar in concept but
- the difference in practical register formats, which is not described in this
- document.
-
-The MPU protects memory assets by regions. Each region represents a memory
-range with specific access attributes.
-
-.. note::
- The maximum numbers of MPU regions are platform-specific.
-
-The SPM is running under the privileged mode for handling access from services.
-The MPU region for SPM needs to be available all the time since SPM controls
-the MPU setting while scheduling.
-
-Since partitions are scheduled by SPM, the MPU regions corresponding to the
-partitions can be configured dynamically while scheduling. Since there is only
-one running at a time and all others are deactivated, the SPM needs to set up
-necessary regions for each asset type in one partition only.
-
-There is re-usable code like the C-Runtime and RoT Service API which are same
-across different partitions. TF-M creates a Secure Partition Runtime Library
-(SPRTL) as a specific library shared by the Secure Partition. Please refer to
-:doc:`Secure Partition Runtime Library `
-for more detail.
-
-.. note::
- Enable SPRTL makes it hard to comply with the rules I4, I5 and I6,
- duplicating the library code can be one solution but it is not "shared"
- library anymore.
-
-As mentioned in the last chapter, MMIO needs extra MPU regions as private data.
-
-MPU Region Access Permission
-============================
-The following content would mention the memory access permission to represent
-the corresponded asset classes.
-
-These access permissions are available on Armv8m MPU:
-
-- Privileged Read-Only (RO)
-- All RO
-- Privileged Read-Write (RW)
-- All RW
-- Execution Never (XN)
-
-And one more Armv8.1M access permssion:
-
-- Privileged Execution Never (PXN)
-
-The available regions type list:
-
-======== =========== =============== ========================================
-Type Attributes Privilege Level Asset
-======== =========== =============== ========================================
-P_RO RO Privileged PRoT Code
-P_ROXN RO + XN Privileged PRoT Constant Data
-P_RWXN RW + XN Privileged PRoT Private Data/Peripheral
-A_RO RO Any privilege Partition/SPRTL Code
-A_ROXN RO + XN Any privilege Partition/SPRTL Constant Data
-A_RWXN RW + XN Any privilege Partition/SPRTL Private Data/Peripheral
-A_ROPXN RO + PXN Any privilege Armv8.1M Partition/SPRTL Code
-======== =========== =============== ========================================
-
-Example Image Layout
-====================
-The secure firmware image contains components such as partitions, SPM and the
-shared code and data. Each component may have different class assets. There
-would be advantages if placing the assets from all components with the same
-access attributes into one same region:
-
-- The data relocating or clearing when booting can be done in one step instead
- of breaking into fragments.
-- Assets with statically assigned access attribute can share the same MPU
- region which saves regions.
-
-Take the TF-M existing implementation image layout as an example::
-
- Level 1 Level 2 Level 3
- Boundaries Boundaries Boundaries
- +------------+----------+------------------------------------+
- | | | PRoT SPM Code |
- | | PRoT +------------------------------------+
- | | Code | PRoT Service Code |
- | Code +----------+------------------------------------+
- | (ROM) | | Partition 1 Code |
- | | +------------------------------------+
- | | ARoT | Partition N Code |
- | | Code +------------------------------------+
- | | | SPRTL Code |
- +------------+----------+------------------------------------+
- Check [4] for more details between Code and Constant Data.
- +------------+----------+------------------------------------+
- | | PRoT | PRoT SPM Constant Data |
- | | Constant +------------------------------------+
- | | Data | PRoT Service Constant Data |
- | Constant +----------+------------------------------------+
- | Data | ARoT | Partition 1 Constant Data |
- | (ROM) | Constant +------------------------------------+
- | | Data | Partition N Constant Data |
- | | +------------------------------------+
- | | | SPRTL Constant Data |
- +------------+----------+------------------------------------+
-
- +------------+----------+------------------------------------+
- | | PRoT | PRoT SPM Private Data |
- | | Private +------------------------------------+
- | | Data | PRoT Service Private Data |
- | Private +----------+------------------------------------+
- | Data | | Partition 1 Private Data |
- | (RAM) | ARoT +------------------------------------+
- | | Private | Partition N Private Data |
- | | Data +------------------------------------+
- | | | SPRTL Private Data |
- +------------+----------+------------------------------------+
-
-.. note::
- 1. Multiple binaries image implementation could also reference this layout if
- its hardware protection unit can cover the exact boundaries mentioned
- above.
- 2. Private data includes both initialized and non-initialized (ZI) sections.
- Check chapter ``3.1.1`` of ``FF-M`` for the details.
- 3. This diagram shows the boundaries but not orders. The order of regions
- inside one upper region can be adjusted freely.
- 4. As described in the ``important`` of `Memory Asset Class`_, the setting
- between Code and Constant Data can be skipped if the executable access
- method is not applied to constant data. In this case, the groups of Code
- and Constant Data can be combined or even mixed -- but the boundary
- between PRoT and ARoT are still required under level higher than 1.
-
-Example Region Numbers under Isolation Level 3
-==============================================
-The following table lists the required regions while complying the rules for
-implementing isolation level 3. The level 1 and level 2 can be exported by
-simplifying the items in level 3 table.
-
-.. important::
- The table described below is trying to be shared between all supported
- platforms in Trusted Firmware - M. It is obvious that some platforms have
- special characteristics. In that case, the specific layout table for a
- particular platform can be totally redesigned but need to fulfil the
- isolation level requirements.
-
-- Care only the running partitions assets since deactivated partition does not
- need regions.
-- `X` indicates the existence of this region can't comply with the rule.
-- An `ATTR + n` represent extra ``n`` regions are necessary.
-- Here assumes the rules with a greater number covers the requirements in the
- rules with less number.
-
-Here lists the required regions while complying with the rules:
-
-+------------------+-------------+-------------+-------------+-------------+
-| Region Purpose | I1 I2 I3 | I4 | I5 | I6 |
-+==================+=============+=============+=============+=============+
-| PRoT SPM Code | A_RO | P_RO | P_RO | P_RO |
-+------------------+ | | +-------------+
-| PRoT Service Code| | | | A_ROPXN |
-+------------------+ +-------------+-------------+ |
-| Active Partition | | A_RO | A_ROPXN | |
-| Code | | | | |
-+------------------+ +-------------+-------------+-------------+
-| SPRTL Code | | ``X`` | ``X`` | ``X`` |
-+------------------+-------------+-------------+-------------+-------------+
-| PRoT SPM RO | A_ROXN | P_ROXN | P_ROXN | P_ROXN |
-+------------------+ | | +-------------+
-| PRoT Service RO | | | | A_ROXN |
-+------------------+ +-------------+-------------+ |
-| Active Partition | | A_ROXN | A_ROXN | |
-| RO | | | | |
-+------------------+ +-------------+-------------+-------------+
-| SPRTL RO | | ``X`` | ``X`` | ``X`` |
-+------------------+-------------+-------------+-------------+-------------+
-| PRoT SPM RW | P_RWXN | P_RWXN | P_RWXN | P_RWXN |
-+------------------+ | | +-------------+
-| PRoT Service RW | | | | A_RWXN |
-+------------------+-------------+-------------+-------------+ |
-| Active Partition | A_RWXN | A_RWXN | A_RWXN | |
-| RW | | | | |
-+------------------+-------------+-------------+-------------+-------------+
-| SPRTL RW [5] | A_RWXN + 1 | ``X`` | ``X`` | ``X`` |
-+------------------+-------------+-------------+-------------+-------------+
-| Partition Peri | A_RWXN + n | A_RWXN + n | A_RWXN + n | A_RWXN + n |
-+------------------+-------------+-------------+-------------+-------------+
-| Total Numbers | [1] | [2] | [3] | [4] |
-+------------------+-------------+-------------+-------------+-------------+
-
-.. note::
- 1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while
- n equals the maximum peripheral numbers needed by one partition. This is
- the configuration chosen by the reference implementation.
- 2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN,
- the minimal result is `6`, and SPRTL can not be applied.
- 3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
- A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
- is required.
- 4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
- A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
- is required. To comply with this rule, the PSA RoT Service needs
- to be implemented as Secure Partitions.
- 5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM
- can update this region with the activate partition's metadata for
- implementing functions with owner SP's context, such as heap functions.
- This region can be skipped if there is no metadata required (such as no
- heap functionalities required).
-
- The memory-mapped regions for peripherals have different memory access
- attributes in general, they are standalone regions in MPU even their
- attributes covers 'A_RWXN'.
-
-.. important::
- The default memory map is not involved in this example, because it grants PSA
- RoT domain program (especially SPM) the ability to access the place not
- covered in an explicitly defined region. In a system lack of enough MPU
- regions, the default memory map can be applied, in this case, the whole image
- layout needs to be audited to find out if the uncovered region contains
- garbage or gadget data which could provide an attack.
-
-Interfaces
-==========
-The isolation implementation is based on the HAL framework. The SPM relies on
-the HAL API to perform the necessary isolation related operations.
-
-The requirement the software need to do are these:
-
-- Create enough isolation protection at the early stage of system booting, just
- need to focus on the SPM domain.
-- Create an isolation domain between secure and non-secure before the jump to
- the non-secure world.
-- Create an isolation domain for each Secure Partition after the Secure
- Partition is loaded and before jumping to its entry point. The isolation
- domain should cover all the assets of the Secure Partition, include all its
- memory, interrupts, and peripherals.
-- Switch isolation domains when scheduling different Secure Partitions.
-- It is also a requirement that the platform needs to help to check if the
- caller of the PSA APIs is permitted to access some memory ranges.
-
-
-The design document
-:doc:`TF-M Hardware Abstraction Layer `
-gives a detail design, include the platform initialization, isolation
-interfaces. Please refer to it for more detail.
-
-Appendix
-========
-| `PSA Firmware_Framework for M`_
-
-.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html
-
-| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_
-
-.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/hardware_abstraction_layer.rst b/docs/design_documents/hardware_abstraction_layer.rst
deleted file mode 100644
index 588e5faad1..0000000000
--- a/docs/design_documents/hardware_abstraction_layer.rst
+++ /dev/null
@@ -1,671 +0,0 @@
-##########################
-Hardware Abstraction Layer
-##########################
-
-:Organization: Arm Limited
-:Contact: tf-m@lists.trustedfirmware.org
-
-:API Version: 0.9
-
-************
-Introduction
-************
-:term:`TF-M` :term:`HAL` abstracts the hardware-oriented and platform specific
-operations on the :term:`SPE` side and provides a set of APIs to the upper
-layers such as :term:`SPM`, :term:`RoT Service`.
-The :term:`HAL` aims to cover the platform different aspects whereas common
-architecturally defined aspects are done generically within the common
-:term:`SPE`.
-In some cases, although the operations are defined architecturally,
-it may not be possible to generalize implementations because lots of information
-is only known to platforms.
-It is more efficient to define a :term:`HAL` API for those architectural
-operations as well.
-
-.. note::
- :term:`TBSA-M` provides the hardware requirements for security purposes.
- :term:`TF-M` :term:`HAL` tries to reference :term:`TBSA-M` recommendations in
- the interfaces from the software perspective only. Please reference
- :term:`TBSA-M` for your security hardware design.
-
-Design Goals
-============
-:term:`TF-M` :term:`HAL` is designed to simplify the integration efforts on
-different platforms.
-
-:term:`TF-M` :term:`HAL` is designed to make it easy to use the hardware and
-develop the :term:`SPM` and :term:`RoT Service` which need to access the
-devices.
-
-:term:`TF-M` :term:`HAL` is designed to make the structure clearer and let the
-:term:`TF-M` mainly focus on :term:`PSA` implementation.
-
-********
-Overview
-********
-This section provides an overview of the abstraction layer structure.
-
-.. figure:: media/hal_structure.png
-
-Here lists a minimal set of necessary functionalities:
-
- - **Isolation API**: Provides the necessary isolation functionalities required
- by the :term:`PSA-FF-M` and :term:`TBSA-M`, and provides APIs to :term:`SPM`
- to check the permissions of memory access.
- - **Platform API**: Provides the platform initialization, platform-specific
- memory information, system reset, etc.
- - **Log dev API**: Provides the log system functions.
- - **Interrupt API**: Provides the interrupt functions.
-
-.. note::
- - There is a non-secure :term:`HAL` that focuses on the mailbox operation API
- for Dual-core topology. For more information about it, please refer to
- :doc:`Mailbox Design in TF-M on Dual-core System
- `.
- - The minimal set of :term:`TF-M` :term:`HAL` is sufficient for Secure
- Partitions by using customized peripheral interfaces. To provide easier
- portability for the Secure Partitions, a Secure Partition :term:`HAL` is
- provided in this design too.
- - The debug mechanisms give the external entity the corresponding right to
- access the system assets. :term:`TF-M` ensures that the external entity is
- permitted access to those assets. Currently, :term:`TF-M` only needs the
- debug authentication. The whole debug mechanism and related :term:`HAL` will
- be enhanced in the future. Please refer to the :doc:`Debug authentication
- settings section ` for more detail.
-
-*****************
-Design Principles
-*****************
-As :term:`TF-M` runs on resource-constrained devices, the :term:`HAL` tries to
-avoid multiple level abstractions which cost more resources.
-
-Part of the :term:`HAL` interfaces does not focus on exact hardware operations
-such as power on/off or PIN manipulation.
-Instead, the :term:`HAL` abstracts higher-level interfaces to reserve the
-implementation flexibility for the platform vendors.
-
-The :term:`TF-M` :term:`HAL` should be easy to deprecate APIs and provide
-compatibilities.
-Any API incompatibility should be detected during building.
-
-:term:`TF-M` relies on the :term:`HAL` APIs to be implemented correctly and
-trusts the :term:`HAL` APIs.
-:term:`TFM` can provide assertions to detect common programming errors but
-essentially no further extensive checks will be provided.
-
-************
-Source Files
-************
-This section describes the source file of the :term:`TF-M` :term:`HAL`,
-including the header and c files.
-
-tfm_hal_defs.h
-==============
-This header file contains the definitions of common macros and types used by all
-:term:`HAL` APIs. Please refer to `Status Codes`_ for detailed definitions.
-
-tfm_hal_[module].[h/c]
-======================
-All other headers and c files are classified by the modules, such as isolation,
-platform, interrupt, devices, etc.
-
-.. note::
- There are common files in the platform folder include the implemented
- :term:`HAL` APIs. The platform vendors can use them directly but need to
- implement all the sub APIs.
-
-************
-Status Codes
-************
-These are common status and error codes for all :term:`HAL` APIs.
-
-Types
-=====
-tfm_hal_status_t
-----------------
-This is a status code to be used as the return type of :term:`HAL` APIs.
-
-.. code-block:: c
-
- enum tfm_hal_status_t {
- TFM_HAL_ERROR_MEM_FAULT = SCHAR_MIN,
- TFM_HAL_ERROR_MAX_VALUE,
- TFM_HAL_ERROR_BAD_STATE,
- TFM_HAL_ERROR_NOT_SUPPORTED,
- TFM_HAL_ERROR_INVALID_INPUT,
- TFM_HAL_ERROR_NOT_INIT,
- TFM_HAL_ERROR_GENERIC,
- TFM_HAL_SUCCESS = 0
- };
-
-Error Codes
-===========
-Negative values indicate an error. Zero and positive values indicate success.
-
-Here is the general list. The detailed usages for each error code are described
-in the API introduction sections.
-
-TFM_HAL_SUCCESS
----------------
-Status code to indicate general success.
-
-TFM_HAL_ERROR_GENERIC
----------------------
-Status code to indicate an error that does not correspond to any defined failure
-cause.
-
-TFM_HAL_ERROR_NOT_INIT
-----------------------
-Status code to indicate that the module is not initialed.
-
-TFM_HAL_ERROR_INVALID_INPUT
----------------------------
-Status code to indicate that the input is invalid.
-
-TFM_HAL_ERROR_NOT_SUPPORTED
----------------------------
-Status code to indicate that the requested operation or a parameter is not
-supported.
-
-TFM_HAL_ERROR_BAD_STATE
------------------------
-Status code to indicate that the requested action cannot be performed in the
-current state.
-
-TFM_HAL_ERROR_MAX_VALUE
------------------------
-Status code to indicate that the current number has got the max value.
-
-TFM_HAL_ERROR_MEM_FAULT
------------------------
-Status code to indicate that the memory check failed.
-
-***************************
-API Definition for TF-M SPM
-***************************
-This section describes the APIs defined for :term:`TF-M` :term:`SPM`.
-
-Platform API
-============
-The platform API is a higher-level abstraction layer of the platform, other than
-a dedicated API set for the special hardware devices.
-
-APIs
-----
-tfm_hal_platform_init()
-^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- enum tfm_hal_status_t tfm_hal_platform_init(void)
-
-**Description**
-
-This API performs the platform-specific initialization.
-
-This API is called after architecture and platform common initialization has
-finished during system early startup.
-
-**Parameter**
-
-- ``void`` - None.
-
-**Return Values**
-
-- ``TFM_HAL_SUCCESS`` - Init success.
-- ``TFM_HAL_ERROR_GENERIC`` - Generic errors.
-
-tfm_hal_system_reset()
-^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- void tfm_hal_system_reset(void)
-
-**Description**
-
-This API performs a system reset.
-
-The platform can uninitialize some resources before reset.
-
-**Parameter**
-
-- ``void`` - None
-
-**Return Values**
-
-- ``void`` - None
-
-**Note**
-
-This API should not return.
-
-Isolation API
-=============
-The :term:`PSA-FF-M` defines three isolation levels and a memory access rule to
-provide diverse levels of securitiy. The isolation API provides the functions to
-implement these requirements.
-
-Memory Access Attributes
-------------------------
-The memory access attributes are encoded as bit fields, you can logic OR them to
-have a combination of the atrributes, for example
-``TFM_HAL_MEM_ATTR_UNPRIVILEGED | TFM_HAL_MEM_ATTR_READABLE`` is unprivileged
-readable. The data type is `uint32_t`.
-
-TFM_HAL_MEM_ATTR_EXECUTABLE
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The memory is executable.
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_EXECUTABLE (1UL << 0)
-
-TFM_HAL_MEM_ATTR_READABLE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-The memory is readable.
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_READABLE (1UL << 1)
-
-TFM_HAL_MEM_ATTR_WRITABLE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-The memory is writable.
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_WRITABLE (1UL << 2)
-
-TFM_HAL_MEM_ATTR_UNPRIVILEGED
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The memory is unprivileged mode accessible.
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_UNPRIVILEGED (1UL << 3)
-
-TFM_HAL_MEM_ATTR_DEVICE
-^^^^^^^^^^^^^^^^^^^^^^^
-The memory is a MMIO device.
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_DEVICE (1UL << 4)
-
-TFM_HAL_MEM_ATTR_NS
-^^^^^^^^^^^^^^^^^^^
-The memory is accessible from :term:`NSPE`
-
-.. code-block:: c
-
- #define TFM_HAL_MEM_ATTR_NS (1UL << 5)
-
-APIs
-----
-tfm_hal_set_up_static_boundaries()
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- tfm_hal_status_t tfm_hal_set_up_static_boundaries(void)
-
-**Description**
-
-This API sets up the static isolation boundaries which are constant throughout
-the runtime of the system.
-
-The boundaries include:
-
-- The SPE boundary between the :term:`SPE` and the :term:`NSPE`
-- The PSA RoT isolation boundary between the PSA Root of Trust and the
- Application Root of Trust which is for isolation level 2 and 3 only.
-
-Please refer to the :term:`PSA-FF-M` for the definitions of the isolation
-boundaries.
-
-**Return Values**
-
-- ``TFM_HAL_SUCCESS`` - the isolation boundaries have been set up.
-- ``TFM_HAL_ERROR_GENERIC`` - failed to set up the isolation boundaries.
-
-tfm_hal_mpu_update_partition_boundary
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start,
- uintptr_t end);
-
-**Description**
-
-This API updates the partition isolation boundary for isolation level 3.
-Inside the partition isolation boundary is the private data of the running
-Secure Partition.
-This boundary is updated dynamically when :term:`SPM` switches Partitions in
-isolation level 3.
-
-The access permissions of the boundary is all privileged mode read-write.
-
-Platforms decide which :term:`MPU` region the paritition boundary uses.
-
-**Parameter**
-
-- ``start`` - start address of the partition boundary.
-- ``end`` - end address of the partition boundary.
-
-**Return Values**
-
-- ``TFM_HAL_SUCCESS`` - the isolation boundary has been set up.
-- ``TFM_HAL_ERROR_GENERIC`` - failed to set upthe isolation boundary.
-
-**Note**
-
-This API is only for platforms using :term:`MPU` as isolation hardwares.
-A generic API for all platforms will be introduced in future versions.
-
-tfm_hal_memory_has_access()
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base,
- size_t size,
- uint32_t attr)
-
-**Description**
-
-This API checks if the memory region defined by ``base`` and ``size`` has the
-given access atrributes - ``attr``.
-
-The Attributes include :term:`NSPE` access, privileged mode, and read-write
-permissions.
-
-**Parameter**
-
-- ``base`` - The base address of the region.
-- ``size`` - The size of the region.
-- ``attr`` - The `Memory Access Attributes`_.
-
-**Return Values**
-
-- ``TFM_HAL_SUCCESS`` - The memory region has the access permissions.
-- ``TFM_HAL_ERROR_MEM_FAULT`` - The memory region does not have the access
- permissions.
-- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs.
-- ``TFM_HAL_ERROR_GENERIC`` - An error occurred.
-
-Log API
-=======
-The log API is used by the :term:`TF-M` :doc:`log system `.
-The log device could be uart, memory, usb, etc.
-
-APIs
-----
-tfm_hal_output_partition_log()
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- int32_t tfm_hal_output_partition_log(const unsigned char *str, uint32_t len)
-
-**Description**
-
-This API is called by Secure Partition to output logs.
-
-**Parameter**
-
-- ``str`` - The string to output.
-- ``len`` - Length of the string in bytes.
-
-**Return Values**
-
-- Positive values - Number of bytes output.
-- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized.
-- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` or
- ``len`` is zero.
-
-**Note**
-
-None.
-
-tfm_hal_output_spm_log()
-^^^^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- int32_t tfm_hal_output_spm_log(const unsigned char *str, uint32_t len)
-
-**Description**
-
-This API is called by :term:`SPM` to output logs.
-
-**Parameter**
-
-- ``str`` - The string to output.
-- ``len`` - Length of the string in bytes.
-
-**Return Values**
-
-- Positive numbers - Number of bytes output.
-- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized.
-- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL``
- or ``len`` is zero.
-
-**Note**
-
-Please check :doc:`TF-M log system ` for more
-information.
-
-************************************
-API Definition for Secure Partitions
-************************************
-The Secure Partition (SP) :term:`HAL` mainly focuses on two parts:
-
- - Peripheral devices. The peripherals accessed by the :term:`TF-M` default
- Secure Partitions.
- - Secure Partition abstraction support. The Secure Partition data that must be
- provided by the platform.
-
-The Secure Partition abstraction support will be introduced in the peripheral
-API definition.
-
-ITS and PS flash API
-====================
-There are two kinds of flash:
-
- - Internal flash. Accessed by the PSA Internal Trusted Storage (ITS) service.
- - External flash. Accessed by the PSA Protected Storage (PS) service.
-
-The ITS HAL for the internal flash device is defined in the ``tfm_hal_its.h``
-header and the PS HAL in the ``tfm_hal_ps.h`` header.
-
-Macros
-------
-Internal Trusted Storage
-^^^^^^^^^^^^^^^^^^^^^^^^
-TFM_HAL_ITS_FLASH_DRIVER
-~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for
-ITS. It must have been allocated by the platform and will be declared extern in
-the HAL header.
-
-TFM_HAL_ITS_PROGRAM_UNIT
-~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the size of the ITS flash device's physical program unit (the smallest
-unit of data that can be individually programmed to flash). It must be equal to
-TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile
-time so that filesystem structures can be statically sized.
-
-TFM_HAL_ITS_FLASH_AREA_ADDR
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the base address of the dedicated flash area for ITS.
-
-TFM_HAL_ITS_FLASH_AREA_SIZE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the size of the dedicated flash area for ITS in bytes.
-
-TFM_HAL_ITS_SECTORS_PER_BLOCK
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the number of contiguous physical flash erase sectors that form a
-logical filesystem erase block.
-
-Protected Storage
-^^^^^^^^^^^^^^^^^
-TFM_HAL_PS_FLASH_DRIVER
-~~~~~~~~~~~~~~~~~~~~~~~
-Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for
-PS. It must have been allocated by the platform and will be declared extern in
-the HAL header.
-
-TFM_HAL_PS_PROGRAM_UNIT
-~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the size of the PS flash device's physical program unit (the smallest
-unit of data that can be individually programmed to flash). It must be equal to
-TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile
-time so that filesystem structures can be statically sized.
-
-TFM_HAL_PS_FLASH_AREA_ADDR
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the base address of the dedicated flash area for PS.
-
-TFM_HAL_PS_FLASH_AREA_SIZE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the size of the dedicated flash area for PS in bytes.
-
-TFM_HAL_PS_SECTORS_PER_BLOCK
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the number of contiguous physical flash erase sectors that form a
-logical filesystem erase block.
-
-Optional definitions
---------------------
-The ``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` and
-``TFM_HAL_ITS_SECTORS_PER_BLOCK`` definitions are optional. If not defined, the
-platform must implement ``tfm_hal_its_fs_info()`` instead.
-
-Equivalently, ``tfm_hal_its_ps_info()`` must be implemented by the platform if
-``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` or
-``TFM_HAL_ITS_SECTORS_PER_BLOCK`` is not defined.
-
-Objects
--------
-ARM_DRIVER_FLASH
-^^^^^^^^^^^^^^^^
-The ITS and PS HAL headers each expose a CMSIS Flash Driver instance.
-
-.. code-block:: c
-
- extern ARM_DRIVER_FLASH TFM_HAL_ITS_FLASH_DRIVER
-
- extern ARM_DRIVER_FLASH TFM_HAL_PS_FLASH_DRIVER
-
-The CMSIS Flash Driver provides the flash primitives ReadData(), ProgramData()
-and EraseSector() as well as GetInfo() to access flash device properties such
-as the sector size.
-
-Types
------
-tfm_hal_its_fs_info_t
-^^^^^^^^^^^^^^^^^^^^^
-Struct containing information required from the platform at runtime to configure
-the ITS filesystem.
-
-.. code-block:: c
-
- struct tfm_hal_its_fs_info_t {
- uint32_t flash_area_addr;
- size_t flash_area_size;
- uint8_t sectors_per_block;
- };
-
-Each attribute is described below:
-
- - ``flash_area_addr`` - Location of the block of flash to use for ITS
- - ``flash_area_size`` - Number of bytes of flash to use for ITS
- - ``sectors_per_block`` - Number of erase sectors per logical FS block
-
-tfm_hal_ps_fs_info_t
-^^^^^^^^^^^^^^^^^^^^^
-Struct containing information required from the platform at runtime to configure
-the PS filesystem.
-
-.. code-block:: c
-
- struct tfm_hal_ps_fs_info_t {
- uint32_t flash_area_addr;
- size_t flash_area_size;
- uint8_t sectors_per_block;
- };
-
-Each attribute is described below:
-
- - ``flash_area_addr`` - Location of the block of flash to use for PS
- - ``flash_area_size`` - Number of bytes of flash to use for PS
- - ``sectors_per_block`` - Number of erase sectors per logical FS block
-
-Functions
----------
-tfm_hal_its_fs_info()
-^^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- enum tfm_hal_status_t tfm_hal_its_fs_info(struct tfm_hal_its_fs_info_t *fs_info);
-
-**Description**
-
-Retrieves the filesystem configuration parameters for ITS.
-
-**Parameter**
-
-- ``fs_info`` - Filesystem config information
-
-**Return values**
-
-- ``TFM_HAL_SUCCESS`` - The operation completed successfully
-- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter
-
-**Note**
-
-This function should ensure that the values returned do not result in a security
-compromise. The block of flash supplied must meet the security requirements of
-Internal Trusted Storage.
-
-tfm_hal_ps_fs_info()
-^^^^^^^^^^^^^^^^^^^^
-**Prototype**
-
-.. code-block:: c
-
- enum tfm_hal_status_t tfm_hal_ps_fs_info(struct tfm_hal_ps_fs_info_t *fs_info);
-
-**Description**
-
-Retrieves the filesystem configuration parameters for PS.
-
-**Parameter**
-
-- ``fs_info`` - Filesystem config information
-
-**Return values**
-
-- ``TFM_HAL_SUCCESS`` - The operation completed successfully
-- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter
-
-**Note**
-
-This function should ensure that the values returned do not result in a security
-compromise.
-
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/index.rst b/docs/design_documents/index.rst
deleted file mode 100644
index 9f85a76500..0000000000
--- a/docs/design_documents/index.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-Design Documents
-================
-
-.. toctree::
- :maxdepth: 2
- :titlesonly:
- :glob:
- :numbered:
-
- */index
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/index.rst.in b/docs/design_documents/index.rst.in
deleted file mode 100644
index b5cf149af8..0000000000
--- a/docs/design_documents/index.rst.in
+++ /dev/null
@@ -1,30 +0,0 @@
-Design Documents
-================
-
-.. toctree::
- :maxdepth: 1
- :caption: Accepted design documents
- :glob:
- :numbered:
-
- @ACCEPTED_DD_LIST@
-
-.. toctree::
- :maxdepth: 1
- :caption: Draft design documents
- :glob:
- :numbered:
-
- @DRAFT_DD_LIST@
-
-.. toctree::
- :maxdepth: 1
- :caption: Rejected design documents
- :glob:
- :numbered:
-
- @REJECTED_DD_LIST@
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/media/hal_structure.png b/docs/design_documents/media/hal_structure.png
deleted file mode 100644
index 0f4c4c0018..0000000000
Binary files a/docs/design_documents/media/hal_structure.png and /dev/null differ
diff --git a/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png b/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png
deleted file mode 100644
index 548e79d3d1..0000000000
Binary files a/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png and /dev/null differ
diff --git a/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png b/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png
deleted file mode 100644
index ac39cf258e..0000000000
Binary files a/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png and /dev/null differ
diff --git a/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png b/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png
deleted file mode 100644
index 288bc534fb..0000000000
Binary files a/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png and /dev/null differ
diff --git a/docs/design_documents/media/symmetric_initial_attest/iat_decode.png b/docs/design_documents/media/symmetric_initial_attest/iat_decode.png
deleted file mode 100644
index e35183bacc..0000000000
Binary files a/docs/design_documents/media/symmetric_initial_attest/iat_decode.png and /dev/null differ
diff --git a/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png b/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png
deleted file mode 100644
index 893c62eedf..0000000000
Binary files a/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png and /dev/null differ
diff --git a/docs/design_documents/media/tfm_crypto_design.png b/docs/design_documents/media/tfm_crypto_design.png
deleted file mode 100644
index 6e8d48b200..0000000000
Binary files a/docs/design_documents/media/tfm_crypto_design.png and /dev/null differ
diff --git a/docs/design_documents/profiles/index.rst b/docs/design_documents/profiles/index.rst
deleted file mode 100644
index e856cf8078..0000000000
--- a/docs/design_documents/profiles/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-TF-M Profiles
-=============
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/profiles/tfm_profile_large.rst b/docs/design_documents/profiles/tfm_profile_large.rst
deleted file mode 100644
index 31c67c39ff..0000000000
--- a/docs/design_documents/profiles/tfm_profile_large.rst
+++ /dev/null
@@ -1,459 +0,0 @@
-#######################################
-Trusted Firmware-M Profile Large Design
-#######################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-TF-M Profiles defines 3 profiles: Profile Small, Profile Medium and Profile
-Large. Each profile provides a predefined list of TF-M configurations to meet
-the security requirement of typical use cases with device hardware constraints.
-TF-M Profiles align with PSA specifications and certification requirements.
-
-As one of TF-M Profiles, Profile Large protects less resource-constrained Arm
-Cortex-M devices.
-
-Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to
-enable more secure features to support higher level of security required in more
-complex usage scenarios.
-
- - Isolation level 3 enables additional isolation between
- :term:`Application RoT` (App RoT) services.
- - More crypto algorithms and cipher suites are selected to securely connect
- devices to remote services offered by various major Cloud Service
- Providers (CSP)
- - Basic software countermeasures against physical attacks can be enabled.
-
-Profile Large can be aligned as a reference implementation with the requirements
-defined in PSA Certified Level 3 Lightweight Protection Profile [3]_.
-
-**************
-Overall design
-**************
-
-TF-M Profile Large defines the following feature set:
-
- - Firmware Framework
-
- - Inter-Process Communication (IPC) model [4]_
- - Isolation level 3 [4]_
-
- - Internal Trusted Storage (ITS)
-
- - Crypto
-
- - Support both symmetric ciphers and asymmetric ciphers
- - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support
- direct secure connection to major CSPs, including
-
- - Authenticated Encryption with Associated Data (AEAD) algorithm
- - Asymmetric key algorithm based signature and verification
- - Public-key cryptography based key exchange
- - Hash function
- - HMAC for default Pseudorandom Function (PRF)
-
- - Asymmetric digital signature and verification for Initial Attestation
- Token (IAT)
- - Asymmetric algorithms for firmware image signature verification
- - Key derivation
-
- - Initial Attestation
-
- - Asymmetric key algorithm based Initial Attestation
-
- - Secure boot
-
- - Anti-rollback protection
- - Multiple image boot
-
- - Protected Storage (PS) if off-chip storage device is integrated
-
- - Data confidentiality
- - Data integrity
- - Rollback protection
-
- - Software countermeasures against physical attacks
-
-**************
-Design details
-**************
-
-More details of TF-M Profile Large design are described in following sections.
-
-Firmware framework
-==================
-
-Profile Large selects IPC model and isolation level 3 by default.
-
-Isolation level 3 supports additional isolation between App RoT services,
-compared to isolation level 2. It can protect :term:`RoT` services from each
-other when their vendors don't trust each other.
-
-Crypto service
-==============
-
-Profile Large supports direct connection to Cloud services via common protocols,
-such as TLS 1.2.
-
-In some usage scenarios, PSA RoT can be managed by device manufacturer or other
-vendors and is out of control of application developers.
-Profile Large selects alternative crypto algorithms for each crypto function to
-support multiple common cipher suites required by various major CSPs. Therefore,
-application developers can support services for diverse CSPs on same devices
-with Profile Large, without relying on PSA RoT upgrades of crypto.
-
-Devices meeting Profile Large should be in a position to offer at least two
-alternatives to every cryptographic primitive for symmetric, asymmetric and
-hash, and be able to use them for encryption, AEAD, signature and verification.
-
-It will cost more resource in Profile Large to support more crypto algorithms
-and cipher suites, compared to Profile Medium [2]_.
-
-Boot loader
-===========
-
-BL2 implementation can be device specific. Devices may implement diverse
-boot processes with different features and configurations.
-However, the boot loader must support anti-rollback protection. Boot loader must
-be able to prevent unauthorized rollback, to protect devices from being
-downgraded to earlier versions with known vulnerabilities.
-
-MCUBoot in TF-M is configured as multiple image boot by default in Profile
-Large. In multiple image boot, secure and non-secure images can be signed
-independently with different keys and they can be updated separately. It can
-support multiple vendors scenarios, in which non-secure and secure images are
-generated and updated by different vendors.
-Multiple image boot may cost larger memory footprint compared with single image
-boot.
-
-Boot loader can implement software countermeasures to mitigate physical attacks.
-
-Protected Storage
-=================
-
-PS service is required if an off-chip storage device is integrated and used on
-the platform.
-
-Anti-rollback protection in PS relies on non-volatile counter(s) provided by
-TF-M Platform :term:`Secure Partition` (SP).
-
-TF-M audit logging service
-==========================
-
-TF-M audit logging service allows secure services in the system to log TF-M
-events and information.
-
-TF-M audit logging service is not enabled in Profile Large since its IPC model
-dedicated interface is not ready yet.
-
-.. note ::
-
- **Implementation note**
-
- Please note that there is no dedicated PSA specification for Audit Logging
- yet.
- The design, interfaces and implementation of TF-M audit logging service may
- change.
-
-Software countermeasures against physical attacks
-=================================================
-
-TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile
-Medium by default. It enables the following countermeasure techniques:
-
- - Control flow monitor
- - Failure loop hardening
- - Complex constants
- - Redundant variables and condition checks
-
-Refer to TF-M physical attack mitigation design document [6]_ for FIH library
-details.
-
-.. note ::
-
- **TF-M FIH library is still under development**.
-
- TF-M FIH library hardens TF-M critical execution steps to make physical
- attacks more difficult, together with device hardware countermeasures.
- It is not guaranteed that TF-M FIH library is able to mitigate all kinds of
- physical attacks.
-
-.. note ::
-
- **Implementation note**
-
- TF-M FIH library doesn't cover platform specific critical configurations.
- Platforms shall implement software countermeasures against physical attacks
- to protect platform specific implementation.
-
-**************
-Implementation
-**************
-
-Overview
-========
-
-The basic idea is to add dedicated profile CMake configuration files under
-folder ``config/profile`` for TF-M Profile Large default configuration, the
-same as other TF-M Profiles do.
-
-The top-level Profile Large config file collects all the necessary configuration
-flags and set them to default values, to explicitly enable the features required
-in Profile Large and disable the unnecessary ones, during TF-M build.
-
-A platform/use case can provide a configuration extension file to overwrite
-Profile Large default setting and append other configurations.
-This configuration extension file can be added via parameter
-``TFM_EXTRA_CONFIG_PATH`` in build command line.
-
-The behaviour of the Profile Large build flow (particularly the order of
-configuration loading and overriding) can be found at
-:ref:`tfm_cmake_configuration`
-
-The details of configurations will be covered in each module in
-`Implementation details`_.
-
-Implementation details
-======================
-
-This section discusses the details of Profile Large implementation.
-
-Top-level configuration files
------------------------------
-
-The firmware framework configurations in ``config/profile/profile_large`` are
-shown below.
-
-.. table:: Config flags in Profile Large top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | Configs | Descriptions | Default value |
- +============================================+====================================+====================================================================================================+
- | ``TFM_ISOLATION_LEVEL`` | Select level 3 isolation | ``3`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PSA_API`` | Select IPC model | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``ITS_BUF_SIZE`` | ITS internal transient buffer size | ``64`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_CRYPTO`` | Enable Crypto service | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | MbedTLS config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_INITIAL_ATTESTATION`` | Enable Initial Attestation service | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_ | Enable PS service | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_PLATFORM`` | Enable TF-M Platform SP | ``ON`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
- | ``TFM_PARTITION_AUDIT_LOG`` | Disable TF-M audit logging service | ``OFF`` |
- +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
-
-.. [a] PS service is enabled by default. Platforms without off-chip storage
- devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
- service. See `Protected Storage Secure Partition`_ for details.
-
-Crypto service configurations
------------------------------
-
-Crypto Secure Partition
-^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Large enables Crypto SP in top-level CMake config file and selects
-all the Crypto modules.
-
-MbedTLS configurations
-^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Large adds a dedicated MbedTLS config file
-``tfm_mbedcrypto_config_profile_large.h`` under
-``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one
-``tfm_mbedcrypto_config_default.h`` [7]_.
-
-Major MbedTLS configurations are set as listed below:
-
- - Enable SHA256 and SHA512
- - Enable generic message digest wrappers
- - Enable AES
- - Enable CCM mode, GCM mode and CBC mode for symmetric ciphers
- - Disable other modes for symmetric ciphers
- - Enable ECDH
- - Enable ECDSA
- - Enable RSA
- - Select ECC curve ``secp256r1`` and ``secp384r1``
- - Enable HMAC-based key derivation function
- - Other configurations required by selected option above
-
-A device/use case can append an extra config header to the Profile Large default
-MbedTLS config file to override the default settings. This can be done by
-setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the
-platform config file ``platform/ext/config.cmake``.
-This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE``
-options, but is preferred as it keeps all configuration in cmake.
-
-Internal Trusted Storage configurations
----------------------------------------
-
-ITS service is enabled in top-level Profile Large CMake config file by default.
-
-The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by
-default. A platform/use case can overwrite the buffer size in its specific
-configuration extension according to its actual requirement of assets and Flash
-attributes.
-
-Profile Large CMake config file won't touch the configurations of device
-specific Flash hardware attributes.
-
-Protected Storage Secure Partition
-----------------------------------
-
-Data confidentiality, integrity and anti-rollback protection are enabled by
-default in PS.
-
-If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform
-hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can
-be executed in hardware crypto accelerator.
-
-If platforms don't integrate any off-chip storage device, platforms can disable
-PS in platform specific configuration extension file via
-``platform/ext/config.cmake``.
-
-BL2 setting
------------
-
-Profile Large enables MCUBoot provided by TF-M by default. A platform can
-overwrite this configuration by disabling MCUBoot in its configuration extension
-file ``platform/ext/config.cmake``.
-
-If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
-default.
-
-If a device implements its own boot loader, the configurations are
-implementation defined.
-
-Software countermeasure against physical attacks
-------------------------------------------------
-
-Profile Large selects TF-M FIH library Profile Medium by specifying
-``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file.
-
-System integrators shall implement software countermeasures in platform specific
-implementations.
-
-Device configuration extension
-------------------------------
-
-To change default configurations and add platform specific configurations,
-a platform can add a platform configuration file at
-``platform/ext/config.cmake``
-
-Test configuration
-------------------
-
-Some cryptography tests are disabled due to the reduced MbedTLS config.
-Profile Large specific test configurations are also specified in Profile Large
-top-level CMake config file ``config/profile/profile_large``.
-
-.. table:: Profile Large crypto test configuration
- :widths: auto
- :align: center
-
- +--------------------------------------------+---------------+-----------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+===============+=========================================+
- | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``ON`` | Test CBC cryptography mode |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``ON`` | Test GCM cryptography mode |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``ON`` | Test SHA-512 cryptography algorithm |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_HKDF`` | ``ON`` | Test HMAC-based key derivation function |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
- +--------------------------------------------+---------------+-----------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
- +--------------------------------------------+---------------+-----------------------------------------+
-
-****************
-Platform support
-****************
-
-To enable Profile Large on a platform, the platform specific CMake file should
-be added into the platform support list in top-level Profile Large CMake config
-file.
-
-Building Profile Large
-======================
-
-To build Profile Large, argument ``TFM_PROFILE`` in build command line should be
-set to ``profile_large``.
-
-Take AN521 as an example:
-
-The following commands build Profile Large without test cases on **AN521** with
-build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_large \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- ../
- cmake --build ./ -- install
-
-The following commands build Profile Large with regression test cases on
-**AN521** with build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_large \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DTEST_S=ON -DTEST_NS=ON \
- ../
- cmake --build ./ -- install
-
-More details of building instructions and parameters can be found TF-M build
-instruction guide [9]_.
-
-*********
-Reference
-*********
-
-.. [1] :doc:`Trusted Firmware-M Profile Small Design `
-
-.. [2] :doc:`Trusted Firmware-M Profile Medium Design `
-
-.. [3] `PSA Certified Level 3 Lightweight Protection Profile `_
-
-.. [4] `Arm Platform Security Architecture Firmware Framework 1.0 `_
-
-.. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 `_
-
-.. [6] `Physical attack mitigation in Trusted Firmware-M `
-
-.. [7] :doc:`Crypto design `
-
-.. [8] :doc:`ITS integration guide `
-
-.. [9] :doc:`TF-M build instruction `
-
---------------
-
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/profiles/tfm_profile_medium.rst b/docs/design_documents/profiles/tfm_profile_medium.rst
deleted file mode 100644
index 8413635cc9..0000000000
--- a/docs/design_documents/profiles/tfm_profile_medium.rst
+++ /dev/null
@@ -1,477 +0,0 @@
-########################################
-Trusted Firmware-M Profile Medium Design
-########################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-Compared with Profile Small, Profile Medium aims to securely connect devices to
-Cloud services with asymmetric cipher support.
-Profile Medium target devices need more resources for more cipher algorithms
-and higher isolation levels.
-
-For more descriptions and background of TF-M Profile, please refer to Profile
-Small design document [PROFILE-S]_.
-
-**************
-Overall design
-**************
-
-TF-M Profile Medium defines the following feature set:
-
- - Firmware Framework
-
- - Inter-Process Communication (IPC) model [PSA-FF-M]_
- - Isolation level 2 [PSA-FF-M]_
-
- - Internal Trusted Storage (ITS)
-
- - Crypto
-
- - Support both symmetric ciphers and asymmetric ciphers
- - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for
- IoT [RFC7925]_ and CoAP [RFC7252]_, including
-
- - Authenticated Encryption with Associated Data (AEAD) algorithm
- - Asymmetric key algorithm based signature and verification
- - Public-key cryptography based key exchange
- - Hash function
- - HMAC for default Pseudorandom Function (PRF)
-
- - Asymmetric digital signature and verification for Initial Attestation
- Token (IAT)
-
- - Initial Attestation
-
- - Asymmetric key algorithm based Initial Attestation
-
- - Lightweight boot
-
- - Anti-rollback protection
- - Multiple image boot
-
- - Protected Storage (PS) if off-chip storage device is integrated
-
- - Data confidentiality
- - Data integrity
- - Rollback protection
-
-**************
-Design details
-**************
-
-More details of TF-M Profile Medium design are described in following sections.
-
-Firmware framework
-==================
-
-Profile Medium with IPC model and isolation level 2 aims to support usage
-scenarios which require more complicated secure service model and additional
-protection to PSA RoT.
-
-Level 2 isolation
------------------
-
-Profile Medium selects isolation level 2 by default. In addition to isolation
-level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the
-Application Root of Trust (App RoT) in level 2 isolation.
-
-IPC model
----------
-
-Profile Medium enables IPC model by default. IPC model can achieve a more
-flexible framework and higher levels of isolation, but may require more memory
-footprint and bring in longer latency, compared to Library model.
-
-TF-M IPC model implementation follows the PSA Firmware Framework for M
-(PSA-FF-M) [PSA-FF-M]_.
-
-Crypto service
-==============
-
-Compared to Profile Small, Profile Medium includes asymmetric cipher to support
-direct connection to Cloud services via common protocols, such as TLS/DTLS 1.2.
-
-As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default
-selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires:
-
- - ECDHE_ECDSA as key exchange algorithm.
- - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm.
- Platforms can implement AES-128-CCM with truncated authentication tag to
- achieve less network bandwidth [RFC7925]_.
- - SHA256 as Hash function.
- - HMAC as Message Authentication Code algorithm.
-
-Applications can also support TLS PSK [RFC4279]_ cipher suites, such as
-``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_.
-
-.. note ::
-
- **Implementation note**
-
- Developers can replace default algorithms with others or implement more
- algorithms according to actual usage scenarios and device capabilities.
-
- If a Crypto hardware accelerator is integrated, the cipher suites and
- algorithms also depend on those accelerator features.
-
-More details of cipher suite are described below.
-
-Digital signature and verification
-----------------------------------
-
-ECDSA is selected by default in Profile Medium.
-ECDSA requires much shorter keys compared with RSA at the same security level.
-Therefore, ECDSA can cost less storage area for assets and less network
-bandwidth to setup a TLS connection.
-ECDSA is also preferred for forward compatibility of future TLS versions.
-
-As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More
-ECC curves can be added based on the requirements in production.
-
-If usage scenarios require RSA algorithm for backward compatibility and legacy
-applications, platforms can add RSA support or replace ECDSA with RSA. The
-cipher suite should be switched accordingly.
-
-AEAD algorithm
---------------
-
-If Protected Storage (PS) is implemented, it is recommended to select the same
-AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite.
-
-Internal Trusted Storage
-========================
-
-The configuration of ITS is the same as those in Profile Small [PROFILE-S]_.
-
-Lightweight boot
-================
-
-BL2 implementation can be device specific. Devices may implement diverse
-boot processes with different features and configurations.
-However, the boot loader must support anti-rollback protection. Boot loader must
-be able to prevent unauthorized rollback, to protect devices from being
-downgraded to earlier versions with known vulnerabilities.
-
-MCUBoot in TF-M is configured as multiple image boot by default in Profile
-Medium. In multiple image boot, secure and non-secure images can be signed
-independently with different keys and they can be updated separately. It can
-support multiple vendors scenarios, in which non-secure and secure images are
-generated and updated by different vendors.
-Multiple image boot may require more storage area compared with single image
-boot.
-
-Protected Storage
-=================
-
-PS service is required if an off-chip storage device is integrated and used on
-the platform.
-
-TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and
-integrity. It is recommended to select the same AEAD algorithm as the one used
-for TLS/DTLS cipher suite.
-
-Anti-rollback protection in PS relies on non-volatile counter(s) provided by
-TF-M Platform Secure Partition (SP).
-
-TF-M audit logging service
-==========================
-
-TF-M audit logging service allows secure services in the system to log critical
-system events and information.
-
-TF-M audit logging service is not enabled in Profile Medium since its IPC model
-dedicated interface is not ready yet.
-
-.. note ::
-
- **Implementation note**
-
- Please note that there is no dedicated PSA specification for Audit Logging
- yet.
- The design, interfaces and implementation of TF-M audit logging service may
- change.
-
-**************
-Implementation
-**************
-
-Overview
-========
-
-The basic idea is to add dedicated profile CMake configuration files under
-folder ``config/profile`` for TF-M Profile Medium default configuration, the
-same as Profile Small does.
-
-The top-level Profile Medium config file collects all the necessary
-configuration flags and set them to default values, to explicitly enable the
-features required in Profile Medium and disable the unnecessary ones, during
-TF-M build.
-
-A platform/use case can provide a configuration extension file to overwrite
-Profile Medium default setting and append other configurations.
-This configuration extension file can be added via parameter
-``TFM_EXTRA_CONFIG_PATH`` in build command line.
-
-The behaviour of the Profile Medium build flow (particularly the order of
-configuration loading and overriding) can be found at
-:ref:`tfm_cmake_configuration`
-
-The details of configurations will be covered in each module in
-`Implementation details`_.
-
-Implementation details
-======================
-
-This section discusses the details of Profile Medium implementation.
-
-Top-level configuration files
------------------------------
-
-The firmware framework configurations in ``config/profile/profile_medium`` are
-shown below.
-
-.. table:: Config flags in Profile Medium top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================================================================================+=====================================+
- | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PSA_API`` | ``True`` | Select IPC model |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
-
-.. [1] PS service is enabled by default. Platforms without off-chip storage
- devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
- service. See `Protected Storage Secure Partition`_ for details.
-
-.. Note::
-
- Where a configuration is the same as the default in
- ``config/config_default.cmake``, it is omitted from the profile configuration
- file.
-
-Test configuration
-^^^^^^^^^^^^^^^^^^
-
-Standard regression test configuration applies. This means that enabling
-regression testing via
-
-``-DTEST_S=ON -DTEST_NS=ON``
-
-Will enable testing for all enabled partitions. See above for details of enabled
-partitions. Because Profile Medium enables IPC mode, the IPC tests are also
-enabled.
-
-Some cryptography tests are disabled due to the reduced Mbed Crypto config.
-
-.. table:: TFM options in Profile Medium top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================================================================================+=====================================+
- | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
-
-Device configuration extension
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To change default configurations and add platform specific configurations,
-a platform can add a platform configuration file at
-``platform/ext/config.cmake``
-
-Crypto service configurations
------------------------------
-
-Crypto Secure Partition
-^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Medium enables Crypto SP in top-level CMake config file and selects
-all the Crypto modules.
-
-Mbed Crypto configurations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Medium adds a dedicated Mbed Crypto config file
-``tfm_mbedcrypto_config_profile_medium.h`` at
-``/lib/ext/mbedcrypto/mbedcrypto_config``
-file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_.
-
-Major Mbed Crypto configurations are set as listed below:
-
- - Enable SHA256
- - Enable generic message digest wrappers
- - Enable AES
- - Enable CCM mode for symmetric ciphers
- - Disable other modes for symmetric ciphers
- - Enable ECDH
- - Enable ECDSA
- - Select ECC curve ``secp256r1``
- - Other configurations required by selected option above
-
-Other configurations can be selected to optimize the memory footprint of Crypto
-module.
-
-A device/use case can append an extra config header to the Profile Medium
-default Mbed Crypto config file. This can be done by setting the
-``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
-config file ``platform/ext/config.cmake``. This cmake variable is
-a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
-it keeps all configuration in cmake.
-
-Internal Trusted Storage configurations
----------------------------------------
-
-ITS service is enabled in top-level Profile Medium CMake config file by default.
-
-The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to
-32 bytes by default. A platform/use case can overwrite the buffer size in its
-specific configuration extension according to its actual requirement of assets
-and Flash attributes.
-
-Profile Medium CMake config file won't touch the configurations of device
-specific Flash hardware attributes [ITS-INTEGRATE]_.
-
-Protected Storage Secure Partition
-----------------------------------
-
-Data confidentiality, integrity and anti-rollback protection are enabled by
-default in PS.
-
-If PS is selected, AES-CCM is used as AEAD algorithm by default. It requires to
-enable PS implementation to select diverse AEAD algorithm.
-
-If platforms don't integrate any off-chip storage device, platforms can disable
-PS in platform specific configuration extension file via
-``platform/ext/config.cmake``.
-
-BL2 setting
------------
-
-Profile Medium enables MCUBoot provided by TF-M by default. A platform can
-overwrite this configuration by disabling MCUBoot in its configuration extension
-file ``platform/ext/config.cmake``.
-
-If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
-default in TF-M Profile Medium top-level CMake config file.
-
-If a device implements its own boot loader, the configurations are
-implementation defined.
-
-****************
-Platform support
-****************
-
-To enable Profile Medium on a platform, the platform specific CMake file should
-be added into the platform support list in top-level Profile Medium CMake config
-file.
-
-Building Profile Medium
-=======================
-
-To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be
-set to ``profile_medium``.
-
-Take AN521 as an example:
-
-The following commands build Profile Medium without test cases on **AN521** with
-build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_medium \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- ../
- cmake --build ./ -- install
-
-The following commands build Profile Medium with regression test cases on
-**AN521** with build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_medium \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DTEST_S=ON -DTEST_NS=ON \
- ../
- cmake --build ./ -- install
-
-.. Note::
-
- - For devices with more contrained memory and flash requirements, it is
- possible to build with either only TEST_S enabled or only TEST_NS enabled.
- This will decrease the size of the test images. Note that both test suites
- must still be run to ensure correct operation.
-
-More details of building instructions and parameters can be found TF-M build
-instruction guide [TFM-BUILD]_.
-
-*********
-Reference
-*********
-
-.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 `_
-
-.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things `_
-
-.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design `
-
-.. [RFC7252] `The Constrained Application Protocol (CoAP) `_
-
-.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_
-
-.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS `_
-
-.. [CRYPTO-DESIGN] :doc:`Crypto design `
-
-.. [ITS-INTEGRATE] :doc:`ITS integration guide `
-
-.. [TFM-BUILD] :doc:`TF-M build instruction `
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/profiles/tfm_profile_small.rst b/docs/design_documents/profiles/tfm_profile_small.rst
deleted file mode 100644
index abd49c8c8f..0000000000
--- a/docs/design_documents/profiles/tfm_profile_small.rst
+++ /dev/null
@@ -1,645 +0,0 @@
-#######################################
-Trusted Firmware-M Profile Small Design
-#######################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-The capabilities and resources may dramatically vary on different IoT devices.
-Some IoT devices may have very limited memory resource. The program on those
-devices should keep small memory footprint and basic functionalities.
-On the other hand, some devices may consist of more memory and extended storage,
-to support stronger software capabilities.
-
-Diverse IoT use cases also require different levels of security and requirements
-on device resource. For example, use cases require different cipher
-capabilities. Selecting cipher suites can be sensitive to memory footprint on
-devices with constrained resource.
-
-Trusted Firmware-M (TF-M) defines 3 general profiles, Profile Small,
-Profile Medium and Profile Large, to provide different levels of security to fit
-diverse device capabilities and use cases.
-Each profile specifies a predefined list of features, targeting typical use
-cases with specific hardware constraints. Profiles can serve as reference
-designs, based on which developers can continue further development and
-configurations, according to use case.
-
-As one of the TF-M Profiles, TF-M Profile Small (Profile S) consists of
-lightweight TF-M framework and basic Secure Services to keep smallest memory
-footprint, supporting fundamental security features on devices with ultra
-constrained resource.
-
-This profile enables connecting with Edge Gateways and IoT Cloud Services
-supporting secure connection based solely on symmetric cryptography.
-
-This document summarizes and discusses the features specified in TF-M Profile
-Small.
-
-**************
-Overall design
-**************
-
-TF-M Profile Small defines the following features:
-
- - Lightweight framework
-
- - Library model
- - Level 1 isolation
- - Buffer sharing allowed
- - Single secure context
-
- - Crypto
-
- - Symmetric cipher only
- - Cipher suite for symmetric-key algorithms based protocols, such as
- cipher suites defined in TLS pre-shared key (TLS-PSK) [1]_.
-
- - Advanced Encryption Standard (AES) as symmetric crypto algorithm
- - SHA256 as Hash function
- - HMAC as Message Authentication Code algorithm
-
- - Internal Trusted Storage (ITS)
-
- - No encryption
- - No rollback protection
- - Decrease internal transient buffer size
-
- - Initial Attestation
-
- - Based on symmetric key algorithms
-
- - Lightweight boot
-
- - Single image boot
- - Anti-rollback protection is enabled
-
-
-Protected Storage, audit logging and other Secure Services provided by TF-M are
-disabled by default.
-
-**************
-Design details
-**************
-
-More details of TF-M Profile Small design are discussed in following sections.
-
-Lightweight framework
-=====================
-
-Library model
--------------
-
-Profile Small selects Library model in TF-M. Library model implements secure
-function calls, via which clients directly call secure services. It provides a
-more simple implementation of TF-M framework and may reduce memory footprint,
-compared with Inter-Process Communication (IPC) model [2]_.
-
-.. note ::
-
- **Implementation note**
-
- Please note that there is no public dedicated specification for Library
- model.
- The design, interfaces and implementation of Library model in TF-M may
- change.
-
-Level 1 isolation
------------------
-
-So far, TF-M Library model only supports level 1 isolation [2]_, which isolates
-Secure Processing Environment (SPE) from Non-secure Processing Environment
-(NSPE). Neither level 2 nor level 3 isolation [2]_ is implemented in TF-M
-Library model.
-
-PSA Root of Trust (PSA RoT) and Application Root of Trust (ARoT) are isolated
-from each other in level 2 isolation.
-Individual secure partitions are isolated from each other even within a
-particular security domain (PSA RoT, ARoT), in level 3 isolation.
-
-Profile Small dedicated use cases with simple service model may not require
-level 2 or level 3 isolation. Devices which Profile Small aims at may be unable
-to implement stricter isolation, limited by hardware capabilities.
-
-Level 1 isolation reduces requirements enforced by hardware isolation and cost
-of software for management.
-
-.. note ::
-
- **Security note**
-
- If a device or a use case enforces level 2 or level 3 isolation, it is
- suggested to apply other configurations, other than TF-M Profile Small.
-
-Buffer sharing allowed
-----------------------
-
-To simplify interface and reduce memory footprint, TF-M Library model directly
-handles client call input vectors from non-secure client buffers and later
-writes results back to those buffers, without keeping a copy in a transient
-buffer inside TF-M.
-
-.. note ::
-
- **Security note**
-
- There can be security vulnerabilities if non-secure client buffers are
- directly shared between NSPE and SPE, such as Time-of-check to time-of-use
- (TOCTOU) attack.
-
- Developers need to check if this can meet the Security Functional
- Requirements (SFR) of the integration of their devices.
- Some SFRs are listed in a set of example Threat Models and Security Analyses
- (TMSA) offered by PSA for common IoT use cases. [3]_
-
-Single secure context
----------------------
-
-TF-M Library model only supports single secure context.
-
-It cannot support multiple contexts or the scheduling implemented in IPC model.
-It neither can support multiple outstanding PSA client calls.
-
-But correspondingly, it can save memory footprint and runtime complexity in
-context management and scheduling.
-
-.. note ::
-
- **Security note**
-
- Non-secure software should prevent triggering multiple outstanding PSA
- client calls concurrently. Otherwise, it may crash current running secure
- context.
-
-Crypto service
-==============
-
-TF-M Profile Small only requires symmetric crypto since symmetric algorithms
-require shorter keys and less computational burden, compared with asymmetric
-crypto.
-
-By default, TF-M Profile Small requires the same capabilities as defined in
-TLS-PSK, to support symmetric key algorithms based protocols.
-
-.. note ::
-
- **Implementation note**
-
- Please note that TF-M Profile Small doesn't require that TLS-PSK is
- mandatory in applications. Instead, Profile Small only requires the same
- capabilities as defined in TLS-PSK, such as one symmetric cipher algorithm
- and one hash function.
-
-TF-M Profile Small selects TLS-PSK cipher suite TLS_PSK_WITH_AES_128_CCM [4]_
-as reference, which requires:
-
- - AES-128-CCM (AES CCM mode with 128-bit key) as symmetric crypto algorithm
- - SHA256 as Hash function
- - HMAC as Message Authentication Code algorithm
-
-TLS_PSK_WITH_AES_128_CCM is selected since it requires small key length and less
-hardware capabilities, while keeping enough level of security.
-
-.. note ::
-
- **Implementation note**
-
- Developers can replace default algorithms with others or implement more
- algorithms.
-
- Proper symmetric key algorithms and cipher suites should be selected
- according to device capabilities, the use case and the requirement of peers
- in connection.
-
- Refer to `Crypto service configuration`_ for implementation details of
- configuring algorithms and cipher suites.
-
-.. note ::
-
- **Security note**
-
- It is recommended not to use MD5 or SHA-1 for message digests as they are
- subject to collision attacks [5]_ [6]_.
-
-Secure Storage
-==============
-
-TF-M Profile Small assumes that extremely constrained devices only contain basic
-on-chip storage, without external or removable storage.
-As a result, TF-M Profile Small includes ITS service and disables Protected
-Storage service.
-
-Encryption and rollback protection
-----------------------------------
-
-Neither encryption nor rollback protection is enabled in current ITS
-implementation.
-
-It is expected that ITS relies solely on the physical inaccessibility property
-of on-chip storage, together with PSA isolation, without requiring additional
-cryptographic protection.
-
-Internal transient buffer
--------------------------
-
-ITS implements a internal transient buffer [7]_ to hold the data read
-from/written to storage, especially for flash, to solve the alignment and
-security issues.
-
-The internal transient buffer is aligned to the flash device’s program unit.
-Copying data to it from the caller can align all write requests to the flash
-device’s program unit.
-The internal transient buffer can help protect Flash access from some attacks,
-such as TOCTOU attack.
-
-Although removing this internal buffer can save some memory consumption,
-typically 512 bytes, it may bring alignment or security issues.
-Therefore, to achieve a better trade-off between memory footprint and security,
-TF-M Profile Small optimizes the internal buffer size to 32 bytes by default.
-
-As discussed in `Crypto service`_, TF-M Profile Small requires AES-128 and
-SHA-256, which use 128-bit key and 256-bit key respectively.
-Besides, either long public/private keys or PKI-based certificates should be
-very rare as asymmetric crypto is not supported in Profile Small.
-Therefore, a 32-byte internal buffer should cover the assets in TF-M Profile
-Small use cases.
-
-The buffer size can be adjusted according to use case and device Flash
-attributes. Refer to `Internal Trusted Storage configurations`_ for more
-details.
-
-Initial Attestation
-===================
-
-Profile Small requires an Initial Attestation secure service based on symmetric
-key algorithms. Refer to PSA Attestation API document [8]_ for details of
-Initial Attestation based on symmetric key algorithms.
-
-It can heavily increase memory footprint to support Initial Attestation based on
-asymmetric key algorithms, due to asymmetric ciphers and related PKI modules.
-
-.. note ::
-
- **Implementation note**
-
- As pointed out by PSA Attestation API document [8]_, the use cases of
- Initial Attestation based on symmetric key algorithms can be limited due to
- the associated infrastructure costs for key management and operational
- complexities. It may also restrict the ability to interoperate with
- scenarios that involve third parties.
-
- If asymmetric key algorithms based Initial Attestation is required in use
- scenarios, it is recommended to select other TF-M Profiles which support
- asymmetric key algorithms.
-
-.. note ::
-
- **Implementation note**
-
- It is recommended to utilize the same MAC algorithm supported in Crypto
- service to complete the signing in ``COSE_Mac0``, to minimize memory
- footprint.
-
-Lightweight boot
-================
-
-If MCUBoot provided by TF-M is enabled, single image boot [9]_ is selected by
-default in Profile Small.
-In case of single image boot, secure and non-secure images are handled as a
-single blob and signed together during image generation.
-
-However, secure and non-secure images must be updated together in single image
-boot. It may decrease the flexibility of image update and cost longer update
-process. Since the image sizes should usually be small with limited
-functionalities in Profile Small dedicated use case, the cost may still be
-reasonable.
-
-BL2 implementation can be device specific. Devices may implement diverse
-boot processes with different features and configurations.
-However, anti-rollback protection is required as a mandatory feature of boot
-loader. Boot loader should be able to prevent unauthorized rollback, to protect
-devices from being downgraded to earlier versions with known vulnerabilities.
-
-**************
-Implementation
-**************
-
-Overview
-========
-
-The basic idea is to add dedicated profile CMake configuration files under
-folder ``config/profile`` for TF-M Profile Small default configuration.
-
-The top-level Profile Small config file collects all the necessary
-configuration flags and set them to default values, to explicitly enable the
-features required in Profile Small and disable the unnecessary ones, during
-TF-M build.
-
-A platform/use case can provide a configuration extension file to overwrite
-Profile Small default setting and append other configurations.
-This configuration extension file can be added via parameter
-``TFM_EXTRA_CONFIG_PATH`` in build command line.
-
-The behaviour of the Profile Small build flow (particularly the order of
-configuration loading and overriding) can be found at
-:ref:`tfm_cmake_configuration`
-
-The details of configurations will be covered in each module in
-`Implementation details`_.
-
-Implementation details
-======================
-
-This section discusses the details of Profile Small implementation.
-
-Top-level configuration files
------------------------------
-
-The firmware framework configurations in ``config/profile/profile_small`` are
-shown below.
-
-.. table:: TFM options in Profile Small top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================================================================================+=====================================+
- | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
-
-.. note ::
-
- **Implementation note**
-
- The following sections focus on the feature selection via configuration
- setting.
- Dedicated optimization on memory footprint is not covered in this document.
-
-Test configuration
-^^^^^^^^^^^^^^^^^^
-
-Standard regression test configuration applies. This means that enabling
-regression testing via
-
-``-DTEST_S=ON -DTEST_NS=ON``
-
-Will enable testing for all enabled partitions. See above for details of enabled
-partitions. Because Profile Small does not enable IPC mode, the IPC tests are
-not enabled.
-
-Some cryptography tests are disabled due to the reduced Mbed Crypto config.
-
-.. table:: TFM options in Profile Small top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================================================================================+=====================================+
- | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
-
-Device configuration extension
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To change default configurations and add platform specific configurations,
-a platform can add a platform configuration file at
-``platform/ext/config.cmake``
-
-TF-M framework setting
-----------------------
-
-The top-level Profile Small CMake config file selects Library model and level 1
-isolation.
-
-Crypto service configuration
-----------------------------
-
-Crypto Secure Partition
-^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Small enables Crypto Secure Partition (SP) in its top-level CMake
-config file. Crypto SP modules not supported in TF-M Profile Small are disabled.
-The disabled modules are shown below.
-
- - Disable asymmetric cipher
-
-Other modules and configurations [10]_ are kept as default values.
-
-Additional configuration flags with more fine granularity can be added to
-control building of specific crypto algorithms and corresponding test cases.
-
-Mbed Crypto configurations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TF-M Profile Small adds a dedicated Mbed Crypto config file
-``tfm_mbedcrypto_config_profile_small.h`` at
-``/lib/ext/mbedcrypto/mbedcrypto_config``
-file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_.
-
-Major Mbed Crypto configurations are set as listed below:
-
- - Enable SHA256
- - Enable generic message digest wrappers
- - Enable AES
- - Enable CCM mode for symmetric ciphers
- - Disable other modes for symmetric ciphers
- - Disable asymmetric ciphers
- - Disable HMAC-based key derivation function (HKDF)
-
-Other configurations can be selected to optimize the memory footprint of Crypto
-module.
-
-A device/use case can append an extra config header to the Profile Small
-default Mbed Crypto config file. This can be done by setting the
-``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
-config file ``platform/ext/config.cmake``. This cmake variable is
-a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
-it keeps all configuration in cmake.
-
-Internal Trusted Storage configurations
----------------------------------------
-
-ITS service is enabled in top-level Profile Small CMake config file.
-
-The internal transient buffer size ``ITS_BUF_SIZE`` [7]_ is set to 32 bytes by
-default. A platform/use case can overwrite the buffer size in its specific
-configuration extension according to its actual requirement of assets and Flash
-attributes.
-
-Profile Small CMake config file won't touch the configurations of device
-specific Flash hardware attributes [7]_.
-
-Initial Attestation secure service
-----------------------------------
-
-TF-M Profile Small provides a reference implementation of symmetric key
-algorithms based Initial Attestation, using HMAC SHA-256 as MAC algorithm in
-``COSE_Mac0`` structure. The implementation follows PSA Attestation API document
-[8]_.
-
-Profile Small top-level config file enables Initial Attestation secure service
-and selects symmetric key algorithms based Initial Attestation by default.
-
- - Set ``TFM_PARTITION_INITIAL_ATTESTATION`` to ``ON``
- - Set ``SYMMETRIC_INITIAL_ATTESTATION`` to ``ON``
-
-Symmetric and asymmetric key algorithms based Initial Attestation can share the
-same generations of token claims, except Instance ID claim.
-
-Profile Small may implement the procedure or rely on a 3rd-party tool to
-construct and sign ``COSE_Mac0`` structure.
-
-Details of symmetric key algorithms based Initial Attestation design will be
-covered in a dedicated document.
-
-Disabled secure services
-------------------------
-
-Audit logging, Protected Storage, and Platform Service are disabled by default
-in Profile Small top-level CMake config file.
-
-BL2 setting
------------
-
-Profile Small enables MCUBoot provided by TF-M by default. A platform can
-overwrite this configuration by disabling MCUBoot in its configuration extension
-file ``platform/ext/config.cmake``.
-
-If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M
-Profile Small top-level CMake config file.
-
-If a device implements its own boot loader, the configurations are
-implementation defined.
-
-.. table:: BL2 options in Profile Small top-level CMake config file
- :widths: auto
- :align: center
-
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | Configs | Default value | Descriptions |
- +============================================+=====================================================================================================+=====================================+
- | ``BL2`` | ``ON`` | Enable MCUBoot bootloader |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
- | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images |
- +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
-
-****************
-Platform support
-****************
-
-Building Profile Small
-======================
-
-To build Profile Small, argument ``TFM_PROFILE`` in build command line should be
-set to ``profile_small``.
-
-Take AN521 as an example.
-
-The following commands build Profile Small without test cases on **AN521** with
-build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_small \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- ../
- cmake --build ./ -- install
-
-The following commands build Profile Small with regression test cases on **AN521**
-with build type **MinSizeRel**, built by **Armclang**.
-
-.. code-block:: bash
-
- cd
- mkdir build && cd build
- cmake -DTFM_PLATFORM=mps2/an521 \
- -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
- -DTFM_PROFILE=profile_small \
- -DCMAKE_BUILD_TYPE=MinSizeRel \
- -DTEST_S=ON -DTEST_NS=ON \
- ../
- cmake --build ./ -- install
-
-.. Note::
-
- - For devices with more contrained memory and flash requirements, it is
- possible to build with either only TEST_S enabled or only TEST_NS enabled.
- This will decrease the size of the test images. Note that both test suites
- must still be run to ensure correct operation.
-
-More details of building instructions and parameters can be found TF-M build
-instruction guide [11]_.
-
-*********
-Reference
-*********
-
-.. [1] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_
-
-.. [2] `DEN0063 Arm Platform Security Architecture Firmware Framework 1.0 `_
-
-.. [3] `PSA analyze stage `_
-
-.. [4] `AES-CCM Cipher Suites for Transport Layer Security (TLS) `_
-
-.. [5] `Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms `_
-
-.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths `_
-
-.. [7] :doc:`ITS integration guide `
-
-.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) `_
-
-.. [9] :doc:`Secure boot `
-
-.. [10] :doc:`Crypto design `
-
-.. [11] :doc:`TF-M build instruction `
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/ps_key_management.rst b/docs/design_documents/ps_key_management.rst
deleted file mode 100644
index 80a39be492..0000000000
--- a/docs/design_documents/ps_key_management.rst
+++ /dev/null
@@ -1,183 +0,0 @@
-========================================
-Protected Storage service key management
-========================================
-
-:Author: Jamie Fox
-:Organization: Arm Limited
-:Contact: Jamie Fox
-:Status: Accepted
-
-Background
-==========
-The PSA Protected Storage API requires confidentiality for external storage to
-be provided by:
-
- **cryptographic ciphers using device-bound keys**, a tamper resistant
- enclosure, or an inaccessible deployment location, depending on the threat
- model of the deployed system.
-
-A TBSA-M-compliant device must embed a Hardware Unique Key (HUK), which provides
-the root of trust (RoT) for confidentiality in the system. It must have at least
-128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted
-code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_
-
-In the current implementation, the Protected Storage (PS) service reads the HUK
-directly and imports it into the Crypto partition for further use. This has
-multiple drawbacks:
-
-- If there were a flaw in PS that allowed an attacker to obtain its key, then
- the HUK would be exposed, and so the attacker would be able to decrypt not
- just protected storage but also anything else encrypted with the HUK or a key
- derived from the HUK.
-- Using the same key for two or more different cryptographic algorithms may
- reduce the security provided by one or more of them.
-- It is not possible to re-key if the HUK is used directly, for example in the
- case of a lost key.
-- It is incompatible with devices where the HUK is in an enclave and cannot be
- read directly.
-
-Proposal
-========
-Each time the system boots, PS will request that the Crypto service uses a key
-derivation function (KDF) to derive a storage key from the HUK. The storage key
-could be kept in on-chip volatile memory private to the Crypto partition, or it
-could remain inside a secure element. Either way it will not be returned to PS.
-
-For each call to the PSA Protected Storage APIs, PS will make requests to the
-Crypto service to perform AEAD encryption and/or decryption operations using the
-storage key (providing a fresh nonce for each encryption).
-
-At no point will PS access the key material itself, only referring to the HUK
-and storage key by their handles in the Crypto service.
-
-Key derivation
-==============
-PS will make key derivation requests to the Crypto service with calls to the
-PSA Crypto APIs. In order to derive the storage key, the following calls will be
-made::
-
- /* Open a handle to the HUK */
- psa_open_key(PSA_KEY_LIFETIME_PERSISTENT,
- TFM_CRYPTO_KEY_ID_HUK,
- &huk_key_handle)
-
- /* Set up a key derivation operation with the HUK as the input key */
- psa_key_derivation(&ps_key_generator,
- huk_key_handle,
- TFM_CRYPTO_ALG_HUK_DERIVATION,
- PS_KEY_SALT, PS_KEY_SALT_LEN_BYTES,
- PS_KEY_LABEL, PS_KEY_LABEL_LEN_BYTES,
- PS_KEY_LEN_BYTES)
-
- /* Create the storage key from the key generator */
- psa_generator_import_key(ps_key_handle,
- PS_KEY_TYPE,
- PSA_BYTES_TO_BITS(PS_KEY_LEN_BYTES),
- &ps_key_generator)
-
-.. note:: ``TFM_CRYPTO_KEY_ID_HUK`` is a PSA Crypto key ID that is assumed in
- this design to identify the hardware unique key.
-
- ``ps_key_handle`` is a PSA Crypto key handle to a volatile key, set
- up in the normal way. After the call to ``psa_generator_import_key``,
- it contains the storage key.
-
- ``PS_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract'
- step of HKDF, which is redundant when the input key material is a
- cryptographically strong key. [RFC5869]_ It must be constant so that
- the same key can be derived each boot, to decrypt previously-stored
- data.
-
- ``PS_KEY_LABEL`` can be any string that is independent of the input
- key material and different to the label used in any other derivation
- from the same input key. It prevents two different contexts from
- deriving the same output key from the same input key.
-
-In the call to ``psa_key_derivation()``, ``TFM_CRYPTO_ALG_HUK_DERIVATION`` is
-supplied as the key derivation algorithm argument. This indicates that the key
-derivation should be done from the HUK, and allows it to be implemented in a
-platform-defined way (e.g. using a crypto accelerator). The system integrator
-should choose the most optimal algorithm for the platform, or fall back to the
-software implementation if none is available.
-
-When implemented in software, the key derivation function used by the crypto
-service to derive the storage key will be HKDF, with SHA-256 as the underlying
-hash function. HKDF is suitable because:
-
-- It is simple and efficient, requiring only two HMAC operations when the length
- of the output key material is less than or equal to the hash length (as is the
- case here).
-- The trade-off is that HKDF is only suitable when the input key material has at
- least as much entropy as required for the output key material. But this is the
- case here, as the HUK has 128 bits of entropy, the same as required by PS.
-- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally
- analysed. [HKDF]_
-- It is supported by the TF-M Crypto service.
-
-The choice of underlying hash function is fairly straightforward: it needs to be
-a modern standardised algorithm, considered to be secure and supported by TF-M
-Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in
-the family, SHA-256 is the simplest and provides more than enough output length.
-
-Keeping the storage key private to PS
--------------------------------------
-The salt and label fields are not generally secret, so an Application RoT
-service could request the Crypto service to derive the same storage key from the
-HUK, which violates isolation between Application RoT partitions to some extent.
-This could be fixed in a number of ways:
-
-- Only PSA RoT partitions can request Crypto to derive keys from the HUK.
-
- - But then either PS has to be in the PSA RoT or request a service in the PSA
- RoT to do the derivation on its behalf.
-
-- PS has a secret (pseudo)random salt, accessible only to it, that it uses to
- derive the storage key.
-
- - Where would this salt be stored? It cannot be generated fresh each boot
- because the storage key must stay the same across reboots.
-
-- The Crypto service appends the partition ID to the label, so that no two
- partitions can derive the same key.
-
- - Still need to make sure only PSA RoT partitions can directly access the HUK
- or Secure Enclave. The label is not secret, so any actor that can access the
- HUK could simply perform the derivation itself, rather than making a request
- to the Crypto service.
-
-The third option would solve the issue with the fewest drawbacks, so this option
-is the one that is proposed.
-
-Key use
-=======
-To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same
-way as the current implementation, but ``ps_key_handle`` will refer to the
-storage key, rather than the imported HUK. For each encryption operation, the
-following call is made (and analogously for decryption)::
-
- psa_aead_encrypt(ps_key_handle, PS_CRYPTO_ALG,
- crypto->ref.iv, PS_IV_LEN_BYTES,
- add, add_len,
- in, in_len,
- out, out_size, out_len)
-
-Future changes
-==============
-In the future, the client's partition ID and the asset's UID could be used to
-derive a key that is unique to that asset, each time the Protected Storage APIs
-are called (*key diversification*). To achieve this, the key derivation must use
-a ``label`` parameter that is unique to each client ID, UID pair.
-
-References
-==========
-.. [TBSA-M] Arm Platform Security Architecture Trusted Base System Architecture
- for Armv6-M, Armv7-M and Armv8-M, version 1.0
-.. [HKDF] Hugo Krawczyk. 2010. Cryptographic extraction and key derivation: the
- HKDF scheme. In Proceedings of the 30th annual conference on Advances in
- cryptology (CRYPTO'10)
-.. [RFC5869] IETF RFC 5869: HMAC-based Extract-and-Expand Key Derivation
- Function (HKDF)
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/secure_boot_hw_key_integration.rst b/docs/design_documents/secure_boot_hw_key_integration.rst
deleted file mode 100644
index 186e4a649b..0000000000
--- a/docs/design_documents/secure_boot_hw_key_integration.rst
+++ /dev/null
@@ -1,166 +0,0 @@
-HW crypto key integration in TF-M secure boot
-=============================================
-
-:Author: Tamas Ban
-:Organization: Arm Limited
-:Contact: Tamas Ban
-:Status: Accepted
-
-Abstract
---------
-
-`PSA Trusted Boot and Firmware Update `__
-specification requires the support of at least one immutable root of trust
-public key (ROTPK) for firmware verification. This can be stored using a locked
-on-chip flash memory, a secure-element or on-chip OTP memory. It also beneficial
-to be able to provision these keys during the factory life-cycle of the device
-independently from any software components. The current key handling solution
-in TF-M secure boot does not supports this key provisioning process. MCUBoot
-requires compile time built-in public key(s) for image verification. This
-limitation does not fit well with a scenario with multiple vendors where
-multiple MCU software components might be deployed by different vendors in
-different points in the life-cycle of the device and they do not want to share
-the keys in-advance for embedding in the bootloader code. The goal of this
-document to propose a solution to decouple MCUBoot from public key(s) and
-enable the independent deployment of ROTPK.
-
-Existing key handling solution
-------------------------------
-
-MCUBoot code contains a compile-time built-in key array which can store any
-number of key(s) for firmware verification: ``bl2/ext/mcuboot/keys.c``. These
-public key(s) must be available when MCUBoot image is built. There is a script
-``bl2/ext/mcuboot/scipt/imgtool.py`` which can generate a new key pair, and
-extract the public key part in the expected ASN.1 format and encode it as C
-structure. The script is also capable of signing the image with the private key.
-In order to identify and validate the corresponding public key during image
-verification the hash of the public key is appended to the image manifest area
-(TLV encoded metadata). During image verification the bootloader retrieves the
-hash of the public key from the manifest area and compare against the on-the-fly
-calculated hash value of the built-in public keys. An exact match identifies and
-validates the public key which must be used for image verification.
-
-Current memory layout::
-
- |----------------------|
- | |
- | MCUBoot code |
- | |
- | Full public key |
- | |
- |----------------------|
- | |
- | Image |
- | |
- |----------------------|
- | Image Manifest(TLV) |
- | |
- | Hash of public key |
- |----------------------|
- | |
- | Rest of memory |
- | |
-
-Requirements
-------------
-
-- Multiple independent vendor scenario must be supported, when more than one
- ROTPK is provisioned to the device.
-- The corresponding public key for image verification must be identifiable and
- verifiable.
-- Key identity must be immutable and anchored to the device itself.
-- Key(s) can be provisioned independently from bootloader.
-
-Design proposal
----------------
-HW key(s) might stored in OTP memory which is an expensive resource, so
-storing a large key (such as RSA) is inefficient. Therefore, it is assumed that
-only the hash of the ROTPK will be stored in the HW. If only the hash of the
-public key is stored in the HW then the whole public key must be transfered to
-the device, because it must be available during image verification. This
-transfer can be done in the same way as how the hash of the key is transfered
-to the device with the current solution. A new TLV type (TLV_KEY) can be
-introduced to carry the whole public key. The corresponding public key will be
-appended to the image itself in the manifest area. It has the drawback that the
-image will be bigger, but it is assumed that the additional cost of the bigger
-image (extra flash area + power for download) is less than the cost of the OTP
-area.
-
-The verification flow:
-
- - Look up the TLV_KEY field to get the public key.
- - Calculates its hash(SHA256) value.
- - Get the hash of ROTPK from the platform layer (stored in HW)
- - Compare the two hash values, if they match then the key can be used to
- validate the image. In case of failure consider the images as unauthenticated.
-
-Proposed memory layout::
-
- |----------------------|
- | |
- | MCUBoot code |
- | |
- | NO PUBLIC KEY |
- | |
- |----------------------|
- | |
- | Image |
- | |
- |----------------------|
- | Image Manifest(TLV) |
- | |
- | Full public key |
- |----------------------|
- | |
- | |
- | Rest of memory |
- | |
- | |
- |----------------------|
- | Immutable memory |
- | |
- | Hash of public key |
- |----------------------|
- | |
-
-Platform support
-----------------
-
-A new platform API used by the bootloader must be introduced to retrieve the
-image corresponding hash of ROTPK:
-
-``enum tfm_plat_err_t tfm_plat_get_rotpk_hash(uint8_t image_id,
-uint8_t *rotpk_hash, uint32_t *rotpk_hash_size);``
-
-The mapping between image identity and public key can be hard-code in the
-platform layer. This simplifies the validation of the public key, because no
-look-up would be needed. It is assumed that the memory area of the ROTPK hash is
-not directly accessible, therefore a buffer is allocated by the caller to store
-the hash there.
-
-Compile time configurability
-----------------------------
-
-The solution must be compile time configurable in order to be able to switch
-between built-in key(s) and HW key(s) support, and also due to backwards
-compatibility.
-
-Tooling
--------
-
-``bl2/ext/mcuboot/scipt/imgtool.py`` will be modified to include the whole
-public key to the TLV area (instead of the hash).
-
-Table to compare the current and proposed solution::
-
- |---------|-----------------------|-------------------|--------------------|
- | |Key format in manifest |Key in MCUBoot code| Key in HW |
- |---------|-----------------------|-------------------|--------------------|
- |Proposed | Full public key | No key embedded | Hash of public key |
- |---------|-----------------------|-------------------|--------------------|
- |Current | Hash of public key | Full public key | No key in HW |
- |---------|-----------------------|-------------------|--------------------|
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/secure_boot_rollback_protection.rst b/docs/design_documents/secure_boot_rollback_protection.rst
deleted file mode 100644
index 711fac321e..0000000000
--- a/docs/design_documents/secure_boot_rollback_protection.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-#######################################
-Rollback protection in TF-M secure boot
-#######################################
-
-:Author: Tamas Ban
-:Organization: Arm Limited
-:Contact: Tamas Ban
-:Status: Accepted
-
-Anti-rollback protection
-========================
-The goal of anti-rollback protection is to prevent downgrading of the device to
-an older version of its software, which has been deprecated due to security
-concerns.
-
-Elements of software upgrade
-============================
-During a software upgrade the following entities are involved:
-
- - Boot loader
- - Manifest data: Metadata of the software image: size, version, hash,
- signature, etc.
- - Software image: binary data, elf, etc.
-
-Validation of new image
-=======================
-Boot loader is responsible to authenticate the new image according to the
-required policies and decide whether the new image is fulfilling all the
-requirements. Boot loader verifies the image integrity (hash calculation) and
-the origination (signature validation), and might verify other requirements as
-well. If the new image is successfully authenticated then the boot loader is in
-charge to do the necessary steps (load to execute address, etc.) to enable the
-new image to be executed. During the validation process the image and the
-manifest data is checked.
-
-Manifest format in MCUBoot
-==========================
-MCUBoot has a custom manifest format, which is composed of two parts:
-
- - Image header: Prepended to the beginning of the image.
- It is integrity protected:
- - TLV section: Appended to the end of the image. It is not integrity protected:
-
- - Hash of public key, hash of image, signature of image
-
-.. code-block:: c
-
- struct image_header {
- uint32_t ih_magic;
- uint32_t ih_load_addr;
- uint16_t ih_hdr_size;
- uint16_t _pad1;
- uint32_t ih_img_size;
- uint32_t ih_flags;
- struct image_version ih_ver;
- uint32_t _pad2;
- };
-
-Security counter
-================
-The aim of a security counter is to have an independent (from the image version)
-counter in the image manifest to ensure anti-rollback protection. During
-software release the value of this counter must be increased if a security flaw
-was fixed in the current version. Later when this image is installed on the
-device then it is not allowed to go back to earlier versions. It is beneficial
-to handle this counter independently from image main version number:
-
- - It does not need to increase with each software release
- - It makes it possible to do software downgrade to some extent: if the security
- counter has the same value in the older image then it is accepted.
- - If the boot loader verifies multiple images then these can be handled
- independently.
-
-However, as an alternative solution the image version number also could serve
-as the security counter of the image. Even the version number itself could be
-checked during the anti-rollback verification or the value of the security
-counter could be derived from the image main version. It is the responsibility
-of the software issuer to define which policy to apply.
-
-Implementation of security counter
-==================================
-The value of the security counter is a security critical data. Any change in
-its value has a security implication. Therefore it must be in the integrity
-protected part of the image manifest. Because the image header is almost fully
-utilized (few unused fields) and the change of image header structure could
-lead to compatibility issues between boot loader and runtime software, it is
-proposed to extend the integrity protection to some part of the TLV section.
-One of the unused fields in the image header can be used to store the size of
-the integrity protected area of the TLV section. This is necessary to know how
-to calculate properly the image hash and signature. With this extension of the
-integrity protected area other attributes that require integrity protection
-can easily be added to the image manifest.
-
-Trusted non-volatile (NV) counters
-==================================
-The Trusted Base System Architecture (TBSA-M) defines non-volatile (NV) counters
-or version counters as a counter with the following properties:
-
- - It must only be possible to increment a version counter through a Trusted
- access.
- - It must only be possible to increment a version counter. It must not be
- possible to decrement it.
- - When a version counter reaches its maximum value, it must not roll over,
- and no further changes must be possible.
- - A version counter must be non-volatile, and the stored value must survive
- a power down period up to the lifetime of the device.
-
-Trusted non-volatile counters can be used to store the value of security
-counters per updatable software image. Ideally all independently updatable
-software images should have a separate security counter. In current TF-M
-implementation the BL2 is not updatable and the secure and non-secure images
-are updated together as a single binary. Therefore, one counter is enough to
-implement rollback protection. In future the secure and non-secure binaries
-will be handled independently; at that time the introduction of a second
-counter will be necessary.
-
-Currently the NV counters can be manipulated through the interface described
-in ``tfm_plat_nv_counters.h``.
-
-NV counters and anti-rollback protection
-========================================
-Trusted non-volatile counters might not be supported by a hardware platform.
-In this case anti-rollback protection might still be feasible.
-
-The device threat model needs to consider the following aspects:
-
- - What is the trust level of the boot loader towards the active software
-
- - If the boot loader cannot protect the anti-rollback mechanism from the
- secure image then the following threat is unmitigated: The content of the
- memory area which holds the active image could be replaced with a valid but
- an older version of the software with software only attack, i.e.: remote
- code execution.
- - If the boot loader does not trust the loaded image at all then security
- counter must have a copy in NV counter area.
-
- - Another aspect to consider is where the active image is stored
-
- - Trusted memory: i.e. on-chip flash (eFlash). The threat that a malicious
- actor can modify the content of trusted memory with HW attack is out of
- scope for the current implementation. It is assumed that if an active image
- and related manifest data is stored in trusted memory then the included
- security counter cannot be compromised.
- - Untrusted memory: i.e. external (off-chip) storage, where malicious actor
- can physically access it so it is possible to modify its content, therefore
- the value of included security counter is unreliable.
-
-If the active image is stored in untrusted storage and it is feasible to modify
-its content (i.e. replace the whole image to an older version including
-corresponding manifest) then the value of security counter must be copied to
-the NV counter area. During software validation the boot loader must compare
-the new image's security counters against the security counter stored in
-non-volatile counters.
-
-If the active image is stored in trusted memory and boot loader trusts in the
-active software then it is not mandatory to store the security counter to
-non-volatile counter area. During software validation the boot loader is
-allowed to compare the new image's security counters against active image's
-security counter.
-
-The evaluation of trusted and untrusted memory must be done per target platform
-during threat modelling.
-
-For the most robust implementation the following principles should be applied:
-
- - Always use NV counters for storing security counter value if supported by
- the hardware.
- - Each software stage must not be able to decrease their corresponding NV
- counter.
-
-Boot flow with anti-rollback protection
-=======================================
-During software upgrade as part of the image validation process the new and
-active image security counters must be compared. The new image can be accepted
-if its security counter has a greater or equal value than the active image
-security counter. From where to extract the active image security counter it
-can be platform dependent. It might read out directly from active image
-manifest data (only if it is in trusted memory) or the corresponding
-non-volatile counter is read.
-
-If non-volatile counters are used to save security counters then their value
-must be updated:
-
- - If the boot loader does not support to revert previous images (just
- overwrites the previously active image with the new one) in case of faulty
- update then the non-volatile counter can be updated to be equal with the
- new image security counter after successful authentication of the new image.
- - If revert is supported then non-volatile counter can be updated just after
- a test run of the new software when its health check is done. Just in case
- of successful health check can the counter updated to avoid the prevention
- of the revert. This might require a secondary restart of the device.
-
-Tool support
-============
-There is a Python script, ``imgtool.py`` which is used to prepare the new image
-for upgrade (add header, sign the image, append TLV section). This script must
-be modified to get an additional command line argument which serves as security
-counter. The security counter must be included in the integrity protected part
-of the TLV section.
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/secure_enclave_solution.rst b/docs/design_documents/secure_enclave_solution.rst
deleted file mode 100644
index ce665ac229..0000000000
--- a/docs/design_documents/secure_enclave_solution.rst
+++ /dev/null
@@ -1,122 +0,0 @@
-##############################################
-Secure Enclave solution for Trusted Firmware-M
-##############################################
-
-:Author: Mark Horvath
-:Organization: Arm Limited
-:Contact: Mark Horvath
-:Status: Draft
-
-********
-Abstract
-********
-
-This document summarizes the design goals and one possible implementation
-of the TF-M Secure Enclave solution.
-
-************
-Introduction
-************
-
-If a separate subsystem can provide the PSA Root of Trust (RoT) in a system
-then an additional physical separation exists between the most trusted and
-other domains. In such a system at least two subsystems are present, a Secure
-Enclave (SE) whose only task is to provide PSA RoT and an application core
-where any other application specific functionality can be placed. The latter
-core (or cores) are referred as *Host* in this document.
-
-The current design assumes that Host is a v8-m core with security extension.
-
-************
-Requirements
-************
-
-- Secure Enclave shall implement secure boot-flow (start-up first at reset and
- validate its own and the Host image or images before release Host from reset)
-- Secure Enclave shall provide the PSA RoT services
-- Host shall provide not just the non-secure context but the Application RoT as
- well
-- It shall be transparent to the (secure or non-secure) applications running on
- host whether the RoT services are provided by the same subsystem or by a
- Secure Enclave.
-
-.. Note::
-
- In comparison, in a Dual Core system the whole secure context is placed on a
- separate subsystem, while a Secure Enclave only implements the PSA RoT
- security domain.
-
-***************
-Proposed design
-***************
-
-As the clients and the services are running on different cores only the IPC
-model can be used on both Secure Enclave and Host.
-
-Secure Enclave
-==============
-
-To provide the required functionality it is enough to run the current PSA RoT
-secure partitions on the Secure Enclave, so no need for non-secure context
-there. (It is enough if the Secure Enclave's architecture is v6-m, v7-m or v8-m
-without the security extension.)
-
-Secure Enclave can treat all clients running on Host as non-secure (even the
-services running on Host's secure side). This means that fom Secure Enclave's
-point of view all Host images, Host's RAM and shared memory between Host and
-Secure Enclave if present are treated as non-secure. (Just like in the Dual CPU
-solution.) But the clients need to be distinguished, otherwise some
-functionalities are not working, for example:
-- Protected Storage partition shall run on Host, but the PS area is handled by
-Internal Trusted Storage partition (running on Secure Enclave). ITS partition
-decides whether it should work on PS or ITS assets by checking the client ID.
-- If a secure partition on host creates a crypto key, no other client shall be
-able to destroy it.
-
-Communication
-=============
-
-To communicate between Host and Secure Enclave, the existing mailbox solution
-can be reused as it is.
-
-Host
-====
-
-On Host the current TF-M software architecture can be placed to provide
-non-secure context and Application RoT domain.
-
-One solution to forward a PSA RoT IPC message from a client running on Host to
-the Secure Enclave is to add a proxy partition to the secure side. This PSA
-Proxy partition can provide all the RoT services to the system by forwarding
-the messages over the mailbox solution.
-
-If the new partition's manifest contains all the PSA RoT service IDs SPM will
-deliver all IPC messages there. Then the messages just must be blindly copied
-into the mailbox. PSA proxy can use the non-secure interface of the mailbox,
-but it is placed on the secure side of Host. (From SE's point of view this is
-in fact the non-secure side of the mailbox as whole Host is treated as
-non-secure.)
-
-It is important to verify IOVECs before forwarding them to SE, otherwise a
-malicous actor could use SE to access a memory area otherwise unaccessable. If
-PSA proxy uses the current secure partition interface then this is ensured by
-Host's SPM.
-
-SE treats all clients of Host as non-secure, so all PSA messages shall have a
-negative client ID when pushed into SE's SPM. This is given for the clients on
-the non-secure side of Host, but the secure side clients of Host have positive
-client IDs. The straightforward solution is to translate the positive client
-IDs into a predefined negative range in PSA proxy, and push the translated
-values into the mailbox. Of course this range shall be reserved for this use
-only and no clients on non-secure side of Host shall have client ID from this
-range.
-
-To avoid blocking Host when a message is sent PSA Proxy shall handle the
-service requests in non-blocking mode. And to maximize bandwidth PSA Proxy
-shall be able to push new messages into the mailbox, while others still not
-answered. To achieve these the mailbox interrupts needs to be handled in the
-PSA Proxy partition.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/source_structure.rst b/docs/design_documents/source_structure.rst
deleted file mode 100644
index a549bf7515..0000000000
--- a/docs/design_documents/source_structure.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-###################################
-Trusted Firmware-M Source Structure
-###################################
-
-:Organization: Arm Limited
-:Contact: tf-m@lists.trustedfirmware.org
-
-.. note::
- Reference the document :doc:`Glossary ` for terms
- and abbreviations.
-
-************
-Introduction
-************
-TF-M is designed to provide a user-friendly source structure to ease
-integration and service development. This document introduces the source
-structure and its design intention of TF-M.
-
-.. note::
- - This document goes ahead of the implementation so the existing source
- structure may be different from the description listed here. It is
- recommended to refer to this document for ongoing code structure changes.
- - By getting feedback from the practical implementation, this document is
- updated continuously before it is detailed enough to be a user guide.
-
-****************
-Source Structure
-****************
-The description of the source structure is broken down into subsections, each
-subsection introduces one detailed folder.
-
-Root Directory
-==============
-This table describes the structure under the root directory with part of
-possible folders. Note that the ``Detailed`` field indicates if the folder is
-described in details here in this document:
-
-============= ==================================== ====================
-Folder name Purpose Detailed
-============= ==================================== ====================
-bl2 The 2nd stage bootloader. No.
-cmake Cmake files. No.
-configs Configuration system files. No.
-docs The documentations. No.
-lib The 3rd party library. No.
-**platform** Platform intermedia files. See `'platform'`_.
-**secure_fw** The secure firmware. See `'secure_fw'`_.
-tools Tools in scripts for building. No.
-============= ==================================== ====================
-
-'platform'
-==========
-The platform sources contain necessary platform sources or intermedia files
-pointing to the sources out of TF-M folder.
-
-========================= =============================================
-Folder name Purpose
-========================= =============================================
-common/\* Common HAL implementation.
-include/\* Platform public headers.
- Vendor specific folders.
-========================= =============================================
-
-.. note::
- The ``common`` folder contains the example implementation of the ``HAL`` API
- bases on common ``system`` (CMSIS e.g.). The platform could reference to
- sources in the ``common`` folder directly if applicable or apply a
- customized HAL implementation.
- A ``system`` can have a standalone folder under ``common``, depends on how
- 'common' this system is. Each ``platform vendor`` is assigned with one
- folder for usage. As the content of the ``vendor`` folder comes by the
- contribution of vendors, the ``vendor`` manages the structure inside it.
-
-'secure_fw'
-===========
-This folder contains components needed by secure firmware, and the exported
-interfaces for application, service development and HAL integration:
-
-================= ===================================== ======================
-Folder name Purpose Detailed
-================= ===================================== ======================
-**include** Public headers of 'secure_fw'. See `'include'`_
-**partitions** Default services and supportings. See `'partitions'`_
-**spm** PSA-FF-M SPM implementation. [1] See `'spm'`_
-================= ===================================== ======================
-
-.. note::
- 1. A PSA-FF-M complied SPM implementation.
-
- The headers referenced by other modules are public headers and put under the
- 'include' folder of the current module. Do not put headers not referenced by
- other modules in this 'include' folder.
-
-'include'
----------
-This folder holds headers for client, services and platform integration usage.
-
-=========================== ===================================================
-Folder name Purpose
-=========================== ===================================================
-psa/\* PSA FF Client API.
-=========================== ===================================================
-
-.. note::
- TFM applies an explicit including policy. Each module's headers are put into
- a specific folder which follows the pattern '\*/inc', this folder needs to be
- added into the project's searching path if this project needs to include
- headers in this folder. The 'inc' in a path indicates the end of
- including-path. If there are subfolders under folder 'inc', apply a
- hierarchy including.
-
-'partitions'
-------------
-This folder contains default services implemented as partitions and necessary
-partition runtime utilities provided by TF-M.
-
-================================= =============================================
-Folder name Purpose
-================================= =============================================
-lib/sprt/\* The SPRTL sources and intermedia files. [1]
-lib/sprt/shared\* Sources can be shared by out of SPRTL. [2]
-/\* Files for 'partition_x'.
-/include/\* RoT Service API headers of 'partition_x'. [3]
-/\* Files for 'partition_y'.
-/include/\* RoT Service API headers of 'partition_y'. [3]
-================================= =============================================
-
-.. note::
- 1. The SPRTL sources and intermediate files. SPRTL contains sources from
- other folders, such as necessary RoT Service API implementation from
- 'partitions' folder.
- 2. The sources here can be referenced by the building system out of SPRTL.
- Generally, they are runtime and PSA APIs.
- 3. Here takes 'partition_x' and 'partition_y' as an example, and showcases
- a detailed structure of them. The `` contains the RoT Service
- API for client calls. The folder name of this client-orient folder is
- decided by the service developer.
-
-'spm'
------
-The SPM is the core component to provide a mechanism for providing secure
-services.
-
-=================================== ===========================================
-Folder name Purpose
-=================================== ===========================================
-include/\* SPM public headers.
-ffm/\* SPM logic complies with PSA-FF-M and
- its necessary supporting functionalities,
- such as the runtime API and the thread
- operation, etc.
-cmsis_psa/\* CMSIS implementation for PSA-FF-M SPM. [1]
-cmsis_func/\* The library model implementation. [2]
-\* Implementation sources.
-=================================== ===========================================
-
-.. note::
- 1. CMSIS is the first implementation system.
- 2. This folder contains a function call based secure firmware implementation.
- This model is the prototype model which would be updated after the PSA
- model. Create a standalone folder to hold it.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/symmetric_initial_attest.rst b/docs/design_documents/symmetric_initial_attest.rst
deleted file mode 100644
index 00642b87ec..0000000000
--- a/docs/design_documents/symmetric_initial_attest.rst
+++ /dev/null
@@ -1,601 +0,0 @@
-#################################################
-Symmetric key algorithm based Initial Attestation
-#################################################
-
-:Authors: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
-************
-Introduction
-************
-
-This document proposes a design of symmetric key algorithm based Initial
-Attestation in TF-M.
-
-Symmetric key algorithm based Initial Attestation
-(*symmetric Initial Attestation* for short) signs and verifies Initial
-Attestation Token (IAT) with a symmetric cryptography signature scheme, such as
-HMAC.
-It can reduce TF-M binary size and memory footprint on ultra-constrained devices
-without integrating asymmetric ciphers.
-
-This proposal follows PSA Attestation API document [1]_.
-
-.. note ::
-
- As pointed out by PSA Attestation API [1]_, the use cases of Initial
- Attestation based on symmetric key algorithms can be limited due to
- the associated infrastructure costs for key management and operational
- complexities. It may also restrict the ability to interoperate with
- scenarios that involve third parties.
-
-***************
-Design overview
-***************
-
-The symmetric Initial Attestation follows the existing IAT generation sequence
-for Initial Attestation based on asymmetric key algorithm
-(*asymmetric Initial Attestation* for short).
-
-As Profile Small design [2]_ requests, a configuration flag
-``SYMMETRIC_INITIAL_ATTESTATION`` selects symmetric initial attestation during
-build.
-
-The top-level design is shown in :ref:`overall-diagram-figure` below.
-
-.. _overall-diagram-figure:
-
-.. figure:: media/symmetric_initial_attest/overall_diagram.png
- :align: center
-
- Overall design diagram
-
-Symmetric Initial Attestation adds its own implementations of some steps in IAT
-generation in Initial Attestation secure service. More details are covered in
-`IAT generation in Initial Attestation secure service`_.
-
-The interfaces and procedures of Initial Attestation secure service are not
-affected. Refer to Initial Attestation Service Integration Guide [3]_ for
-details of the implementation of Initial Attestation secure service.
-
-Symmetric Initial Attestation invokes ``t_cose`` library to build up
-``COSE_Mac0`` structure.
-``COSE_Mac0`` support is added to ``t_cose`` library in TF-M since official
-``t_cose`` hasn't supported ``COSE_Mac0`` yet. The design of ``COSE_Mac0``
-support is covered in `COSE_Mac0 support in t_cose`_.
-
-.. note ::
-
- The ``COSE_Mac0`` implementation in this proposal is a prototype only for
- Proof of Concept so far. It may be replaced after ``t_cose`` officially
- supports ``COSE_Mac0`` message.
-
-Several HAL APIs are defined to fetch platform specific assets required by
-Symmetric Initial Attestation. For example, ``tfm_plat_get_symmetric_iak()``
-fetches symmetric Initial Attestation Key (IAK). Those HAL APIs are summarized
-in `HAL APIs`_.
-
-Decoding and verification of symmetric Initial Attestation is also included in
-this proposal for regression test.
-The test suites and IAT decoding are discussed in `TF-M Test suite`_.
-
-``QCBOR`` library and Crypto service are also invoked. But this proposal doesn't
-require any modification to either ``QCBOR`` or Crypto service. Therefore,
-descriptions of ``QCBOR`` and Crypto service are skipped in this document.
-
-****************************************************
-IAT generation in Initial Attestation secure service
-****************************************************
-
-The sequence of IAT generation of symmetric Initial Attestation is shown in
-:ref:`ia-service-figure` below.
-
-.. _ia-service-figure:
-
-.. figure:: media/symmetric_initial_attest/ia_service_flow.png
- :align: center
-
- Symmetric IAT generation flow in Initial Attestation secure service
-
-In Initial Attestation secure service, symmetric Initial Attestation implements
-the following steps in ``attest_create_token()``, which are different from those
-of asymmetric Initial Attestation.
-
- - Fetch and register IAK
- - ``attest_token_start()``
- - Instance ID claims
- - ``attest_token_finish()``
-
-If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, symmetric Initial Attestation
-dedicated implementations of those steps are included in build.
-Otherwise, asymmetric Initial Attestation dedicated implementations are included
-instead.
-
-Symmetric Initial Attestation implementation resides a new file
-``attest_symmetric_key.c`` to handle symmetric IAK and Instance ID related
-operations.
-Symmetric Initial Attestation dedicated ``attest_token_start()`` and
-``attest_token_finish()`` are added in ``attestation_token.c``.
-
-The details are covered in following sections.
-
-Register symmetric IAK
-======================
-
-Symmetric Initial Attestation dedicated ``attest_symmetric_key.c`` implements 4
-major functions. The functions are listed in the table below.
-
-.. table:: Functions in ``attest_symmetric_key.c``
- :widths: auto
- :align: center
-
- +-------------------------------------------------+----------------------------------------------------+
- | Functions | Descriptions |
- +=================================================+====================================================+
- | ``attest_register_initial_attestation_key()`` | Fetches device symmetric IAK, imports it into |
- | | Crypto service and get the handle. |
- | | The handle will be used to compute the |
- | | authentication tag of IAT. |
- | | Invokes HAL API ``tfm_plat_get_symmetric_iak()`` |
- | | to fetch symmetric IAK from device. |
- | | |
- | | Refer to `HAL APIs`_ for more details. |
- +-------------------------------------------------+----------------------------------------------------+
- | ``attest_unregister_initial_attestation_key()`` | Destroys the symmetric IAK handle after IAT |
- | | generation completes. |
- +-------------------------------------------------+----------------------------------------------------+
- | ``attest_get_signing_key_handle()`` | Return the IAK handle registered in |
- | | ``attest_register_initial_attestation_key()``. |
- +-------------------------------------------------+----------------------------------------------------+
- | ``attest_get_instance_id()`` | Return the Instance ID value calculated in |
- | | ``attest_register_initial_attestation_key()``. |
- | | |
- | | Refer to `Instance ID claim`_ for more details. |
- +-------------------------------------------------+----------------------------------------------------+
-
-``attest_register_initial_attestation_key()`` and
-``attest_unregister_initial_attestation_key()`` share the same API declarations
-with asymmetric Initial Attestation.
-
-``attest_get_signing_key_handle()`` and ``attest_get_instance_id()`` are defined
-by symmetric Initial Attestation but can be shared with asymmetric Initial
-Attestation later.
-
-.. note ::
-
- Only symmetric IAK for HMAC algorithm is allowed so far.
-
-Instance ID calculation
------------------------
-
-In symmetric Initial Attestation, Instance ID is also calculated in
-``attest_register_initial_attestation_key()``, after IAK handle is registered.
-It can protect critical symmetric IAK from being frequently fetched, which
-increases the risk of asset disclosure.
-
-The Instance ID value is the output of hashing symmetric IAK raw data *twice*,
-as requested in PSA Attestation API [1]_. HMAC-SHA256 may be hard-coded as the
-hash algorithm of Instance ID calculation.
-
-.. note ::
-
- According to RFC2104 [4]_, if a HMAC key is longer than the HMAC block size,
- the key will be first hashed. The hash output is used as the key in HMAC
- computation.
-
- In current design, HMAC is used to calculate the authentication tag of
- ``COSE_Mac0``. Assume that symmetric IAK is longer than HMAC block size
- (HMAC-SHA256 by default), the Instance ID is actually the HMAC key for
- ``COSE_Mac0`` authentication tag generation, if Instance ID value is the
- output of hashing IAK only *once*.
- Therefore, attackers may request an valid IAT from device and fake malicious
- ones by using Instance ID to calculate valid authentication tags, to cheat
- others.
-
- As a result, symmetric IAK raw data should be hashed *twice* to generate the
- Instance ID value.
-
-The Instance ID calculation result is stored in a static buffer.
-Token generation process can call ``attest_get_instance_id()`` to
-fetch the data from that static buffer.
-
-attest_token_start()
-====================
-
-Symmetric Initial Attestation dedicated ``attest_token_start()`` initializes the
-``COSE_Mac0`` signing context and builds up the ``COSE_Mac0`` Header.
-
-The workflow inside ``attest_token_start()`` is shown in
-:ref:`attest-token-start-figure` below.
-
-.. _attest-token-start-figure:
-
-.. figure:: media/symmetric_initial_attest/attest_token_start.png
- :align: center
-
- Workflow in symmetric Initial Attestation ``attest_token_start()``
-
-Descriptions of each step are listed below:
-
-#. ``t_cose_mac0_sign_init()`` is invoked to initialize ``COSE_Mac0`` signing
- context in ``t_cose``.
-
-#. The symmetric IAK handle is returned by ``attest_get_signing_key_handle()``.
- See the details in `Register symmetric IAK`_.
-
-#. The symmetric IAK handle is set into ``COSE_Mac0`` signing context via
- ``t_cose_mac0_set_signing_key()``.
-
-#. Initialize ``QCBOR`` encoder.
-
-#. The header parameters are encoded into ``COSE_Mac0`` structure in
- ``t_cose_mac0_encode_parameters()``.
-
-#. ``QCBOREncode_OpenMap()`` prepares for encoding the ``COSE_Mac0`` payload,
- which is filled with IAT claims.
-
-All the ``COSE_Mac0`` functionalities in ``t_cose`` are covered in
-`COSE_Mac0 support in t_cose`_.
-
-Instance ID claim
-=================
-
-Symmetric Initial Attestation also implements Instance ID claims in
-``attest_add_instance_id_claim()``.
-
-The Instance ID value is fetched via ``attest_get_instance_id()``.
-The value has already been calculated during symmetric IAK registration. See
-`Instance ID calculation`_ for details.
-
-The other steps are the same as those in asymmetric Initial Attestation
-implementation. The UEID type byte is set to 0x01.
-
-attest_token_finish()
-=====================
-
-Symmetric Initial Attestation dedicated ``attest_token_finish()`` calls
-``t_cose_mac0_encode_tag()`` to calculate and encode the authentication tag of
-``COSE_Mac0`` structure.
-
-The whole COSE and CBOR encoding are completed in ``attest_token_finish()``.
-
-The simplified flow in ``attest_token_finish()`` is shown in
-:ref:`attest-token-finish-figure` below.
-
-.. _attest-token-finish-figure:
-
-.. figure:: media/symmetric_initial_attest/attest_token_finish.png
- :align: center
-
- Workflow in symmetric Initial Attestation ``attest_token_finish()``
-
-***************************
-COSE_Mac0 support in t_cose
-***************************
-
-``COSE_Mac0`` supports in ``t_cose`` in TF-M include the following major
-functionalities:
-
- - Encoding ``COSE_Mac0`` structure
- - Decoding and verifying ``COSE_Mac0`` structure
- - HMAC computation to generate and verify authentication tag
- - Short-circuit tagging for test mode
-
-According to RFC8152 [5]_, ``COSE_Mac0`` and ``COSE_Sign1`` have similar
-structures. Therefore, the prototype follows ``COSE_Sign1`` implementation to
-build up ``COSE_Mac0`` file structure and implement ``COSE_Mac0`` encoding and
-decoding.
-
-Although ``COSE_Mac0`` can share lots of data types, APIs and encoding/decoding
-steps with ``COSE_Sign1`` in implementation, this prototype separates
-``COSE_Mac0`` implementation from ``COSE_Sign1``. ``COSE_Mac0`` owns its
-dedicated signing/verification contexts, APIs and encoding/decoding process.
-The purposes of separating ``COSE_Mac0`` and ``COSE_Sign1`` are listed below
-
-- It can keep changes to ``COSE_Sign1`` as small as possible and avoid conflicts
- with development in ``COSE_Sign1```. It can decrease conflicts if ``t_cose``
- in TF-M is synchronized with original ``t_cose`` repository later.
-- ``COSE_Mac0`` and ``COSE_Sign1`` are exclusive in TF-M use cases.
- It cannot decrease TF-M memory footprint by extracting the common components
- shared by ``COSE_Mac0`` and ``COSE_Sign1`` but can make the design
- over-complicated.
-
-.. note ::
-
- Only HMAC is supported in current ``COSE_Mac0`` prototype.
-
-File structure
-==============
-
-New files are added to implement the functionalities listed above. The structure
-of files is shown in the table below.
-
-.. table:: New files in ``t_cose``
- :widths: auto
- :align: center
-
- +---------------------+--------------------------------+----------------------------------------------+
- | Directory | Files | Descriptions |
- +=====================+================================+==============================================+
- | ``src`` | ``t_cose_mac0_sign.c`` | Encode ``COSE_Mac0`` structure |
- | +--------------------------------+----------------------------------------------+
- | | ``t_cose_mac0_verify.c`` | Decode and verify ``COSE_Mac0`` structure. |
- +---------------------+--------------------------------+----------------------------------------------+
- | ``inc`` | ``t_cose_mac0_sign.h`` | Data type definitions and function |
- | | | declarations of encoding and signing |
- | | | ``COSE_Mac0`` message. |
- | +--------------------------------+----------------------------------------------+
- | | ``t_cose_mac0_verify.h`` | Data type definitions and function |
- | | | declarations of verifying ``COSE_Mac0`` |
- | | | message. |
- +---------------------+--------------------------------+----------------------------------------------+
-
-Other ``t_cose`` files may also be changed to add ``COSE_Mac0`` associated data
-types and function declarations.
-
-HMAC operations are added in ``crypto_adapters/t_cose_psa_crypto.c``.
-Preprocessor flags are added to select corresponding crypto for COSE message
-signing and verification.
-
- - ``T_COSE_ENABLE_SIGN1`` selects ECDSA and Hash operations for
- ``COSE_Sign1``.
- - ``T_COSE_ENABLE_MAC0`` selects HMAC operations for ``COSE_Mac0``.
-
-Encoding COSE_Mac0
-==================
-
-Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` encoding exports similar
-functions to Initial Attestation secure service.
-The major functions are listed below.
-
-Initialize signing context
---------------------------
-
-``t_cose_mac0_sign_init()`` initializes ``COSE_Mac0`` signing context and
-configures option flags and algorithm used in signing.
-
-.. code-block:: c
-
- static void
- t_cose_mac0_sign_init(struct t_cose_mac0_sign_ctx *me,
- int32_t option_flags,
- int32_t cose_algorithm_id);
-
-The ``COSE_Mac0`` signing context is defined as
-
-.. code-block:: c
-
- struct t_cose_mac0_sign_ctx {
- /* Private data structure */
- uint8_t protected_parameters_buffer[
- T_COSE_MAC0_MAX_SIZE_PROTECTED_PARAMETERS];
- struct q_useful_buf_c protected_parameters; /* The encoded protected parameters */
- int32_t cose_algorithm_id;
- struct t_cose_key signing_key;
- int32_t option_flags;
- struct q_useful_buf_c kid;
- ...
- };
-
-Set signing key
----------------
-
-``t_cose_mac0_set_signing_key()`` sets the key used in ``COSE_Mac0`` signing.
-Optional ``kid``, as a key identifer, will be encoded into ``COSE_Mac0`` Header
-unprotected bucket.
-
-.. code-block:: c
-
- static void
- t_cose_mac0_set_signing_key(struct t_cose_mac0_sign_ctx *me,
- struct t_cose_key signing_key,
- struct q_useful_buf_c kid);
-
-Encode Header parameters
-------------------------
-
-``t_cose_mac0_encode_parameters()`` encodes the ``COSE_Mac0`` Header parameters
-and outputs the encoded context to ``cbor_encode_ctx``.
-
-.. code-block:: c
-
- enum t_cose_err_t
- t_cose_mac0_encode_parameters(struct t_cose_mac0_sign_ctx *context,
- QCBOREncodeContext *cbor_encode_ctx);
-
-Calculate and add authentication tag
-------------------------------------
-
-``t_cose_mac0_encode_tag()`` calculates the authentication tag and finishes the
-``COSE_Mac0`` message.
-
-.. code-block:: c
-
- enum t_cose_err_t
- t_cose_mac0_encode_tag(struct t_cose_mac0_sign_ctx *context,
- QCBOREncodeContext *cbor_encode_ctx);
-
-Decoding COSE_Mac0
-==================
-
-Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` decoding exports similar
-functions to test suite of Initial Attestation.
-The major functions are listed below.
-
-Initialize verification context
--------------------------------
-
-``t_cose_mac0_verify_init()`` initializes ``COSE_Mac0`` verification context and
-configures option flags in verification.
-
-.. code-block:: c
-
- static void
- t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context,
- int32_t option_flags);
-
-The ``COSE_Mac0`` verification context is defined as
-
-.. code-block:: c
-
- struct t_cose_mac0_verify_ctx {
- /* Private data structure */
- struct t_cose_key verification_key;
- int32_t option_flags;
- };
-
-Set verification key
---------------------
-
-``t_cose_mac0_set_verify_key()`` sets the key for verifying ``COSE_Mac0``
-authentication tag.
-
-.. code-block:: c
-
- static void
- t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context,
- struct t_cose_key verify_key);
-
-Decode and verify COSE_Mac0
----------------------------
-
-``t_cose_mac0_verify()`` decodes the ``COSE_Mac0`` structure and verifies the
-authentication tag.
-
-.. code-block:: c
-
- enum t_cose_err_t
- t_cose_mac0_verify(struct t_cose_mac0_verify_ctx *context,
- struct q_useful_buf_c cose_mac0,
- struct q_useful_buf_c *payload,
- struct t_cose_parameters *parameters);
-
-Short-circuit tagging
-=====================
-
-If ``T_COSE_OPT_SHORT_CIRCUIT_TAG`` option is enabled, ``COSE_Mac0`` encoding
-will hash the ``COSE_Mac0`` content and add the hash output as an authentication
-tag. It is useful when critical symmetric IAK is unavailable or cannot be
-accessed, perhaps because it has not been provisioned or configured for the
-particular device. It is only for test and must not be used in actual use case.
-The ``kid`` parameter will either be skipped in ``COSE_Mac0`` Header.
-
-If ``T_COSE_OPT_ALLOW_SHORT_CIRCUIT`` option is enabled, ``COSE_Mac0`` decoding
-will only verify the hash output, without requiring symmetric key for
-authentication tag verification.
-
-***************
-TF-M Test suite
-***************
-
-Symmetric Initial Attestation adds dedicated non-secure and secure test suites.
-The test suites also follow asymmetric Initial Attestation test suites
-implementation but optimize the memory footprint.
-Symmetric Initial Attestation non-secure and secure test suites request Initial
-Attestation secure service to generate IATs. After IATs are generated
-successfully, test suites decode IATs and parse the claims.
-Secure test suite also verifies the authentication tag in ``COSE_Mac0``
-structure.
-
-Symmetric Initial Attestation implements its dedicated
-``attest_token_decode_validate_token()`` in ``attest_symmetric_iat_decoded.c``
-to perform IAT decoding required by test suites.
-If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected,
-``attest_symmetric_iat_decoded.c`` is included in build.
-Otherwise, asymmetric Initial Attestation dedicated implementations are included
-instead.
-
-The workflow of symmetric Initial Attestation dedicated
-``attest_token_decode_validate_token()`` is shown below.
-
-.. _iat-decode-figure:
-
-.. figure:: media/symmetric_initial_attest/iat_decode.png
- :align: center
-
- Workflow in symmetric Initial Attestation ``attest_token_decode_validate_token()``
-
-If the decoding is required from secure test suite,
-``attest_token_decode_validate_token()`` will fetch symmetric IAK to verify the
-authentication tag in ``COSE_Mac0`` structure.
-If the decoding is required from non-secure test suite,
-``attest_token_decode_validate_token()`` will decode ``COSE_Mac0`` only by
-setting ``T_COSE_OPT_DECODE_ONLY`` option flag. Non-secure must not access the
-symmetric IAK.
-
-********
-HAL APIs
-********
-
-HAL APIs are summarized below.
-
-Fetch device symmetric IAK
-==========================
-
-``tfm_plat_get_symmetric_iak()`` fetches device symmetric IAK.
-
- .. code-block:: c
-
- enum tfm_plat_err_t tfm_plat_get_symmetric_iak(uint8_t *key_buf,
- size_t buf_len,
- size_t *key_len,
- psa_algorithm_t *key_alg);
-
- **Parameters:**
-
- +-------------+-----------------------------------------------------------+
- | ``key_buf`` | Buffer to store the symmetric IAK. |
- +-------------+-----------------------------------------------------------+
- | ``buf_len`` | The length of ``key_buf``. |
- +-------------+-----------------------------------------------------------+
- | ``key_len`` | The length of the symmetric IAK. |
- +-------------+-----------------------------------------------------------+
- | ``key_alg`` | The key algorithm. Only HMAC SHA-256 is supported so far. |
- +-------------+-----------------------------------------------------------+
-
-It returns error code specified in ``enum tfm_plat_err_t``.
-
-Get symmetric IAK key identifier
-================================
-
-``attest_plat_get_symmetric_iak_id()`` gets the key identifier of the symmetric
-IAK as the ``kid`` parameter in COSE Header.
-
-Optional if device doesn't install a key identifier for symmetric IAK.
-
- .. code-block:: c
-
- enum tfm_plat_err_t attest_plat_get_symmetric_iak_id(void *kid_buf,
- size_t buf_len,
- size_t *kid_len);
-
- **Parameters:**
-
- +-------------+-------------------------------------+
- | ``kid_buf`` | Buffer to store the IAK identifier. |
- +-------------+-------------------------------------+
- | ``buf_len`` | The length of ``kid_buf``. |
- +-------------+-------------------------------------+
- | ``kid_len`` | The length of the IAK identifier. |
- +-------------+-------------------------------------+
-
-It returns error code specified in ``enum tfm_plat_err_t``.
-
-*********
-Reference
-*********
-
-.. [1] `PSA Attestation API 1.0 (ARM IHI 0085) `_
-
-.. [2] :doc:`Trusted Firmware-M Profile Small Design `
-
-.. [3] :doc:`Initial Attestation Service Integration Guide `
-
-.. [4] `HMAC: Keyed-Hashing for Message Authentication `_
-
-.. [5] `CBOR Object Signing and Encryption (COSE) `_
-
-----------------
-
-*Copyright (c) 2020 Arm Limited. All Rights Reserved.*
diff --git a/docs/design_documents/tfm_code_generation_with_jinja2.rst b/docs/design_documents/tfm_code_generation_with_jinja2.rst
deleted file mode 100644
index 2e730238db..0000000000
--- a/docs/design_documents/tfm_code_generation_with_jinja2.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-###########################
-Code Generation With Jinja2
-###########################
-
-:Author: Mate Toth-Pal
-:Organization: Arm Limited
-:Contact: Mate Toth-Pal
-:Status: Accepted
-
-***************************************
-Generating files from templates in TF-M
-***************************************
-
-Some of the files in TF-M are generated from template files. The files to be
-generated are listed in ``tools/tfm_generated_file_list.yaml``. For each
-generated file ``/`` the template file is
-``/.template``. The templates are populated with
-partition information from the partition manifests. The manifests to be used for
-the generation are listed in ``tools/tfm_manifest_list.yaml``.
-
-****************************************
-Custom generator script - Current method
-****************************************
-
-``tools/tfm_parse_manifest_list.py`` Python script is used to generate files
-from the templates. This script calls the ``tools/generate_from_template.py`` to
-parse the template files, and uses ``tools/keyword_substitution.py`` to
-substitute the keychains with actual values from the manifest files.
-
-*************************************
-Use Jinja2 template engine - proposal
-*************************************
-
-The proposal is to eliminate the template parser and substituter scripts, and
-call the Jinja2 template engine library from
-``tools/tfm_parse_manifest_list.py`` to do the substitution.
-
-More information on jinja2: http://jinja.pocoo.org/
-
-Changes needed:
-===============
-
-- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2
- library instead of the custom scripts. The data structure required by the
- library is very similar to the one required by the current scripts.
-- template files needs to be rewritten to the Jinja syntax: The control
- characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be
- added to iterate over the substitutions.
-
-Improvements over the current solution
-======================================
-
-- Compatible with Python 2.7 and Python 3, while current solution only supports
- Python 2.7
-- More advanced functionality: direct control over the list of items for a
- keychain, meta information on that list (like length)
-- Well documented (see website)
-- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a
- well established software in contrast with the current proprietary solution.
-
-*******
-Example
-*******
-
-Below code snippet enumerates services in Secure Partitions:
-
-.. code-block::
-
- {% for partition in partitions %}
- {% if partition.manifest.services %}
- {% for service in partition.manifest.services %}
- {do something for the service}
- {% endfor %}
- {% endif %}
- {% endfor %}
-
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_cooperative_scheduling_rules.rst b/docs/design_documents/tfm_cooperative_scheduling_rules.rst
deleted file mode 100644
index b1c4e768b3..0000000000
--- a/docs/design_documents/tfm_cooperative_scheduling_rules.rst
+++ /dev/null
@@ -1,211 +0,0 @@
-############################
-Cooperative Scheduling Rules
-############################
-
-:Author: Ashutosh Singh
-:Organization: Arm Limited
-:Contact: Ashutosh Singh
-:Status: Accepted
-
-TF-M Scheduler - Rules
-======================
-
-On ArmV8-M CPUs, NSPE and SPE share the same physical processing element(PE). A
-TF-M enabled system need to be able to handle asynchronous events (interrupts)
-regardless of current security state of the PE, and that may lead to scheduling
-decisions. This introduces significant complexity into TF-M. To keep the
-integrity of (NSPE and SPE) schedulers and call paths between NSPE and SPE,
-following set of rules are imposed on the TF-M scheduler design.
-
-Objectives and Requirements
-===========================
-
-1. Decoupling of scheduling decisions between NSPE and SPE
-2. Efficient interrupt handling by SPE as well as NSPE
-3. Reduce critical sections on the secure side to not block interrupts
- unnecessarily
-4. Scalability to allow simplification/reduction of overheads to scale down the
- design for constrained devices
-5. Reduce impact on NSPE software design
-
- a. NSPE interrupt handling implementation should be independent
- b. Impact on the NSPE scheduler should be minimal
- c. No assumptions should be made about NSPE's scheduling capabilities
-
-Scheduler Rules for context switching between SPE and NSPE
-==========================================================
-
-To allow coherent cooperative scheduling, following set of rules are imposed on
-security state changes.
-The switching between SPE and NSPE can be triggered in multiple ways.
-
-`Involuntary security state switch`; when the software has no control over the
-switch:
-
-- A NSPE interrupt take control into NSPE from SPE
-- A SPE interrupt takes control into SPE from NSPE
-
-`Voluntary security state switch`; when software programmatically makes the
-switch:
-
-- A NSPE exception handler returns from NSPE to pre-empted SPE context
-- A SPE exception handler returns from SPE to pre-empted NSPE context
-- NSPE makes a function call into SPE
-- SPE returns a call from NSPE
-- SPE makes a function call into NSPE (not covered in current design)
-- NSPE returns a call from SPE (not covered in current design)
-
-In order to maintain the call stack integrity across NSPE and SPE, following
-rules are imposed on all security state switches.
-
-Rules for NSPE Exception handling
----------------------------------
-
-1. **The NSPE exception handler is allowed to trigger a NSPE context switch**
- **(regardless of security state of the preempted context.**
-
-This is expected behaviour of any (RT)OS.
-
-2. **The NSPE scheduler must eventually 'restore' the preempted (by**
- **exception) context.**
-
-This is expected behaviour of any (RT)OS.
-
-3. **If NSPE exception results in a NSPE context switch, SPM must be informed**
- **of the scheduling decision; this must be done BEFORE the execution of**
- **newly scheduled-in context.**
-
-This is to ensures integrity of the call stack when SPE is ready to return a
-previous function call from NSPE.
-
-Rules for SPE Exception handling
---------------------------------
-
-1. **All of the SPE interrupts must have higher priority than NSPE interrupts**
-
-This is rule is primarily for simplifying the SPM design.
-
-2. **The SPE interrupt handler is allowed to trigger a SPE context switch**
- **(regardless of security state of the pre-empted context)**
-
-If the SPE context targeted by the interrupt is not same as current SPE context,
-the SPM may choose to switch the current running SPE context based on priority.
-
-3. **SPE scheduler must treat pre-empted context as one of the SPE contexts**
-
- a. If the pre-empted SPE context is SP1, the TCB for SP1 should be used for
- saving the context. i.e. the context of SP1 should be saved before
- scheduling anything other secure partition.
- b. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is
- pre-empted by SPE exception (before NSPE scheduling decision is communicated
- back to SPM) -- SP1 TCB must be used for saving the context
- In this case SPM is not yet aware of the NSPE context switch, from SPM's
- standpoint SP1 is still executing, so SPM assumes that the preempted context
- is SP1.
- c. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is
- pre-empted by SPE exception `after` NSPE scheduling decision is
- communicated back to SPM) - a TCB dedicated to NSPE should be used for
- saving the context.
-
- When NSPE scheduler communicates the scheduling decision to SPM, SPM must save
- the SP1 context, if a SPE interrupt preempts the currently running NSPE context,
- SPM should save the context to a dedicated NSPE TCB.
-
- d. The SPE scheduler must eventually 'restore' the pre-empted context.
- This is an expected behaviour of any scheduler.
-
-4. **All of the interrupts belonging to a partition must have same priority.**
-
-This serializes ISR execution targeted for same partition.
-
-5. **In case of nested interrupts, all of the ISRs must run to finish before**
- **any service code is allowed to run**
-
-This is an expected behaviour of any scheduler.
-
-6. **If the previously preempted context was a NSPE ISR context, SPE ISR**
- **handler must return to preempted NSPE context.**
-
-This is an expected behaviour of any scheduler to return to preempted context.
-
-Rules for NSPE to SPM function call (and NSPE scheduler)
---------------------------------------------------------
-
-1. Current NSPE context must have been communicated to SPM, otherwise SPM cannot
- guarantee NSPE function calling stack integrity.
-
-Rules for Function Return from SPE to NSPE with result
-------------------------------------------------------
-
-1. **The result available on SPE side are for currently active NSPE context.**
-
-To maintain call stack integrity, if SPE is ready to return to NSPE, it can do
-function return only if the SPE return path corresponds to currently active NSPE
-context.
-
-2. **Last entry into secure world happened programmatically (Voluntary**
- **security state switch into SPE)**
-
-i.e. control is voluntarily given back by NSPE, either through a function call,
-or a context restore via 'return to SPE from NSPE'. As opposed to a SPE
-interrupt bringing back the execution into SPE.
-
-3. **The current NSPE call stack has not already been returned with SPM_IDLE.**
-
-This rule applies if following optional feature is enabled.
-
-Rules for Return from SPE to NSPE with SPM_IDLE
------------------------------------------------
-
-This is optional part of the design as it introduces significant complexity on
-both sides of the security boundary.
-It allows yielding of the CPU to NSPE when SPE has not CPU execution to do but
-it has not yet finished the previous request(s) from NSPE; i.e. SPE is waiting
-on arrival of a SPE interrupt.
-
-1. **Last entry into secure world happens programmatically (Voluntary**
- **security context switch into SPE)**
-
-i.e. control is voluntarily given back by NSPE, either through a function call,
-or a context restore via 'return to SPE from NSPE'. As opposed to a SPE
-interrupt bringing back the execution into SPE.
-
-2. **The result for the currently active NSPE entity is not yet available,**
- **the called service is waiting (on interrupt/event).**
-
-SPE request corresponding to currently active NSPE caller is not yet completed
-and is waiting on an ISR.
-
-3. **The current NSPE call stack has not already been returned with SPM_IDLE.**
-
-Rules for NSPE pend irq based return from SPE to NSPE
------------------------------------------------------
-
-This is optional part of the design as it introduces significant complexity on
-both sides. This works in conjunction with [Rules for Return from SPE to NSPE
-with SPM_IDLE](#rules-for-return-from-spe-to-nspe-with-spm_idle).
-In this scenario, when SPE is ready with result for a previous call from NSPE,
-it raises a pended IRQ to NSPE instead of returning the function call path.
-
-1. **The SPE has finished a NSPE request.**
-
-2. **The corresponding NSPE context has already been returned with SPM_IDLE.**
-
-Rules for ISR pre-emption
--------------------------
-
-1. **A higher priority NSPE interrupt is allowed to preempt a lower priority**
- **NSPE ISR**
-
-2. **A higher priority SPE interrupt is allowed to preempt a lower priority**
- **SPE ISR**
-
-3. **A SPE interrupt is allowed to preempt NSPE ISR**
-
-4. **A NSPE interrupt is not allowed to preempt SPE ISR**
-
-5. **All interrupts belonging to a service must have same priority**
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_crypto_design.rst b/docs/design_documents/tfm_crypto_design.rst
deleted file mode 100644
index e2785a5dfa..0000000000
--- a/docs/design_documents/tfm_crypto_design.rst
+++ /dev/null
@@ -1,198 +0,0 @@
-Crypto Service design
-=====================
-
-:Author: Antonio de Angelis
-:Organization: Arm Limited
-:Contact: Antonio de Angelis
-:Status: Accepted
-
-.. contents:: Table of Contents
-
-Abstract
---------
-
-This document describes the design of the TF-M Cryptographic Secure Service
-(in short, TF-M Crypto service).
-
-Introduction
-------------
-
-The TF-M Crypto service provides an implementation of the PSA Crypto API
-in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which
-is a reference implementation of the PSA Crypto API. For more details on
-the PSA Crypto API or the Mbed Crypto implementation, please refer
-directly to the ``mbed-crypto`` GitHub repository [1]_ .
-
-The service can be used by other services running in the SPE, or by
-applications running in the NSPE, to provide cryptographic
-functionalities.
-
-Components
-----------
-
-The TF-M Crypto service is implemented by a number of different software
-components, which are listed below:
-
-.. table:: Components table
- :widths: auto
-
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | **Component name** | **Description** | **Location** |
- +=============================+===============================================================+======================================================================+
- | SPE client API interface | This module exports the client API of PSA Crypto to the other | ``./secure_fw/partitions/crypto/tfm_crypto_secure_api.c`` |
- | | services available in TF-M. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | NSPE client API interface | This module exports the client API of PSA Crypto to the NSPE | ``./interface/src/tfm_crypto_api.c`` |
- | | (i.e. to the applications). | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, |
- | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` |
- | | during TF-M boot and provides the infrastructure to service | |
- | | requests when TF-M is built for IPC mode. | |
- | | Due to the fact that the functions available in the Service | |
- | | modules use the Uniform Signature prototype [2]_ , the | |
- | | dispatching mechanism of IPC requests is based on a look up | |
- | | table of function pointers. | |
- | | This design allows for better scalability and support of a | |
- | | higher number of Secure functions with minimal overhead and | |
- | | duplication of code. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` |
- | | operations in the Secure world. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Service modules | These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key,| ``./secure_fw/partitions/crypto/crypto_aead.c`` |
- | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/partitions/crypto/crypto_asymmetric.c`` |
- | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/partitions/crypto/crypto_cipher.c`` |
- | | They provide parameter sanitation and context retrieval for | ``./secure_fw/partitions/crypto/crypto_key_derivation.c`` |
- | | multipart operations, and dispatching to the corresponding | ``./secure_fw/partitions/crypto/crypto_hash.c`` |
- | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/partitions/crypto/crypto_key.c`` |
- | | functionality. | ``./secure_fw/partitions/crypto/crypto_mac.c`` |
- | | All the functions in the Service modules are based on the | |
- | | Uniform Signature prototype [2]_ . | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/crypto/manifest.yaml`` |
- | | for both library mode and IPC mode. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/partitions/crypto/CMakeLists.inc`` |
- | | build the service as part of the Secure FW build. The service | ``./secure_fw/partitions/crypto/CMakeLists.txt`` |
- | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` |
- | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/partitions/crypto/tfm_crypto_api.h`` |
- | | library as part of the Secure FW build process and archive it | ``./secure_fw/partitions/crypto/tfm_crypto_signal.h`` |
- | | with the static library of the Crypto service. | ``./secure_fw/partitions/crypto/spe_crypto.h`` |
- | | The headers are used to export the public prototypes of the | |
- | | functions in the Service modules ``tfm_crypto_api.h``, and | |
- | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | |
- | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | |
- | | which the service handler waits for requests when the service | |
- | | is built for IPC mode. | |
- | | The header available in the interface, ``tfm_crypto_defs.h`` | |
- | | , contains types and defines for building the NSPE interface | |
- | | as part of a Non-Secure application. | |
- | | Finally, the ``crypto_spe.h`` header is used during the | |
- | | build of the Mbed Crypto library, when the Mbed Crypto config | |
- | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | |
- | | custom prefix to the PSA API symbols so that duplication of | |
- | | symbol names is avoided. | |
- | | The prefix used for the PSA API symbols of the Mbed Crypto | |
- | | library is chosen to be ``mbedcrypto__``. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
- | Documentation | The integration guide contains the description of the TF-M | ``./docs/user_guides/services/tfm_crypto_integration_guide.rst`` |
- | | Crypto service modules and interfaces. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
-
-The interaction between the different components is described by the
-following block diagram:
-
-.. figure:: media/tfm_crypto_design.png
-
- Block diagram of the different components of the TF-M Crypto service. A
- dotted line is used to indicate the interaction with a library.
-
-Note: in IPC mode, the interaction between components is slightly
-different, as the Service modules are not called directly through the
-TF-M Secure Partition Manager but through the IPC handler which resides
-in the Init module.
-
-Service API description
------------------------
-
-Most of the APIs exported by the TF-M Crypto service (i.e. from the Service
-modules) is based on the Uniform Signature prototypes [2]_ and have a direct
-correspondence with the PSA Crypto API. The Alloc and Init modules instead
-export some APIs which are specific to the TF-M Crypto service, and are
-available only to the Service modules or the SPM. For a detailed description
-of the prototypes please refer to the ``tfm_crypto_api.h`` header.
-
-.. table:: Init and Alloc modules APIs
- :widths: auto
-
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
- | **Function** | **Module** | **Caller** | **Scope** |
- +================================+==============+=================+======================================================+
- | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC |
- | | | | mode, it calls the IPC service request handler. |
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
- | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the |
- | | | | concurrent operation contexts storage area. |
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
- | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart |
- | | | | operation. It returns an handle to the allocated |
- | | | | context in secure memory. |
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
- | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context|
- | | | | of a multipart operation, based on the handle given |
- | | | | as input. |
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
- | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context |
- | | | | of a multipart operation, based on the handle given |
- | | | | as input. |
- +--------------------------------+--------------+-----------------+------------------------------------------------------+
-
-Configuration parameters
-------------------------
-
-The TF-M Crypto service exposes some configuration parameters to tailor
-the service configuration in terms of supported functionalities and
-hence FLASH/RAM size to meet the requirements of different platforms and
-use cases. These parameters can be provided via CMake parameters during
-the CMake configuration step and as a configuration header to allow the
-configuration of the Mbed Crypto library.
-
-.. table:: Configuration parameters table
- :widths: auto
-
- +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
- | **Parameter** | **Type** | **Description** | **Scope** | **Default** |
- +===============================+===========================+================================================================+=========================================+====================================================+
- | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 8096 (bytes) |
- | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | |
- +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
- | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 |
- | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| use case and platform requirements. | |
- | | | for multi-part operations, that can be allocated simultaneously| | |
- | | | at any time. | | |
- +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
- | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC mode builds. In IPC mode, | To be configured based on the desired | 5120 (bytes) |
- | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | |
- | | | temporarily in an internal scratch buffer whose size is | | |
- | | | determined by this parameter. | | |
- +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
- | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./platform/ext/common/tfm_mbedcrypto_config.h`` |
- | | | algorithms through the usage of a a configuration header file | application and platform requirements. | |
- | | | at build time. This allows for tailoring FLASH/RAM requirements| | |
- | | | for different platforms and use cases. | | |
- +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
-
-References
-----------
-
-.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/ARMmbed/mbed-crypto
-
-.. [2] Uniform Signature prototypes: \ https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/
-
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_fwu_service.rst b/docs/design_documents/tfm_fwu_service.rst
deleted file mode 100644
index 6d90de4579..0000000000
--- a/docs/design_documents/tfm_fwu_service.rst
+++ /dev/null
@@ -1,313 +0,0 @@
-#######################
-Firmware Update Service
-#######################
-
-:Author: Sherry Zhang
-:Organization: Arm Limited
-:Contact: Sherry Zhang
-:Status: Draft
-
-.. contents:: Table of Contents
-
-***************************************
-Introduction of Firmware Update service
-***************************************
-The Firmware Update(FWU) service provides the functionality of updating firmware
-images. It provides a standard interface for updating firmware and it is
-platform independent. TF-M defines a shim layer to support cooperation between
-bootloader and FWU service.
-
-This partition supports the following features:
-
-- Query image information
- Fetch information about the firmware images on the device. This covers the
- images in the running area and also the staging area.
-- Store image
- Write a candidate image to its staging area.
-- Validate image
- Starts the validation of the image.
-- Trigger reboot
- Trigger a reboot to restart the platform.
-
-**********
-Components
-**********
-The structure of the TF-M Firmware Update service is listed below:
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | **Component name** | **Description** | **Location** |
- +=============================+===============================================================+==================================================================================+
- | SPE client API interface | This module exports the client API of PSA Firmware Update to | ``./secure_fw/partitions/firmware_update/tfm_fwu_secure_api.c`` |
- | | the other services available in TF-M. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | NSPE client API interface | This module exports the client API of PSA Firmware Update to | ``./interface/src/tfm_firmware_update_func_api.c`` |
- | | the NSPE(i.e. to the applications). | ``./interface/src/tfm_firmware_update_ipc_api.c`` |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/firmware_update/tfm_firmware_update.yaml`` |
- | | for both library mode and IPC mode. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | Secure functions and IPC | This module handles all the secure function requests in | ``./secure_fw/partitions/firmware_update/tfm_fwu_req_mngr.c`` |
- | request handlers | library model and all the service requests in IPC model. | |
- | | It maitains the image state context and calls the image ID | |
- | | converter to achieve the firmware update functionalities. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | Image ID Converter | This module converts the image ID between psa_image_id_t, | ``./secure_fw/partitions/firmware_update/tfm_fwu_internal.c`` |
- | | which is the image ID structure in user interfaces, and | |
- | | bl_image_id_t which is the image ID structure in bootloader. | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | Shim layer between FWU and | This module provides the APIs with the functionality of | ``./secure_fw/partitions/firmware_update/tfm_bootloader_fwu_abstraction.h`` |
- | bootloader | operating the bootloader to cooperate with the Firmware Update| |
- | | service | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
- | Shim layer example based on | This module is the implementation of the shim layer between | ``./secure_fw/partitions/firmware_update/bootloader/mcuboot/tfm_mcuboot_fwu.c`` |
- | MCUboot | FWU and bootloader based on MCUboot. | |
- | | | |
- +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
-
-***********************
-Service API description
-***********************
-This service follows the `Firmware Update API `_ spec of version 0.7.
-It implements the mandatory interface functions listed in section 5.1 and the
-optional interface ``psa_fwu_accept()``. Please refer to Firmware Update spec
-for the detailed description.
-
-*************************************
-Shim Layer between FWU and bootloader
-*************************************
-The firmware update operations are achieved by calling the shim layer APIs
-between bootloader and FWU.
-
-Shim layer introduction
-=======================
-This shim layer provides the APIs with the functionality of operating the
-bootloader to cooperate with the Firmware Update service. This shim layer
-is decoupled from bootloader implementation. Users can specify a specific
-bootloader by setting ``TFM_FWU_BOOTLOADER_LIB`` build configuration and
-adding the specific build scripts into that file. By default, the MCUboot
-is chosen as the bootloader.
-
-Interfaces of the shim Layer
-============================
-
-fwu_bootloader_init(function)
------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_init(void);
-
-Description
-^^^^^^^^^^^
-Bootloader related initialization for the firmware update, such as reading
-some necessary shared data from the memory if needed.
-
-Parameters
-^^^^^^^^^^
- N/A
-
-fwu_bootloader_staging_area_init(function)
-------------------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_staging_area_init(bl_image_id_t bootloader_image_id);
-
-Description
-^^^^^^^^^^^
-Prepare the staging area of the image with the given ID for image download.
-For example, initialize the staging area, open the flash area, and so on.
-The image will be written into the staging area later.
-
-Parameters
-^^^^^^^^^^
-- ``bootloader_image_id``: The identifier of the target image in bootloader.
-
-fwu_bootloader_load_image(function)
------------------------------------
-Prototype
-^^^^^^^^^
-
-.. code-block:: c
-
- psa_status_t fwu_bootloader_load_image(bl_image_id_t bootloader_image_id,
- size_t image_offset,
- const void *block,
- size_t block_size);
-
-Description
-^^^^^^^^^^^
-Load the image to its staging area.
-
-Parameters
-^^^^^^^^^^
-- ``bootloader_image_id``: The identifier of the target image in bootloader.
-- ``image_offset``: The offset of the image being passed into block, in bytes.
-- ``block``: A buffer containing a block of image data. This might be a complete image or a subset.
-- ``block_size``: Size of block.
-
-fwu_bootloader_install_image(function)
----------------------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_install_image(bl_image_id_t bootloader_image_id,
- bl_image_id_t *dependency,
- psa_image_version_t *dependency_version);
-
-Description
-^^^^^^^^^^^
-Check the authenticity and integrity of the image. If a reboot is required to
-complete the check, then mark this image as a candidate so that the next time
-bootloader runs it will take this image as a candidate one to bootup. Return
-the error code PSA_SUCCESS_REBOOT.
-
-Parameters
-^^^^^^^^^^
-- ``bootloader_image_id``: The identifier of the target image in bootloader.
-- ``dependency``: Bootloader image ID of dependency if needed.
-- ``dependency_version``: Bootloader image version of dependency if needed.
-
-fwu_bootloader_mark_image_accepted(function)
---------------------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_mark_image_accepted(void);
-
-Description
-^^^^^^^^^^^
-Call this API to mark the running images as permanent/accepted to avoid
-revert when next time bootup. Usually, this API is called after the running
-images have been verified as valid.
-
-Parameters
-^^^^^^^^^^
- N/A
-
-fwu_bootloader_abort(function)
-------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_abort(void);
-
-Description
-^^^^^^^^^^^
-Abort the current image download process.
-
-Parameters
-^^^^^^^^^^
- N/A
-
-fwu_bootloader_get_image_info(function)
----------------------------------------
-Prototype
-^^^^^^^^^
-.. code-block:: c
-
- psa_status_t fwu_bootloader_get_image_info(bl_image_id_t bootloader_image_id,
- bool staging_area,
- tfm_image_info_t *info);
-
-Description
-^^^^^^^^^^^
-Get the image information of the given bootloader_image_id in the staging area
-or the running area.
-
-Parameters
-^^^^^^^^^^
- - ``bootloader_image_id``: The identifier of the target image in bootloader.
- - ``active_image``: Indicates image location.
-
- - ``True``: the running image.
- - ``False``: the image in the passive(or staging) slot.
-
- - ``info``: Buffer containing the image information.
-
-******************************************
-Additional shared data between BL2 and SPE
-******************************************
-An additional TLV area "image version" is added into the shared memory between
-BL2 and TF-M. So that the firmware update partition can get the image version.
-Even though the image version information is also included in the ``BOOT RECORD``
-TLV area which is encoded by CBOR, adding a dedicated ``image version`` TLV area
-is preferred to avoid involving the CBOR encoder which can increase the code
-size. The FWU partition will read the shared data at the partition
-initialization.
-
-******************
-Image ID structure
-******************
-The structure of image ID is:
- image_id[7:0]: slot.
- image_id[15:8]: image type.
- image_id[31:16]: specific image ID.
-
-Three image types are defined in this partition.
-- FWU_IMAGE_TYPE_NONSECURE: the non_secure image
-- FWU_IMAGE_TYPE_SECURE: the secure image
-- FWU_IMAGE_TYPE_FULL: the secure + non_secure image
-
-.. Note::
-
- Currently, images update with dependency is not supported by FWU in multiple image boot.
-
-Macros **FWU_CALCULATE_IMAGE_ID**, **FWU_IMAGE_ID_GET_TYPE** and
-**FWU_IMAGE_ID_GET_SLOT** are dedicated to converting the image id, type, and
-slot. The service users can call these macros to get the image ID.
-
-.. Note::
-
- The image ID structure, as well as the macros listed here, is TF-M specific implementation.
-
-***********************************
-Benefits Analysis on this Partition
-***********************************
-
-Implement the FWU functionality in the non-secure side
-======================================================
-The Firmware Update APIs listed in `User interfaces`_ can also be implemented
-in the non-secure side. The library model implementation can be referred to for
-the non-secure side implementation.
-
-Pros and Cons for Implementing FWU APIs in Secure Side
-======================================================
-
-Pros
-----
-- It protects the image in the passive or staging area from being tampered with
- by the NSPE. Otherwise, a malicious actor from NSPE can tamper the image
- stored in the non-secure area to break image update.
-
-- It protects secure image information from disclosure. In some cases, the
- non-secure side shall not be permitted to get secure image information.
-
-- It protects the active image from being manipulated by NSPE. Some bootloader
- supports testing the image. After the image is successfully installed and
- starts to run, the user should set the image as permanent image if the image
- passes the test. To achieve this, the area of the active image needs to be
- accessed. In this case, implementing FWU service in SPE can prevent NSPE
- from manipulating the active image area.
-
-- On some devices, such as the Arm Musca-B1 board, the passive or staging area
- is restricted as secure access only. In this case, the FWU partition should
- be implemented in the secure side.
-
-Cons
-----
-- It increases the image size of the secure image.
-- It increases the execution latency and footprint. Compared to implementing
- FWU in NSPE directly, calling the Firmware Update APIs which are implemented
- in the secure side increases the execution latency and footprint.
-- It can increase the attack surface of the secure runtime.
-
-Users can decide whether to call the FWU service in TF-M directly or implement
-the Firmware Update APIs in the non-secure side based on the pros and cons
-analysis above.
-
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_its_512_flash.rst b/docs/design_documents/tfm_its_512_flash.rst
deleted file mode 100644
index aa58c2b036..0000000000
--- a/docs/design_documents/tfm_its_512_flash.rst
+++ /dev/null
@@ -1,104 +0,0 @@
-###############################################################
-Add support for block-aligned flash in Internal Trusted Storage
-###############################################################
-
-:Author: Minos Galanakis
-:Organization: Arm Limited
-:Contact: Minos Galanakis
-:Status: Accepted
-
-Abstract
-========
-
-The proposal is describing a mechanism to enable the use of larger flash
-devices, imposing a requirement for word-aligned full-block program operations,
-in Trusted Firmware-M.
-
-
-Requirements
-============
-
-- Allow page-aligned writes for up to 512 Bytes per page.
-- Guarantee data integrity and power-failure reliability.
-- Do not alter existing supported platform behaviour.
-
-Current implementation
-======================
-
-In the current ITS filesystem design, each filesystem create or write operation
-requires two flash blocks to be updated: first the data block and then the
-metadata block. Buffering is avoided as much as possible to reduce
-RAM requirements.
-
-However, if the ITS_FLASH_PROGRAM_UNIT is 512 Bytes then the data will have to
-stored in a temporary memory location in order to be able to write
-that much data in one-shot.
-
-Proposed implementation overview
-================================
-
-1. A new block-sized static buffer should be added to its_flash.c when
- ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported.
-2. Methods calling the flash API such as ``its_flash_write()`` or
- ``its_flash_block_to_block_move()`` will populate the buffer instead of
- directly programming the flash.
-3. A new method ``its_flash_flush()``, should be provided in order to flush
- the block buffer to the device.
-4. ``its_flash_flush()`` should be called twice: Once after a data block
- update and once more after the metadata block update is completed.
-5. The proposed design should require that the data block update is always
- completed before the metadata block update starts
-6. Writes to the block buffer should be atomic, and guarded against corruption
- by data from different blocks.
-
-Considerations
-==============
-
-- The proposed implementation will increase the RAM usage of ITS by the size
- of a block, only for platforms which require block-aligned writes.
-- Currently power-failure is detected by software by incrementing an 8-bit
- metadata header field (``swap_count``), as the last written byte. When the
- proposed block-buffer is used, the block is programmed in one-shot and the
- order the bytes are written on the physical device, is hardware dependent.
-- A set of guarantees are required by the supported flash ECC devices.
- The device's flash APIs should provide a mechanism to capture and raise
- incomplete program operations, as well as write bytes in a sequential order.
-
-For example, if a board powers down through a 512 page program operation, the
-next read operation should return an error rather than read invalid data.
-
-Functional flow diagram
-=======================
-
-The logic of the proposal is described in the following diagram
-
-.. code-block::
-
- |----------------------|
- | data write() |
- |----------------------|
- | | |------------------------------|
- |-> | its_flash_write | ---> | data[] -> its_block_buffer[] |
- | | | |------------------------------|
- | |----------------------|
- | | | |------------------------------------|
- | | its_flash_flush | ---> | its_block_buffer[] -> flash dev IO |
- | | | |------------------------------------|
- | |----------------------|
- | |
- | ------------------------------------
- | |
- | V
- | |----------------------| |--------------------------|
- | | data write() complete| | metadata write() complete|
- | |----------------------| |--------------------------|
- | <-| Metadata write() | |
- |----------------------| |
- V
- |--------------------------|
- | Operation Complete |
- |--------------------------|
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_its_service.rst b/docs/design_documents/tfm_its_service.rst
deleted file mode 100644
index a9c71b7ac6..0000000000
--- a/docs/design_documents/tfm_its_service.rst
+++ /dev/null
@@ -1,281 +0,0 @@
-======================================
-Internal Trusted Storage (ITS) Service
-======================================
-
-:Author: Jamie Fox
-:Organization: Arm Limited
-:Contact: Jamie Fox
-:Status: Accepted
-
-PSA Internal Trusted Storage
-============================
-PSA Internal Trusted Storage (ITS) is a PSA RoT Service for storing the most
-security-critical device data (e.g. cryptographic keys) in internal storage,
-which is trusted to provide data confidentiality and authenticity. This
-contrasts with PSA Protected Storage, which is an Application RoT service that
-allows larger data sets to be stored securely in external flash, with the option
-for encryption, authentication and rollback protection to protect the
-data-at-rest.
-
-Current TF-M Secure Storage
-===========================
-Currently, the TF-M Secure Storage service implements PSA Protected Storage
-version 1.0-beta2. There is not yet an implementation of PSA Internal Trusted
-Storage in TF-M.
-
-New TF-M service
-================
-The proposal is to implement the *PSA Internal Trusted Storage API* with the
-*TF-M Internal Trusted Storage service*. It can be abbreviated to *TF-M ITS
-service* in general and to ``its`` in code. This name has the advantage of
-making clear the correspondence between the service and the API it implements.
-
-If this name is adopted, then it may make sense to rename the *Secure Storage
-service* to the *Protected Storage service* in the future to match. Then "secure
-storage" could refer to the two services as a collective.
-
-The TF-M ITS service will implement PSA ITS version 1.0. It will be provided by
-a separate partition to Protected Storage, for a couple of reasons:
-
-- To permit isolation between the services.
-
- - ITS is a PSA RoT Service, while Protected Storage is an Application RoT
- Service.
-
-- To avoid circular dependencies.
-
- - The PSA Firmware Framework does not permit circular dependencies between
- partitions, which would occur if Protected Storage and ITS were provided by
- the same partition. Protected Storage depends on Crypto, which in turn
- depends on ITS.
-
-The existing SST filesystem will be reused to provide the backend of the
-service, with the flash layer modified to direct storage to internal flash,
-rather than external.
-
-Compared to Protected Storage, encryption, authentication and rollback
-protection are not required, so the SST encrypted object layer and the crypto
-and NV counter interfaces are not required. The rollback protection feature of
-the object table is also not required.
-
-Code structure
-==============
-The code structure of the service will be as follows:
-
-TF-M repo:
-
-``interface/``
-
-- ``include/psa/internal_trusted_storage.h`` - PSA ITS API
-- ``src/tfm_its_api.c`` - PSA ITS API implementation for NSPE
-
-``secure_fw/ns_callable/tfm_veneers.c`` - ITS veneers (auto-generated from
-manifest)
-
-``secure_fw/partitions/internal_trusted_storage/``
-
-- ``tfm_internal_trusted_storage.yaml`` - Partition manifest
-- ``tfm_its_secure_api.c`` - PSA ITS API implementation for SPE
-- ``tfm_its_req_mngr.c`` - Uniform secure functions and IPC request handlers
-- ``tfm_internal_trusted_storage.h`` - TF-M ITS API (with client_id parameter)
-- ``tfm_internal_trusted_storage.c`` - TF-M ITS implementation, using the
- flash_fs as a backend
-- ``flash_fs/`` - Filesystem
-- ``flash/`` - Flash interface
-
-tf-m-tests repo:
-
-``test/suites/its/``
-
-- ``non_secure/psa_its_ns_interface_testsuite.c`` - Non-secure interface tests
-- ``secure/psa_its_s_interface_testsuite.c`` - Secure interface tests
-
-TF-M ITS implementation
------------------------
-The following APIs will be exposed by ``tfm_internal_trusted_storage.h``::
-
- psa_status_t tfm_its_init(void);
-
- psa_status_t tfm_its_set(int32_t client_id,
- psa_storage_uid_t uid,
- size_t data_length,
- const void *p_data,
- psa_storage_create_flags_t create_flags);
-
- psa_status_t tfm_its_get(int32_t client_id,
- psa_storage_uid_t uid,
- size_t data_offset,
- size_t data_size,
- void *p_data,
- size_t *p_data_length);
-
- psa_status_t tfm_its_get_info(int32_t client_id,
- psa_storage_uid_t uid,
- struct psa_storage_info_t *p_info);
-
- psa_status_t tfm_its_remove(int32_t client_id,
- psa_storage_uid_t uid);
-
-That is, the TF-M ITS APIs will have the same prototypes as the PSA ITS APIs,
-but with the addition of a ``client_id`` parameter, which will be passed from
-the ITS request manager. A ``tfm_its_init`` function will also be present, which
-will be called at initialisation time and not exposed through a veneer or SID.
-
-The implementation in ``tfm_internal_trusted_storage.c`` must validate the
-parameters (excepting memory references, which are validated by the SPM),
-translate the UID and client ID into a file ID and then make appropriate calls
-to the filesystem layer. It must also take care ensure that any PSA Storage
-flags associated with the UID are honoured.
-
-Filesystem
-----------
-The ITS filesystem will be copied and modified from the SST filesystem. The
-modifications required will be to rename symbols from ``sst`` to ``its`` and to
-update the implementation to be aligned with the latest version of the PSA
-Storage spec (which consists mainly of moving to the ``psa_status_t`` error type
-and using common error codes from ``psa/error.h``).
-
-The filesystem will also be modified to align the size of each file stored to
-the alignment requirement exposed by the flash interface, by adding appropriate
-padding.
-
-The filesystem code will be de-duplicated again once the ITS service is
-implemented (see below).
-
-Flash layer
------------
-The flash layer will be copied from SST, and modified to direct writes to the
-internal flash device. It too needs to be updated to use ``psa_status_t`` error
-types.
-
-Platform layer
---------------
-The TF-M platform layer must be be updated to distinguish between the external
-flash device used for Protected Storage and internal flash device used for ITS.
-A flash region for the relevant storage service needs to be allocated in each.
-
-On test platforms these may just be two distinct regions of the same flash
-device, but in general they will separate devices with their own drivers.
-
-Detailed design considerations
-==============================
-
-Mapping UID onto file ID
-------------------------
-The ITS APIs identify assets with 64-bit UIDs, to which the ITS service must
-append the 32-bit client ID of the calling partition for access control. The
-existing filesystem uses 32-bit file IDs to identify files, so some mapping
-would be required to convert between the identifiers.
-
-SST uses the object table to do the mapping from client ID, UID pairs to file
-IDs, which means making an extra filesystem read/write for each get/set
-operation. This mapping has minimal overhead for SST though, because object
-table lookups are already required for rollback protection.
-
-For ITS, no rollback protection feature is required, so there are two options:
-
-- Keep a simplified version of the SST object table that just maps from
- (client ID, UID) to file ID
-
-- Modify the filesystem to take (at least) 96-bit file IDs, in the form of a
- fixed-length char buffer.
-
-The advantage of the former is that it would require no extra modification to
-the existing filesystem code, and the existing SST object table could be cut
-down for ITS. However, it would mean that every ITS request would invoke twice
-the number of filesystem operations, increasing latency and flash wear. The code
-size of the ITS partition would be increased, as would RAM usage as the table
-would need to be read into RAM.
-
-The latter option would make the filesystem slightly more complex: the size of a
-metadata entry would be increased by 64-bits and the 96-bit fids would need to
-be copied and compared with ``memcpy`` and ``memcmp`` calls. On the other hand,
-mapping onto file IDs would incur only the cost of copying the UID and client ID
-values into the file ID buffer.
-
-A third, even more general, solution would be to use arbitrary-length
-null-terminated strings as the file IDs. This is the standard solution in
-full-featured filesystems, but we do not currently require this level of
-complexity in secure storage.
-
-With this in mind, the proposed option is the second.
-
-Storing create flags
---------------------
-The ITS APIs provide a 32-bit ``create_flags`` parameter, which contains bit
-flags that determine the properties of the stored data. Only one flag is
-currently defined for ITS: ``PSA_STORAGE_FLAG_WRITE_ONCE``, which prevents a UID
-from being modified or deleted after it is set for the first time.
-
-There are two places that these flags could be stored: in the file data or as
-part of the file metadata.
-
-For the first option, the ITS implementation would need to copy to the flags
-into the buffer containing the data, and adjust the size accordingly, for each
-set operation, and the reverse for each get. Every get_info operation would need
-to read some of the file data, rather than just the metadata, implying a second
-flash read. A potential downside is that many of the cryptographic assets stored
-in ITS will be aligned to power-of-two sizes; adding an extra 32-bits would
-misalign the size, which may reduce flash performance or necessitate adding
-padding to align to the flash page size.
-
-To implement the second option, a 32-bit ``flag`` field would be added to the
-filesystem's metadata structure, whose interpretation is defined by the user.
-This field would clearly be catered towards the PSA Storage APIs, even if
-nominally generic, and alternative filesystems may not have any such field.
-However, it is a more intuitive solution and would simplify both flash alignment
-and get_info operations.
-
-Overall, it seems more beneficial to store the flags in the metadata, so this is
-the proposed solution.
-
-Code sharing between Protected Storage and ITS
-----------------------------------------------
-To de-duplicate the filesystem code used by both Protected Storage and ITS, it
-is proposed that Protected Storage calls ITS APIs as its backend filesystem.
-
-Protected Storage essentially becomes an encryption, authentication and rollback
-protection layer on top of ITS. It makes IPC requests or secure function calls
-to the ITS service to do filesystem operations on its behalf.
-
-This has a couple of advantages:
-
-- It shrinks Protected Storage's stack size, because the filesystem and flash
- layer stack is only in ITS.
-
-- It automatically solves the problem of ensuring mutual exclusion in the
- filesystem and flash layers when Protected Storage and ITS are called
- concurrently. The second request to ITS will just be made to wait by the SPM.
-
-The disadvantage of this approach is that it will increase the latency of
-Protected Storage requests, due to the extra overhead associated with making a
-second IPC request or secure function call. It also limits Protected Storage to
-using only the ITS APIs, unless extra veneers are added solely for Protected
-Storage to use. This, for example, prevents Protected Storage from doing partial
-writes to file without reading and re-writing the whole file.
-
-ITS will need to be modified to direct calls from Protected Storage to a
-different flash device. It can use the client ID to detect when the caller is
-Protected Storage, and pass down the identity of the flash device to use to the
-flash layer, which then calls the appropriate driver.
-
-An open question is what to do if Protected Storage itself wants to store
-something in internal storage in the future (e.g. rollback counters, hash
-tree/table or top hash). A couple of possible solutions would be:
-
-- Divide up the UIDs, so certain UIDs from Protected Storage refer to assets in
- internal storage, and others to ones in external storage.
-
-- Use the ``type`` field of ``psa_call`` in IPC model and extra veneers in
- library model to distinguish between internal and external storage requests.
-
-The other option for code sharing would be for Protected Storage and ITS to
-directly share filesystem code, which would be placed in a shared code region.
-With this approach, mutual exclusion to the flash device would need to be
-implemented separately, as would some way of isolating static memory belonging
-to each partition but not the code. Because of these complications, this option
-has not been considered further at this time.
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_log_system_design_document.rst b/docs/design_documents/tfm_log_system_design_document.rst
deleted file mode 100644
index 269bcfc69d..0000000000
--- a/docs/design_documents/tfm_log_system_design_document.rst
+++ /dev/null
@@ -1,209 +0,0 @@
-##########################
-Log system design document
-##########################
-
-:Authors: Shawn Shan
-:Organization: Arm Limited
-:Contact: shawn.shan@arm.com
-
-**********
-Background
-**********
-
-In current TF-M log system, the SPM and Secure partitions share the same log
-APIs and implementations. While TF-M is keep evolving, the requirements for the
-log system has changed:
-
- - Log level is required for both SPM and SP sides to output message in
- different scenarios.
- - SPM only needs simple log format such as hex and string, while SP needs rich
- formatting.
- - Distinctions on log output between SPM and SP are required.
-
-A new log system is needed to separate the SPM and Secure partitions and to
-meet their different requirements.
-
-******
-Design
-******
-
-To allow customizable configurations, the log interfaces are defined as macros.
-The macros are easy to be forwarded or even empty. When SPM trying to output
-message and a value, it relies on a wrapper function, and finally output the
-formatted message by the HAL API.
-
-The design principles of TF-M log system:
-
- - Configurable log levels.
- - Separated SPM and SP log implementations.
- - Platforms provide log HAL implementations.
-
-SPM Log System
-==============
-
-Level Control
--------------
-Three log levels for SPM log system are defined:
-
- - TFM_SPM_LOG_LEVEL_DEBUG
- - TFM_SPM_LOG_LEVEL_INFO
- - TFM_SPM_LOG_LEVEL_ERROR
- - TFM_SPM_LOG_LEVEL_SILENCE
-
-Then a macro ``TFM_SPM_LOG_LEVEL`` is defined as an indicator, it should
-be equal to one of the four log levels.
-
-API Definition
---------------
-The following three APIs LOG APIs output the given 'msg' with hexadecimal
-formatted 'val' together. These APIs provide constrained ability to output
-numbers inside SPM. The 'msg' can be skipped with giving an empty string like
-"". And these APIs supports constant 'msg' string only, giving a runtime string
-as parameter 'msg' would potentially cause a runtime error.
-
- SPMLOG_DBGMSGVAL(msg, val);
-
- SPMLOG_INFMSGVAL(msg, val);
-
- SPMLOG_ERRMSGVAL(msg, val);
-
-A C-function needs to work as an underlayer for these APIs as string formatting
-is required. Check 'spm_log_msgval' for details.
-
-.. code-block:: c
-
- /**
- * brief Output the given message plus one value as hexadecimal. The message
- * can be skipped if the 'msg' is 'NULL' or 'len' equals 0. The
- * formatted hexadecimal string for 'value' has a '0x' prefix and
- * leading zeros are not stripped. This function rely on HAL API
- * 'tfm_hal_output_spm_log' to output the formatted string.
- *
- * \param[in] msg A string message
- * \param[in] len The length of the message
- * \param[in] value A value need to be output
- *
- * \retval >=0 Number of chars output.
- * \retval <0 TFM HAL error code.
- */
- int32_t spm_log_msgval(const char *msg, size_t len, uint32_t value)
-
-The following three APIs output a message in string.
-
- SPMLOG_DBGMSG(msg);
-
- SPMLOG_INFMSG(msg);
-
- SPMLOG_ERRMSG(msg);
-
-Here is a table about the effective APIs with different SPM log level.
-
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| | TFM_SPM_LOG_LEVEL_DEBUG | TFM_SPM_LOG_LEVEL_INFO | TFM_SPM_LOG_LEVEL_ERROR | TFM_SPM_LOG_LEVEL_SILENCE |
-+==================+=========================+===========================+===========================+=============================+
-| SPMLOG_DBGMSGVAL | Yes | No | No | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| SPMLOG_INFMSGVAL | Yes | Yes | No | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| SPMLOG_ERRMSGVAL | Yes | Yes | Yes | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| SPMLOG_DBGMSG | Yes | No | No | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| SPMLOG_INFMSG | Yes | Yes | No | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-| SPMLOG_ERRMSG | Yes | Yes | Yes | No |
-+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
-
-HAL API
--------
-Define HAL API for SPM log system:
-
-.. code-block:: c
-
- /* SPM log HAL API */
- int32_t tfm_hal_output_spm_log(const char *str, uint32_t len);
-
-Take debug message as an example:
-
-.. code-block:: c
-
- /* For debug message */
- #define SPMLOG_DBGMSG(msg) tfm_hal_output_spm_log(msg, sizeof(msg))
- /* For debug message with a value */
- #define SPMLOG_DBGMSGVAL(msg, val) spm_log_msgval(msg, sizeof(msg), val)
-
-Partition Log System
-====================
-Partition log outputting required rich formatting in particular cases. There is
-a customized print inside TF-M(``tfm_log_printf``), and it is wrapped as macro.
-
-Level Control
--------------
-Three log levels for partition log system are defined:
-
- - TFM_PARTITION_LOG_LEVEL_DEBUG
- - TFM_PARTITION_LOG_LEVEL_INFO
- - TFM_PARTITION_LOG_LEVEL_ERROR
- - TFM_PARTITION_LOG_LEVEL_SILENCE
-
-Then a macro ``TFM_PARTITION_LOG_LEVEL`` is defined as an indicator. It should
-be equal to one of the four log levels and it is an overall setting for all
-partitions.
-
-Log Format
-----------
-Compared to SPM, SP log API supports formatting. Similar to ``printf``, these
-log APIs use a format outputting to output various type of data:
-
-.. code-block:: c
-
- %d - decimal signed integer
- %u - decimal unsigned integer
- %x - hex(hexadecimal)
- %c - char(character)
- %s - string
-
-API Definition
---------------
-Define partition log APIs:
-
- LOG_DBGFMT(...);
-
- LOG_INFFMT(...);
-
- LOG_ERRFMT(...);
-
-Here is a table about the effective APIs with different partition log level.
-
-+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
-| | TFM_PARTITION_LOG_LEVEL_DEBUG | TFM_PARTITION_LOG_LEVEL_INFO | TFM_PARTITION_LOG_LEVEL_ERROR | TFM_PARTITION_LOG_LEVEL_SILENCE |
-+============+===============================+=================================+=================================+=================================+
-| LOG_DBGFMT | Yes | No | No | No |
-+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
-| LOG_INFFMT | Yes | Yes | No | No |
-+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
-| LOG_ERRFMT | Yes | Yes | Yes | No |
-+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
-
-HAL API
--------
-Please refers to the HAL design document.
-
-***********
-Log Devices
-***********
-In most of the cases, a serial device could be used as a log device. And in
-other particular cases, a memory-based log device could be applied as well.
-These log device interfaces are abstracted into HAL APIs.
-
-.. note::
-
- It is not recommended to re-use the same HAL for both SPM and SP log
- outputting especially when SPM and SP run under different privileged level,
- which makes them have a different information confidential level. Unless:
-
- - The SPM log outputting would be disabled as silence in the release version.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_non-secure_interrupt_handling.rst b/docs/design_documents/tfm_non-secure_interrupt_handling.rst
deleted file mode 100644
index 6560a0cf85..0000000000
--- a/docs/design_documents/tfm_non-secure_interrupt_handling.rst
+++ /dev/null
@@ -1,318 +0,0 @@
-#############################
-Non-Secure Interrupt Handling
-#############################
-
-:Author: Mate Toth-Pal
-:Organization: Arm Limited
-:Contact: Mate Toth-Pal
-:Status: Accepted
-
-
-*****
-Terms
-*****
-
-========== ================================================
-Term Meaning
-========== ================================================
-AIRCR Application Interrupt and Reset Control Register
-AIRCR.PRIS PRIoritize Secure exceptions
-ISR Interrupt Service Routine
-NS Non-Secure
-NSPM Non-Secure Partition Manager
-SAU Security Attribution Unit
-SPM Secure Partition Manager
-TF-M Trusted Firmware-M
-========== ================================================
-
-************
-Introduction
-************
-
-In the current design it is possible to use Non-secure interrupts, however the
-Non-secure interrupts cannot pre-empt Secure service execution. TF-M core
-achieves this by making the following configurations:
-
-1. ``AIRCR.PRIS`` is set to 1 during TF-M core initialisation. This
- de-prioritizes Non-secure exceptions compared to Secure exceptions, so that
- they cannot interrupt Secure Handler mode. the ``AIRCR.PRIS`` bit remains set
- during TF-M run. The bit is set in the function
-
-.. code-block:: c
-
- static void tfm_arch_set_secure_exception_priorities(void);
-
-.. Note::
-
- Setting ``AIRCR.PRIS`` in itself doesn't prevent NS interrupts to pre-empt
- Secure Thread mode when it runs on normal priority i.e., 256.
-
-2. On Secure service entry ``PRIMASK_NS`` is set, to boost the Non-secure
- execution priority so that all NS interrupts are masked. This is done in the
- ``TFM_NS_EXC_DISABLE()`` macro called from
-
-.. code-block:: c
-
- static int32_t tfm_start_partition(struct tfm_sfn_req_s *desc_ptr, uint32_t excReturn)
-
-.. Note::
-
- '2.' is only in Library model.
-
-In the below chapters a design is proposed to enable Non-secure interrupts to
-pre-empt Secure Thread mode.
-
-**********************************
-Limitations of the proposed design
-**********************************
-
-Library model
-=============
-
-The proposed design keeps the Secure lock in place, which means Non-secure code
-can do a single Secure service call, all further calls to Secure services will
-be rejected until the first Secure service call returns.
-
-IPC model
-=========
-
-The PSA client API can only be entered once. All the functions in the client API
-(``psa_framework_version``, ``psa_version``, ``psa_connect``, ``psa_call``,
-``psa_close``) are part of the same critical section.
-
-Non-secure software
-===================
-
-The Non-secure API functions that wraps the Secure service veneers (either
-Library or IPC model) should continue to use the NS locking mechanism currently
-implemented by calling ``tfm_ns_lock_dispatch(...)``.
-
-If any of the Non-secure software decides to bypass the locking mechanism, then
-concurrent access of veneer functions is detected by TF-M, and NS software
-execution is halted.
-
-.. Note::
-
- This makes denial of service attack possible by a malicious NS application
-
-***************************************************
-Enabling NS interrupts to pre-empt Secure execution
-***************************************************
-
-To enable NS interrupts, 2) described in chapter 'Current design' must be turned
-off. (For details see implementation notes)
-
-When a Non-secure interrupt is triggered during Secure code execution, and the
-ISR have to be executed based on the priority settings, the hardware saves the
-current execution context on the current Secure stack, and clears the general
-purpose registers, to prevents data leakage. After that the NS ISR starts
-execution.
-
-When the Non-secure ISR returns with the EXC_RETURN value provided to it in the
-link register, the context is fetched from the Secure stack, and the Secure code
-continues execution.
-
-If TF-M is used with a single threaded NS software, the mechanisms provided by
-the HW is enough to maintain the consistency of the system, and keep the
-secrets.
-
-However if the NS software is allowed to change execution context during an
-interrupt (e.g an NS operating system schedules another thread during a SysTick
-interrupt), then the Secure code can return execution to an NS thread, with the
-context of a different thread. So extra measures needs to be introduced in TF-M
-to prevent this.
-
-For IPC model
-=============
-
-In the current implementation there is no locking mechanism on the Secure side
-that would prevent the Non-secure code to enter psa_client functions multiple
-times. (For the Library model the ``tfm_secure_lock global`` variable is used
-for this purpose). Note, that the ``tfm_ns_lock_dispatch(...)`` function that
-is used by the NS service API implementations to prevent Secure services to be
-called simultaneously can be bypassed by a malicious Non-secure application, so
-a Secure side locking mechanism have to be implemented.
-
-When an NS client calls a PSA client API function, the client ID of the calling
-NS context have to be saved, and execution can only return to NS if the current
-scheduled NS thread is the one that did the call.
-
-For Library model
-=================
-
-As currently there is no scheduling in the Library model, the calls follow each
-other just like in an ordinary function call scheme. Then when the original
-Secure service that was called from the NS code is about to return, it has to
-check for the current NS client ID, and only return if it is the same as the one
-saved on Secure service entry from NS. If the ID's don't match, the Secure side
-waits so that NS OS can do context switch.
-
-Common measures
-===============
-
-Exception priorities
---------------------
-
-The priority of the Secure SVC and the Secure faults must be higher than any
-Secure exception in the system.
-
-.. note::
-
- The priority of PendSV Is set to be the lowest priority Secure interrupt,
- but still higher than the maximum possible NS execution priority when
- ``AIRCR.PRIS`` is set.
-
-NSPM
-----
-
-If the Non-secure software allows the use of multiple threads, it needs to use
-the NSPM feature of TF-M. It is expected, that all the NS context that use
-Secure services have a unique client ID, and the other contexts, that don't use
-Secure service need to have a client ID that doesn't match with any of the
-client IDs of the Secure service calling contexts.
-
-In other words, for all the *cs(0)*, *cs(1)*, ..., *cs(n)* NS contexts that use
-Secure services and for all *cn(0)*, *cn(1)*, ..., *cn(m)* NS contexts that
-don't use Secure service (where *n* > 0, *m* >= 0):
-
-- *cs(i).client_id* != *cs(j).client_id* (where 0 <= *i* < *j* <= *n*)
-- *cs(i).client_id* != *cn(j).client_id* (where 0 <= *i* <= *n* and 0 <= *j*
- <= *m*)
-
-Entering from Non-secure to Secure
-----------------------------------
-
-The Secure code can be entered through the following gateways:
-
-1. NSPM related functions (``TZ_(...)``,
- ``tfm_register_client_id(...)``)
-
- These functions are expected to be called from Handler mode. The execution
- priority, after the execution crosses the security boundary will be the same
- as it was during NS execution. This means a malicious Non-secure application,
- can set up Non-secure interrupt priorities in a way that it can enter one or
- more of the NSPM APIs simultaneously.
-
- This might leave the NSPM database in an inconsistent state, however if the
- attacker has influence over the interrupt priorities, they can gain no
- additional privilege by this.
-
- .. Note::
- The NS software is able to consume the main stack of the Secure software.
- The Main Secure stack have to be protected by MSPLIM, to prevent stack
- overflow. However a denial of service attack is still possible.
-
-2. PSA Client API, Library model service veneers
-
- When a veneer is called from Non-secure, the Secure code have to check
- whether the veneer is only entered by a single NS thread. This can be done by
- checking the veneer stack usage. It can only contain the locals of the veneer
- implementation. If the veneer has been entered from multiple NS threads,
- there is at least one extra context stack frame that was created by the
- hardware when the veneer execution had been interrupted by the NS systick.
-
-********************
-Implementation notes
-********************
-
-IPC model
-=========
-
-Save NS client ID on Secure service veneer entry
-------------------------------------------------
-
-As long as the Secure lock is in place, a single client ID have to be stored, so
-it can be done in a global variable.
-
-The caller client ID can be saved in the function
-``void tfm_psa_ipc_request_handler(uint32_t svc_ctx[])`` depending on the return
-value of the PSA API function. (Doesn't execute any Secure service code, only
-sets signals, and triggers scheduling. If the return value is success, that
-means a scheduling is to happen, and a secure service is about to be entered.)
-
-Check client ID on Secure service return
-----------------------------------------
-
-The saved client ID can be compared with the current client ID in the function
-``tfm_core_ns_ipc_request``, after the SVC return. Before doing the comparison,
-``BASEPRI_NS`` must be set to 1.
-
-The original ``BASEPRI_NS`` value can be stored in a global variable (because of
-the single context).
-
-If the client ID's don't match, ``BASEPRI_NS`` must be reset, WFI to be issued,
-and start the checking sequence from the beginning.
-
-Library model
-=============
-
-Save NS client ID on Secure veneer entry
-----------------------------------------
-
-As long as the Secure lock is in place, only a single client ID have to be
-stored, so it can be done in a global variable.
-
-The caller client ID can be saved in the function
-``uint32_t tfm_core_partition_request_svc_handler(uint32_t *svc_args, uint32_t excReturn)``.
-
-Check client ID on SP return
-----------------------------
-
-The saved client ID can be compared with the current client ID in the function
-``tfm_core_partition_request``, after the ``tfm_core_sfn_request return``.
-
-If the client ID's don't match, WFI to be issued, and the checking sequence have
-to be started from the beginning.
-
-Common
-======
-
-Enforce single NS entry to Secure
----------------------------------
-
-On Secure service entry (from the SVC implementation) check that (pseudocode)
-
-.. code-block:: c
-
- svc_handler()
- {
- /* If there are multiple context stacked in veneer stack, hang NSPE */
- expected_sp_top = veneer_stack_addr -
- sizeof(svc_state_context) + sizeof(locals);
- if (__get_PSP() != expected_sp_top) {
- /* Multiple frames are existing, panic */
- panic();
- }
- }
-
-*******
-Testing
-*******
-
-Basic scenario
-==============
-
-Basic testing of the feature is possible, by adding a new scenario to the
-existing IRQ test. The flow of the test would be something like this:
-
-============ ===================== ===========================================
-IRQ_TEST_1 prepare test scenario Do nothing
-CORE_TEST_2 prepare test scenario Do nothing
-NS prepare test scenario Initialise and start timer
-IRQ_TEST_1 execute test scenario Do nothing
-CORE_TEST_2 execute test scenario Busy wait until NS interrupt is
- acknowledged (a flag in non Secure data is
- set) set flag CORE_TEST_2 waits on
-NS execute test scenario Do nothing
-============ ===================== ===========================================
-
-The test is successful if NS execute test scenario returns.
-
-Advanced scenarios
-==================
-
-Testing advanced scenarios (that involves NS scheduling during secure execution,
-NS interrupting Secure interrupt, Secure interrupting NS interrupt) would
-require more advanced test framework and are not covered in this proposal.
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_non_secure_client_management.rst b/docs/design_documents/tfm_non_secure_client_management.rst
deleted file mode 100644
index 970550aa49..0000000000
--- a/docs/design_documents/tfm_non_secure_client_management.rst
+++ /dev/null
@@ -1,388 +0,0 @@
-############################
-Non-secure Client Management
-############################
-
-:Author: Miklos Balint
-:Organization: Arm Limited
-:Contact: Miklos Balint
-:Status: Accepted
-
-***********
-Terminology
-***********
-
-**Secure service call**: request to a secure partition by a secure or non-secure
-client thread
-
-**Secure function call**: any function call from NSPE to SPE
-
-**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure
-context management
-
-**Client ID**: the identifier defining a single entity within the system,
-determining its access policies for any given secure assets
-
-*************************
-Assumptions, restrictions
-*************************
-
-This design considers as its baseline the current operation of TF-M: an
-operating mode where at any given time only a single non-secure access is
-permitted to call a secure service.
-
-If a non-secure RTOS/bare-metal application does not use the API calls defined
-in this design, that non-secure application is still able to use secure services
-using a single, default non-secure client context. That remains a supported use
-case and use of this API is optional and is only needed if multiple access
-policies and/or concurrent secure contexts initiated by non-secure threads are
-required.
-
-Investigation is ongoing to address the option of enabling multiple concurrent
-calls by non-secure threads without the use of the context management API below.
-
-******
-Issues
-******
-
-The topics being discussed in this document:
-
-- NS client/thread awareness in TF-M Core
-- "Known client" list
-
-Improvements, alternatives, investigations
-
-- Concurrent secure service requests
-- NS to S priority inheritance
-- NS privilege to be derived from CONTROL_NS register
-
-**************
-Design details
-**************
-
-NS thread awareness in TF-M Core
-================================
-
-Description
------------
-
-TrustZone context management API defines a set of secure function calls from NS
-RTOS handler mode to TF-M Core to get notification of context switch.
-
-While CMSIS context management can be used to directly expose secure context
-management to the non-secure OS, TF-M has a proprietary implementation: the
-context management API is used to get notification of NS context switches and
-to track various non-secure clients.
-
-.. _`API definition`:
-
-API definition
---------------
-
-TZ_MemoryId_t data type
-^^^^^^^^^^^^^^^^^^^^^^^
-
-TZ Memory ID identifies an allocated memory slot.
-
-TF-M usage
-""""""""""
-
-``TZ_MemoryId_t`` is used for an index into an array containing active NS client
-IDs. The memory ID is required by CMSIS to be a positive integer, so it is
-mapped to the array index by being decremented by 1.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- typedef uint32_t TZ_MemoryId_t;
-
-Context management initialization: TZ_InitContextSystem_S
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Initialize secure context memory system.
-
-Return value
-""""""""""""
-
-This function returns execution status: 1 for success, 0 for error.
-
-TF-M usage
-""""""""""
-
-This function call is used to identify a non-secure RTOS that has TZ context
-management capabilities, as this function is expected to be called before any
-other TZ API function is used.
-
-Signature
-""""""""""
-
-.. code-block:: c
-
- uint32_t TZ_InitContextSystem_S (void);
-
-Context allocation: TZ_AllocModuleContext_S
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Allocate context memory for calling secure software modules in TrustZone.
-
-Parameters
-""""""""""
-
-``module`` [input]: identifies software modules called from non-secure mode
-
-Return value
-""""""""""""
-
-``value != 0`` TrustZone memory slot identifier
-``value == 0`` no memory available or internal error
-
-TF-M usage
-""""""""""
-
-This function is used to identify a new non-secure thread that may be identified
-as a client in the non-secure domain. The ``module`` parameter is unused. The
-returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array
-where the client ID for the newly allocated context is stored.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
-
-Context freeing: TZ_FreeModuleContext_S
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Free context memory that was previously allocated with TZ_AllocModuleContext_S
-
-Parameters
-""""""""""
-
-``id`` [input]: TrustZone memory slot identifier
-
-Return value
-""""""""""""
-
-Execution status (1: success, 0: error)
-
-TF-M usage
-""""""""""
-
-This function indicates that a non-secure client is inactive, meaning that any
-subsequent references to the client ID are considered erroneous. In effect, the
-client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as
-free.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
-
-Context activation: TZ_LoadContext_S
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Load secure context (called on RTOS thread context switch)
-
-Parameters
-""""""""""
-
-``id`` [input]: TrustZone memory slot identifier
-
-Return value
-""""""""""""
-
-Execution status (1: success, 0: error)
-
-TF-M usage
-""""""""""
-
-The client ID indexed by ``(id – 1)`` becomes the active NS client. Any
-subsequent secure service requests coming from non-secure domain will be
-associated with this client ID.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
-
-Context deactivation: TZ_StoreContext_S
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Store secure context (called on RTOS thread context switch)
-
-Parameters
-""""""""""
-
-``id`` [input]: TrustZone memory slot identifier
-
-Return value
-""""""""""""
-
-Execution status (1: success, 0: error)
-
-TF-M usage
-""""""""""
-
-The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure
-service requests coming from non-secure domain will be invalid until a new NS
-context is loaded.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
-
-Security implications (to be assessed separately if needed)
------------------------------------------------------------
-
-If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed
-to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee
-non-secure client isolation. Support for this API is only an enabler for a
-non-secure RTOS feature.
-
-Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of
-assets owned by secure entities to non-secure actors after the introduction of
-this feature as a malicious NS handler can only ever assume the identity of
-another non-secure client and cannot elevate its access privileges to those of
-secure clients.
-
-Known client list
-=================
-
-Description
------------
-
-A different – but related – API to that defined by CMSIS is proposed in this
-design to register a specific client ID to the active non-secure thread.
-
-The purpose of this API is to provide non-secure privileged code with the
-ability to associate the active non-secure context with a pre-defined identity.
-This enables the application of a pre-set access policy on the secure side to be
-applied to the non-secure thread.
-
-Use cases
----------
-
-It is valid for non-secure privileged code to only support the TF-M-specific API
-defined below and not the CMSIS TZ API defined previously. In this case the
-single non-secure client is still able to access resources based on a
-pre-defined access policy in secure services without relying on the default
-non-secure identity configured in TF-M.
-
-If used in conjunction with the TZ API, this function can provide a means to
-assign and identify multiple non-secure client IDs based on the active context,
-overriding TF-M’s default non-secure client identity assignment policy.
-
-API definition
---------------
-
-NS RTOS client registration API – secure function calls from NS handler mode to
-TF-M Core to associate a “known” Client ID to the active non-secure thread.
-
-Register specific client ID: ``tfm_register_client_id``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Assign client ID to the current TZ context.
-
-**Note**: This function must be called from handler mode so that TF-M can verify
-that it was sent by a privileged entity.
-
-This function call must follow all TZ_AllocModuleContext_S function calls to
-override the default NS client IDs allocated by TF-M.
-
-Secure and non-secure client IDs are allocated from different ranges (negative
-IDs for non-secure clients, positive for secure clients). The function call is
-rejected if called with a secure ID.
-
-Parameters
-""""""""""
-
-``ns_client_id`` [input]: The client ID to be assigned to the current context
-
-Return value
-""""""""""""
-
-``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error
-code in case of error.
-
-Signature
-"""""""""
-
-.. code-block:: c
-
- enum tfm_status_e tfm_register_client_id (int32_t ns_client_id);
-
-********************
-Implementation notes
-********************
-
-Option to reduce required context switch notifications
-======================================================
-
-According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called
-"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at
-thread context switch before running a thread". The API definition does not
-define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are
-made without an interleaving StoreContext.
-
-The proposal for TF-M is to accept this as a valid scenario where the second
-``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with
-the previous active Memory_Id.
-
-This assumption does not alter the intended use of ``TZ_StoreContext_S()``,
-which remains a valid call with the behaviour as defined in the
-`API definition`_ section above.
-
-******************************************
-Investigations, improvements, alternatives
-******************************************
-
-Concurrent secure service requests
-==================================
-
-If there are concurrent services requests, TF-M needs to identify the client for
-each request and should make their corresponding context available in the secure
-domain. Client ID needs to be associated with the secure service request so that
-a NS context switch does not break client identification.
-
-If a non-secure client is blocked on an asynchronous secure service completion,
-the NS TFM library must provide a semaphore the NS thread can wait on, whereby
-NS RTOS can schedule a different context.
-
-Should a secure service completion happen for an inactive NS context, a
-notification mechanism needs to be created to activate the given NS context.
-
-The proposal is for the NS TFM library to include a NS IRQ handler for a
-reserved interrupt signal. The ISR would identify the context to be activated
-and release the corresponding semaphore.
-
-NS to S priority inheritance
-============================
-
-Whether or not NS thread priorities should be influencing secure service
-prioritization needs to be analysed. It is raised as a topic of discussion and
-is not detailed in this document further at this stage.
-
-NS privilege check for secure function calls
-============================================
-
-Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to
-call context management veneers in handler mode. This can be a more generic
-approach, but implications are to be investigated.
-
-**********
-References
-**********
-
-Description of the TZ API:
-https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/design_documents/tfm_partition_and_service_design_document.rst b/docs/design_documents/tfm_partition_and_service_design_document.rst
deleted file mode 100644
index 500e7a11dd..0000000000
--- a/docs/design_documents/tfm_partition_and_service_design_document.rst
+++ /dev/null
@@ -1,150 +0,0 @@
-#####################################
-Partition and Service Design Document
-#####################################
-
-:Authors: Summer Qin
-:Organization: Arm Limited
-:Contact: summer.qin@arm.com
-:Status: Accepted
-
-***********
-Terminology
-***********
-Secure Partition - A thread of execution with protected runtime state within the
-Secure Processing Environment. Container for the implementation of one or more
-RoT Services. Multiple Secure Partitions are allowed in a platform.
-SPM - Secure Partition Manager.
-
-***************
-Design Overview
-***************
-As the PSA Firmware Framework described: "A Secure Partition is one execution
-environment. Partition provides access to resources, protection of its own code
-and data and mechanisms to interact with other components in the system. Each
-Secure Partition is a single thread of execution and is the smallest unit of
-isolation: if the strongest isolation level is implemented, every Secure
-Partition is isolated from every other Secure Partition.
-Security functionality is exposed by PSA as a collection of Root of Trust
-Services. Each RoT Service is a set of related security functionality. RoT
-Service are typically implemented within a Secure Partition."
-
-******************
-Partition Database
-******************
-Partition Database collects partition information of all existing partitions.
-These partitions are built together as built-in partitions at the current stage.
-Partition's code and private date are put into dedicated regions, while
-Partition Database are put in TF-M SPM region. There is a defined structure for
-partition information:
-
-.. code-block:: c
-
- struct spm_partition_desc_t {
- struct spm_partition_runtime_data_t runtime_data;
- const struct spm_partition_static_data_t *static_data;
- const struct platform_data_t *platform_data;
- };
-
-The structure describes the partition information from four aspects and every
-structure member has its own detailed members. These members can be recorded in
-partition information:
-
-- Runtime data contains runtime change-able members like context, stack and so
- on.
-- Static data contains partition id, flags, priority and init function entry.
-- Platform data contains a single peripheral's information this partition owns.
- This is a little different from the PSA Firmware Framework defines.
-- Memory data contains partition memory region address and size.
-
-These data types with different names also have different accessing attribute
-requirements and can be put in memory with different attributes. The listed four
-types of data can be defined with a different qualifier to indicate the
-accessing attribute and finally, these data are linked into a global structure
-type 'spm_partition_desc_t' for usage. Define the global partition_list array to
-store all the partitions information and all members are set to zero so that
-partition_list will be stored in bss segment. For static information, like
-static member, platform member, and some memory data, assign this information
-with 'const' qualifier. This would avoid involving unnecessary read-only data
-into the read-write area and cause storage waste. The partition's database is
-managed by the following steps:
-
-#. The four types of data are defined with different qualifier in
- 'tfm_spm_db.inc'. For example, static data is qualified with 'const' to
- indicate it is a read-only data.
-#. Include partition predefined static information in spm_api.c by adding the
- tfm_spm_db.inc file.
-#. Initialize the partition runtime information
-#. Assign the static data, platform data and memory data to corresponding
- partition.
-
-Partition Database Generating
-=============================
-Partition Database is represented as a global array that contains objects of
-type spm_partition_desc_t. The include file named tfm_spm_db.inc contains this
-array which is auto-generated from tfm_spm_db.inc.template by a tool script
-named as 'tfm_parse_manifest_list.py'. This tool parses partition manifests and
-converts members in manifest into the array member.
-
-Partition Database Initialization
-=================================
-The dedicated partition information file will be added into spm initialization
-file to initialize the global spm data array g_spm_partition_db.
-
-.. code-block:: c
-
- #include "secure_fw/partitions/tfm_spm_db.inc"
-
-Built-in Partitions
-===================
-Currently, there are two built-in internal partitions which have no manifest,
-and all the information is statically defined. These two partitions are:
-non-secure partition and core partition. They are added to the first and second
-position of the array.
-
-****************
-Service Database
-****************
-Each Secure Partition can host one or more RoT Services. Typically, related
-services that share underlying functionality or data would be implemented within
-the same Secure Partition.
-All the services are registered in every partition's manifest. There is a
-defined structure for service information:
-
-.. code-block:: c
-
- struct tfm_spm_service_t {
- const struct tfm_spm_service_db_t *service_db;
- struct spm_partition_desc_t *partition;
- struct bi_list_node_t handle_list;
- struct tfm_msg_queue_t msg_queue;
- struct bi_list_node_t list;
- };
-
-These members are necessary for a service and the following bullets explain the
-members:
-
-- Service database contains service name, partition id, service signal, service
- identifier, non-secure client(if it can be called by non-secure client),
- version and version_policy.
-- Partition points to the secure partition data.
-- Handle list contains the handle connected to the service.
-- Message queue contains the message for the service.
-- List is the service list indicator. It is a double-chain list node.
-
-The member tfm_spm_service_db_t contains statically defined service information.
-This variable can be defined statically with a qualifier 'const' to put it into
-the read-only data.
-The service information is managed by the following steps:
-
-#. Define five types of data with different qualifiers in
- 'tfm_service_list.inc'. For example, service db is qualified with 'const' to
- indicate it is a read-only data.
-#. Include service predefined static information in spm_api_ipc.c by adding the
- tfm_service_list.inc file.
-#. Assign the service db to the corresponding service.
-#. Get the corresponding partition information and link with the service.
-#. Initialize the handle_list of every service.
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_physical_attack_mitigation.rst b/docs/design_documents/tfm_physical_attack_mitigation.rst
deleted file mode 100644
index a167d12530..0000000000
--- a/docs/design_documents/tfm_physical_attack_mitigation.rst
+++ /dev/null
@@ -1,626 +0,0 @@
-#################################################
-Physical attack mitigation in Trusted Firmware-M
-#################################################
-
-:Authors: Tamas Ban; David Hu
-:Organization: Arm Limited
-:Contact: tamas.ban@arm.com; david.hu@arm.com
-:Status: Draft
-
-************
-Requirements
-************
-PSA Certified Level 3 Lightweight Protection Profile [1]_ requires protection
-against physical attacks. This includes protection against manipulation of the
-hardware and any data, undetected manipulation of memory contents, physical
-probing on the chip's surface. The RoT detects or prevents its operation outside
-the normal operating conditions (such as voltage, clock frequency, temperature,
-or external energy fields) where reliability and secure operation has not been
-proven or tested.
-
-.. note::
-
- Mitigation against certain level of physical attacks is a mandatory
- requirement for PSA Level 3 certification.
- The :ref:`tf-m-against-physical-attacks` discussed below
- doesn't provide mitigation against all the physical attacks considered in
- scope for PSA L3 certification. Please check the Protection Profile document
- for an exhaustive list of requirements.
-
-****************
-Physical attacks
-****************
-The goal of physical attacks is to alter the expected behavior of a circuit.
-This can be achieved by changing the device's normal operating conditions to
-untested operating conditions. As a result a hazard might be triggered on the
-circuit level, whose impact is unpredictable in advance but its effect can be
-observed. With frequent attempts, a weak point of the system could be identified
-and the attacker could gain access to the entire device. There is a wide variety
-of physical attacks, the following is not a comprehensive list rather just give
-a taste of the possibilities:
-
- - Inject a glitch into the device power supply or clock line.
- - Operate the device outside its temperature range: cool down or warm it up.
- - Shoot the chip with an electromagnetic field. This can be done by passing
- current through a small coil close to the chip surface, no physical contact
- or modification of the PCB (soldering) is necessary.
- - Point a laser beam on the chip surface. It could flip bits in memory or a
- register, but precise knowledge of chip layout and design is necessary.
-
-The required equipment and cost of these attacks varies. There are commercial
-products to perform such attacks. Furthermore, they are shipped with a scripting
-environment, good documentation, and a lot of examples. In general, there is a
-ton of videos, research paper and blogs about fault injection attacks. As a
-result the threshold, that even non-proficient can successfully perform such
-attack, gets lower over time.
-
-*****************************************************************
-Effects of physical attacks in hardware and in software execution
-*****************************************************************
-The change in the behavior of the hardware and software cannot be seen in
-advance when performing a physical attack. On circuit-level they manifest
-in bit faults. These bit faults can cause varied effects in the behavior of
-the device micro-architecture:
-
- - Instruction decoding pipeline is flushed.
- - Altering instructions when decoding.
- - Altering data when fetching or storing.
- - Altering register content, and the program counter.
- - Flip bits in register or memory.
-
-These phenomenons happen at random and cannot be observed directly but the
-effect can be traced in software execution. On the software level the following
-can happen:
-
- - A few instructions are skipped. This can lead to taking different branch
- than normal.
- - Corrupted CPU register or data fetch could alter the result of a comparison
- instruction. Or change the value returned from a function.
- - Corrupted data store could alter the config of peripherals.
- - Very precise attacks with laser can flip bits in any register or in memory.
-
-This is a complex domain. Faults are not well-understood. Different fault models
-exist but all of them target a specific aspect of fault injection. One of the
-most common and probably the easily applicable fault model is the instruction
-skip.
-
-***********************************
-Mitigation against physical attacks
-***********************************
-The applicability of these attacks highly depends on the device. Some
-devices are more sensitive than others. Protection is possible at hardware and
-software levels as well.
-
-On the hardware level, there are chip design principles and system IPs that are
-resistant to fault injection attacks. These can make it harder to perform a
-successful attack and as a result the chip might reset or erase sensitive
-content. The device maker needs to consider what level of physical attack is in
-scope and choose a SoC accordingly.
-
-On top of hardware-level protection, a secondary protection layer can be
-implemented in software. This approach is known as "defence in depth".
-
-Neither hardware nor software level protection is perfect because both can be
-bypassed. The combination of them provides the maximum level of protection.
-However, even when both are in place, it is not certain that they provide 100%
-protection against physical attacks. The best of what is to achievable to harden
-the system to increase the cost of a successful attack (in terms of time and
-equipment), thereby making it non profitable to perform them.
-
-.. _phy-att-countermeasures:
-
-Software countermeasures against physical attacks
-=================================================
-There are practical coding techniques which can be applied to harden software
-against fault injection attacks. They significantly decrease the probability of
-a successful attack:
-
- - Control flow monitor
-
- To catch malicious modification of the expected control flow. When an
- important portion of a program is executed, a flow monitor counter is
- incremented. The program moves to the next stage only if the accumulated
- flow monitor counter is equal to an expected value.
-
- - Default failure
-
- The return value variable should always contain a value indicating
- failure. Changing its value to success is done only under one protected
- flow (preferably protected by double checks).
-
- - Complex constant
-
- It is hard to change a memory region or register to a pre-defined value, but
- usual boolean values (0 or 1) are easier to manipulate.
-
- - Redundant variables and condition checks
-
- To make branch condition attack harder it is recommended to check the
- relevant condition twice (it is better to have a random delay between the
- two comparisons).
-
- - Random delay
-
- Successful fault injection attacks require very precise timing. Adding
- random delay to the code execution makes the timing of an attack much
- harder.
-
- - Loop integrity check
-
- To avoid to skip critical loop iterations. It can weaken the cryptographic
- algorithms. After a loop has executed, check the loop counter whether it
- indeed has the expected value.
-
- - Duplicated execution
-
- Execute a critical step multiple times to prevent fault injection from
- skipping the step. To mitigate multiple consecutive fault injections, random
- delay can be inserted between duplicated executions.
-
-These techniques should be applied in a thoughtful way. If it is applied
-everywhere then it can result in messy code that makes the maintenance harder.
-Code must be analysed and sensitive parts and critical call path must be
-identified. Furthermore, these techniques increase the overall code size which
-might be an issue on the constrained devices.
-
-Currently, compilers are not providing any support to implement these
-countermeasures automatically. On the contrary, they can eliminate the
-protection code during optimization. As a result, the C level protection does
-not add any guarantee about the final behavior of the system. The effectiveness
-of these protections highly depends on the actual compiler and the optimization
-level. The compiled assembly code must be visually inspected and tested to make
-sure that proper countermeasures are in-place and perform as expected.
-
-.. _phy-att-threat-model:
-
-******************************************
-TF-M Threat Model against physical attacks
-******************************************
-
-Physical attack target
-======================
-A malicious actor performs physical attack against TF-M to retrieve assets from
-device. These assets can be sensitive data, credentials, crypto keys. These
-assets are protected in TF-M by proper isolation.
-
-For example, a malicious actor can perform the following attacks:
-
- - Reopen the debug port or hinder the closure of it then connect to the device
- with a debugger and dump memory.
- - Bypass secure boot to replace authentic firmware with a malicious image.
- Then arbitrary memory can be read.
- - Assuming that secure boot cannot be bypassed then an attacker can try to
- hinder the setup of the memory isolation hardware by TF-M
- :term:`Secure Partition Manager` (SPM) and manage to execute the non-secure
- image in secure state. If this is achieved then still an exploitable
- vulnerability is needed in the non-secure code which can be used to inject
- and execute arbitrary code to read the assets.
- - Device might contain unsigned binary blob next to the official firmware.
- This can be any data, not necessarily code. If an attacker manages to
- replace this data with arbitrary content (e.g. a NOP slide leading to a
- malicious code) then they can try to manipulate the program counter to jump
- to this area before setting up the memory isolation.
-
-.. _attacker-capability:
-
-Assumptions on attacker capability
-==================================
-It is assumed that the attacker owns the following capabilities to perform
-physical attack against devices protected by TF-M.
-
- - Has physical access to the device.
- - Able to access external memory, read and possibly tamper it.
- - Able to load arbitrary candidate images for firmware upgrade.
- - Able to manage that bootloader tries to upgrade the arbitrary image from
- staging area.
- - Able to inject faults on hardware level (voltage or power glitch, EM pulse,
- etc.) to the system.
- - Precise timing of fault injection is possible once or a few times, but in
- general the more intervention is required for a successful attack the harder
- will be to succeed.
-
-It is out of the scope of TF-M mitigation if an attacker is able to directly
-tamper or disclose the assets. It is assumed that an attacker has the following
-technical limitations.
-
- - No knowledge of the image signing key. Not able to sign an arbitrary image.
- - Not able to directly access to the chip through debug port.
- - Not able to directly access internal memory.
- - No knowledge of the layout of the die or the memory arrangement of the
- secure code, so precise attack against specific registers or memory
- addresses are out of scope.
-
-Physical attack scenarios against TF-M
-======================================
-Based on the analysis above, a malicious actor may perform physical attacks
-against critical operations in :term:`SPE` workflow and critical modules in
-TF-M, to indirectly gain unauthenticated accesses to assets.
-
-Those critical operations and modules either directly access the assets or
-protect the assets from disclosure. Those operations and modules can include:
-
- - Image validation in bootloader
- - Isolation management in TF-M, including platform specific configuration
- - Cryptographic operations
- - TF-M Secure Storage operations
- - PSA client permission check in TF-M
-
-The detailed scenarios are discussed in following sections.
-
-Physical attacks against bootloader
------------------------------------
-Physical attacks may bypass secure image validation in bootloader and a
-malicious image can be installed.
-
-The countermeasures is bootloader specific implementation and out of the scope
-of this document. TF-M relies on MCUboot by default. MCUboot has already
-implemented countermeasures against fault injection attacks [3]_.
-
-.. _physical-attacks-spm:
-
-Physical attacks against TF-M SPM
----------------------------------
-TF-M SPM initializes and manages the isolation configuration. It also performs
-permission check against secure service requests from PSA clients.
-
-Static isolation configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-It is TF-M SPM's responsibility to build up isolation during the initialization
-phase. If this is missed or not done correctly then it might be possible for
-non-secure code to access some secure memory area or an external device can
-access assets in the device through a debug port.
-
-Therefore, hindering the setup of memory or peripheral isolation hardware is an
-obvious candidate for physical attacks. The initialization phase has a constant
-time execution (like the previous boot-up state), therefore the timing of the
-attack is simpler, compared to cases when secure and non-secure runtime firmware
-is up-and-running for a while and IRQs make timing unpredictable.
-
-Some examples of attacking isolation configuration are shown in the list below.
-
- - Hinder the setting of security regions. Try to execute non-secure code as
- secure.
- - Manipulate the setting of secure regions, try to extend the non-secure
- regions to cover a memory area which otherwise is intended to be secure
- area.
- - Hinder the setting of isolation boundary. In this case vulnerable ARoT code
- has access to all memory.
- - Manipulate peripheral configuration to give access to non-secure code to a
- peripheral which is intended to be secure.
-
-PSA client permission checks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-TF-M SPM performs several permission checks against secure service requests from
-a PSA client, such as:
-
-- Check whether the PSA client is a non-secure client or a secure client
-
- NS client's PSA client ID is negative. NS client is not allowed to directly
- access secure areas. A malicious actor can inject faults when TF-M SPM
- authenticates a NS client. It may manipulate TF-M to accept it as a secure
- client and allow the NS client to access assets.
-
-- Memory access checks
-
- TF-M SPM checks whether the request has correct permission to access a secure
- memory area. A malicious actor can inject faults when TF-M SPM checks memory
- access permission. It may skip critical check steps or corrupt the check
- result. Thereby a malicious service request may pass TF-M memory access check
- and accesses assets which it is not allowed to.
-
-The physical attacks mentioned above relies on the a malicious NS application or
-a vulnerable RoT service to start a malicious secure service request to access
-the assets. The malicious actor has to be aware of the accurate timing of
-dealing with the malicious request in TF-M SPM. The timing can be affected by
-other clients and interrupts.
-It should be more difficult than pure fault injection.
-
-Dynamic isolation boundary configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Physical attack may affect the isolation boundary setting during TF-M context
-switch, especially in Isolation Level 3. For example:
-
- - A fault injection may cause TF-M SPM to skip clear privileged state before
- switching in an ARoT service.
- - A fault injection may cause TF-M SPM to skip updating MPU regions and
- therefore the next RoT service may access assets belonging to a previous
- one.
-
-However, it is much more difficult to find out the accurate timing of TF-M
-context switch, compared to other scenarios in TF-M SPM. It also requires a
-vulnerable RoT service to access assets after fault injection.
-
-Physical attacks against TF-M Crypto service
---------------------------------------------
-Since crypto operations are done by mbedTLS library or by a custom crypto
-accelerator engine and its related software driver stack, the analysis of
-physical attacks against crypto operations is out-of-scope for this document.
-However, in general the same requirements are applicable for the crypto, to be
-compliant with PSA Level 3 certification. That is, it must be resistant against
-physical attacks. So crypto software and hardware must be hardened against
-side-channel and physical attacks.
-
-Physical attacks against Secure Storage
----------------------------------------
-Physical attacks against Internal Trusted Storage
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Based on the assumption in :ref:`attacker-capability`, a malicious actor is
-unable to directly retrieve assets via physical attacks against
-:term:`Internal Trusted Storage` (ITS).
-
-Instead, a malicious actor can inject faults into isolation configuration of ITS
-area in TF-M SPM to gain the access to assets stored in ITS. Refer to
-:ref:`physical-attacks-spm` for details.
-
-Physical attacks against Protected Storage
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Based on the assumption in :ref:`attacker-capability`, a malicious actor can be
-able to directly access external storage device.
-Therefore :term:`Protected Storage` (PS) shall enable encryption and
-authentication by default to detect tampering with the content in external
-storage device.
-
-A malicious actor can also inject faults into isolation configuration of PS and
-external storage device peripherals in TF-M SPM to gain the access to assets
-stored in PS. Refer to :ref:`physical-attacks-spm` for details.
-
-It is out of the scope of TF-M to fully prevent malicious actors from directly
-tampering with or retrieving content stored in external storage devices.
-
-Physical attacks against platform specific implementation
----------------------------------------------------------
-Platform specific implementation includes critical TF-M HAL implementations.
-A malicious actor can perform physical attack against those platform specific
-implementations to bypass the countermeasures in TF-M common code.
-
-Debug access setting
-^^^^^^^^^^^^^^^^^^^^
-TF-M configures debug access according to device lifecycle and accessible debug
-certificates. In general, TF-M locks down the debug port if the device is in
-secure production state. TF-M exposed a HAL API for this purpose.
-The system integrator is responsible to implement this API on a particular SoC
-and harden it against physical attacks:
-
-.. code-block:: c
-
- enum tfm_plat_err_t tfm_spm_hal_init_debug(void);
-
-Platform specific isolation configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-TFM SPM exposes a HAL API for static and dynamic isolation configuration. The
-system integrator is responsible to implement these API on a particular SoC and
-harden it against physical attacks.
-
-.. code-block:: c
-
- enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(void);
- enum tfm_plat_err_t tfm_spm_hal_configure_default_isolation(
- uint32_t partition_idx,
- const struct platform_data_t *platform_data);
- enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start,
- uintptr_t end);
-
-Memory access check
-^^^^^^^^^^^^^^^^^^^
-TFM SPM exposes a HAL API for platform specific memory access check. The
-system integrator is responsible to implement these API on a particular SoC and
-harden it against physical attacks.
-
-.. code-block:: c
-
- tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base,
- size_t size,
- uint32_t attr);
-
-.. _tf-m-against-physical-attacks:
-
-*********************************************
-TF-M countermeasures against physical attacks
-*********************************************
-This section propose a design of software countermeasures against physical
-attacks.
-
-Fault injection hardening library
-=================================
-There is no open-source library which implements generic mitigation techniques
-listed in :ref:`phy-att-countermeasures`.
-TF-M project implements a portion of these techniques. TF-M software
-countermeasures are implemented as a small library Fault Injection Hardening
-(FIH) in TF-M code base. A similar library was first introduced and tested in
-the MCUboot project (version 1.7.0) [2]_ which TF-M relies on.
-
-The FIH library is put under TF-M ``lib/fih/``.
-
-The implementation of the different techniques was assigned to fault injection
-protection profiles. Four profile (OFF, LOW, MEDIUM, HIGH) was introduced to fit
-better to the device capability (memory size, TRNG availability) and to
-protection requirements mandated by the device threat model. Fault injection
-protection profile is configurable at compile-time, default value: OFF.
-
-Countermeasure profiles and corresponding techniques are listed in the table
-below.
-
-+--------------------------------+-------------+----------------+--------------+------------------+
-| Countermeasure | Profile LOW | Profile MEDIUM | Profile HIGH | Comments |
-+================================+=============+================+==============+==================+
-| Control flow monitor | Y | Y | Y | |
-+--------------------------------+-------------+----------------+--------------+------------------+
-| Failure loop hardening | Y | Y | Y | |
-+--------------------------------+-------------+----------------+--------------+------------------+
-| Complex constant | | Y | Y | |
-+--------------------------------+-------------+----------------+--------------+------------------+
-| Redundant variables and checks | | Y | Y | |
-+--------------------------------+-------------+----------------+--------------+------------------+
-| Random delay | | | Y | Implemented, but |
-| | | | | depends on HW |
-| | | | | capability |
-+--------------------------------+-------------+----------------+--------------+------------------+
-
-Similar to MCUboot four profiles are supported, it can be configured at build
-time by setting(default is OFF):
-
- ``-DTFM_FIH_PROFILE=``
-
-How to use FIH library
-======================
-As analyzed in :ref:`phy-att-threat-model`, this section focuses on integrating
-FIH library in TF-M SPM to mitigate physical attacks.
-
- - Identify critical function call path which is mandatory for configuring
- isolation or debug access. Transfer them to ``fih_int`` functions with the
- usage of ``FIH_CALL`` and ``FIH_RET`` macros. These are providing the extra
- checking functionality (control flow monitor, redundant checks and
- variables, random delay, complex constant) according to the profile
- settings. More details about usage can be found here:
- ``tf-m/lib/fih/inc/fault_injection_hardening.h``
-
- Take simplified TF-M SPM initialization flow as an example:
-
- .. code-block:: c
-
- main()
- |
- |--> tfm_core_init()
- | |
- | |--> tfm_spm_hal_init_debug()
- | | |
- | | |--> platform specific debug init
- | |
- | |--> tfm_hal_set_up_static_boundaries()
- | |
- | |--> platform specific isolation impl.
- |
- |--> During each partition initialization
- |
- |--> tfm_spm_hal_configure_default_isolation()
- |
- |--> platform specific peripheral
- isolation impl.
-
- - Might make the important setting of peripheral config register redundant
- and verify them to match expectations before continue.
-
- - Implements an extra verification function which checks the critical hardware
- config before secure code switches to non-secure. Proposed API for this
- purpose:
-
- .. code-block:: c
-
- fih_int tfm_spm_hal_verify_isolation_hw(void);
-
- This function is intended to be called just before the security state
- transition and is responsible for checking all critical hardware
- configuration. The goal is to catch if something is missed and act according
- to system policy. The introduction of one more checking point requires one
- more intervention with precise timing. The system integrator is responsible
- to implement this API on a particular SoC and harden it against physical
- attacks. Make sure that all platform dependent security feature is properly
- configured.
-
- - The most powerful mitigation technique is to add random delay to the code
- execution. This makes the timing of the attack much harder. However it
- requires an entropy source. It is recommended to use the ``HIGH`` profile
- when hardware support is available. There is a porting API layer to fetch
- random numbers in FIH library:
-
- .. code-block:: c
-
- int fih_delay_init(void);
- unsigned char fih_delay_random_uchar(void);
-
- - Similar countermeasures can be implemented in critical steps in platform
- specific implementation.
-
- Take memory isolation settings on AN521 and Musca-B1 platforms as an
- example.
- The following hardware components are responsible for memory isolation in a
- SoC, which is based on SSE-200 subsystem.
- System integrators must examine the chip specific memory isolation solution,
- identify the key components and harden the configuration of those.
- This list just serves as an example here for easier understanding:
-
- - Implementation Defined Attribution Unit (IDAU): Implementation defined,
- it can be a static config or dynamic.
- Contains the default security access permissions of the memory map.
- - SAU: The main module in the CPU to determine the security settings of
- the memory.
- - :term:`MPC`: External module from the CPU point of view. It protects the
- non security aware memories from unauthenticated access. Having a
- properly configured MPC significantly increases the security of the
- system.
- - :term:`PPC`: External module from the CPU
- point of view. Protects the non security aware peripherals from
- unauthenticated access.
- - MPU: Protects memory from unprivileged access. ARoT code has only a
- restricted access in secure domain. It mitigates that a vulnerable or
- malicious ARoT partition can access to device assets.
-
- The following AN521/Musca-B1 specific isolation configuration functions
- shall be hardened against physical attacks.
-
- .. code-block:: c
-
- sau_and_idau_cfg()
- mpc_init_cfg()
- ppc_init_cfg()
-
- Some platform specific implementation rely on platform standard device
- driver libraries. It can become much more difficult to maintain drivers if
- the standard libraries are modified with FIH library. Platform specific
- implementation can implement duplicated execution and redundant variables/
- condition check when calling platform standard device driver libraries
- according to usage scenarios.
-
-Impact on code size
-===================
-The addition of protection code against physical attacks increases the code
-size. The actual increase depends on the selected profile and where the
-mitigation code is added.
-
-Attack experiment with SPM
-==========================
-The goal is to bypass the setting of memory isolation hardware with simulated
-instruction skips in fast model execution (FVP_MPS2_AEMv8M) in order to execute
-the regular non-secure test code in secure state. This is done by identifying
-the configuration steps which must be bypassed to make this happen. The
-instruction skip simulation is achieved by breakpoints and manual manipulation
-of the program counter. The following steps are done on AN521 target, but this
-can be different on another target:
-
- - Bypass the configuration of isolation HW: SAU, MPC.
- - Bypass tfm_spm_hal_nvic_interrupt_enable: The state of the MPC is checked
- here whether is it initialized or not.
- - Bypass the setting of the PSP limit register. Otherwise, a stack overflow
- exception will happen. Because the secure PSP will be overwritten by the
- address of the non-secure stack and on this particular target the non-secure
- stack is on lower address than the value in the secure PSP_LIMIT register.
- - Avoid the clearing of the least significant bit in the non-secure entry
- point, where BLXNS/BXNS is jumping to non-secure code. Having the least
- significant bit cleared indicates to the hardware to switch security state.
-
-The previous steps are enough to execute the non-secure Reset_Handler() in
-secure state. Usually, RTOS is executing on the non-secure side. In order to
-properly boot it up further steps are needed:
-
- - Set the S_VTOR system register to point the address of the NS Vector table.
- Code is executed in secure state therefore when an IRQ hit then the handler
- address is fetched from the table pointed by S_VTOR register. RTOS usually
- do an SVC call at start-up. If S_VTOR is not modified then SPM's SVC handler
- will be executed.
- - TBC: RTX osKernelStart still failing.
-
-The bottom line is that in order to execute the regular non-secure code in
-secure state the attacker need to interfere with the execution flow at many
-places. Successful attack can be made even harder by adding the described
-mitigation techniques and some random delays.
-
-
-*********
-Reference
-*********
-
-.. [1] `PSA Certified Level 3 Lightweight Protection Profile `_
-
-.. [2] `MCUboot project `_
-
-.. [3] `MCUboot fault injection mitigation `_
diff --git a/docs/design_documents/tfm_psa_inter_process_communication.rst b/docs/design_documents/tfm_psa_inter_process_communication.rst
deleted file mode 100644
index 19691711bc..0000000000
--- a/docs/design_documents/tfm_psa_inter_process_communication.rst
+++ /dev/null
@@ -1,234 +0,0 @@
-################################
-TF-M Inter-Process Communication
-################################
-
-:Authors: Ken Liu, Mingyang Sun
-:Organization: Arm Limited
-:Contact: ken.liu@arm.com, mingyang.sun@arm.com
-:Status: Accepted
-
-***********
-Terminology
-***********
-
-IPC - Inter-Process Communication
-
-For more terminology please check Reference_ document.
-
-***************
-Design Overview
-***************
-IPC re-uses existed components in library model:
-
-- SPM – for partition information and isolation actions
-- Core – for exception handling
-
-Extra components for implementing IPC:
-
-- Memory pool
-- Message manager
-- Thread
-- Synchronization objects
-- PSA API
-
-**********************
-Implementation Details
-**********************
-Listed modules are all internal modules except PSA API. Prototypes and
-definitions are not listed for internal modules in this document. For PSA
-API definitions, check them in PSA Firmware Framework specification in the
-reference chapter.
-
-SPM and Core
-============
-SPM manages Secure Partition information. Enhancements need to be done in SPM
-data structure for Secure Partition for IPC due to:
-
-- IPC model requires each Secure Partition has its own stack area while
- isolation level 1 of library model makes all partition shares same stack
- pointer. This needs to be changed while implementing IPC.
-- Multiple services are holding in same Secure Partition and each service
- has its own information like message queue, SID and priority.
-- Changed information related manifest items need to be changed, too.
-
-Modifications in Core:
-
-- More SVC calls need to be added into list since PSA API are implemented as
- SVC calls in TF-M.
-- New PendSV handler for thread scheduling.
-- Arch-related context stacking and switching.
-
-Memory Pool
-===========
-Handles of connection and messages for Secure Partition needs to be allocated
-dynamically. A memory pool is provided in the system to handle dynamic
-allocation. Each memory pool item contains below information:
-
-- A list iterator to chain all of memory pool items.
-- An information member to record information like size and types.
-- The memory item body for caller usage.
-
-A memory area needs to be provided in SPM for the memory pool. It could be an
-array of memory areas defined in the linker script. Two chains are available to
-manage the items: free chain and used chain. And an LRU (Last recent used)
-mechanism is applied for fast seeking while item allocating and destroying.
-
-Message Manager
-===============
-Message Manager handles message creating, pushing, retrieving and destroy. A
-message contains below information:
-
-- Message sender and destination
-- Message status
-- IO vectors for service
-- 'psa_msg_t' for service
-
-A checking needs to be performed in SPM before creating a message to detect if
-a message with the same sender and destination is ongoing. This avoids repeat
-messages are available in the queue.
-
-Thread
-======
-Each Secure Partition has a thread as execution environment. Secure Partition
-is defined statically in TF-M manifest, which indicates that a number of
-threads are statically defined. Threads are chained in SPM and sorted with
-its priority, and there is an extra indicator point to first running thread
-with the highest priority. This helps fast seeking of running threads while
-the scheduler is switching threads.
-
-Thread context contains below information:
-
-- Priority
-- Status
-- Stack pointer
-- Stack pointer limitation
-- Entry
-- Parameter
-- Entry return value
-- Context
-- List iterator
-
-Thread API provides below functions:
-
-- Thread creating and destroying
-- Thread status retrieving and changing
-- Current thread retrieving
-- Thread context switching
-
-PendSV exception in TF-M core is the place thread context APIs been called.
-Before thread switching taking place, isolation status needs to be changed
-based on Secure Partition change and current isolation level – a thread is a
-member of partition which means thread switching caused a partition switching.
-
-Synchronization API
-===================
-A first synchronization object is an event. This could be applied into event
-waiting in the partition, and message response handling in IPC. The event
-object contains below members:
-
-- Owner thread who is waiting for this event
-- Event status (Ready or Not-Ready)
-- List iterator for synchronization objects management
-
-Event API Limitation: could be waited by one thread only.
-
-PSA API
-=======
-This chapter describes the PSA API in an implementation manner.
-
-- API type: could be Client API and Service Partition API
-- Block-able: Block-able API may block caller thread; Non-Block API does not
- block caller thread.
-- Description: The functionality description and important comments.
-
-.. code-block:: c
-
- uint32_t psa_framework_version(void);
- uint32_t psa_version(uint32_t sid);
-
-- Client API
-- Non-Block API
-- These 2 functions are finally handled in SPM and return the framework version
- or version to the caller.
-
-.. code-block:: c
-
- psa_handle_t psa_connect(uint32_t sid, uint32_t version);
- psa_status_t psa_call(psa_handle_t handle, int32_t type,
- const psa_invec *in_vec, size_t in_len,
- psa_outvec *out_vec, size_t out_len);
- void psa_close(psa_handle_t handle);
-
-- Client API
-- Block-able API
-- These 3 APIs are implemented in the same manner and just different
- parameters. SPM converts each call into a corresponding message with a
- parameter in the message body and pushes the message into service queue to
- wait for the response. Scheduler switches to a specified thread (partition)
- and makes Secure Partition to have chance retrieving and process message.
- After a message response is returned to the caller, the waiting caller gets
- to go and get the result.
-
-.. code-block:: c
-
- psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
-
-- Secure Partition API
-- Block-able API
-- This API blocks caller partition if there is no expected event for it. This
- function is implemented based on event API.
-
-.. code-block:: c
-
- void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
- psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);
- size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
- void *buffer, size_t num_bytes);
- size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx,
- size_t num_bytes);
- void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
- const void *buffer, size_t num_bytes);
- void psa_reply(psa_handle_t msg_handle, psa_status_t status);
- void psa_clear(void);
- void psa_eoi(psa_signal_t irq_signal);
-
-- Secure Partition API
-- Non-Block
-- These APIs do not take the initiative to change caller status. They process
- data and return the processed data back to the caller.
-
-.. code-block:: c
-
- void psa_notify(int32_t partition_id);
-
-- Secure Partition API
-- Non-Block
-- This API sets DOORBELL bit in destination partition's event. This API does
- not take the initiative to change caller status.
-
-.. code-block:: c
-
- void psa_panic(void);
-
-- Secure Partition API
-- Block-able API
-- This function will terminate execution within the calling Secure Partition
- and will not return.
-
-*********
-Reference
-*********
-
-| `PSA Firmware Framework specification URL`_
-| `Slides includes IPC basic introduction URL`_
-| `IPC model implementation URL`_
-
-.. _PSA Firmware Framework specification URL: https://pages.arm.com/psa-
- resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
-.. _Slides includes IPC basic introduction URL: https://connect.linaro.org/
- resources/yvr18/sessions/yvr18-108/
-.. _IPC model implementation URL: https://www.youtube.com/watch?v=6wEFoq49qUw
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
deleted file mode 100644
index 47a3db512a..0000000000
--- a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
+++ /dev/null
@@ -1,234 +0,0 @@
-###################################
-Secure Partition Interrupt Handling
-###################################
-
-:Author: Miklos Balint
-:Organization: Arm Limited
-:Contact: Miklos Balint
-:Status: Accepted
-
-Secure Partitions that implement peripheral drivers may need to use interrupts
-to efficiently manage PE utilization.
-
-************************
-Partition implementation
-************************
-
-IRQ lines declared in manifest files for Secure Partitions are assigned IRQ
-signals as described in PSA Firmware Framework.
-
-Interrupt handling is implemented as interrupt service routines (Partition ISR)
-that are executed in the partition context.
-
-Partitions that are owners of IRQ must define interrupt service routines for
-them.
-
-manifest file IRQ declaration example
-=====================================
-
-.. code-block:: json
-
- {"irqs": [
- {
- "line_num": 17,
- "signal": "RTC"
- },
- {
- "line_name": "UART1_IRQ",
- "signal": "UART1"
- }
- ]}
-
-See
-:doc:`secure IRQ handling <../getting_started/tfm_secure_irq_handling>` for
-further information on IRQ source and signal.
-
-Partition ISR function
-======================
-
-The symbol name of the ISR implemented for a given interrupt must be
-``manifest[‘irqs’][idx].signal`` attribute post-fixed with "_isr".
-
-Partition ISR has the signature of a regular interrupt service routine, e.g.:
-
-.. code-block:: c
-
- void UART1_isr(void);
-
-*************
-SPM behaviour
-*************
-
-In the vector table, each interrupt that has an associated partition ISR is
-assigned to an SPM interrupt handler (SPM ISR) that delegates handling to a
-Partition ISR.
-
-Each partition is allocated an asserted signal mask. Every IRQ associated with
-the partition is assigned a position in the signal mask.
-
-When a secure hardware interrupt is asserted, the SPM:
-
-- Acknowledges the interrupt and masks the hardware interrupt line.
-
-- Identifies the Secure Partition which has registered the interrupt (in the
- manifest). This identification can happen either
-
- - using a runtime lookup or
-
- - by registering different instances of the SPM ISR for each interrupt, so the
- runtime lookup is avoided both for the partition Id and the ISR function
- location.
-
-- Sets up execution environment for the secure partition that has registered the
- interrupt.
-
-- Asserts the IRQ signal for the interrupt in the partition's signal mask.
-
-- Execute Partition ISR. If the partition’s stack is active at the time of
- pre-emption by the interrupt (i.e. the Secure Partition is not in idle state),
- the Partition ISR stack frame will be amended to that. If the Secure Partition
- had been idle, a stack frame will be reserved for the duration of the
- Partition ISR execution. The Secure Partition state is changed to running for
- the duration of the Partition ISR.
-
-When the Secure Partition ISR returns, execution is returned to the context
-pre-empted by the IRQ.
-
-Implementation notes
-====================
-
-Interrupts can pre-empt NSPE or secure service execution. Pre-emption of an
-interrupt is only possible by an interrupt of a higher priority, ensuring
-deterministic nesting/un-nesting of stack frames.
-
-*************
-API functions
-*************
-
-psa_wait()
-==========
-
-A call to ``psa_wait()`` from a secure service yields execution to the framework
-and becomes blocked waiting for the assertion of a signal. In the meantime, SPM
-will schedule other contexts that are ready to run. The client remains blocked
-until the service function returns.
-
-If an IRQ signal matching one in ``signal_mask`` to ``psa_wait()`` is asserted,
-the Secure Partition becomes ready to run. When the scheduler activates the
-Secure Partition, the IRQ signal(s) that had been asserted are returned by
-``psa_wait()``. When the service function completes its execution and returns,
-control is taken back to client.
-
-.. Note::
-
- The only signals implemented in the current TF-M implementation are
- interrupt signals.
-
-Signature
----------
-
-.. code-block:: c
-
- psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
-
-Parameters
-----------
-
-``psa_signal_t signal_mask`` defines the set of interrupt signals that can
-resume execution of the secure service.
-
-``uint32_t timeout`` defines timeout for the function, as defined in PSA
-Firmware Framework 1.0-beta-0 (Chapter 4.3.3).
-
-Return
-------
-
-The return value indicates the signal(s) that triggered the resumption of the
-service; i.e. If multiple interrupt events have been handled, it will be
-indicated by the mask value in the return code.
-
-tfm_enable_irq()
-================
-
-A call to ``tfm_enable_irq()`` from a secure service enables an irq.
-
-Signature
----------
-
-.. code-block:: c
-
- void tfm_enable_irq(psa_signal_t irq_signal);
-
-Parameters
-----------
-
-``psa_signal_t irq_signal`` defines the interrupt signal to be enabled.
-
-Return
-------
-
-``void`` Success.
-
-Does not return: The call is invalid, one or more of the following are true:
-
-- irq_signal is not an interrupt signal.
-- irq_signal indicates more than one signal.
-
-tfm_disable_irq()
-=================
-
-A call to ``tfm_disable_irq()`` from a secure service disables an irq.
-
-Signature
----------
-
-.. code-block:: c
-
- void tfm_disable_irq(psa_signal_t irq_signal);
-
-Parameters
-----------
-``psa_signal_t irq_signal`` defines the interrupt signal to be disabled.
-
-Return
-------
-
-``void``: Success.
-
-Does not return: The call is invalid, one or more of the following are true:
-
-- irq_signal is not an interrupt signal.
-- irq_signal indicates more than one signal.
-
-psa_eoi()
-=========
-
-A call ``to psa_eoi()`` from a secure service function or a Partition ISR
-informs SPM that an interrupt has been processed. This clears the IRQ signal in
-the asserted signal mask associated with the partition.
-
-Signature
----------
-
-.. code-block:: c
-
- void psa_eoi(psa_signal_t irq_signal);
-
-Parameters
-----------
-
-``psa_signal_t irq_signal`` defines the interrupt signal that has been
-processed.
-
-Return
-------
-
-``void``: Success.
-
-Does not return: The call is invalid, one or more of the following are true:
-
-- ``irq_signal`` is not an interrupt signal.
-- ``irq_signal`` indicates more than one signal.
-- ``irq_signal`` is not currently asserted.
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_secure_partition_runtime_library.rst b/docs/design_documents/tfm_secure_partition_runtime_library.rst
deleted file mode 100644
index 97e8444174..0000000000
--- a/docs/design_documents/tfm_secure_partition_runtime_library.rst
+++ /dev/null
@@ -1,361 +0,0 @@
-################################
-Secure Partition Runtime Library
-################################
-
-:Organization: Arm Limited
-:Contact: tf-m@lists.trustedfirmware.org
-
-**********
-Background
-**********
-Trusted Firmware - M (TF-M) uses a toolchain provided runtime library and
-supervisor calls to easily implement the PSA Firmware Framework (PSA FF) API.
-This working model works well under isolation level 1 since there are no data
-isolation requirements. While TF-M is evolving, this model is not suitable
-because:
-
- - The high-level isolation requires isolating data but some toolchain library
- interfaces have their own global data which cannot be shared between the
- Secure Partitions.
- - The toolchain libraries are designed without taking security as a core
- design principle.
-
-A TF-M specific runtime library is needed for the following reasons:
-
- - Easier evaluation or certification by security standards.
- - Source code transparency.
- - Sharing code to save ROM and RAM space for TF-M.
-
-PSA FF specification also describes the requirements of C runtime API for Secure
-Partitions.
-
-This runtime library is named the ``Secure Partition Runtime Library``, and the
-abbreviation is ``SPRTL``.
-
-****************
-Design Principal
-****************
-The following requirements are mandatory for SPRTL implementation:
-
-.. important::
- - **CODE ONLY** - No read-write data should be introduced into runtime library
- implementation.
- - **Thread safe** - All functions are designed with thread-safe consideration.
- These APIs access caller stack and caller provided memory only.
- - **Isolation** - Runtime API code is set as executable and read-only in
- higher isolation levels.
- - **Security first** - SPRTL is designed for security and it may come with
- some performance loss.
-
-API Categories
-==============
-Several known types of functions are included in SPRTL:
-
- - C runtime API.
- - RoT Service API.
- - PSA Client and Service API.
- - [Future expansion, to be detailed later] other secure API.
-
-Security Implementation Requirements
-------------------------------------
-If ``malloc/realloc/free`` are provided, they must obey additional requirements
-compared to the C standard: newly allocated memory must be initialized to
-ZERO, and freed memory must be wiped immediately in case the block contains
-sensitive data.
-
-The comparison API ('memcmp' e.g.), they should not return immediately when the
-fault case is detected. The implementation should execute in linear time based
-on input to avoid execution timing side channel attack.
-
-The pointer validation needs to be considered. In general, at least the
-'non-NULL' checking is mandatory. A detection for invalid pointer leads to a
-``psa_panic()``.
-
-The following section describes the first 3 API types and the implementation
-requirements.
-
-C Runtime API
--------------
-PSA FF describes a small set of the C standard library. Part of toolchain
-library API can be used as default if these APIs meet the `Design Principal`_
-and `Security Implementation Requirements`_. The toolchain 'header' and 'types'
-can be reused to simplify the implementation.
-
-These APIs can take the toolchain provided version, or separately implemented
-in case there are extra requirements:
-
-.. note::
- - 'memcpy()/memmove()/memset()'
- - String API
-
-These APIs are proposed to be implemented with the security consideration
-mentioned in `Security Implementation Requirements`_:
-
-.. note::
- - 'memcmp()'
- - Other comparison API if referenced ('strcmp' e.g.).
-
-The following functions are optional, but if present, they must conform to
-additional `Security Implementation Requirements`_:
-
-.. note::
- - 'malloc()/free()/realloc()'
- - 'assert()/printf()'
-
-The following APIs are coupled with toolchain library much so applying toolchain
-library implementation is recommended:
-
-.. note::
- - Division and modulo - arithmetic operations.
- - Other low level or compiler specific functions (such as 'va_list').
-
-Besides the APIs mentioned above, the following runtime APIs are required for
-runtime APIs with private runtime context ('malloc' e.g.):
-
-.. note::
- - '__sprtmain()' - partition entry runtime wrapper.
-
-RoT Service API
----------------
-The description of RoT Service API in PSA FF:
-
-.. note::
- Arm recommends that the RoT Service developer also defines an RoT Service API
- and implementation to encapsulate the use of the IPC protocol, and improve the
- usability of the service for client firmware.
-
-Part of the RoT Service API have proposed specifications, such as the PSA
-Cryptography API, PSA Storage API, and PSA Attestation API. It is suggested that
-the service developer create documents of their RoT Service API and make them
-publicly available.
-
-The RoT Service API has a large amount and it is the main part of SPRTL. This
-chapter describes the general implementation of the RoT Service API and the
-reason for putting them into SPRTL.
-
-In general, a client uses the PSA Client API to access a secure service.
-For example:
-
-.. code-block:: c
-
- /* Example, not a real implementation */
- caller_status_t psa_example_service(void)
- {
- ...
- handle = psa_connect(SERVICE_SID, SERVICE_VERSION);
- if (INVALID_HANDLE(handle)) {
- return INVALID_RETURN;
- }
-
- status = psa_call(handle, type, invecs, inlen, outvecs, outlen);
-
- psa_close(handle);
-
- return TO_CALLER_STATUS(status);
- }
-
-This example encapsulates the PSA Client API, and can be provided as a simpler
-and more generic API for clients to call. It is not possible to statically link
-this API to each Secure Partition because of the limited storage space. The
-ideal solution is to put it inside SPRTL and share it to all Secure Partitions.
-This would simplify the caller logic into this:
-
-.. code-block:: c
-
- if (psa_example_service() != STATUS_SUCCESS) {
- /* do something */
- }
-
-This is the simplest case of encapsulating PSA Client API. If a RoT Service API
-is connect heavy, then, the encapsulation can be changed to include a connection
-handle inside a context data structure. This context data structure type is
-defined in RoT Service headers and the instance is allocated by API caller since
-API implementation does not have private data.
-
-.. note::
- - Even the RoT Service APIs are provided in SPRTL for all clients, the SPM
- performs the access check eventually and decides if the access to service
- can be processed.
- - For those RoT Service APIs only get called by a specific client, they can be
- implemented inside the caller client, instead of putting it into SPRTL.
-
-PSA Client and Service API
---------------------------
-Most of the PSA APIs can be called directly with supervisor calls. The only
-special function is ``psa_call``, because it has **6** parameters. This makes
-the supervisor call handler complex because it has to extract the parameters
-from the stack. The definition of psa_call is the following:
-
-.. code-block:: c
-
- psa_status_t psa_call(psa_handle_t handle, int32_t type,
- const psa_invec *in_vec, size_t in_len,
- psa_outvec *out_vec, size_t out_len);
-
-The parameters need to be packed to avoid passing parameters on the stack, and
-the supervisor call needs to unpack the parameters back to **6** for subsequent
-processing.
-
-Privileged Access Supporting
-============================
-Due to specified API (printf, e.g.) need to access privileged resources, TF-M
-Core needs to provide interface for the resources accessing. The permission
-checking must happen in Core while caller is calling these interface.
-
-Secure Partition Scratch Area
-=============================
-For the API needs partition specific private data, there needs to be a way to
-pass the partition specific data for the API. Use C language preprocessor to
-forward the existing prototype declaration can work, but it has the risks of
-breaking the build since this method needs compilers support ('-include' e.g.).
-Furthermore, no valid runtime tricks can work due to these limitations on
-M-profile architecture:
-
-.. note::
- - We cannot apply the aligned mask on a stack address to get stack bottom
- where the private data pointer stands. This is because aligned stack bottom
- is not supported.
- - We cannot read special registers such as 'PSPLIMIT' for retrieving the
- private data pointer while executing in unprivileged mode.
- - Furthermore, some earlier versions of the ARM architecture do not have
- certain special-purpose registers ('PSPLIMIT' etc.).
-
-A system-provided scratch area is a precondition for implementing APIs that need
-to access private data (such as 'malloc'). The requirements for implementing
-such an area are:
-
-.. important::
- - The area must be ``READ-ONLY`` for the running Secure Partition.
- - The SPM must put the running Secure Partition's metadata into this area
- while scheduling.
-
-With these requirements, the passed parameters can be retrieved by SPRTL easily
-with a read operation on the fixed memory address.
-
-Tooling Support on Partition Entry
-==================================
-PSA FF requires each Secure Partition to have an entry point. For example:
-
-.. code-block:: c
-
- /* The entry point function must not return. */
- void entry_point(void);
-
-Each partition has its own dedicated metadata for heap tracking and other
-runtime state. The metadata is designed to be saved at the read-write data area
-of a partition with a specific name. A generic entry point needs to be available
-to get partition metadata and do initialization before calling into the actual
-partition entry. This generic entry point is defined as '__sprtmain':
-
-.. code-block:: c
-
- void __sprtmain(void)
- {
- /* Get current SP private data from scratch area */
- struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data;
-
- /* Potential heap init - check later chapter */
- if (m->heap_size) {
- m->heap_instance = tfm_sprt_heap_init(m->heap_sa, m->heap_sz);
- }
-
- /* Call thread entry 'entry_point' */
- m->thread_entry();
-
- /* SVC back to tell Core end this thread */
- SVC(THREAD_EXIT);
- }
-
-Since SPM is not aware of the '__sprtmain' in SPRTL, it just calls into the
-entry point listed in partition runtime data structure. And the partition writer
-may be not aware of running of '__sprtmain' as the generic wrapper entry,
-tooling support needs to happen to support this magic. Here is an example of
-partition manifest:
-
-.. code-block:: sh
-
- {
- "name": "TFM_SP_SERVICE",
- "type": "PSA-ROT",
- "priority": "NORMAL",
- "entry_point": "tfm_service_entry",
- "stack_size": "0x1800",
- "heap_size": "0x1000",
- ...
- }
-
-Tooling would do manipulation to tell SPM the partition entry as '__sprtmain',
-and TF-M SPM would switch the activated metadata into the scratch area. Finally,
-the partition entry point gets called and run, tooling helps on the decoupling
-of SPM and SPRTL implementation. The pseudo code of a tooling result:
-
-.. code-block:: c
-
- struct partition_t sp1 {
- .name = "TFM_SP_SERVICE",
- .type = PSA_ROT,
- .priority = NORMAL,
- .id = 0x00000100,
- .entry_point = __sprtmain, /* Tell SPM entry is '__sprtmain' */
- .metadata = { /* struct sprt_meta_t */
- .heap_sa = sp1_heap_buf,
- .heap_sz = sizeof(sp1_heap_buf),
- .thread_entry = sp1_entry, /* Actual Partition Entry */
- .heap_instance = NULL,
- },
- }
-
-Implementation
-==============
-The SPRTL C Runtime sources are put under:
-'$TFM_ROOT/secure_fw/partitions/lib/sprt/'
-
-The output of this folder is a static library named as 'libtfm_sprt.a'. The code
-of 'libtfm_sprt.a' is put into a dedicated section so that a hardware protected
-region can be applied to contain it.
-
-The RoT Service API are put under service interface folder. These APIs are
-marked with the same section attribute where 'libtfm_sprt.a' is put.
-
-The Formatting API - 'printf' and variants
-------------------------------------------
-The 'printf' and its variants need special parameters passing mechanism. To
-implement these APIs, the toolchain provided builtin macro 'va_list', 'va_start'
-and 'va_end' cannot be avoided. This is because of some scenarios such as when
-'stack canaries' are enabled, only the compiler knows the format of the 'canary'
-in order to extract the parameters correctly.
-
-To provide a simple implementation, the following requirements are defined for
-'printf':
-
-- Format keyword 'xXduscp' needs to be supported.
-- Take '%' as escape flag, '%%' shows a '%' in the formatted string.
-- To save heap usage, 32 bytes buffer in the stack for collecting formatted
- string.
-- Flush string outputting due to: a) buffer full b) function ends.
-
-The interface for flushing can be a logging device.
-
-Function with Implied Parameters
---------------------------------
-Take 'malloc' as an example. There is only one parameter for 'malloc' in
-the prototype. Heap management code is put in the SPRTL for sharing with caller
-partitions. The heap instance belongs to each partition, which means this
-instance needs to be passed into the heap management code as a parameter. For
-allocation API in heap management, it needs two parameters - 'size' and
-'instance', while for 'malloc' caller it needs a 'malloc' with one parameter
-'size' only. As mentioned in the upper chapter, this instance can be retrieved
-from the Secure Partition scratch area. The implementation can be:
-
-.. code-block:: c
-
- void *malloc(size_t sz)
- {
- struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data;
-
- return tfm_sprt_alloc(m->heap_instance, sz);
- }
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/tfm_uniform_secure_service_signature.rst b/docs/design_documents/tfm_uniform_secure_service_signature.rst
deleted file mode 100644
index 70c6c6031a..0000000000
--- a/docs/design_documents/tfm_uniform_secure_service_signature.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-################################
-Uniform Secure Service Signature
-################################
-
-:Author: Miklos Balint
-:Organization: Arm Limited
-:Contact: Miklos Balint
-:Status: Accepted
-
-**********************************
-Declaring secure service interface
-**********************************
-
-The following alternative secure service signature is proposed as an
-amendment to existing implementation.
-
-Individual signatures - current method
-======================================
-
-A ``_veneers.c`` file is created in the ``secure_fw/ns_callable``
-directory, that specifies the signature for each veneer function, and calls the
-secure function from the veneers. The respective
-``interface/include/_veneers.h`` file with the veneer declarations
-have to be created and maintained manually.
-Note that at present TF-M framework limits the range of valid return values a
-secure service can provide, reserving a range for framework error codes.
-
-Uniform signatures - proposal
-=============================
-
-The proposal is to use a uniform signature for all the secure functions of the
-secure service. There are multiple advantages of this method:
-
-- TF-M Core can do a sanity check on the access rights of the veneer
- parameters, and there is no need for the secure services to make these checks
- individually. Please note that in the present implementation sanity check is
- only fully supported for level 1 isolation.
-
-- The veneer declarations and implementations for the secure functions can be
- generated automatically from a template (using the secure function list in the
- secure service's manifest)
-
-The signature for such secure services would look like this:
-
-.. code-block:: c
-
- psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len,
- struct psa_outvec *out_vec, size_t out_len);
-
-where
-
-Return value:
--------------
-
-``psa_status_t`` is a status code whose values are described in PSA Firmware
-Framework (as in version 1.0-beta-0 chapter 4.3.3).
-
-Note:
------
-The return value limitations imposed by TF-M framework for proprietary
-secure service veneers would not apply to secure services using the uniform
-signature. This is analogous to how PSA Firmware Framework handles values
-returned by ``psa_reply()`` function.
-
-Arguments:
-----------
-
-.. code-block:: c
-
- /**
- * A read-only input memory region provided to a RoT Service.
- */
- typedef struct psa_invec {
- const void *base; /*!< the start address of the memory buffer */
- size_t len; /*!< the size in bytes */
- } psa_invec;
-
- /**
- * A writable output memory region provided to a RoT Service.
- */
- typedef struct psa_outvec {
- void *base; /*!< the start address of the memory buffer */
- size_t len; /*!< the size in bytes */
- } psa_outvec;
-
- /**
- * in_len: the number of input parameters, i.e. psa_invecs
- * out_len: the number of output parameters, i.e. psa_outvecs
- */
-
-The number of vectors that can be passed to a secure service is constrained:
-
-.. code-block:: c
-
- in_len + out_len <= PSA_MAX_IOVEC
-
-The veneer function declarations and implementations are generated in the
-``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c``
-files respectively. The veneer functions are created with the name
-``tfm__veneer``
-
-Services that implement the uniform signature do not need to manually fill
-the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro.
-
-*************
-Compatibility
-*************
-
-Note that the proposal is for the two types of services (those with proprietary
-signatures and those with uniform signatures) to co-exist, with the intention of
-eventually phasing out proprietary signatures in favour of the more robust,
-uniform signature.
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 4b08906f8b..c6d8d34977 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -2,12 +2,15 @@ Getting Started Guides
======================
.. toctree::
:maxdepth: 1
- :caption: Contents
:glob:
:numbered:
- *
+ tfm_sw_requirement
+ tfm_build_instruction
+ tfm_build_instruction_iar
+ tfm_user_guide
+ /tools/index
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/os_migration_guide_armv8m.rst b/docs/getting_started/os_migration_guide_armv8m.rst
deleted file mode 100644
index 752c33284f..0000000000
--- a/docs/getting_started/os_migration_guide_armv8m.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-#########################################################
-Generic OS migration from Armv7-M to Armv8-M architecture
-#########################################################
-The purpose of this document is to list a set of requirements needed for
-migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
-
-********************
-List of requirements
-********************
-- If the same OS codebase is used for both Secure and Non Secure builds, it is
- suggested to put specific code targeted to the Non Secure build under a
- compile time switch, e.g. ``#if (DOMAIN_NS == 1U)``. The OS build system in
- this case needs to be amended accordingly to support this new switch.
-- If the OS implements stack limit checking, the ``PSPLIM`` register
- needs to be initialized and properly handled during thread context switch
- operations.
-- If the OS manipulates directly the Link Register, the default Link Register
- value used in Handler mode transitions needs to be differentiated between
- Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
-- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
- as described
- `here `__
- , and would like to use the non-secure client identification feature of TF-M,
- then it also have to use the
- ``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
- API function provided by TF-M, as described in
- :doc:`NS client identification documentation `.
-- if the OS doesn't support the API mentioned above, it should set
- ``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
-- .. Note::
-
- This is NOT REQUIRED when the Non Secure OS build is meant
- to be integrated with TF-M running in Secure world.
-
- If generic function calls into Secure world have to be supported in Non Secure
- builds, integrate an API for secure stack memory management (e.g. the
- TrustZone API for secure stack memory management described in
- ``tz_context.h``).
-
---------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index cdfcab5498..453d1d9ada 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -167,7 +167,7 @@ TF-M Profiles
TF-M Profiles are implemented as a single cmake configuration file, under the
``config/profile`` directory. A good understanding can be gained quickly by
looking at the Profile configuration files, but the ultimate reference for
-Profiles are the design documents in the ``docs/design_documents/profiles/``
+Profiles are the design documents in the ``docs/technical_references/profiles/``
directory.
PSA test configuration
@@ -563,4 +563,4 @@ Alternately using traditional cmake syntax
--------------
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_integration_guide.rst b/docs/getting_started/tfm_integration_guide.rst
deleted file mode 100644
index a37a4cb8d3..0000000000
--- a/docs/getting_started/tfm_integration_guide.rst
+++ /dev/null
@@ -1,180 +0,0 @@
-#################
-Integration guide
-#################
-The purpose of this document is to provide a guide on how to integrate TF-M
-with other hardware platforms and operating systems.
-
-*****************
-How to build TF-M
-*****************
-Follow the :doc:`Build instructions `.
-
-********************************************************
-How to export files for building non-secure applications
-********************************************************
-Explained in the :doc:`Build instructions `.
-
-*************************
-How to add a new platform
-*************************
-The hardware platforms currently supported are:
-
-- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
-- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
-- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
-- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3)
-- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
-- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
-- CoreLink SSE-200 Subsystem for MPS3 (AN524)
-- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547)
-- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs)
-- nRF9160 DK (Cortex-M33)
-- nRF5340 PDK/DK (Cortex-M33 Application MCU)
-
-The files related to the supported platforms are contained under the
-``platform`` subfolder. The platform specific files are under
-``platform/ext/target``, which is organised by boards
-(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common``
-is used to store source and header files which are platform generic.
-
-More information about subsystems supported by the MPS2+ board can be found in:
-`MPS2+ homepage `__
-
-More information about subsystems supported by the MPS3 board can be found in:
-`MPS3 homepage `__
-
-More information about the Musca-B1 test chip board can be found in:
-`Musca-B1 homepage `__
-
-More information about the Musca-S1 test chip board can be found in:
-`Musca-S1 homepage `__
-
-More information about subsystems supported by the MPS3 board can be found in:
-`MPS3 homepage `__
-
-More information about the Corstone-300 FVPs can be found in:
-`Arm Ecosystem FVPs homepage `__
-
-More information about the STM32L5xx platform can be found in:
-`STM32L5 series product page `__
-
-More information about the nRF5340 PDK platform can be found in:
-`nRF5340 PDK product page `__
-
-More information about the nRF9160 DK platform can be found in:
-`nRF9160 DK product page `__
-
-Generic drivers and startup/scatter files
-=========================================
-The addition of a new platform means the creation of a new subfolder inside
-``target/`` to provide an implementation of the drivers currently
-used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the
-drivers, startup and scatter files need to be provided for the supported
-toolchains.
-
-There are also board specific drivers which are used by the board
-platform to interact with the external world, for example during tests, that
-have to be provided, e.g. to blink LEDs or count time in the MPS2 board.
-
-.. Note::
-
- Currently ITS, PS and BL2 bootloader use different flash interface
-
-Target configuration files
-==========================
-Inside the base root folder of the selected target, each implementation has to
-provide its own copy of ``target_cfg.c/.h``. This file has target specific
-configuration functions and settings that are called by the TF-M during the
-platform configuration step during TF-M boot. Examples of the configurations
-performed during this phase are the MPC configuration, the SAU configuration,
-or eventually PPC configuration if supported by the hardware platform.
-Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect
-the stdout on UART (this is currently used by TF-M to log messages).
-
-Platform retarget files
-=======================
-An important part that each new platform has to provide is the set of retarget
-files which are contained inside the ``retarget`` folder. These files define the
-peripheral base addresses for the platform, both for the secure and non-secure
-aliases (when available), and bind those addresses to the base addresses used by
-the devices available in the hardware platform.
-
-***************************
-How to integrate another OS
-***************************
-To work with TF-M, the OS needs to support the Armv8-M architecture and, in
-particular, it needs to be able to run in the non-secure world. More
-information about OS migration to the Armv8-M architecture can be found in the
-:doc:`OS requirements `. 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
-``/interface`` path. The NS side is only allowed to call
-TF-M secure functions (veneers) from the NS Thread mode. For this reason, the
-API is a collection of functions in the ``/interface/include``
-directory. For example, the interface for the Protected Storage (PS) service
-is described in the file ``psa_ps_api.h`` as a collection of functions that
-call service veneer functions. This API is a wrapper for the secure veneers,
-and returns the return value from the service to the caller.
-
-The protected storage service uses a numerical ID, to identify the clients that
-use the service. For details see
-:doc:`ns client identification documentation `.
-
-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
-``/install`` folder structure in the test specific files,
-i.e. ``/install/export/tfm/test/inc``. The non-secure regression
-tests are precompiled and delivered as a static library which is available in
-``/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
-``/install/export/tfm/test/inc``. OS needs to provide the
-implementation of these wrappers to be able to run the tests.
-
-NS client Identification
-========================
-See
-:doc:`ns client identification documentation `.
-
-*********************
-Non-secure interrupts
-*********************
-Non-secure interrupts are allowed to preempt Secure thread mode.
-With the current implementation, a NSPE task can spoof the identity of another
-NSPE task. This is an issue only when NSPE has provisions for task isolation.
-Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
-to NS interrupts to the lower half of available priorities so that it wouldn't
-be possible for any non-secure interrupt to preempt a higher-priority secure
-interrupt.
-
-**********************************
-Integration with non-Cmake systems
-**********************************
-
-Generated Files
-===============
-
-Files that are derived from PSA manifests are generated at build-time by cmake.
-For integration with systems that do no use cmake, the files must be generated
-manually.
-
-The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
-arguments will be needed to be provided. Please refer to
-``tfm_parse_manifest_list.py --help`` for more details.
-
-Some variables are used in the template files, these will need to be set in the
-environment before the script will succeed when the script is not run via cmake.
-
---------------
-
-*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_ns_client_identification.rst b/docs/getting_started/tfm_ns_client_identification.rst
deleted file mode 100644
index 44fd3435ad..0000000000
--- a/docs/getting_started/tfm_ns_client_identification.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-###########################
-Non-Secure Identity Manager
-###########################
-The ID of the current application/thread is known by TF-M, and the PS service
-queries the ID of the currently running client via a dedicated API.
-
-The identity of secure clients can be tracked by TF-M core, because it also
-manages the contexts of the partitions. However to differentiate NS clients, it
-relies on the services provided by the NS OS.
-
-Tracking of context changes are possible by relying on the NS OS calling the
-Thread Context Management for Armv8-M TrustZone APIs, as described
-`here `__
-
-However TF-M needs an extra API, to assign a client ID to the TZ context created
-as a result of the
-``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call.
-
-To do this, the
-``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be
-called from an SVC handler, with the client ID of the currently running client.
-
-In the current implementation of TF-M, an SVC call is provided for the NS
-clients to be called at the beginning of their main function.
-
-``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``
-
-The SVC call handler of the above SVC maps the name of the current thread to a
-hardcoded client id, and sends it to the TF-M core via the earlier discussed
-API.
-
-The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``.
-
-The system integrators **may** implement the non-secure ID mapping based on
-their application/threat model.
-
-In case the NS OS doesn't use the Thread Context Management for Armv8-M
-TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
-client ID to it automatically.
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_secure_boot.rst b/docs/getting_started/tfm_secure_boot.rst
deleted file mode 100644
index 95d3f68ed5..0000000000
--- a/docs/getting_started/tfm_secure_boot.rst
+++ /dev/null
@@ -1,808 +0,0 @@
-###########
-Secure boot
-###########
-For secure devices it is security critical to enforce firmware authenticity to
-protect against execution of malicious software. This is implemented by building
-a trust chain where each step in the execution chain authenticates the next
-step before execution. The chain of trust in based on a "Root of Trust" which
-is implemented using asymmetric cryptography. The Root of Trust is a combination
-of an immutable bootloader and a public key (ROTPK).
-
-.. Warning::
- In order to implement a proper chain of trust functionality, it is
- mandatory that the first stage bootloader and ROTPK is stored in an
- **immutable** way. To achieve this the bootloader code must be stored and
- executed from ROM or such part of flash memory which supports write
- protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If
- the SoC has a built-in BL1 (immutable) bootloader and the immutability of
- TF-M secure boot code is not guaranteed then TF-M secure boot code must be
- authenticated by BL1 bootloader before execution. If immutability of root
- of trust (first stage bootloader + ROTPK) is not ensured then there is a
- risk that the secure boot process could be bypassed, which could lead to
- arbitrary code execution on the device. Current TF-M secure boot code is
- intended to be a second stage bootloader, therefore it requires
- authentication before execution. If TF-M secure boot code is used as a first
- stage bootloader then it must be stored according to the above requirements.
-
-*******************************
-Second stage bootloader in TF-M
-*******************************
-By default, the MCUboot project from
-`GitHub `__ is used as the secure
-bootloader in TF-M. The repository is going to be automatically downloaded by
-CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION``
-CMake variable. If you wish to use a locally downloaded copy, the CMake variable
-``MCUBOOT_PATH`` can be set to its location. This document contains information
-about how MCUboot has been integrated to TF-M. For further information about
-MCUboot design please refer to the `MCUBoot homepage `__.
-
-Bootloader is started when CPU is released from reset. It runs in secure mode.
-It authenticates the firmware image by hash (SHA-256) and digital signature
-(RSA-3072) validation. Public key, that the checks happens against, can be built
-into the bootloader image or can be provisioned to the SoC during manufacturing.
-Metadata of the image is delivered together with the image itself in a header
-and trailer section. In case of successful authentication, bootloader passes
-execution to the secure image. Execution never returns to bootloader until
-next reset.
-
-A default RSA key pair is stored in the repository, public key is in ``keys.c``
-and private key is in ``root-RSA-3072.pem``.
-
-.. Warning::
- DO NOT use them in production code, they are exclusively for testing!
-
-The private key must be stored in a safe place outside of the repository.
-``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository,
-or installed through the pip package manager) can be used to generate new key
-pairs.
-
-The bootloader can handle the secure and non-secure images independently
-(multiple image boot) or together (single image boot). In case of multiple image
-boot they are signed independently with different keys and they can be updated
-separately. In case of single image boot the secure and non-secure image is
-handled as a single blob, therefore they must be contiguous in the device
-memory. In this case they are signed together and also they can be updated only
-together. In order to have the same artefacts at the end of the build regardless
-of how the images are handled (independently or together) the images are always
-concatenated. In case of single image boot they are concatenated first and then
-signed. In case of multiple image boot they are separately signed first and then
-concatenated. Preparation of payload is done by Python scripts:
-``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M
-payload can be found in: ``/bin/tfm_s_ns_signed.bin``
-
-*********************
-Integration with TF-M
-*********************
-MCUBoot assumes a predefined memory layout which is described below (applicable
-for AN521). It is mandatory to define the primary slot and the secondary slot
-partitions, but their size and location can be changed::
-
- - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
- - 0x0008_0000 - 0x000F_FFFF: Primary slot : Single binary blob:
- Secure + Non-Secure image;
- Primary memory partition
- - 0x0008_0000 - 0x0008_03FF: Common image header
- - 0x0008_0400 - 0x0008_xxxx: Secure image
- - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
- - 0x0010_0400 - 0x0010_xxxx: Non-secure image
- - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256), RSA signature and other
- metadata of combined image
-
- - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image;
- Secondary memory partition, structured
- identically to the primary slot
- - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image
- swapping
-
-Multiple image boot requires a slightly different layout::
-
- - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
- - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image
- - 0x0008_0000 - 0x0008_03FF: Secure image header
- - 0x0008_0400 - 0x000x_xxxx: Secure image
- - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other
- metadata of secure image
-
- - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image
- - 0x0010_0000 - 0x0010_03FF: Non-secure image header
- - 0x0010_0400 - 0x001x_xxxx: Non-secure image
- - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other
- metadata of non-secure image
-
- - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image
- - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image
-
- - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image
- swapping, used for secure and non-secure
- image as well
-
-**************************
-Firmware upgrade operation
-**************************
-MCUBoot handles only the firmware authenticity check after start-up and the
-firmware switch part of the firmware update process. Downloading the new version
-of the firmware is out-of-scope for MCUBoot. MCUBoot supports three different
-ways to switch to the new firmware and it is assumed that firmware images are
-executed-in-place (XIP). The default behaviour is the overwrite-based image
-upgrade. In this case the active firmware is always executed from the primary
-slot and the secondary slot is a staging area for new images. Before executing
-the new firmware image, the content of the primary slot must be overwritten with
-the content of the secondary slot (the new firmware image). The second option is
-the image swapping strategy when the content of the two memory slots must be
-physically swapped. This needs the scratch area to be defined in the memory
-layout. The third option is the direct execute-in-place version, which
-eliminates the complexity of image swapping and its administration. Active image
-can be executed from either memory slot, but new firmware must be linked to the
-address space of the proper (currently inactive) memory slot.
-
-Overwrite operation
-===================
-Active image is stored in the primary slot, and this image is started always by
-the bootloader. Therefore images must be linked to the primary slot. If the
-bootloader finds a valid image in the secondary slot, which is marked for
-upgrade, then the content of the primary slot will be simply overwritten with
-the content of the secondary slot, before starting the new image from the
-primary slot. After the content of the primary slot has been successfully
-overwritten, the header and trailer of the new image in the secondary slot is
-erased to prevent the triggering of another unnecessary image upgrade after a
-restart. The overwrite operation is fail-safe and resistant to power-cut
-failures. For more details please refer to the MCUBoot
-`documentation `__.
-
-Swapping operation
-==================
-This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
-switch (see `Build time configuration`_). With swapping image upgrade strategy
-the active image is also stored in the primary slot and it will always be
-started by the bootloader. If the bootloader finds a valid image in the
-secondary slot, which is marked for upgrade, then contents of the primary slot
-and the secondary slot will be swapped, before starting the new image from the
-primary slot. Scratch area is used as a temporary storage place during image
-swapping. Update mark from the secondary slot is removed when the swapping is
-successful. The boot loader can revert the swapping as a fall-back mechanism to
-recover the previous working firmware version after a faulty update. The swap
-operation is fail-safe and resistant to power-cut failures. For more details
-please refer to the MCUBoot
-`documentation `__.
-
-.. Note::
-
- After a successful image upgrade the firmware can mark itself as "OK" at
- runtime by setting the image_ok flag in the flash. When this happens, the
- swap is made "permanent" and MCUBoot will then still choose to run it
- during the next boot. Currently TF-M does not set the image_ok flag,
- therefore the bootloader will always perform a "revert" (swap the images
- back) during the next boot.
-
-Direct execute-in-place operation
-=================================
-This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
-switch (see `Build time configuration`_). When enabling direct-xip operation
-then the active image flag is moved between slots during firmware upgrade. If
-firmware is executed-in-place (XIP), then two firmware images must be generated.
-One of them is linked to be executed from the primary slot memory region and the
-other from the secondary slot. The firmware upgrade client, which downloads the
-new image, must be aware, which slot hosts the active firmware and which acts as
-a staging area and it is responsible for downloading the proper firmware image.
-At boot time MCUBoot inspects the version number in the image header and passes
-execution to the newer firmware version. New image must be marked for upgrade
-which is automatically done by Python scripts at compile time. Image
-verification is done the same way in all operational modes. If new image fails
-during authentication then MCUBoot erases the memory slot and starts the other
-image, after successful authentication.
-
-To select which slot the image is to be executed from, set
-``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create
-two build directories when building images using this mode, as intermediate
-dependencies cannot be reused due to changes in the flash layout.
-
-.. Note::
-
- Only single image boot is supported with direct-xip upgrade mode.
-
-RAM Loading firmware upgrade
-============================
-Musca-S supports an image upgrade mode that is separate to the other (overwrite,
-swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer
-to the table below). Like the direct-xip mode, this selects the newest image
-by reading the image version numbers in the image headers, but instead of
-executing it in place, the newest image is copied to RAM for execution. The load
-address, the location in RAM where the image is copied to, is stored in the
-image header.
-
-.. Note::
-
- Only single image boot is supported with ``RAM load`` upgrade mode.
-
-Summary of different modes for image upgrade
-============================================
-Different implementations of the image upgrade operation (whether through
-overwriting, swapping, direct-xip or loading into RAM and executing from
-there) are supported by the platforms. The table below shows which of these
-modes are supported by which platforms:
-
-+---------------------+-----------------+----------------------------------------------------------+
-| | Without BL2 [1]_| With BL2 [2]_ |
-+=====================+=================+===============+==========+================+==============+
-| | XIP | XIP | XIP | XIP | Not XIP |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| | | Overwrite [3]_| Swap [4]_| direct-xip [5]_| RAM load [6]_|
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN521 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN519 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| FVP_SSE300_MPS2 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| LPC55S69 | Yes | Yes | No | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| Musca-B1 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| Musca-S1 | Yes | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN524 | Yes | No | No | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| AN547 | No | Yes | Yes | Yes | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| PSoC64 | Yes | No | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| STM_DISCO_L562QE | No | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| nRF9160 DK | Yes | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-| nRF5340 PDK/DK | Yes | Yes | No | No | No |
-+---------------------+-----------------+---------------+----------+----------------+--------------+
-
-.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF``
-
-.. [2] BL2 is enabled by default
-
-.. [3] The image executes in-place (XIP) and is in Overwrite mode for image
- update by default
-
-.. [4] To enable XIP Swap mode, assign the "SWAP" string to the
- ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
- configuration file, or include this macro definition in the command line
-
-.. [5] To enable direct-xip, assign the "DIRECT_XIP" string to the
- ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
- configuration file, or include this macro definition in the command line
-
-.. [6] To enable RAM load, assign the "RAM_LOAD" string to the
- ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
- configuration file, or include this macro definition in the command line
-
-*******************
-Multiple image boot
-*******************
-It is possible to update the firmware images independently to support the
-scenario when secure and non-secure images are provided by different vendors.
-Multiple image boot is supported only together with the overwrite and swap
-firmware upgrade modes.
-
-It is possible to describe the dependencies of the images on each other in
-order to avoid a faulty upgrade when incompatible versions would be installed.
-These dependencies are part of the image manifest area.
-The dependencies are composed from two parts:
-
- - **Image identifier:** The number of the image which the current image (whose
- manifest area contains the dependency entry) depends on. The image identifier
- starts from 0.
-
- - **Minimum version:** The minimum version of other image must be present on
- the device by the end of the upgrade (both images might be updated at the
- same time).
-
-Dependencies can be added to the images at compile time with the following
-compile time switches:
-
- - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
- minimum required version of the secure image.
- - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the
- minimum required version of the non-secure image.
-
-Example of how to provide the secure image minimum version::
-
- cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 ..
-
-********************
-Signature algorithms
-********************
-MbedTLS library is used to sign the images. The list of supported signing
-algorithms:
-
- - `RSA-2048`
- - `RSA-3072`: default
-
-Example keys stored in:
-
- - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image
- in case of multiple image boot
- - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple
- image boot
- - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image
- in case of multiple image boot
- - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple
- image boot
-
-************************
-Build time configuration
-************************
-MCUBoot related compile time switches can be set by cmake variables.
-
-- BL2 (default: True):
- - **True:** TF-M built together with bootloader. MCUBoot is executed after
- reset and it authenticates TF-M and starts secure code.
- - **False:** TF-M built without bootloader. Secure image linked to the
- beginning of the device memory and executed after reset. If it is false
- then using any of the further compile time switches is invalid.
-- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"):
- - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite.
- - **"SWAP":** Activate swapping firmware upgrade operation.
- - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade
- operation.
- - **"RAM_LOAD":** Activate RAM loading firmware upgrade operation, where
- the latest image is copied to RAM and runs from there instead of being
- executed in-place.
-- MCUBOOT_SIGNATURE_TYPE (default: RSA):
- - **RSA:** Image is signed with RSA algorithm
-- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072):
- - **2048:** Image is signed with 2048 bit key.
- - **3072:** Image is signed with 3072 bit key.
-- MCUBOOT_IMAGE_NUMBER (default: 2):
- - **1:** Single image boot, secure and non-secure images are signed and
- updated together.
- - **2:** Multiple image boot, secure and non-secure images are signed and
- updatable independently.
-- MCUBOOT_HW_KEY (default: True):
- - **True:** The hash of public key is provisioned to the SoC and the image
- manifest contains the whole public key (imgtool uses
- ``--public_key_format=full``). MCUBoot validates the key before using it
- for firmware authentication, it calculates the hash of public key from the
- manifest and compare against the retrieved key-hash from the hardware.
- This way MCUBoot is independent from the public key(s). Key(s) can be
- provisioned any time and by different parties.
- - **False:** The whole public key is embedded to the bootloader code and the
- image manifest contains only the hash of the public key (imgtool uses
- ``--public_key_format=hash``). MCUBoot validates the key before using it
- for firmware authentication, it calculates the hash of built-in public key
- and compare against the retrieved key-hash from the image manifest. After
- this the bootloader can verify that the image was signed with a private
- key that corresponds to the retrieved key-hash (it can have more public
- keys embedded in and it may have to look for the matching one). All the
- public key(s) must be known at MCUBoot build time.
-- MCUBOOT_LOG_LEVEL:
- Can be used to configure the level of logging in MCUBoot. The possible
- values are the following:
-
- - **OFF**
- - **ERROR**
- - **WARNING**
- - **INFO**
- - **DEBUG**
-
- The logging in MCUBoot can be disabled and thus the code size can be reduced
- by setting it to ``OFF``. Its value depends on the build type. If the build
- type is ``Debug`` then default value is ``INFO``. In case of different kinds
- of ``Release`` builds the default value is ``OFF``. The default value can
- be overridden through the command line or in the CMake GUI regardless of the
- build type.
-- MCUBOOT_ENC_IMAGES (default: False):
- - **True:** Adds encrypted image support in the source and encrypts the
- resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot
- repository.
- - **False:** Doesn't add encrypted image support and doesn't encrypt the
- image.
-
- .. Note::
- The decryption takes place during the upgrade process, when the images
- are being moved between the slots. This means that boards that don't
- already have an image on them with MCUBoot that has been compiled with
- ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load
- an encrypted image to such boards, an upgrade needs to be executed. This
- can be done by using MCUBoot, putting an image in the secondary image
- area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the
- ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using
- ``SWAP``, an image is needed in the primary image area as well, to
- trigger the update.
-
- .. Warning::
- DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is
- exclusively for testing!
-
-Image versioning
-================
-An image version number is written to its header by one of the Python scripts,
-and this number is used by the bootloader when the direct execute-in-place or
-the RAM loading mode is enabled. It is also used in case of multiple image boot
-when the bootloader checks the image dependencies if any have been added to the
-images.
-
-The version number of the image (single image boot) can manually be passed in
-through the command line in the cmake configuration step::
-
- cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=1.2.3+4 ..
-
-Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
-where the missing numbers are automatically set to zero. The image version
-number argument is optional, and if it is left out, then the version numbers of
-the image(s) being built in the same directory will automatically change. In
-this case, the last component (the build number) automatically increments from
-the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
-**until a number is explicitly provided**. If automatic versioning is in place
-and then an image version number is provided for the first time, the new number
-will take precedence and be used instead. All subsequent image versions are
-then set to the last number that has been specified, and the build number would
-stop incrementing. Any new version numbers that are provided will overwrite
-the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
-versioning, please start a clean build without specifying the image version
-number at all. In case of multiple image boot there are separate compile time
-switches for both images to provide their version: ``IMAGE_VERSION_S`` and
-``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``.
-
-Security counter
-================
-Each signed image contains a security counter in its manifest. It is used by the
-bootloader and its aim is to have an independent (from the image version)
-counter to ensure rollback protection by comparing the new image's security
-counter against the original (currently active) image's security counter during
-the image upgrade process. It is added to the manifest (to the TLV area that is
-appended to the end of the image) by one of the Python scripts when signing the
-image. The value of the security counter is security critical data and it is in
-the integrity protected part of the image. The last valid security counter
-should always be stored in a non-volatile and trusted component of the device
-and its value should always be increased if a security flaw was fixed in the
-current image version. The value of the security counter (single image boot) can
-be specified at build time in the cmake configuration step::
-
- cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=42 ../
-
-The security counter can be independent from the image version, but not
-necessarily. Alternatively, if it is not specified at build time with the
-``SECURITY_COUNTER`` option the Python script will automatically generate it
-from the image version number (not including the build number) and this value
-will be added to the signed image. In case of multiple image boot there are
-separate compile time switches for both images to provide their security counter
-value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used
-instead of ``SECURITY_COUNTER_S``. If these are not defined then the security
-counter values will be derived from the corresponding image version similar to
-the single image boot.
-
-***************************
-Signing the images manually
-***************************
-Normally the build system handles the signing (computing hash over the image
-and security critical manifest data and then signing the hash) of the firmware
-images. However, the images also can be signed manually by using the ``imgtool``
-Python program which is located in the MCUboot repository in the ``scripts``
-folder or can be installed with the pip package manager.
-Issue the ``python3 imgtool.py sign --help`` command in the directory for more
-information about the mandatory and optional arguments. The tool takes an image
-in binary or Intel Hex format and adds a header and trailer that MCUBoot is
-expecting. In case of single image boot after a successful build the
-``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure
-images) must be passed to the script and in case of multiple image boot the
-``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed
-images.
-
-Signing the secure image manually in case of multiple image boot
-================================================================
-
-::
-
- python3 bl2/ext/mcuboot/scripts/imgtool.py sign \
- --layout /bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \
- -k /bl2/ext/mcuboot/root-RSA-3072.pem \
- --public-key-format full \
- --align 1 \
- -v 1.2.3+4 \
- -d "(1,1.2.3+0)" \
- -s 42 \
- -H 0x400 \
- /bin/tfm_s.bin \
- /bin/tfm_s_signed.bin
-
-************************
-Testing firmware upgrade
-************************
-As downloading the new firmware image is out of scope for MCUBoot, the update
-process is started from a state where the original and the new image are already
-programmed to the appropriate memory slots. To generate the original and a new
-firmware package, TF-M is built twice with different build configurations.
-
-Overwriting firmware upgrade
-============================
-Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases
-(single image boot), but with two different build configurations: default and
-regression. Save the artifacts between builds, because second run can overwrite
-original binaries. Download default build to the primary slot and regression
-build to the secondary slot.
-
-Executing firmware upgrade on FVP_MPS2_AEMv8M
----------------------------------------------
-.. code-block:: bash
-
- /sw/models/bin/FVP_MPS2_AEMv8M \
- --parameter fvp_mps2.platform_type=2 \
- --parameter cpu0.baseline=0 \
- --parameter cpu0.INITVTOR_S=0x10000000 \
- --parameter cpu0.semihosting-enable=0 \
- --parameter fvp_mps2.DISABLE_GATING=0 \
- --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
- --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal0.quiet=0 \
- --parameter fvp_mps2.telnetterminal1.quiet=1 \
- --parameter fvp_mps2.telnetterminal2.quiet=1 \
- --application cpu0=/bin/bl2.axf \
- --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=/bin/tfm_s_ns_signed.bin@0x10180000
-
-Executing firmware upgrade on SSE 200 FPGA on MPS2 board
---------------------------------------------------------
-
-::
-
- TITLE: Versatile Express Images Configuration File
- [IMAGES]
- TOTALIMAGES: 3 ;Number of Images (Max: 32)
- IMAGE0ADDRESS: 0x00000000
- IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
- IMAGE1ADDRESS: 0x10080000
- IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test binary blob
- IMAGE2ADDRESS: 0x10180000
- IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
-
-The following message will be shown in case of successful firmware upgrade:
-
-::
-
- [INF] Starting bootloader
- [INF] Swap type: test
- [INF] Image upgrade secondary slot -> primary slot
- [INF] Erasing the primary slot
- [INF] Copying the secondary slot to the primary slot: 0x100000 bytes
- [INF] Bootloader chainload address offset: 0x80000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
-
- #### Execute test suites for the Secure area ####
- Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
- ...
-
-To update the secure and non-secure images separately (multiple image boot),
-set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default
-configuration value) and follow the same instructions as in case of single image
-boot.
-
-Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board
-------------------------------------------------------------------
-
-::
-
- TITLE: Versatile Express Images Configuration File
- [IMAGES]
- TOTALIMAGES: 4 ;Number of Images (Max: 32)
- IMAGE0ADDRESS: 0x00000000
- IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
- IMAGE1ADDRESS: 0x10080000
- IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
- IMAGE2ADDRESS: 0x10180000
- IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image
- IMAGE3ADDRESS: 0x10200000
- IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image
-
-Note that both the concatenated binary blob (the images are signed separately
-and then concatenated) and the separate signed images can be downloaded to the
-device because on this platform (AN521) both the primary slots and the secondary
-slots are contiguous areas in the Flash (see `Integration with TF-M`_). The
-following message will be shown in case of successful firmware upgrades:
-
-::
-
- [INF] Starting bootloader
- [INF] Swap type: test
- [INF] Swap type: test
- [INF] Image upgrade secondary slot -> primary slot
- [INF] Erasing the primary slot
- [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
- [INF] Image upgrade secondary slot -> primary slot
- [INF] Erasing the primary slot
- [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
- [INF] Bootloader chainload address offset: 0x80000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
- TFM level is: 1
- [Sec Thread] Jumping to non-secure code...
-
- #### Execute test suites for the Secure area ####
- Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
- ...
-
-Swapping firmware upgrade
-=============================
-Follow the same instructions and platform related configurations as in case of
-overwriting build including these changes:
-
-- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP"
- before build.
-- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image
- boot) or "2" (multiple image boot) before build.
-
-During single image boot the following message will be shown in case of
-successful firmware upgrade, ``Swap type: test`` indicates that images were
-swapped:
-
-::
-
- [INF] Starting bootloader
- [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3
- [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2
- [INF] Boot source: primary slot
- [INF] Swap type: test
- [INF] Bootloader chainload address offset: 0x80000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
-
- #### Execute test suites for the Secure area ####
- Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
- ...
-
-Direct execute-in-place firmware upgrade
-========================================
-Follow the same instructions and platform related configurations as in case of
-overwriting build including these changes:
-
-- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "DIRECT_XIP"
- before build.
-- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir.
-- Make sure the image version number was increased between the two build runs
- either by specifying it manually or by checking in the build log that it was
- incremented automatically.
-
-Executing firmware upgrade on FVP_MPS2_AEMv8M
----------------------------------------------
-
-.. code-block:: bash
-
- /sw/models/bin/FVP_MPS2_AEMv8M \
- --parameter fvp_mps2.platform_type=2 \
- --parameter cpu0.baseline=0 \
- --parameter cpu0.INITVTOR_S=0x10000000 \
- --parameter cpu0.semihosting-enable=0 \
- --parameter fvp_mps2.DISABLE_GATING=0 \
- --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
- --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
- --parameter fvp_mps2.telnetterminal0.quiet=0 \
- --parameter fvp_mps2.telnetterminal1.quiet=1 \
- --parameter fvp_mps2.telnetterminal2.quiet=1 \
- --application cpu0=/bin/bl2.axf \
- --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \
- --data cpu0=/bin/tfm_s_ns_signed.bin@0x10180000
-
-Executing firmware upgrade on SSE 200 FPGA on MPS2 board
---------------------------------------------------------
-
-::
-
- TITLE: Versatile Express Images Configuration File
- [IMAGES]
- TOTALIMAGES: 3 ;Number of Images (Max: 32)
- IMAGE0ADDRESS: 0x00000000
- IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
- IMAGE1ADDRESS: 0x10080000
- IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
- IMAGE2ADDRESS: 0x10180000
- IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
-
-Executing firmware upgrade on Musca-B1 and Musca-S1 boards
-----------------------------------------------------------
-After the two images have been built, they can be concatenated to create the
-combined image using ``srec_cat``:
-
-- Linux::
-
- srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
-
-- Windows::
-
- srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
-
-The following message will be shown in case of successful firmware upgrade,
-notice that image with higher version number (``version=1.2.3.5``) is executed:
-
-::
-
- [INF] Starting bootloader
- [INF] Image 0: version=1.2.3.4, magic= good, image_ok=0x3
- [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3
- [INF] Booting image from the secondary slot
- [INF] Bootloader chainload address offset: 0xa0000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
-
- #### Execute test suites for the Secure area ####
- Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
- ...
-
-Executing firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524)
--------------------------------------------------------------------------
-
-::
-
- TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
-
- [IMAGES]
- TOTALIMAGES: 3 ;Number of Images (Max: 32)
-
- IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
- IMAGE0ADDRESS: 0x00000000
- IMAGE0FILE: \SOFTWARE\bl2.bin ;BL2 bootloader
- IMAGE1UPDATE: AUTO
- IMAGE1ADDRESS: 0x00040000
- IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob
- IMAGE2UPDATE: AUTO
- IMAGE2ADDRESS: 0x000C0000
- IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob
-
-RAM loading firmware upgrade
-============================
-To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOAD"
-(either in the configuration file or through the command line), and then specify
-a destination load address in RAM where the image can be copied to and executed
-from. The ``IMAGE_LOAD_ADDRESS`` macro must be specified in the target dependent
-files, for example with Musca-S, its ``flash_layout.h`` file in the ``platform``
-folder should include ``#define IMAGE_LOAD_ADDRESS #0xA0020000``
-
-Executing firmware upgrade on Musca-S board
---------------------------------------------
-After two images have been built, they can be concatenated to create the
-combined image using ``srec_cat``:
-
-- Linux::
-
- srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
-
-- Windows::
-
- srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
-
-The following message will be shown in case of successful firmware upgrade when,
-RAM loading is enabled, notice that image with higher version number
-(``version=0.0.0.2``) is executed:
-
-::
-
- [INF] Starting bootloader
- [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3
- [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3
- [INF] Image has been copied from the secondary slot in flash to SRAM address 0xA0020000
- [INF] Booting image from SRAM at address 0xA0020000
- [INF] Bootloader chainload address offset: 0x20000
- [INF] Jumping to the first image slot
- [Sec Thread] Secure image initializing!
-
---------------
-
-****************************************
-Integration with Firmware Update service
-****************************************
-The shim layer of the Firmware Update partition calls the APIs in
-bootutil_misc.c to control the image status.
-
-- Call ``boot_write_magic()`` to make the image as a candidate image for booting.
-- Call ``boot_set_confirmed()`` to make the image as a permanent image.
-
-.. Note::
- Currently, in direct-xip mode and ram-load mode, TF-M cannot get the
- information of which slot contains the running image from the bootloader.
- So the Firmware Update partition cannot decide where to write the new
- image. As a result, the firmware update service is not supported in
- direct-xip mode and ram-load mode.
-
-*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_secure_irq_handling.rst b/docs/getting_started/tfm_secure_irq_handling.rst
deleted file mode 100644
index 8cd664e260..0000000000
--- a/docs/getting_started/tfm_secure_irq_handling.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-###################
-Secure IRQ handling
-###################
-
-The Armv8-M Architecture makes it possible to configure interrupts to target
-secure state.
-
-TF-M makes it possible for secure partitions to get notified of secure
-interrupts.
-
-By default TF-M sets up interrupts to target NS state. To configure an interrupt
-to target secure state and assign a handler to it, the manifest of the partition
-must be edited.
-
-See the following example:
-
-
-.. code-block:: yaml
-
- {
- "name": "...",
- "type": "...",
- "priority": "...",
-
- ...
-
- "irqs": [
- {
- "source": "5",
- "signal": "DUAL_TIMER"
- },
- {
- "source": "TFM_IRQ_LINE_TIMER_1",
- "signal": "TIMER_1"
- "tfm_irq_priority": 64,
- }
- ],
-
- ...
-
- }
-
-To set up a handler in a partition, the ``irqs`` node must be added. A single
-secure partition can have handlers registered for multiple IRQs, in this case
-the list ``irqs`` has multiple elements in it.
-
-An IRQ handler is defined by the following nodes:
-
-- ``source``: The IRQ number or the name of the IRQ line. With the name of the
- IRQ line, there must be defined a macro in ``tfm_peripherals_def.h`` which is
- substituted to the IRQ line num. The IRQ line nums and sources are defined by
- each platform: for example, they are defined in ``platform_irq.h`` for the
- Musca-S1 platform. When defining new macros in ``tfm_peripherals_def.h``, it
- is important the macro name matches the platform's handler function for that
- IRQ source.
-- ``signal``: The name of the signal for this IRQ.
-- ``tfm_irq_priority``: The priority of the IRQ. This number must be in the
- range [0-255] inclusive. Please note that some of the less significant bits of
- this value might be dropped based on the number of priority bits implemented
- in the platform.
-
-.. important::
-
- The name of the privileged interrupt handler is derived from the node
- specifying the IRQ line number.
-
- - In case ``source`` is IRQ number, the name of the handler becomes
- ``void irq__Handler(void)``.
- - In case ``source`` is defined IRQ macro, the name of the handler becomes
- ``void _Handler(void)``.
-
- This is important, because the derived name has to be present in the vector
- table as the handler of the IRQ. The platform startup functions are specified
- in the vector table defined in the platform secure startup file. The user
- should verify the names of the generated handlers match for a given platform
- IRQ.
-
-.. Note::
-
- ``signal`` and ``source`` are mandatory.
-
- ``tfm_irq_priority`` is optional. If ``tfm_irq_priority`` is not set for an
- IRQ, the default is value is ``TFM_DEFAULT_SECURE_IRQ_PRIOTITY``.
-
-If an IRQ handler is registered, TF-M will:
-
-- Set the IRQ with number or macro to target secure state
-- Set the priority of IRQ with number or macro to ``tfm_irq_priority`` or to
- the default.
-
-TF-M configures the interrupt lines to be disabled by default. Interrupts for a
-service can be enabled by the secure service by calling
-``void tfm_enable_irq(psa_signal_t irq_signal)``. The function can be called in
-the service init function.
-
-Library model
-=============
-
-In Library model a function with the name derived from the value of the
-``source`` property is generated. This function will be put in the vector table
-by the linker (as the handlers in the startup assembly are defined as weak
-symbols). The code generated for this function will forward the call to the
-function with the name of the value of the ``signal`` property post-fixed with
-``_isr``.
-
-.. hint::
-
- for a signal ``"signal": "DUAL_TIMER"`` the name of the handler function is
- ``DUAL_TIMER_isr``
-
-The signature of the IRQ handler in the partition must be the following:
-
-.. code-block:: c
-
- void partition_irq_handler(void);
-
-The detailed description on how secure interrupt handling works in the Library
-model see
-`Secure Partition Interrupt Handling design document `_.
-
-IPC model
-=========
-
-The detailed description on how secure interrupt handling works in the IPC
-model, see the
-`PSA Firmware Framework and RoT Services specification `_.
-
-**********************
-Implementation details
-**********************
-
-Library model implementation
-============================
-
-As a result of the function call like behaviour of secure services in library
-model, some information that is critical for the SPM to keep track of partition
-states, is stored on the stack of the active partitions. When an interrupt
-happens, and a handler partition is set to running state, it has access to its
-whole stack, and could corrupt the data stacked by the SPM. To prevent this, a
-separate Context stack is introduced for each secure partition, that is used by
-the SPM to save this information before starting to execute secure partition
-code.
-
-A stack frame to this context stack is pushed when the execution in the
-partition is interrupted, and when a handler in the partition interrupts another
-service. So the maximal stack usage can happen in the following situation:
-
-Consider secure partition 'A'. 'A' is running, and then it is interrupted by
-an other partition. Then the lowest priority interrupt of 'A' is triggered.
-Then before the handler returns, the partition is interrupted by another
-partition's handler. Then before the running handler returns, the second
-lowest interrupt of 'A' is triggered. This can go until the highest priority
-interrupt of 'A' is triggered, and then this last handler is interrupted. At
-this point the context stack looks like this:
-
-.. code-block::
-
- +------------+
- | [intr_ctx] |
- | [hndl_ctx] |
- | . |
- | . |
- | . |
- | [intr_ctx] |
- | [hndl_ctx] |
- | [intr_ctx] |
- +------------+
-
- Legend:
- [intr_ctx]: Frame pushed when the partition is interrupted
- [hndl_ctx]: Frame pushed when the partition is handling an interrupt
-
-So the max stack size can be calculated as a function of the IRQ count of 'A':
-
-.. code-block::
-
-
- max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size))
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst
index 55648f49b8..d2b01937c9 100644
--- a/docs/getting_started/tfm_user_guide.rst
+++ b/docs/getting_started/tfm_user_guide.rst
@@ -5,8 +5,8 @@ How to compile and run TF-M and example test application for CoreLink
SSE-200 subsystem on the MPS2 board and on the Fast Model(FVP).
Follow :doc:`build instruction ` to build the binaries.
-Follow :doc:`secure boot ` to build the binaries with or
-without BL2 bootloader.
+Follow :doc:`secure boot ` to build the
+binaries with or without BL2 bootloader.
****************************************************************
Execute TF-M example and regression tests on MPS2 boards and FVP
@@ -565,7 +565,7 @@ port (baud 115200 8n1) the following messages::
Firmware upgrade and image validation with BL2 bootloader
=========================================================
High level operation of BL2 bootloader and instructions for testing firmware
-upgrade is described in :doc:`secure boot `.
+upgrade is described in :doc:`secure boot `.
--------------
@@ -576,4 +576,4 @@ upgrade is described in :doc:`secure boot `.
.. _Keil MDK: http://www2.keil.com/mdk5
.. _Keil MDK Documentation: https://www2.keil.com/mdk5/docs
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644
index 0000000000..73e91aa749
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,165 @@
+###################################
+Glossary of terms and abbreviations
+###################################
+
+************
+TF-M related
+************
+.. glossary::
+
+ Application RoT
+ Application Root of Trust
+ `PSA term`_. The security domain in which additional security services
+ are implemented.
+
+ HAL
+ Hardware Abstraction Layer
+ Interface to abstract hardware-oriented operations and provides a set of
+ APIs to the upper layers.
+
+ RoT
+ 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
+ `PSA term`_. In TF-M this means non secure domain typically running an
+ OS using services provided by TF-M.
+
+ PSA
+ `PSA term`_. Platform Security Architecture.
+
+ PSA-FF
+ `PSA term`_. Platform Security Architecture Firmware Framework.
+
+ PSA-FF-M
+ `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
+ The function entry to a secure service. Multiple SFN per SS are
+ permitted.
+
+ SP : TF-M related
+ Secure Partition
+ A logical container for secure services.
+
+ SPE : TF-M related
+ Secure Processing Environment
+ `PSA term`_. In TF-M this means the secure domain protected by TF-M.
+
+ SPM : TF-M related
+ 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
+ The TF-M component responsible for Secure Partition runtime
+ functionalities.
+
+ SPRTL : TF-M related
+ Secure Partition Runtime Library
+ A library contains the SPRT code and data.
+
+ SS : TF-M related
+ 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
+ Protected Storage
+ Protected storage service provided by TF-M.
+
+ ITS : TF-M related
+ Internal Trusted Storage
+ Internal Trusted Storage service provided by TF-M.
+
+ TFM
+ TF-M
+ Trusted Firmware-M
+ 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
+ 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
+ Bus slave-side security controller for memory regions.
+
+ PPC : SSE-200 platform
+ Peripheral Protection Controller
+ Bus slave-side security controller for peripheral access.
+
+************
+v8M-specific
+************
+.. glossary::
+
+ S/NS : v8M-specific
+ Secure/Non-secure
+ The separation provided by TrustZone hardware components in the system.
+
+ SAU : v8M-specific
+ 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
+ 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
+ Hardware component providing privilege control.
+
+ SVC
+ SuperVisor Call
+ ARMv7M assembly instruction to call a privileged handler function
+
+*********
+Reference
+*********
+
+| `PSA Firmware_Framework for M`_
+
+.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html
+
+.. _PSA term: `PSA Firmware_Framework for 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: https://pages.arm.com/psa-resources-tbsa-m.html
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
index 2199929166..fed9d425e3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,7 +20,7 @@ Trusted Firmware-M Documentation
Introduction
Introducing the Trusted Firmware-M Project: overview,
- architecture, features, and licensing
+ architecture, features, and licensing.
@@ -30,6 +30,13 @@ Trusted Firmware-M Documentation
Follow this guide to set up a development environment on your
system, and then build and run a sample application.
+
+
+
+ Supported Platforms
+
+ List of supported boards and platforms.
+
@@ -39,39 +46,33 @@ Trusted Firmware-M Documentation
to submit patches directly to the project.
-
+
- References
+ Integration Guidelines
- User guides, API Documentation, interfaces
+ Guidelines for integration with TF-M.
-
+
- Design
+ Technical References
- Design documents, threat models.
+ Design documents.
-
+
- Platforms
+ Security
- List of supported boards and platforms.
+ Requirements, processes, and thread models for ensuring security
+ is addressed within the TF-M project.
-
+
- API
+ Releases
- Doxygen documentation.
-
-
-
-
- PSA
-
- Platform Security Architecture (PSA) information.
+ Release notes.
@@ -85,11 +86,12 @@ Trusted Firmware-M Documentation
Home
docs/introduction/index
docs/getting_started/index
- docs/contributing/index
- docs/reference/index
- docs/design_documents/index
platform/ext/index
- docs/threat_models/index
+ docs/contributing/index
+ docs/integration_guide/index
+ docs/technical_references/index
+ docs/security/index
+ docs/releases/index
.. toctree::
@@ -97,11 +99,11 @@ Trusted Firmware-M Documentation
:hidden:
:caption: Quick Links
+ API Reference
Security Center
- docs/reference/changelog
- docs/reference/glossary
- docs/contributing/lic
+ Platform Security Architecture
+ docs/glossary
--------------
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
new file mode 100644
index 0000000000..41bc4d26ad
--- /dev/null
+++ b/docs/integration_guide/index.rst
@@ -0,0 +1,12 @@
+Integration Guide
+=================
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ */index
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/os_migration_guide_armv8m.rst b/docs/integration_guide/os_migration_guide_armv8m.rst
new file mode 100644
index 0000000000..1ca4e3df06
--- /dev/null
+++ b/docs/integration_guide/os_migration_guide_armv8m.rst
@@ -0,0 +1,42 @@
+#########################################################
+Generic OS migration from Armv7-M to Armv8-M architecture
+#########################################################
+The purpose of this document is to list a set of requirements needed for
+migrating a generic OS kernel running on Armv7-M to the Armv8-M architecture.
+
+********************
+List of requirements
+********************
+- If the same OS codebase is used for both Secure and Non Secure builds, it is
+ suggested to put specific code targeted to the Non Secure build under a
+ compile time switch, e.g. ``#if (DOMAIN_NS == 1U)``. The OS build system in
+ this case needs to be amended accordingly to support this new switch.
+- If the OS implements stack limit checking, the ``PSPLIM`` register
+ needs to be initialized and properly handled during thread context switch
+ operations.
+- If the OS manipulates directly the Link Register, the default Link Register
+ value used in Handler mode transitions needs to be differentiated between
+ Secure and Non Secure builds, i.e. ``0xFD`` and ``0xBC``, respectively.
+- If the OS supports the Thread Context Management for Armv8-M TrustZone APIs,
+ as described
+ `here `__
+ , and would like to use the non-secure client identification feature of TF-M,
+ then it also have to use the
+ ``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)``
+ API function provided by TF-M, as described in
+ :doc:`NS client identification documentation `.
+- if the OS doesn't support the API mentioned above, it should set
+ ``TFM_NS_CLIENT_IDENTIFICATION`` to ``OFF`` in the cmake system.
+- .. Note::
+
+ This is NOT REQUIRED when the Non Secure OS build is meant
+ to be integrated with TF-M running in Secure world.
+
+ If generic function calls into Secure world have to be supported in Non Secure
+ builds, integrate an API for secure stack memory management (e.g. the
+ TrustZone API for secure stack memory management described in
+ ``tz_context.h``).
+
+--------------
+
+*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/core_test_services_integration_guide.rst b/docs/integration_guide/services/core_test_services_integration_guide.rst
new file mode 100644
index 0000000000..fb34795656
--- /dev/null
+++ b/docs/integration_guide/services/core_test_services_integration_guide.rst
@@ -0,0 +1,114 @@
+###########################
+Core Test integration guide
+###########################
+
+************
+Introduction
+************
+
+The core test suites test some of the features of the TF-M core. There are
+multiple services that are used by the core test suites. The services are
+defined in the ``test/test_services`` folder.
+
+Currently there are two test suites, *interactive* and *positive*. The positive
+test suite can be run by building using non-secure regression tests using
+``-DTEST_NS``.
+
+The interactive test suite is only available by setting
+``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is
+enabled.
+
+In order to enable the IRQ test module of the postive testsuite, the non-secure
+regression testsuite must be enabled and ``-DTFM_IRQ_TEST=ON`` must be set.
+
+In order to enable the peripheral access test module of the positive testsuite,
+the non-secure regression testsuite must be enabled and
+``-DTFM_PERIPH_ACCESS_TEST=ON`` must be set.
+
+**************************
+Platform specific features
+**************************
+For certain test cases the core test services rely on platform functionality.
+The required features are:
+
+- Access to LEDs or registers that can be used as scratch registers for
+ read/write access tests
+- Get a button state that can be pressed by the user to simulate a secure
+ service with an arbitrarily long blocking execution.
+- Access to a timer that is able to interrupt the core running TF-M.
+
+The functionality that have to be implemented by the platform is described in
+``platform/include/tfm_plat_test.h``. For details see the documentation of the
+functions.
+
+It is the responsibility of the platform implementation to ensure that the
+resources needed for the core test services are properly linked to the service.
+This can be achieved by using the
+``TFM_LINK_SET__IN_PARTITION_SECTION(...)`` macros in
+``platform/include/tfm_plat_defs.h``. More details regarding the usage of these
+macros are available in the header file.
+
+It is possible that a platform implementation mocks the implementation of some
+or all of the functions, by returning the values expected by the test cases,
+without actually executing the action expected by the test. A platform can also
+set the corresponding control flag to ``OFF`` to skip a test case. For example,
+A platform can skip peripheral access test case by setting
+``TFM_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file.
+
+******************
+IRQ handling tests
+******************
+
+The IRQ handling test currently tests the following scenarios:
+
+- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``)
+- S code execution is interrupted by a secure IRQ, The handler is not the
+ interrupted service (``IRQ_TEST_SCENARIO_2``)
+- S code execution is interrupted by a secure IRQ, The handler is the
+ interrupted service (``IRQ_TEST_SCENARIO_3``)
+- S code waits for an interrupt (calling ``psa_wait()``), the handler is in
+ the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()``
+ returns (``IRQ_TEST_SCENARIO_4``)
+- S code waits for a non-secure interrupt to be triggered
+ (``IRQ_TEST_SCENARIO_5``)
+
+The following test services participate in the test execution:
+
+- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ
+ handler
+- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the
+ IRQ handler
+
+All the test executions are initiated from the NS positive test suite. For each
+scenario the non-secure testcase calls the following secure functions in order:
+
+#. prepare_test_scenario for ``TFM_IRQ_TEST_1``
+#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. prepare_test_scenario_ns
+#. execute_test_scenario for ``TFM_IRQ_TEST_1``
+#. execute_test_scenario for ``TFM_SP_CORE_TEST_2``
+#. execute_test_scenario_ns
+
+For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer
+with a convenient init value, and depending on the scenario, one of the
+services, or the NS code enters a busy wait waiting for the timer interrupt to
+be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the
+execute_test_scenario request of the NS code is only replied when the IRQ is
+handled, so no explicit busy wait is required. In all the other cases, handling
+of the irq is signalled to the waiting party by setting a variable in a
+non-secure memory location.
+
+For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for
+it to be triggered
+
+A platform can skip IRQ handling test by setting ``TFM_IRQ_TEST`` to
+``OFF`` in its cmake configuration file.
+
+The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*``
+(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to
+substitute empty string, and are used by the ``tools\generate_breakpoints.py``
+script in the `IRQ testing tool `_.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst
new file mode 100644
index 0000000000..30a2a8a078
--- /dev/null
+++ b/docs/integration_guide/services/index.rst
@@ -0,0 +1,12 @@
+Services
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_attestation_integration_guide.rst b/docs/integration_guide/services/tfm_attestation_integration_guide.rst
new file mode 100644
index 0000000000..2c43ea7bdc
--- /dev/null
+++ b/docs/integration_guide/services/tfm_attestation_integration_guide.rst
@@ -0,0 +1,671 @@
+#############################################
+Initial Attestation Service Integration Guide
+#############################################
+
+************
+Introduction
+************
+TF-M Initial Attestation Service allows the application to prove the device
+identity during an authentication process to a verification entity. The initial
+attestation service can create a token on request, which contains a fix set of
+device specific data.
+
+TF-M Initial Attestation Service by default enables asymmetric key algorithm
+based attestation (*asymmetric attestation* for short). Symmetric key algorithm
+based attestation (*symmetric attestation* for short) can be enabled instead by
+selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``.
+
+ - In asymmetric attestation, device must contain an attestation key pair,
+ which is unique per device. The token is signed with the private part of
+ attestation key pair. The public part of the key pair is known by the
+ verification entity. The public key is used to verify the token
+ authenticity.
+ - In symmetric attestation, device should contain a symmetric attestation
+ key to generate the authentication tag of token content. The verification
+ entity uses the same symmetric key to verify the token authenticity.
+
+The data items in the token used to verify the device integrity and assess its
+trustworthiness. Attestation key provisioning is out of scope for the
+attestation service and is expected to take part during manufacturing of the
+device.
+
+***************************************
+Claims in the initial attestation token
+***************************************
+The initial attestation token is formed of claims. A claim is a data item,
+which is represented in a key - value structure. The following fixed set of
+claims are included in the token:
+
+ - **Auth challenge**: Input object from caller. Can be a single nonce from
+ server or hash of nonce and attested data. It is intended to provide
+ freshness to report and the caller has responsibility to arrange
+ this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be
+ eventually represented by the EAT standard claim nonce. Until such a
+ time as that standard exists, the claim will be represented by a custom
+ claim. Value is encoded as byte string.
+
+ - **Instance ID**: It represents the unique identifier of the instance.
+ In the PSA definition it is:
+
+ - a hash of the public attestation key of the instance in asymmetric
+ attestation.
+ - hashes of the symmetric attestation key of the instance in symmetric
+ attestation.
+
+ The claim is modeled to be eventually represented by the EAT standard
+ claim UEID of type GUID. Until such a time as that standard exists, the
+ claim will be represented by a custom claim Value is encoded as byte
+ string.
+
+ - **Verification service indicator**: Optional, recommended claim. It
+ is used by a Relying Party to locate a validation service for the
+ token. The value is a text string that can be used to locate the service
+ or a URL specifying the address of the service. The claim is modelled to
+ be eventually represented by the EAT standard claim origination. Until
+ such a time as that standard exists, the claim will be represented by
+ a custom claim. Value is encoded as text string.
+
+ - **Profile definition**: Optional, recommended claim. It contains the
+ name of a document that describes the 'profile' of the token, being
+ a full description of the claims, their usage, verification and token
+ signing. The document name may include versioning. Custom claim with a
+ value encoded as text string.
+
+ - **Implementation ID**: Uniquely identifies the underlying immutable PSA
+ RoT. A verification service can use this claim to locate the details of
+ the verification process. Such details include the implementation's origin
+ and associated certification state. Custom claim with a value encoded as
+ byte string.
+
+ - **Client ID**: The partition ID of that secure partition or non-secure
+ thread who called the initial attestation API. Custom claim with a value
+ encoded as a `signed` integer. Negative number represents non-secure
+ caller, positive numbers represents secure callers, zero is invalid.
+
+ - **Security lifecycle**: It represents the current lifecycle state of
+ the instance. Custom claim with a value encoded as an integer.
+
+ - **Hardware version**: Optional claim. Globally unique number in EAN-13
+ format identifying the GDSII that went to fabrication, HW and ROM. It can
+ be used to reference the security level of the PSA-ROT via a certification
+ website. Custom claim with a value is encoded as text string.
+
+ - **Boot seed**: It represents a random value created at system boot
+ time that will allow differentiation of reports from different system
+ sessions. The size is 32 bytes. Custom claim with a value is encoded as
+ byte string.
+
+ - **Software components**: Optional, but required in order to be compliant
+ with the PSA-SM. It represents the software state of the system. The value
+ of the claim is an array of CBOR map entries, with one entry per software
+ component within the device. Each map contains multiple claims that
+ describe evidence about the details of the software component.
+
+ - **No software measurements**: Optional, but required if no software
+ component claims are made. In the event that the implementation does not
+ contain any software measurements then it is mandatory to include this
+ claim to indicate this is a deliberate state. Custom claim with a value
+ encoded as an unsigned integer set to 1.
+
+Each software component claim can include the following properties. Any property
+that is not optional must be included:
+
+ - **Measurement type**: Optional claim. It represents the role of the
+ software component. Value is encoded as short(!) text string.
+
+ - **Measurement value**: It represents a hash of the invariant software
+ component in memory at start-up time. The value must be a cryptographic
+ hash of 256 bits or stronger. Value is encoded as byte string.
+
+ - **Version**: Optional claim. It represents the issued software
+ version. Value is encoded as text string.
+
+ - **Signer ID**: Optional claim, but required in order to be compliant with
+ the PSA-SM. It represents the hash of a signing authority public key.
+ Value is encoded as byte string.
+
+ - **Measurement description**: Optional claim. It represents the way in
+ which the measurement value of the software component is computed. Value
+ is encoded as text string containing an abbreviated description (name)
+ of the measurement method.
+
+*********************************************
+Initial attestation token (IAT) data encoding
+*********************************************
+The initial attestation token is planned to be aligned with future version of
+`Entity Attestation Token `__
+format. The token is encoded according to the
+`CBOR `__ format and signed according to
+`COSE `__ standard.
+
+**************
+Code structure
+**************
+The PSA interface for the Initial Attestation Service is located in
+``interface/include``. The only header to be included by applications that want
+to use functions from the PSA API is ``psa/initial_attestation.h``.
+
+The TF-M Initial Attestation Service source files are located in
+``secure_fw/partitions/initial_attestation``.
+The CBOR library is located in ``lib/ext/qcbor`` folder.
+
+Service source files
+====================
+- CBOR library
+ - ``lib/ext/qcbor`` This library is used to create a proper CBOR token.
+ It can be used on 32-bit and 64-bit machines. It was designed to suite
+ constrained devices with low memory usage and without dynamic memory
+ allocation.
+ It is a fork of this external `QCBOR library `__.
+ - ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR
+ library.
+
+- COSE library:
+ - ``lib/ext/t_cose``: This library is used to sign a CBOR token and create
+ the COSE header and signature around the initial attestation token. Only
+ a subset of the `COSE `__ standard
+ is implemented. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork)
+ signature schemas are supported.
+ - It is a fork of this external `t_cose library `__.
+ - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
+ library with available crypto library in the device.
+ - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the
+ exposed API and ports ``t_cose`` to the PSA Crypto API.
+- Initial Attestation Service:
+ - ``attest_core.c`` : Implements core functionalities such as implementation
+ of APIs, retrieval of claims and token creation.
+ - ``attest_token_encode.c``: Implements the token creation functions such as
+ start and finish token creation and adding claims to the token.
+ - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from
+ platform layer and register it to the TF-M Crypto service for further
+ usage.
+ - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the
+ attestation service to the SPM implementation in TF-M project.
+ - ``tfm_attest_secure_api.c``: Implements the secure API layer to allow
+ other services in the secure domain to request functionalities
+ from the attestation service using the PSA API interface.
+ - ``tfm_attest_req_mngr.c``: Includes the initialization entry of
+ attestation service and handles attestation service requests in IPC
+ model.
+ - ``attest_symmetric_key.c``: Get the symmetric initial attestation key
+ from platform layer and register it into TF-M Crypto service for further
+ usage. Also calculate the Instance ID value based on symmetric initial
+ attestation key.
+
+Service interface definitions
+=============================
+- **Boot loader interface**: The attestation service might include data
+ in the token about the distinct software components in the device. This data
+ is provided by the boot loader and must be encoded in the TLV format,
+ definition is described below in the boot loader interface paragraph. Possible
+ claims in the boot status are describe above in the software components
+ paragraph.
+- **Hardware abstraction layer**:
+ - Headers are located in ``platform/include`` folder.
+ - ``tfm_attest_hal.h``: Expose an API to get the following claims:
+ security lifecycle, verification service indicator, profile definition.
+ - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim.
+ - ``tfm_plat_device_id.h``: Expose an API to get the following claims:
+ implementation ID, hardware version.
+- **SPM interface**:
+ - ``attestation.h``: Expose an API to bind attestation service to an SPM
+ implementation.
+- **PSA interface**:
+ - ``psa/initial_attestation.h``: Public API definition of initial
+ attestation service.
+- **Crypto interface**:
+ - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation
+ to any cryptographic library.
+ - ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from
+ platform layer.
+
+PSA interface
+=============
+The TF-M Initial Attestation Service exposes the following PSA
+interface:
+
+.. code-block:: c
+
+ psa_status_t
+ psa_initial_attest_get_token(const uint8_t *auth_challenge,
+ size_t challenge_size,
+ uint8_t *token_buf,
+ size_t token_buf_size,
+ size_t *token_size);
+
+ psa_status_t
+ psa_initial_attest_get_token_size(size_t challenge_size,
+ size_t *token_size);
+
+ psa_status_t
+ tfm_initial_attest_get_public_key(uint8_t *public_key,
+ size_t public_key_buf_size,
+ size_t *public_key_len,
+ psa_ecc_family_t *elliptic_curve_type);
+
+The caller must allocate a large enough buffer, where the token is going to be
+created by Initial Attestation Service. The size of the created token is highly
+dependent on the number of software components in the system and the provided
+attributes of these. The ``psa_initial_attest_get_token_size()`` function can be
+called to get the exact size of the created token.
+
+System integrators might need to port these interfaces to a custom secure
+partition manager implementation (SPM). Implementations in TF-M project can be
+found here:
+
+- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface
+ implementation for library model
+- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface
+ implementation for IPC model
+- ``secure_fw/partitions/initial_attestation/tfm_attestation_secure_api.c``:
+ secure interface implementation
+
+Secure Partition Manager (SPM) interface
+========================================
+The Initial Attestation Service defines the following interface towards the
+secure partition manager (SPM). System integrators **must** port this interface
+according to their SPM implementation.
+
+.. code:: c
+
+ enum psa_attest_err_t
+ attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
+
+ enum psa_attest_err_t
+ attest_get_caller_client_id(int32_t *caller_id);
+
+- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared
+ memory area between boot loader and runtime software. It might be the case
+ that only SPM has direct access to the shared memory area, therefore this
+ function can be used to copy the service related data from shared memory to
+ a local memory buffer. In TF-M implementation this function must be called
+ during service initialization phase, because the shared memory region is
+ deliberately overlapping with secure main stack to spare some memory and reuse
+ this area during execution. If boot loader is not available in the system to
+ provide attributes of software components then this function must be
+ implemented in a way that just initialize service's memory buffer to:
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr;
+ tlv_header->tlv_magic = 2016;
+ tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
+
+- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread.
+- ``tfm_client.h``: Service relies on the following external definitions, which
+ must be present or included in this header file:
+
+ .. code-block:: c
+
+ typedef struct psa_invec {
+ const void *base;
+ size_t len;
+ } psa_invec;
+
+ typedef struct psa_outvec {
+ void *base;
+ size_t len;
+ } psa_outvec;
+
+Hardware abstraction layer
+==========================
+The following API definitions are intended to retrieve the platform specific
+claims. System integrators **must** implement these interface according to their
+SoC and software design. Detailed definition of the claims are above
+in the claims in the initial attestation token paragraph.
+
+- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the
+ device.
+- ``tfm_attest_hal_get_verification_service()``: Get the verification
+ service indicator for initial attestation.
+- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile
+ definition document for initial attestation.
+- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random
+ number during a boot cycle.
+- ``tfm_plat_get_implementation_id``: Get the implementation ID of the
+ device.
+- ``tfm_plat_get_hw_version``: Get the hardware version of the device.
+
+Boot loader interface
+=====================
+It is **recommended** to have a secure boot loader in the boot chain, which is
+capable of measuring the runtime firmware components (calculates the hash value
+of firmware images) and provide other attributes of these (version, type, etc).
+If the used boot loader is not capable of sharing these information with the
+runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be
+set to OFF (see `Related compile time options`_).
+
+The shared data between boot loader and runtime software is TLV encoded. The
+definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``.
+The shared data is stored in a well known location in secure internal memory
+and this is a contract between boot loader and runtime SW.
+
+The structure of shared data must be the following:
+
+- At the beginning there must be a header: ``struct shared_data_tlv_header``
+ This contains a magic number and a size field which covers the entire size
+ of the shared data area including this header.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_header {
+ uint16_t tlv_magic;
+ uint16_t tlv_tot_len;
+ };
+
+- After the header there come the entries which are composed from an
+ entry header structure: ``struct shared_data_tlv_entry`` and the data. In
+ the entry header is a type field ``tlv_type`` which identify the consumer of
+ the entry in the runtime software and specify the subtype of that data item.
+
+ .. Note::
+
+ There is a size field ``tlv_len`` which has different definitions in the
+ upstream MCUboot repository and in its TF-M forked version:
+
+ - Upstream MCUboot: Covers only the length of data but not the header
+ size.
+ - TF-M MCUboot: Covers the size of the entry header and the data
+ together.
+
+ This difference is handled by TF-M code based on which bootloader is used
+ along with TF-M runtime.
+
+ After the entry header structure comes the actual data.
+
+ .. code-block:: c
+
+ struct shared_data_tlv_entry {
+ uint16_t tlv_type;
+ uint16_t tlv_len;
+ };
+
+- Arbitrary number and size of data entry can be in the shared memory
+ area.
+
+The figure below gives of overview about the ``tlv_type`` field in the entry
+header. The ``tlv_type`` always composed from a major and minorbnumber. Major
+number identifies the addressee in runtime software, which the databentry is
+sent to. Minor number used to encode more info about the data entry. The actual
+definition of minor number could change per major number. In case of boot
+status data, which is going to be processed by initial attestation service
+the minor number is split further to two part: ``sw_module`` and ``claim``. The
+``sw_module`` identifies the SW component in the system which the data item
+belongs to and the ``claim`` part identifies the exact type of the data.
+
+``tlv_type`` description::
+
+ |------------------------------------------------ |
+ | tlv_type (16 bits) |
+ |-------------------------------------------------|
+ | tlv_major(4 bits) | tlv_minor(12 bits) |
+ |-------------------------------------------------|
+ | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
+ |-------------------------------------------------|
+ | MAJOR_CORE | TBD |
+ |-------------------------------------------------|
+
+Overall structure of shared data::
+
+ ---------------------------------------------------------------
+ | Magic number(uint16_t) | Shared data total length(uint16_t) |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+ | . |
+ | . |
+ | . |
+ ---------------------------------------------------------------
+ | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
+ ---------------------------------------------------------------
+ | Raw data |
+ ---------------------------------------------------------------
+
+Crypto interface
+================
+
+Asymmetric key algorithm based attestation
+------------------------------------------
+Device **must** contain an asymmetric key pair. The private part of it is used
+to sign the initial attestation token. Current implementation supports only the
+ECDSA P256 signature over SHA256. The public part of the key pair is used to
+create the key identifier (kid) in the unprotected part of the COSE header. The
+kid is used by verification entity to look up the corresponding public key to
+verify the signature in the token. The `t_cose` part of the initial attestation
+service implements the signature generation and kid creation. But the actual
+calculation of token's hash and signature is done by the Crypto service in the
+device. System integrators might need to re-implement the following functions
+if they want to use initial attestation service with a different cryptographic
+library than Crypto service:
+
+- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value.
+- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key
+ identifier.
+- ``t_cose_crypto_hash_start()``: Start a multipart hash operation.
+- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash
+ operation.
+- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a
+ message.
+
+Interface needed by verification code:
+
+- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value.
+
+Key handling
+^^^^^^^^^^^^
+The provisioning of the initial attestation key is out of scope of the service
+and this document. It is assumed that device maker provisions the unique
+asymmetric key pair during the manufacturing process. The following API is
+defined to retrieve the attestation key pair from platform layer. Software
+integrators **must** port this interface according to their SoC design and make
+sure that key pair is available by Crypto service:
+
+- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key
+ pair from platform layer.
+
+In TF-M project the attestation key is retrieved by initial attestation service.
+The key is registered and unregistered to the Crypto service by attestation
+service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for
+further usage. See in ``attestation_key.c``. In other implementation if the
+attestation key is directly retrieved by the Crypto service then this key
+handling is not necessary.
+
+Symmetric key algorithm based attestation
+-----------------------------------------
+Device **must** contain a symmetric key to generate the authentication tag of
+the initial attestation token. A key identifier (kid) can be encoded in the
+unprotected part of the COSE header. It helps verification entity look up the
+symmetric key to verify the authentication tag in the token.
+
+The `t_cose` part of the initial attestation service implements the
+authentication tag generation. The authentication tag generation is done by the
+Crypto service. System integrators might need to re-implement the following
+functions if platforms provide a different cryptographic library than Crypto
+service:
+
+- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation
+ operation.
+- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC
+ operation.
+- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a
+ message.
+
+Interface needed by verification code:
+
+- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification
+ operation.
+- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of
+ a message.
+
+It also requires the same hash operations as listed in asymmetric key algorithm
+based initial attestation above, in attestation test cases.
+
+Key handling
+^^^^^^^^^^^^
+The provisioning of the initial attestation key is out of scope of the service
+and this document. It is assumed that device maker provisions the symmetric key
+during the manufacturing process. The following API is defined to retrieve the
+symmetric attestation key from platform layer. Software integrators **must**
+port this interface according to their SoC design and make sure that key is
+available by Crypto service:
+
+- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key
+ raw data.
+- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric
+ initial attestation key. The key identifier can be used as ``kid`` parameter
+ in COSE header. Optional.
+
+.. note:
+
+ Asymmetric initial attestation and symmetric initial attestation may share
+ the same HAL APIs in future development.
+
+Initial Attestation Service compile time options
+================================================
+There is a defined set of flags that can be used to compile in/out certain
+service features. The ``CommonConfig.cmake`` file sets the default values of
+those flags. The list of flags are:
+
+- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the
+ attestation token. Default value: ON.
+- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from
+ attestation test suite if it is OFF. Its default value depends on the build
+ type. It is ON if build type is ``Debug``, otherwise OFF (different kinds
+ of ``Release`` builds).
+- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE
+ unprotected header. Key-id is calculated and added to the COSE header based
+ on the value of this flag. Default value: OFF.
+- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded
+ values found in ``platform/ext/common/template/attest_hal.c``. Default value
+ is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet
+ properly ported to it.
+- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation.
+ Default value: OFF.
+
+Related compile time options
+----------------------------
+- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared
+ data area between the boot loader and the runtime firmware when it's ON.
+ Otherwise, when it's OFF does not check the content of the shared data area.
+ Also assume that the TLV header is present and valid (the magic number is
+ correct) and there are no other data entries. Its default value depends on
+ the BL2 flag.
+
+***************************************************************************
+Comparison of asymmetric and symmetric algorithm based token authentication
+***************************************************************************
+The symmetric key based authentication requires a more complex infrastructure
+for key management. Symmetric keys must be kept secret because they are
+sensitive asset, like the private key in case of asymmetric cryptographic
+algorithms. The main difference is that private keys are only stored on
+device, with proper hardware protection against external access, but symmetric
+keys must be known by both party (device and verifier), so they must also be
+stored in a central server of a relying party (who verifies the tokens).
+If keys are revealed then devices can be impersonated. If the database with
+the symmetric keys becomes compromised then all corresponding devices become
+untrusted. Since a centralised database of symmetric keys may need to be network
+connected, this can be considered to be a valuable target for attackers. The
+advantage of ECDSA based token authentication is that sensitive assets is only
+stored one place (in the device) and only one unique key per device. So if a
+device is compromised then only that single device become untrusted. In this
+case, the database of the relying party contains the corresponding public keys,
+which are not considered to be a confidential assets, so they can be shared with
+anybody. This shows the main advantage of asymmetric based authentication,
+because verification of attestation tokens can be done by a third party,
+such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM)
+does not need to operate such a service.
+
++-------------------------+-----------------------------------------+-----------------------------------------+
+| | Symmetric | Asymmetric |
++=========================+=========================================+=========================================+
+| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) |
+| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) |
+| | | - tfm_initial_attest_get_public_key(..) |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Secrets are stored | Device and database | Device only |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Verification database | Same symmetric key | Public keys |
+| contains | | |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| COSE authentication tag | COSE_Mac0 | COSE_Sign1 |
+| in the token | | |
++-------------------------+-----------------------------------------+-----------------------------------------+
+| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning|
+| | symmetric key | service, cloud service provider, CM, DM |
++-------------------------+-----------------------------------------+-----------------------------------------+
+
+************
+Verification
+************
+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. When the user builds TF-M with any of the
+``ConfigRegression*.cmake`` configurations then this test is executed
+automatically. 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):
+
+ - Requirements of presence: optional or mandatory
+ - Expected value: Value check can be disabled or expected value can be provided
+ here.
+
+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
+that user has license for DS-5 and FVP models:
+
+ - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
+ for MPS2 AN521 platform. More info in
+ :doc:`tfm_build_instruction `.
+ - Lunch FVP model in DS-5. More info in
+ :doc:`tfm_user_guide `.
+ - Set a breakpoint in ``test/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:
+
+ - For asymmetric initial attestation, the console prints
+ ``ECDSA signature test of attest token``.
+ - For symmetric initial attestation, the console prints
+ ``Symmetric key algorithm based Initial Attestation test``.
+
+ - At this point the token resides in the model memory and can be dumped to host
+ computer.
+ - The ADDRESS and SIZE attributes of the initial attestation token is stored in
+ the ``completed_token`` local variable. Their value can be extracted in the
+ ``(x)=Variables`` debug window.
+ - Apply commands below in the ``Commands`` debug window to dump the token in
+ binary format to the host computer:
+
+ - For asymmetric initial attestation
+ ``dump memory /iat_01.cbor +``
+ - For symmetric initial attestation
+ ``dump memory /iat_hmac_02.cbor +``
+
+ - Execute commands below on the host computer to verify the token:
+
+ - For asymmetric initial attestation
+ ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem /iat_01.cbor``
+ - For symmetric initial attestation
+ ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key /iat_hmac_02.cbor``
+
+ - Documentation of the iat-verifier can be found
+ :doc:`here `.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_audit_integration_guide.rst b/docs/integration_guide/services/tfm_audit_integration_guide.rst
new file mode 100644
index 0000000000..248f0f9fb1
--- /dev/null
+++ b/docs/integration_guide/services/tfm_audit_integration_guide.rst
@@ -0,0 +1,134 @@
+#######################################
+Audit Logging Service Integration Guide
+#######################################
+
+************
+Introduction
+************
+TF-M Audit logging service allows secure services in the system to log critical
+system events and information that have security implications. This is required
+to post analyse the system behaviour, system events and triage system issues
+offline. This offers a mitigation against the repudiation threat.
+
+The types of information that can be logged are the ID of the entity that
+originated a secure service request, or the relevant output or data
+associated to the authentication mechanism that the requesting service
+has performed on the entity that originated the request. The possible types of
+information that can be logged can be easily extended to accommodate various
+requirements from other secure services.
+
+***************************
+Current service limitations
+***************************
+
+- **Policy manager** - Currently, there is no policy manager implemented, which
+ means that there are no restrictions on the entities which can add or remove
+ items from the log. Also, the item replacement in the log is just replacing
+ older elements first.
+
+- **Encryption** - Support for encryption and authentication is not available
+ yet.
+
+- **Permanent storage** - Currently the Audit Logging service supports only a
+ RAM based storage of the log, permanent storage is not supported yet.
+
+
+**************
+Code structure
+**************
+The PSA interfaces for the Audit logging service are located in
+``interface/include``.
+
+The TF-M Audit logging service source files are located in
+``secure_fw/partitions/audit_logging``.
+
+PSA interfaces
+==============
+The TF-M Audit logging service exposes the following PSA interfaces:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
+ const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
+ uint8_t *buffer, uint32_t *record_size);
+
+ enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
+ *size);
+
+ enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
+ uint32_t *size);
+
+ enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
+ const uint8_t *token, const uint32_t token_size);
+
+The TF-M Audit logging service exposes an additional PSA interface which can
+only be called from secure services:
+
+.. code-block:: c
+
+ enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
+ *record);
+
+Service source files
+====================
+
+- ``audit_core.c`` : This file implements core functionalities such as log
+ management, record addition and deletion and extraction of record information.
+- ``audit_wrappers.c`` : This file implements TF-M compatible wrappers in case
+ they are needed by the functions exported by the core.
+
+*********************************
+Audit logging service integration
+*********************************
+In this section, a brief description of each field of a log record is given,
+with an example on how to perform a logging request from a secure service.
+The secure service that requests the addition of a record to the log has to
+provide data as described by the ``psa_audit_record`` type, defined in
+``interface\include\psa_audit_defs.h``:
+
+.. code-block:: c
+
+ /*!
+ * \struct psa_audit_record
+ *
+ * \brief This structure contains the record that is added to the audit log
+ * by the requesting secure service
+ */
+ struct psa_audit_record {
+ uint32_t size; /*!< Size in bytes of the id and payload fields */
+ uint32_t id; /*!< ID of the record */
+ uint8_t payload[]; /*!< Flexible array member for payload */
+ };
+
+Each field is described as follows:
+
+- ``size`` - This is the size, in bytes, of the ``id`` and ``payload[]`` fields
+ that follow. Given that the ``payload[]`` field is optional, in the current
+ implementation the minimum value to be provided in ``size`` is 4 bytes;
+- ``id`` - This field is meant to be used to store an ID of the log record from
+ the requesting service
+- ``payload[]`` - The payload is an optional content which can be made
+ of one or more Type-Length-Value entries as described by the following type:
+
+.. code-block:: c
+
+ /*!
+ * \struct audit_tlv_entry
+ *
+ * \brief TLV entry structure with a flexible
+ * array member
+ */
+ struct audit_tlv_entry {
+ enum audit_tlv_type type;
+ uint32_t length;
+ uint8_t value[];
+ };
+
+The possible TLV types described by ``enum audit_tlv_type`` can be extended by
+system integrators modifying ``audit_core.h`` as needed. A logging request is
+performed by a secure service which calls the
+Secure-only API function ``psa_audit_add_record()``.
+
+--------------
+
+*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_crypto_integration_guide.rst b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
new file mode 100644
index 0000000000..a124bdf491
--- /dev/null
+++ b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
@@ -0,0 +1,118 @@
+################################
+Crypto Service Integration Guide
+################################
+
+************
+Introduction
+************
+TF-M Crypto service allows application to use cryptography primitives such as
+symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
+authenticated encryption with associated data (AEAD).
+
+**************
+Code structure
+**************
+The PSA interfaces for the Crypto service are located in ``interface/include``.
+The only header to be included by applications that want to use functions from
+the PSA API is ``psa/crypto.h``.
+The TF-M Crypto service source files are located in
+``secure_fw/partitions/crypto``.
+
+PSA interfaces
+==============
+The TF-M Crypto service exposes the PSA interfaces detailed in the header
+``psa/crypto.h``. This header, in turn, includes several other headers which
+are not meant to be included directly by user applications. For a detailed
+description of the PSA API interface, please refer to the comments in the
+``psa/crypto.h`` header itself.
+
+Service source files
+====================
+- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
+ operations
+- ``crypto_hash.c`` : This module handles requests for hashing operations
+- ``crypto_mac.c`` : This module handles requests for MAC operations
+- ``crypto_aead.c`` : This module handles requests for AEAD operations
+- ``crypto_key_derivation.c`` : This module handles requests for key derivation
+ related operations
+- ``crypto_key.c`` : This module handles requests for key related operations
+- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
+ cryptographic operations
+- ``crypto_init.c`` : This module provides basic functions to initialise the
+ secure service during TF-M boot. When the service is built for IPC mode
+ compatibility, this layer handles as well the connection requests and the
+ proper dispatching of requests to the corresponding functions, and it holds
+ the internal buffer used to allocate temporarily the IOVECs needed. The size
+ of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define.
+ This module also provides a static buffer which is used by the Mbed Crypto
+ library for its own allocations. The size of this buffer is controlled by
+ the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define
+- ``crypto_alloc.c`` : This module is required for the allocation and release of
+ crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``,
+ defined in this file, determines how many concurrent contexts are supported
+ for multipart operations (8 for the current implementation). For multipart
+ cipher/hash/MAC/generator operations, a context is associated to the handle
+ provided during the setup phase, and is explicitly cleared only following a
+ termination or an abort
+- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API
+ client interface exposed to the Secure Processing Environment
+- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
+ implements the PSA Crypto API client interface exposed to the Non-Secure
+ Processing Environment.
+- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
+ Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
+ Small by default.
+
+****************************
+Crypto Backend configuration
+****************************
+
+The Crypto service can use either a hardware crypto accelerator backend like
+CC-312 or a software crypto library which by default is MbedTLS.
+
+If using MbedTLS as backend, then the library configuration is supplied using
+the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option.
+
+Platforms can specify an extra config file by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
+around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform
+configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with
+config changes due to TFM Profile.
+
+.. Note::
+
+ The default entropy source configured for MbedTLS is
+ MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness
+ for production devices. It is required for production devices to select
+ either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or
+ provision a unique seed for the device during production and use the
+ MBEDTLS_ENTROPY_NV_SEED option.
+
+**************************
+Crypto service integration
+**************************
+In this section, a brief description of the required flow of operation for the
+functionalities exported by the PSA Crypto interface is given, with particular
+focus on the TF-M Crypto service specific operations. For the details of the
+generic PSA Crypto interface operations, please refer directly to the header
+``psa/crypto.h``.
+
+Most of the PSA Crypto multipart APIs require an operation context to be
+allocated by the application and then to be passed as a pointer during the
+following API calls. These operation contexts are of four main types described
+below:
+
+- ``psa_key_derivation_operation_t`` - Operation context for key derivation
+- ``psa_hash_operation_t`` - Operation context for multipart hash operations
+- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
+- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
+
+The user applications are not allowed to make any assumption about the original
+types behind these typedefs, which are defined inside ``psa/crypto.h``.
+In the scope of the TF-M Crypto service, these types are regarded as handles to
+the corresponding implementation defined structures which are stored in the
+Secure world.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_its_integration_guide.rst b/docs/integration_guide/services/tfm_its_integration_guide.rst
new file mode 100644
index 0000000000..6082e7369c
--- /dev/null
+++ b/docs/integration_guide/services/tfm_its_integration_guide.rst
@@ -0,0 +1,318 @@
+#######################################################
+TF-M Internal Trusted Storage Service Integration Guide
+#######################################################
+
+************
+Introduction
+************
+TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted
+Storage APIs.
+
+The service is backed by hardware isolation of the flash access domain and
+relies on hardware to isolate the flash area from access by the Non-secure
+Processing Environment, as well as the Application Root of Trust at higher
+levels of isolation.
+
+The current ITS service design relies on hardware abstraction provided by TF-M.
+The ITS service provides a non-hierarchical storage model, as a filesystem,
+where all the assets are managed by a linearly indexed list of metadata.
+
+The design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks. Assumed to be provided by the internal flash
+ device, backed by hardware isolation.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistance to tampering by attackers with physical access is
+ assumed to be provided by the internal flash device itself, while resistance
+ to tampering by Non-secure or App RoT attackers also requires hardware
+ isolation.
+
+- **Reliability** - Resistance to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level of configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+*******************************
+Current ITS 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. 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
+ metadata in blocks which are always stored in the same flash location. That
+ increases the number of writes in a specific flash location as every change in
+ the storage area requires a metadata update.
+
+- **Protection against physical storage medium failure** - Complete handling of
+ inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
+ is not supported by the current design.
+
+- **Lifecycle management** - Currently, it does not support any subscription
+ based keys and certificates required in a secure lifecycle management. Hence,
+ an asset's validity time-stamp can not be invalidated based on the system
+ time.
+
+- **Provisioning vs user/device data** - In the current design, all assets are
+ treated in the same manner. In an alternative design, it may be required to
+ create separate partitions for provisioning content and user/device generated
+ content. This is to allow safe update of provisioning data during firmware
+ updates without the need to wipe out the user/device generated data.
+
+**************
+Code Structure
+**************
+TF-M Internal Trusted Storage service code is located in
+``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows:
+
+ - Core files
+ - Flash filesystem interfaces
+ - Flash interfaces
+
+The PSA ITS interfaces for the TF-M ITS service are located in
+``interface/include/psa``.
+
+PSA Internal Trusted Storage Interfaces
+=======================================
+
+The TF-M ITS service exposes the following mandatory PSA ITS interfaces
+version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_its_remove(psa_storage_uid_t uid);
+
+These PSA ITS interfaces and TF-M ITS types are defined and documented in
+``interface/include/psa/storage_common.h``,
+``interface/include/psa/internal_trusted_storage.h``, and
+``interface/include/tfm_its_defs.h``
+
+Core Files
+==========
+- ``tfm_its_req_mngr.c`` - Contains the ITS request manager implementation which
+ handles all requests which arrive to the service. This layer extracts the
+ arguments from the input and output vectors, and it calls the internal trusted
+ storage layer with the provided parameters.
+
+- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted
+ storage API implementations which are the entry points to the ITS service.
+ Constructs a filesystem configuration using information from the ITS HAL,
+ allocates a filesystem context for ITS and makes appropriate FS calls. Also
+ handles requests from the PS partition with a separate FS config and context.
+
+- ``its_utils.c`` - Contains common and basic functionalities used across the
+ ITS service code.
+
+Flash Filesystem Interface
+==========================
+- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used
+ by the internal trusted storage service. The purpose of this abstraction is to
+ have the ability to plug-in other filesystems or filesystem proxies
+ (supplicant).
+
+- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for
+ the required interfaces.
+
+- ``flash_fs/its_flash_fs_mblock.c`` - Contains the metadata block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+- ``flash_fs/its_flash_fs_dblock.c`` - Contains the data block manipulation
+ functions required to implement the ``its_flash_fs`` interfaces in
+ ``flash_fs/its_flash_fs.c``.
+
+The system integrator **may** replace this implementation with its own
+flash filesystem implementation or filesystem proxy (supplicant).
+
+Flash Interface
+===============
+The ITS filesystem flash interface is defined by ``struct its_flash_fs_ops_t``
+in ``flash_fs/its_flash_fs.h``.
+
+Implementations of the ITS filesystem flash interface for different types of
+storage can be found in the ```internal_trusted_storage/flash`` directory.
+
+- ``flash/its_flash.h`` - Helper header that includes the correct ITS flash
+ interface implementation for the target, and abstracts the allocation of
+ different flash device types.
+
+- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND
+ flash device, on top of the CMSIS flash interface implemented by the target.
+ This implementation writes entire block updates in one-shot, so the CMSIS
+ flash implementation **must** be able to detect incomplete writes and return
+ an error the next time the block is read.
+
+- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash
+ device, on top of the CMSIS flash interface implemented by the target.
+
+- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated
+ flash device using RAM, on top of the CMSIS flash interface implemented by the
+ target.
+
+The CMSIS flash interface **must** be implemented for each target based on its
+flash controller.
+
+The ITS flash interface depends on target-specific definitions from
+``platform/ext/target//partition/flash_layout.h``.
+Please see the `Internal Trusted Storage Service HAL` section for details.
+
+*****************************
+ITS Service Integration Guide
+*****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator has to take in
+to account in order to integrate the internal trusted storage service in a new
+platform.
+
+Flash Interface
+===============
+For ITS service operations, a contiguous set of blocks must be earmarked for
+the internal trusted storage area. The design requires either 2 blocks, or any
+number of blocks greater than or equal to 4. Total number of blocks can not be
+0, 1 or 3. This is a design choice limitation to provide power failure safe
+update operations.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a logical filesystem block. The
+maximum size of an asset can be up-to the size of the data block. Typically,
+each logical block corresponds to one physical flash erase sector (the smallest
+unit that can erased), but the ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` configuration
+below allows a number of contiguous erase sectors to form one logical block.
+
+Internal Trusted Storage Service HAL
+====================================
+The ITS service requires the platform to implement the ITS HAL, defined in
+``platform/include/tfm_hal_its.h``.
+
+The following C definitions in the HAL are mandatory, and must be defined by the
+platform in a header named ``flash_layout.h``:
+
+- ``TFM_HAL_ITS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
+ ARM_DRIVER_FLASH object to use for ITS. It must have been allocated by the
+ platform and will be declared extern in the HAL header.
+
+- ``TFM_HAL_ITS_PROGRAM_UNIT`` - Defines the size of the ITS flash device's
+ physical program unit (the smallest unit of data that can be individually
+ programmed to flash). It must be equal to
+ ``TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
+ compile time so that filesystem structures can be statically sized. Valid
+ values are powers of two between 1 and the flash sector size, inclusive.
+
+The following C definitions in the HAL may optionally be defined by the platform
+in the ``flash_layout.h`` header:
+
+- ``TFM_HAL_ITS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
+ flash area for ITS.
+
+- ``TFM_HAL_ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
+ for ITS in bytes.
+
+- ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
+ flash erase sectors that form a logical erase block in the filesystem. The
+ typical value is ``1``, but it may be increased so that the maximum required
+ asset size will fit in one logical block.
+
+If any of the above definitions are not provided by the platform, then the
+``tfm_hal_its_fs_info()`` HAL API must be implemented instead. This function is
+documented in ``tfm_hal_its.h``.
+
+The sectors reserved to be used for Internal Trusted Storage **must** be
+contiguous.
+
+Internal Trusted Storage Service Optional Platform Definitions
+==============================================================
+The following optional platform definitions may be defined in
+``flash_layout.h``:
+
+- ``ITS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
+ RAM FS emulated flash implementation. The buffer must be at least as large as
+ the area earmarked for the filesystem by the HAL.
+- ``ITS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
+ the NAND flash implementation. The buffer must be at least as large as a
+ logical filesystem block.
+- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data
+ between blocks, in bytes. If not provided, defaults to 256. Increasing this
+ value will increase the memory footprint of the service.
+
+More information about the ``flash_layout.h`` content, not ITS related, is
+available in :doc:`platform readme ` along with other
+platform information.
+
+ITS Service Build Definitions
+=============================
+The ITS service uses a set of C definitions to compile in/out certain features,
+as well as to configure certain service parameters. When using the TF-M build
+system, these definitions are controlled by build flags of the same name. The
+``config/config_default.cmake`` file sets the default values of those flags, but
+they can be overwritten based on platform capabilities by setting them in
+``platform/ext/target//config.cmake``. The list of ITS service
+build definitions is:
+
+- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create an ITS flash layout. If this flag is set, ITS service will
+ generate an empty and valid ITS flash layout to store assets. It will
+ erase all data located in the assigned ITS memory area before generating
+ the ITS layout. This flag is required to be set if the ITS memory area
+ is located in a non-persistent memory. This flag can be set if the ITS
+ memory area is located in a persistent memory without a valid ITS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the ITS service is executed.
+- ``ITS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
+ enable/disable the validation mechanism to check the metadata store in flash
+ every time the flash data is read from flash. This validation is required
+ if the flash is not hardware protected against data corruption.
+- ``ITS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
+ the persistent storage device to store the FS in the Internal Trusted Storage
+ service. This flag is ``OFF`` by default. The ITS regression tests write/erase
+ storage multiple time, so enabling this flag can increase the life of flash
+ memory when testing.
+ If this flag is set to ``ON``, ITS_RAM_FS_SIZE must also be provided. This
+ specifies the size of the block of RAM to be used to simulate the flash.
+
+ .. Note::
+ If this flag is disabled when running the regression tests, then it is
+ recommended that the persistent storage area is erased before running the
+ tests to ensure that all tests can run to completion. The type of persistent
+ storage area is platform specific (eFlash, MRAM, etc.) and it is described
+ in corresponding flash_layout.h
+
+- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ ITS area. This size is used to define the temporary buffers used by ITS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as ITS does not use dynamic memory allocation.
+- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ ITS area. This number is used to dimension statically the filesystem metadata
+ tables in RAM (fast access) and flash (persistent storage). The memory used by
+ the filesystem metadata tables is allocated statically as ITS does not use
+ dynamic memory allocation.
+- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer
+ buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset
+ data to be copied between the client and the filesystem in one iteration.
+ Reducing the buffer size will decrease the RAM usage of the partition at the
+ expense of latency, as data will be copied in multiple iterations. *Note:*
+ when data is copied in multiple iterations, the atomicity property of the
+ filesystem is lost in the case of an asynchronous power failure.
+
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_platform_integration_guide.rst b/docs/integration_guide/services/tfm_platform_integration_guide.rst
new file mode 100644
index 0000000000..7858435ac7
--- /dev/null
+++ b/docs/integration_guide/services/tfm_platform_integration_guide.rst
@@ -0,0 +1,113 @@
+##################################
+Platform Service Integration Guide
+##################################
+
+************
+Introduction
+************
+TF-M Platform service is a trusted service which allows secure partitions and
+non-secure applications to interact with some platform-specific components.
+There are a number of features which requires some interaction with
+platform-specific components which are at the same time essential for the
+security of the system.
+Therefore, those components need to be handled by a secure partition which is
+part of the trusted compute base.
+
+These platform-specific components include system reset, power management,
+Debug, GPIO, etc.
+
+************************
+TF-M Platform interfaces
+************************
+The TF-M interfaces for the Platform service are located in
+``interface/include/``.
+The TF-M Platform service source files are located in
+``secure_fw/partitions/platform``.
+
+*********************
+TF-M Platform service
+*********************
+The Platform service interfaces and types are defined and documented in
+``interface/include/tfm_platform_api.h``
+
+- ``platform_sp.h/c`` : These files define and implement functionalities related
+ to the platform service
+- ``tfm_platform_secure_api.c`` : This file implements ``tfm_platform_api.h``
+ functions to be called from the secure partitions. This is the entry point
+ when the secure partitions request an action to the Platform service
+ (e.g system reset).
+
+************
+Platform HAL
+************
+
+The Platform Service relies on a platform-specific implementation to
+perform some functionalities. Mandatory functionality (e.g. system reset)
+that are required to be implemented for a platform to be supported by TF-M have
+their dedicated HAL API functions. Additional platform-specific services can be
+provided using the IOCTL function call.
+
+For API specification, please check: ``platform/include/tfm_platform_system.h``
+
+An implementation is provided in all the supported platforms. Please, check
+``platform/ext/target//services/src/tfm_platform_system.c``
+for examples.
+
+The API **must** be implemented by the system integrators for their targets.
+
+IOCTL
+=====
+
+A single entry point to platform-specific code across the HAL is provided by the
+IOCTL service and HAL function:
+
+.. code-block:: c
+
+ enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request,
+ psa_invec *in_vec,
+ psa_outvec *out_vec);
+
+A request type is provided by the client, with additional parameters contained
+in the optional ``in_vec`` parameter. An optional output buffer can be passed to
+the service in ``out_vec``.
+An IOCTL request type not supported on a particular platform should return
+``TFM_PLATFORM_ERR_NOT_SUPPORTED``
+
+Non-Volatile counters
+=====================
+
+The Platform Service provides an abstracted service for exposing the NV counters
+to the secure world. The following operations are supported:
+
+- Increment a counter.
+- Read a counter value to a preallocated buffer.
+
+.. code-block:: c
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_increment(uint32_t counter_id);
+
+ enum tfm_platform_err_t
+ tfm_platform_nv_counter_read(uint32_t counter_id,
+ uint32_t size, uint8_t *val);
+
+The range of counters id is defined in :
+``platform/include/tfm_plat_nv_counters.h``
+
+For Level 2,3 isolation implementations, secure partitions in the
+Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a
+dependency for access to the NV counter API.
+
+***************************
+Current Service Limitations
+***************************
+- **system reset** - The system reset functionality is only supported in
+ isolation level 1. Currently the mechanism by which PSA-RoT services should
+ run in privileged mode in level 3 is not in place due to an ongoing work in
+ TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service is
+ expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
+ register in level 3 isolation.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst
new file mode 100644
index 0000000000..2c6da7b490
--- /dev/null
+++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst
@@ -0,0 +1,392 @@
+###########################################
+Protected Storage Service Integration Guide
+###########################################
+
+************
+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 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 design addresses the following high level requirements as well:
+
+- **Confidentiality** - Resistance to unauthorised accesses through
+ hardware/software attacks.
+
+- **Access Authentication** - Mechanism to establish requester's identity (a
+ non-secure entity, secure entity, or a remote server).
+
+- **Integrity** - Resistant to tampering by either the normal users of a product,
+ package, or system or others with physical access to it. If the content of the
+ protected storage is changed maliciously, the service is able to detect it.
+
+- **Reliability** - Resistant to power failure scenarios and incomplete write
+ cycles.
+
+- **Configurability** - High level configurability to scale up/down memory
+ footprint to cater for a variety of devices with varying security
+ requirements.
+
+- **Performance** - Optimized to be used for resource constrained devices with
+ very small silicon footprint, the PPA (power, performance, area) should be
+ optimal.
+
+******************************
+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.
+
+- **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
+ metadata in blocks which are always stored in the same flash location. That
+ increases the number of writes in a specific flash location as every change in
+ the storage area requires a metadata update.
+
+- **PSA internal trusted storage API** - In the current design, the service does
+ not use the PSA Internal Trusted Storage API to write the rollback protection
+ values stored in the internal storage.
+
+- **Protection against physical storage medium failure** - Complete handling of
+ inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
+ is not supported by the current design.
+
+- **Key diversification** - In a more robust design, each asset would be
+ encrypted through a different key.
+
+- **Lifecycle management** - Currently, it does not support any subscription
+ based keys and certificates required in a secure lifecycle management. Hence,
+ an asset's validity time-stamp can not be invalidated based on the system
+ time.
+
+- **Provisioning vs user/device data** - In the current design, all assets are
+ treated in the same manner. In an alternative design, it may be required to
+ create separate partitions for provisioning content and user/device generated
+ content. This is to allow safe update of provisioning data during firmware
+ updates without the need to wipe out the user/device generated data.
+
+**************
+Code Structure
+**************
+Protected storage service code is located in
+``secure_fw/partitions/protected_storage/`` and is divided as follows:
+
+ - Core files
+ - Cryptographic interfaces
+ - Non-volatile (NV) counters interfaces
+
+The PSA PS interfaces for PS service are located in ``interface/include/psa``
+
+PSA Protected Storage Interfaces
+================================
+
+The PS service exposes the following mandatory PSA PS interfaces, version 1.0:
+
+.. code-block:: c
+
+ psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
+ psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
+ psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
+ psa_status_t psa_ps_remove(psa_storage_uid_t uid);
+ uint32_t psa_ps_get_support(void);
+
+For the moment, it does not support the extended version of those APIs.
+
+These PSA PS interfaces and PS TF-M types are defined and documented in
+``interface/include/psa/protected_storage.h``,
+``interface/include/psa/storage_common.h`` and
+``interface/include/tfm_ps_defs.h``
+
+Core Files
+==========
+- ``tfm_ps_req_mngr.c`` - Contains the PS request manager implementation which
+ handles all requests which arrive to the service. This layer extracts the
+ arguments from the input and output vectors, and it calls the protected
+ storage layer with the provided parameters.
+
+- ``tfm_protected_storage.c`` - Contains the TF-M protected storage API
+ implementations which are the entry points to the PS service.
+
+- ``ps_object_system.c`` - Contains the object system implementation to manage
+ all objects in PS area.
+
+- ``ps_object_table.c`` - Contains the object system table implementation which
+ complements the object system to manage all object in the PS area.
+ The object table has an entry for each object stored in the object system
+ and keeps track of its version and owner.
+
+- ``ps_encrypted_object.c`` - Contains an implementation to manipulate
+ encrypted objects in the PS object system.
+
+- ``ps_utils.c`` - Contains common and basic functionalities used across the
+ PS service code.
+
+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 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
+`.
+
+The ITS service implementation in
+``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``,
+constructs a filesystem configuration for Protected Storage based on
+target-specific definitions from the Protected Storage HAL. Please see the
+`Protected Storage Service HAL` section for details of these.
+
+Cryptographic Interface
+=======================
+- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for
+ the protected storage service.
+
+- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic
+ operations with calls to the TF-M Crypto service.
+
+Non-volatile (NV) Counters Interface
+====================================
+The current PS service provides rollback protection based on NV
+counters.
+PS defines and implements the following NV counters functionalities:
+
+- ``nv_counters/ps_nv_counters.h`` - Abstracts PS non-volatile
+ counters operations. This API detaches the use of NV counters from the TF-M NV
+ counters implementation, provided by the platform, and provides a mechanism to
+ compile in a different API implementation for test purposes. A PS test suite
+ **may** provide its own custom implementation to be able to test different PS
+ service use cases.
+
+- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces
+ based on TF-M NV counters implementation provided by the platform.
+
+****************************
+PS Service Integration Guide
+****************************
+This section describes mandatory (i.e. **must** implement) or optional
+(i.e. **may** implement) interfaces which the system integrator have to take
+in to account in order to integrate the protected storage service in a new
+platform.
+
+Maximum Asset Size
+==================
+An asset is stored in a contiguous space in a block/sector. The maximum
+size of an asset can be up-to the size of the data block/sector minus the object
+header size (``PS_OBJECT_HEADER_SIZE``) which is defined in
+``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the
+``PS_ENCRYPTION`` flag status.
+
+Protected Storage Service HAL
+=============================
+The PS service requires the platform to implement the PS HAL, defined in
+``platform/include/tfm_hal_ps.h``.
+
+The following C definitions in the HAL are mandatory, and must be defined by the
+platform in a header named ``flash_layout.h``:
+
+- ``TFM_HAL_PS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
+ ARM_DRIVER_FLASH object to use for PS. It must have been allocated by the
+ platform and will be declared extern in the HAL header.
+
+- ``TFM_HAL_PS_PROGRAM_UNIT`` - Defines the size of the PS flash device's
+ physical program unit (the smallest unit of data that can be individually
+ programmed to flash). It must be equal to
+ ``TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
+ compile time so that filesystem structures can be statically sized. Valid
+ values are powers of two between 1 and the flash sector size, inclusive.
+
+The following C definitions in the HAL may optionally be defined by the platform
+in the ``flash_layout.h`` header:
+
+- ``TFM_HAL_PS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
+ flash area for PS.
+
+- ``TFM_HAL_PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
+ for PS in bytes.
+
+- ``TFM_HAL_PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
+ flash erase sectors that form a logical erase block in the filesystem. The
+ typical value is ``1``, but it may be increased so that the maximum required
+ asset size will fit in one logical block.
+
+If any of the above definitions are not provided by the platform, then the
+``tfm_hal_ps_fs_info()`` HAL API must be implemented instead. This function is
+documented in ``tfm_hal_ps.h``.
+
+The sectors reserved to be used for Protected Storage **must** be contiguous
+sectors starting at ``TFM_HAL_PS_FLASH_AREA_ADDR``.
+
+The design requires either 2 blocks, or any number of blocks greater than or
+equal to 4. Total number of blocks can not be 0, 1 or 3. This is a design choice
+limitation to provide power failure safe update operations.
+
+Protected Storage Service Optional Platform Definitions
+=======================================================
+The following optional platform definitions may be defined in
+``flash_layout.h``:
+
+- ``PS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
+ RAM FS emulated flash implementation. The buffer must be at least as large as
+ the area earmarked for the filesystem by the HAL.
+- ``PS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
+ the NAND flash implementation. The buffer must be at least as large as a
+ logical filesystem block.
+
+More information about the ``flash_layout.h`` content, not PS related, is
+available in :doc:`platform readme ` along with other
+platform information.
+
+TF-M NV Counter Interface
+=========================
+To have a platform independent way to access the NV counters, TF-M defines a
+platform NV counter interface. For API specification, please check:
+``platform/include/tfm_plat_nv_counters.h``
+
+The system integrators **may** implement this interface based on the target
+capabilities and set the ``PS_ROLLBACK_PROTECTION`` flag to compile in
+the rollback protection code.
+
+Secret Platform Unique Key
+==========================
+The encryption policy relies on a secret hardware unique key (HUK) per device.
+It is system integrator's responsibility to provide an implementation which
+**must** be a non-mutable target implementation.
+For API specification, please check:
+``platform/include/tfm_plat_crypto_keys.h``
+
+A stub implementation is provided in
+``platform/ext/common/template/crypto_keys.c``
+
+Non-Secure Identity Manager
+===========================
+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:`NS client identification documentation `
+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 `
+provides further details of non-secure implementation requirements for TF-M.
+
+Cryptographic Interface
+=======================
+The reference encryption policy is built on AES-GCM, and it **may** be replaced
+by a vendor specific implementation.
+
+The PS service abstracts all the cryptographic requirements and specifies the
+required cryptographic interface in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h``
+
+The PS service cryptographic operations are implemented in
+``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using
+calls to the TF-M Crypto service.
+
+PS Service Build Definitions
+============================
+The PS service uses a set of C definitions to compile in/out certain features,
+as well as to configure certain service parameters. When using the TF-M build
+system, these definitions are controlled by build flags of the same name. The
+``config/config_default.cmake`` file sets the default values of those flags, but
+they can be overwritten based on platform capabilities by setting them in
+``platform/ext/target//config.cmake``. The list of PS service build
+definitions is:
+
+- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption
+ option to encrypt the protected storage data.
+- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
+ to create a PS flash layout. If this flag is set, PS service will
+ generate an empty and valid PS flash layout to store assets. It will
+ erase all data located in the assigned PS memory area before generating
+ the PS layout. This flag is required to be set if the PS memory area
+ is located in a non-persistent memory. This flag can be set if the PS
+ memory area is located in a persistent memory without a valid PS flash
+ layout in it. That is the case when it is the first time in the device
+ life that the PS service is executed.
+- ``PS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
+ enable/disable the validation mechanism to check the metadata store in flash
+ every time the flash data is read from flash. This validation is required
+ if the flash is not hardware protected against malicious writes. In case
+ the flash is protected against malicious writes (i.e embedded flash, etc),
+ this validation can be disabled in order to reduce the validation overhead.
+- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable
+ rollback protection in protected storage service. This flag takes effect only
+ if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on.
+- ``PS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
+ the persistent storage device to store the FS in the Protected Storage
+ service. This flag is ``OFF`` by default. The PS regression tests write/erase
+ storage multiple time, so enabling this flag can increase the life of flash
+ memory when testing.
+ If this flag is set to ``ON``, PS_RAM_FS_SIZE must also be provided. This
+ specifies the size of the block of RAM to be used to simulate the flash.
+
+ .. Note::
+ If this flag is disabled when running the regression tests, then it is
+ recommended that the persistent storage area is erased before running the
+ tests to ensure that all tests can run to completion. The type of persistent
+ storage area is platform specific (eFlash, MRAM, etc.) and it is described
+ in corresponding flash_layout.h
+
+- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ PS area. This size is used to define the temporary buffers used by PS to
+ read/write the asset content from/to flash. The memory used by the temporary
+ buffers is allocated statically as PS does not use dynamic memory allocation.
+- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ PS area. This number is used to dimension statically the object table size in
+ RAM (fast access) and flash (persistent storage). The memory used by the
+ 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
+ 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
+ overridden to ``OFF`` when building the regression tests. In this case,
+ the PS rollback protection test suite will not be built, as it relies
+ on extra functionality provided by the virtual NV counters to simulate
+ different rollback scenarios. The remainder of the PS test suites will
+ run using the hardware NV counters. Please note that running the tests in
+ this configuration will quickly increase the hardware NV counter values,
+ which cannot be decreased again.
+ Overriding this flag from its default value of ``OFF`` when not
+ building the regression tests is not currently supported.
+
+--------------
+
+*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst
new file mode 100644
index 0000000000..2c0509b3fb
--- /dev/null
+++ b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst
@@ -0,0 +1,83 @@
+#####################################
+PSA Proxy Partition Integration Guide
+#####################################
+
+************
+Introduction
+************
+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 `.
+
+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
+``psa_write`` is used to give back the results to the caller.) By default this
+memory is allocated from BSS, but if that is not accessible to the Secure
+Enclave other memory area can be used. To communicate with the Secure Enclave
+the mailbox solution is used, and Proxy uses the Non-secure side of mailbox.
+(The secure side of the mailbox is handled by the Secure Enclave.)
+
+***************************************
+Current PSA Proxy partition limitations
+***************************************
+- Client IDs are not forwarded to Secure Enclave. For Non-secure clients this
+ is straightforward, but for calls coming from other secure partitions the IDs
+ must be translated to a negative value. The reason is all clients on Host
+ are treated as non-secure from Secure Enclave's point of view. (This is the
+ cause why Protected Storage messages also forwarded. Protected Storage uses
+ Internal Trusted Storage partition to manage the PS flash area. But as client
+ IDs are not forwarded the ITS partition running on Secure Enclave can not
+ know whether should work on ITS or PS flash.)
+- Sending of the mailbox messages is a blocking call in Proxy, so control is
+ not given back to Host's SPM while waiting for Secure Enclave's answer.
+- Only one message can be put into the mailbox at a time.
+- Current platform partition provides Non Volatile (NV) counter, System Reset,
+ and IOCTL services. But while NV counters and System Reset shall be provided
+ by the Secure Enclave, IOCTL probably shall be provided by Host, as the
+ underlaying HW probably placed in Host subsystem. So the current platform
+ partition should be split into two halves by conditional compilation, and
+ Proxy should forward only the calls provided by Secure Enclave.
+- PSA Proxy can only get the IPC parameters by PSA read, so the parameters need
+ to be copied to a shared memory, because the partition cannot forward the
+ original pointers. This copy might be omitted on platforms where Secure
+ Enclave has access to all Host memory areas, if all security risks are
+ addressed. Note that IOVECs shall be verified by Host's SPM and sent to SE
+ with the mailbox message.
+
+**************
+Code Structure
+**************
+PSA Proxy partition code is located in ``secure_fw/partitions/psa_proxy/``.
+As Proxy can be treated as an alternative implementation of all the PSA RoT
+services, the Secure and Non-secure interface implementations of the forwarded
+services are reused without modification.
+
+Files
+=====
+- ``psa_proxy.c`` - Handles IPC messages and manages communication with the
+ Secure Enclave.
+
+- ``psa_proxy_shared_mem_mngr.c`` - Responsible to manage the shared memory
+ area used to share the input and output parameters with Secure Enclave.
+
+*****************
+Integration Guide
+*****************
+- Non-secure mailbox interface must be provided.
+- Shared memory must be configured:
+ - If Secure Enclave can access TF-M's BSS section it is enough to set the
+ area's size by the ``SHARED_BUFFER_SIZE`` macro.
+ - If a special memory region must be used as the shared memory the
+ ``PSA_PROXY_SHARED_MEMORY_BASE`` and ``PSA_PROXY_SHARED_MEMORY_SIZE``
+ macros must be set. (Not just for compilation but for linking as well,
+ becuase these macros used in the linker script/scatter file too.)
+- If memories are mapped to different addresses for Host and Secure Enclave
+ address translation can be turned on by setting
+ ``PSA_PROXY_ADDR_TRANSLATION`` macro and implementing the interface defined
+ by ``platform/include/tfm_plat_psa_proxy_addr_trans.h`` header.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/services/tfm_secure_partition_addition.rst b/docs/integration_guide/services/tfm_secure_partition_addition.rst
new file mode 100644
index 0000000000..9343aab2d4
--- /dev/null
+++ b/docs/integration_guide/services/tfm_secure_partition_addition.rst
@@ -0,0 +1,467 @@
+#######################
+Adding Secure Partition
+#######################
+
+***********************
+Terms and abbreviations
+***********************
+This document uses the following terms and abbreviations.
+
+.. table:: term table
+ :widths: auto
+
+ ================== ==================================
+ **Term** **Meaning**
+ ================== ==================================
+ FF Firmware Framework
+ ID Identifier
+ IPC Interprocess communication
+ IPC model The secure IPC framework
+ irqs Interrupt requests
+ Library model The secure function call framework
+ MMIO Memory Mapped I/O
+ PSA Platform Security Architecture
+ RoT Root of Trust
+ SID RoT Service ID
+ SP Secure Partition
+ SPM Secure Partition Manager
+ TF-M Trusted firmware M
+ ================== ==================================
+
+************
+Introduction
+************
+Secure Partition is an execution environment that provides the following
+functions to Root of Trust (RoT) Services:
+
+- Access to resources, protection of its own code and data.
+- Mechanisms to interact with other components in the system.
+
+Each Secure Partition is a single thread of execution and the smallest unit of
+isolation.
+
+This document mainly describes how to add a secure partition in TF-M and
+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
+ model.
+
+ The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to
+ `PSA Firmware Framework specification`_ for details.
+
+*******
+Process
+*******
+The main steps to add a secure partition are as follows:
+
+- `Add source folder`_
+- `Add manifest`_
+- `Add configuration`_
+- `Implement the RoT services`_
+
+Add source folder
+=================
+Add a source folder under ``/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
+- CMake configuration files
+- Source code files
+
+Add manifest
+============
+Each Secure Partition must have resource requirements declared in a manifest
+file. The Secure Partition Manager (SPM) uses the manifest file to assemble and
+allocate resources within the SPE. The manifest includes the following:
+
+- A Secure Partition name.
+- A list of implemented RoT Services.
+- Access to other RoT Services.
+- Memory requirements.
+- Scheduling hints.
+- Peripheral memory-mapped I/O regions and interrupts.
+
+.. Note::
+ 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:
+
+.. code-block:: yaml
+
+ {
+ "psa_framework_version": 1.0,
+ "name": "TFM_SP_EXAMPLE",
+ "type": "PSA-ROT",
+ "priority": "HIGH",
+ "entry_point": "example_main",
+ "stack_size": "0x0200",
+ "services" : [
+ {
+ "name": "ROT_A",
+ "sid": "0x0000F000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ }
+ ],
+ "mmio_regions": [
+ {
+ "name": "TFM_PERIPHERAL_A",
+ "permission": "READ-WRITE"
+ }
+ ],
+ "irqs": [
+ {
+ "source": "TFM_A_IRQ",
+ "signal": "SPM_CORE_A_IRQ",
+ "tfm_irq_priority": 64,
+ }
+ ],
+ "linker_pattern": {
+ "object_list": [
+ "*EXAMPLE.*"
+ ]
+ }
+ }
+
+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
+``/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.
+
+.. code-block:: c
+
+ #define name id-value
+
+Here is the Secure Partition ID table used in TF-M.
+
+.. table:: PID table
+ :widths: auto
+
+ =============================== =================
+ **Partition name** **Partition ID**
+ =============================== =================
+ Reserved 0-255
+ TFM_SP_PS 256
+ TFM_SP_ITS 257
+ TFM_SP_AUDIT_LOG 258
+ TFM_SP_CRYPTO 259
+ TFM_SP_PLATFORM 260
+ TFM_SP_INITIAL_ATTESTATION 261
+ TFM_SP_CORE_TEST 262
+ TFM_SP_CORE_TEST_2 263
+ TFM_SP_SECURE_TEST_PARTITION 264
+ TFM_SP_IPC_SERVICE_TEST 265
+ TFM_SP_IPC_CLIENT_TEST 266
+ TFM_IRQ_TEST_1 267
+ TFM_SP_PS_TEST 268
+ =============================== =================
+
+About where to add the definition, please refer to the chapter `Add
+configuration`_.
+
+RoT Service ID (SID) Distribution
+---------------------------------
+An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit
+number that is associated with a symbolic name in the Secure Partition
+manifest. The bits [31:12] uniquely identify the vendor of the RoT Service.
+The remaining bits [11:0] can be used at the discretion of the vendor.
+
+Here is the RoT Service ID table used in TF-M.
+
+.. table:: SID table
+ :widths: auto
+
+ =========================== ====================== ========================
+ **Services** **Vendor ID(20 bits)** **Function ID(12 bits)**
+ =========================== ====================== ========================
+ audit_logging 0x00000 0x000-0x01F
+ initial_attestation 0x00000 0x020-0x03F
+ platform 0x00000 0x040-0x05F
+ protected_storage 0x00000 0x060-0x06F
+ internal_trusted_storage 0x00000 0x070-0x07F
+ crypto 0x00000 0x080-0x09F
+ firmware_update 0x00000 0x0A0-0x0BF
+ test_secure_service 0x0000F 0x000-0x01F
+ core_test 0x0000F 0x020-0x03F
+ core_test_2 0x0000F 0x040-0x05F
+ tfm_ipc_client 0x0000F 0x060-0x07F
+ tfm_ipc_service 0x0000F 0x080-0x09F
+ tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF
+ tfm_ps_test_service 0x0000F 0x0C0-0x0DF
+ =========================== ====================== ========================
+
+mmio_regions
+------------
+This attribute is a list of MMIO region objects which the Secure Partition
+needs access to. TF-M only supports the ``named_region`` current. Please refer
+to PSA FF for more details about it. The user needs to provide a name macro to
+indicate the variable of the memory region.
+
+TF-M uses the below structure to indicate a peripheral memory.
+
+.. code-block:: c
+
+ struct platform_data_t {
+ uint32_t periph_start;
+ uint32_t periph_limit;
+ int16_t periph_ppc_bank;
+ int16_t periph_ppc_loc;
+ };
+
+.. Note::
+ This structure is not expected by TF-M, it's only that the current
+ 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:
+
+.. 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.
+
+The ``signal`` must be the upper case of the secure function name.
+
+.. code-block:: yaml
+
+ "secure_functions": [
+ {
+ "name": "TFM_EXAMPLE_A",
+ "signal": "EXAMPLE_A_FUNC",
+ "sid": "0x00000000",
+ "non_secure_clients": true,
+ "version": 1,
+ "version_policy": "STRICT"
+ },
+
+Add configuration
+=================
+The following configuration tasks are required for the newly added secure
+partition:
+
+Add CMake configure files
+-------------------------
+- CMakeLists.txt, which is the compilation configuration for this module.
+
+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``.
+Please refer to the source code of TF-M for more detail.
+
+Update manifest list
+--------------------
+The ``/tools/tfm_manifest_list.yaml`` is used to collect
+necessary information of secure partition.
+
+- ``name``: The name string of the secure partition.
+- ``short_name``: should be the same as the ``name`` in the secure partition
+ manifest file.
+- ``manifest``: the relative path of the manifest file to TF-M root.
+- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC
+ model.
+- ``conditional``: Optional. Configure control macro for this partition.
+- ``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`_.
+
+Reference configuration example:
+
+.. code-block:: yaml
+
+ {
+ "name": "Example Service",
+ "short_name": "TFM_SP_EXAMPLE",
+ "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml",
+ "tfm_partition_ipc": true,
+ "conditional": "TFM_PARTITION_EXAMPLE",
+ "version_major": 0,
+ "version_minor": 1,
+ "pid": 256
+ }
+
+.. Note::
+ The manifest configuration can be placed in a different external manifest
+ list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be
+ set to the path of the external manifest list.
+
+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
+``/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.
+
+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
+
+.. code-block:: c
+
+ void example_main(void)
+ {
+ psa_signal_t signals = 0;
+
+ while (1) {
+ signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK);
+ if (signals & ROT_A_SIGNAL) {
+ rot_A();
+ } else {
+ /* Should not come here */
+ psa_panic();
+ }
+ }
+ }
+
+Service implementation
+----------------------
+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
+"Hello World" when called.
+
+.. code-block:: c
+
+ 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";
+
+ 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);
+ break;
+ 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);
+ }
+ }
+ 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();
+ break;
+ }
+ }
+
+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
+``/test/suites/example/non_secure/example_ns_interface_testsuite.c``.
+
+.. code-block:: c
+
+ static void tfm_example_test_1001(struct test_result_t *ret)
+ {
+ char str1[] = "str1";
+ char str2[] = "str2";
+ char str3[128], str4[128];
+ struct psa_invec invecs[2] = {{str1, sizeof(str1)},
+ {str2, sizeof(str2)}};
+ struct psa_outvec outvecs[2] = {{str3, sizeof(str3)},
+ {str4, sizeof(str4)}};
+ psa_handle_t handle;
+ psa_status_t status;
+ uint32_t version;
+
+ version = psa_version(ROT_A_SID);
+ TEST_LOG("TFM service support version is %d.\r\n", version);
+ handle = psa_connect(ROT_A_SID, ROT_A_VERSION);
+ status = psa_call(handle, PSA_IPC_CALL, invecs, 2, outvecs, 2);
+ if (status >= 0) {
+ TEST_LOG("psa_call is successful!\r\n");
+ } else {
+ TEST_FAIL("psa_call is failed!\r\n");
+ return;
+ }
+
+ TEST_LOG("outvec1 is: %s\r\n", outvecs[0].base);
+ TEST_LOG("outvec2 is: %s\r\n", outvecs[1].base);
+ psa_close(handle);
+ ret->val = TEST_PASSED;
+ }
+
+Once the test and service has been implemented, the project can be built and
+executed. The user should see the "Hello World" message in the console as
+received by the testsuite.
+
+Further Notes
+-------------
+
+- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM
+ provides APIs and checking between isolation boundaries, a free accessing
+ of memory can cause program panic.
+- In the IPC model, the memory checking inside partition runtime is
+ unnecessary. SPM handles the checking while memory accessing APIs are
+ called.
+- In the IPC model, the client ID had been included in the message structure
+ and secure partition can get it when calling psa_get() function. The secure
+ partition does not need to call ``tfm_core_get_caller_client_id()`` to get
+ the caller client ID anymore.
+- In the IPC model, SPM will check the security policy and partition
+ dependence between client and service. So the service does not need to
+ validate the secure caller anymore.
+
+*********
+Reference
+*********
+
+| `PSA Firmware Framework specification`_
+
+.. _PSA Firmware Framework specification: https://pages.arm.com/psa-
+ resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
+
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/tfm_integration_guide.rst b/docs/integration_guide/tfm_integration_guide.rst
new file mode 100644
index 0000000000..c398fbf9d8
--- /dev/null
+++ b/docs/integration_guide/tfm_integration_guide.rst
@@ -0,0 +1,180 @@
+#################
+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 `.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions `.
+
+*************************
+How to add a new platform
+*************************
+The hardware platforms currently supported are:
+
+- Soft Macro Model (SMM) Cortex-M33 SSE-200 subsystem for MPS2+ (AN521)
+- Cortex-M23 IoT Kit subsystem for MPS2+ (AN519)
+- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+)
+- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3)
+- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem)
+- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem)
+- CoreLink SSE-200 Subsystem for MPS3 (AN524)
+- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547)
+- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs)
+- nRF9160 DK (Cortex-M33)
+- nRF5340 PDK/DK (Cortex-M33 Application MCU)
+
+The files related to the supported platforms are contained under the
+``platform`` subfolder. The platform specific files are under
+``platform/ext/target``, which is organised by boards
+(e.g. ``platform/ext/target/mps2``), while the folder ``platform/ext/common``
+is used to store source and header files which are platform generic.
+
+More information about subsystems supported by the MPS2+ board can be found in:
+`MPS2+ homepage `__
+
+More information about subsystems supported by the MPS3 board can be found in:
+`MPS3 homepage `__
+
+More information about the Musca-B1 test chip board can be found in:
+`Musca-B1 homepage `__
+
+More information about the Musca-S1 test chip board can be found in:
+`Musca-S1 homepage `__
+
+More information about subsystems supported by the MPS3 board can be found in:
+`MPS3 homepage `__
+
+More information about the Corstone-300 FVPs can be found in:
+`Arm Ecosystem FVPs homepage `__
+
+More information about the STM32L5xx platform can be found in:
+`STM32L5 series product page `__
+
+More information about the nRF5340 PDK platform can be found in:
+`nRF5340 PDK product page `__
+
+More information about the nRF9160 DK platform can be found in:
+`nRF9160 DK product page `__
+
+Generic drivers and startup/scatter files
+=========================================
+The addition of a new platform means the creation of a new subfolder inside
+``target/`` to provide an implementation of the drivers currently
+used by TF-M, in particular MPC, PPC, and USART drivers. In addition to the
+drivers, startup and scatter files need to be provided for the supported
+toolchains.
+
+There are also board specific drivers which are used by the board
+platform to interact with the external world, for example during tests, that
+have to be provided, e.g. to blink LEDs or count time in the MPS2 board.
+
+.. Note::
+
+ Currently ITS, PS and BL2 bootloader use different flash interface
+
+Target configuration files
+==========================
+Inside the base root folder of the selected target, each implementation has to
+provide its own copy of ``target_cfg.c/.h``. This file has target specific
+configuration functions and settings that are called by the TF-M during the
+platform configuration step during TF-M boot. Examples of the configurations
+performed during this phase are the MPC configuration, the SAU configuration,
+or eventually PPC configuration if supported by the hardware platform.
+Similarly, the ``uart_stdout.c`` is used to provide functions needed to redirect
+the stdout on UART (this is currently used by TF-M to log messages).
+
+Platform retarget files
+=======================
+An important part that each new platform has to provide is the set of retarget
+files which are contained inside the ``retarget`` folder. These files define the
+peripheral base addresses for the platform, both for the secure and non-secure
+aliases (when available), and bind those addresses to the base addresses used by
+the devices available in the hardware platform.
+
+***************************
+How to integrate another OS
+***************************
+To work with TF-M, the OS needs to support the Armv8-M architecture and, in
+particular, it needs to be able to run in the non-secure world. More
+information about OS migration to the Armv8-M architecture can be found in the
+:doc:`OS requirements `. 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
+``/interface`` path. The NS side is only allowed to call
+TF-M secure functions (veneers) from the NS Thread mode. For this reason, the
+API is a collection of functions in the ``/interface/include``
+directory. For example, the interface for the Protected Storage (PS) service
+is described in the file ``psa_ps_api.h`` as a collection of functions that
+call service veneer functions. This API is a wrapper for the secure veneers,
+and returns the return value from the service to the caller.
+
+The protected storage service uses a numerical ID, to identify the clients that
+use the service. For details see
+:doc:`ns client identification documentation `.
+
+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
+``/install`` folder structure in the test specific files,
+i.e. ``/install/export/tfm/test/inc``. The non-secure regression
+tests are precompiled and delivered as a static library which is available in
+``/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
+``/install/export/tfm/test/inc``. OS needs to provide the
+implementation of these wrappers to be able to run the tests.
+
+NS client Identification
+========================
+See
+:doc:`ns client identification documentation `.
+
+*********************
+Non-secure interrupts
+*********************
+Non-secure interrupts are allowed to preempt Secure thread mode.
+With the current implementation, a NSPE task can spoof the identity of another
+NSPE task. This is an issue only when NSPE has provisions for task isolation.
+Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
+to NS interrupts to the lower half of available priorities so that it wouldn't
+be possible for any non-secure interrupt to preempt a higher-priority secure
+interrupt.
+
+**********************************
+Integration with non-Cmake systems
+**********************************
+
+Generated Files
+===============
+
+Files that are derived from PSA manifests are generated at build-time by cmake.
+For integration with systems that do no use cmake, the files must be generated
+manually.
+
+The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
+arguments will be needed to be provided. Please refer to
+``tfm_parse_manifest_list.py --help`` for more details.
+
+Some variables are used in the template files, these will need to be set in the
+environment before the script will succeed when the script is not run via cmake.
+
+--------------
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst
index 0fa3aae5a6..bd18888870 100644
--- a/docs/introduction/index.rst
+++ b/docs/introduction/index.rst
@@ -3,7 +3,6 @@ Introduction
.. toctree::
:maxdepth: 1
- :caption: Introduction
:glob:
:numbered:
@@ -11,4 +10,4 @@ Introduction
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/introduction/readme.rst b/docs/introduction/readme.rst
index f57996dc85..2c422f6803 100644
--- a/docs/introduction/readme.rst
+++ b/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 `
-has the list of terms and abbreviations.
+refer to ``Trusted Firmware M.`` :doc:`Glossary ` has the list
+of terms and abbreviations.
#######
License
#######
The software is provided under a BSD-3-Clause :doc:`License `.
Contributions to this project are accepted under the same license with developer
-sign-off as described in the :doc:`Contributing Guidelines `.
+sign-off as described in the :doc:`Contributing Guidelines `.
This project contains code from other projects as listed below. The code from
external projects is limited to ``app``, ``bl2``, ``lib`` and ``platform``
@@ -62,10 +62,10 @@ folders. The original license text is included in those source files.
#########################
Release Notes and Process
#########################
-The :doc:`Release Cadence and Process ` provides
+The :doc:`Release Cadence and Process ` provides
release cadence and process information.
-The :doc:`Change Log & Release Notes ` provides details of
+The :doc:`Releases ` provides details of
major features of the release and platforms supported.
###############
@@ -102,11 +102,11 @@ To build & run TF-M:
on running the example.
To port TF-M to a another system or OS, follow the
-:doc:`OS Integration Guide `
+:doc:`OS Integration Guide `
-Please also see the :doc:`glossary ` of terms used in the project.
+Please also see the :doc:`glossary ` of terms used in the project.
-:doc:`Contributing Guidelines ` contains guidance on how to
+:doc:`Contributing Guidelines ` contains guidance on how to
contribute to this project.
Further documents can be found in the ``docs`` folder.
@@ -162,7 +162,7 @@ Platforms supported
- :doc:`Musca-B1 Secure Enclave. `
-The document :doc:`Platform Deprecation and Removal `
+The document :doc:`Platform Deprecation and Removal `
lists the deprecated platforms planned to be removed from upstream.
####################
@@ -195,7 +195,7 @@ Version history
+-------------+--------------+--------------------+-------------------+
Please refer to
-:ref:`docs/contributing/release_process:Release Version Scheme` for interpreting
+:ref:`docs/releases/release_process:Release Version Scheme` for interpreting
version numbers.
.. _Cortex-M33: https://developer.arm.com/ip-products/processors/cortex-m/cortex-m33
diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst
deleted file mode 100644
index 70a3e28166..0000000000
--- a/docs/reference/changelog.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-##########################
-Change Log & Release Notes
-##########################
-
-This document contains a summary of the new features, changes, fixes and known
-issues in each release of Trusted Firmware-M.
-
-.. include:: ../reference/releases/1.3.0.rst
-.. include:: ../reference/releases/1.2.0.rst
-.. include:: ../reference/releases/1.1.rst
-.. include:: ../reference/releases/1.0.rst
-
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst
deleted file mode 100644
index 73e91aa749..0000000000
--- a/docs/reference/glossary.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-###################################
-Glossary of terms and abbreviations
-###################################
-
-************
-TF-M related
-************
-.. glossary::
-
- Application RoT
- Application Root of Trust
- `PSA term`_. The security domain in which additional security services
- are implemented.
-
- HAL
- Hardware Abstraction Layer
- Interface to abstract hardware-oriented operations and provides a set of
- APIs to the upper layers.
-
- RoT
- 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
- `PSA term`_. In TF-M this means non secure domain typically running an
- OS using services provided by TF-M.
-
- PSA
- `PSA term`_. Platform Security Architecture.
-
- PSA-FF
- `PSA term`_. Platform Security Architecture Firmware Framework.
-
- PSA-FF-M
- `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
- The function entry to a secure service. Multiple SFN per SS are
- permitted.
-
- SP : TF-M related
- Secure Partition
- A logical container for secure services.
-
- SPE : TF-M related
- Secure Processing Environment
- `PSA term`_. In TF-M this means the secure domain protected by TF-M.
-
- SPM : TF-M related
- 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
- The TF-M component responsible for Secure Partition runtime
- functionalities.
-
- SPRTL : TF-M related
- Secure Partition Runtime Library
- A library contains the SPRT code and data.
-
- SS : TF-M related
- 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
- Protected Storage
- Protected storage service provided by TF-M.
-
- ITS : TF-M related
- Internal Trusted Storage
- Internal Trusted Storage service provided by TF-M.
-
- TFM
- TF-M
- Trusted Firmware-M
- 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
- 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
- Bus slave-side security controller for memory regions.
-
- PPC : SSE-200 platform
- Peripheral Protection Controller
- Bus slave-side security controller for peripheral access.
-
-************
-v8M-specific
-************
-.. glossary::
-
- S/NS : v8M-specific
- Secure/Non-secure
- The separation provided by TrustZone hardware components in the system.
-
- SAU : v8M-specific
- 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
- 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
- Hardware component providing privilege control.
-
- SVC
- SuperVisor Call
- ARMv7M assembly instruction to call a privileged handler function
-
-*********
-Reference
-*********
-
-| `PSA Firmware_Framework for M`_
-
-.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html
-
-.. _PSA term: `PSA Firmware_Framework for 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: https://pages.arm.com/psa-resources-tbsa-m.html
-
---------------
-
-*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
deleted file mode 100644
index 7e81349982..0000000000
--- a/docs/reference/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-Reference
-=========
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- changelog
- glossary
- security
- */index
- /tools/index
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/1.0.rst b/docs/reference/releases/1.0.rst
deleted file mode 100644
index 48903f5013..0000000000
--- a/docs/reference/releases/1.0.rst
+++ /dev/null
@@ -1,144 +0,0 @@
-***********
-Version 1.0
-***********
-
-New Features
-============
-- First major release.
-
-- A Secure FW with support for PSA Level 1 and 2 isolation on Armv8-M
- using TrustZone extension and Dual-core Cortex-M config.
-
-- The PSA Firmware Framework (PSA FF)/Dev API interfaces exposed by the
- Secure FW to NS side.
-
-- A secure FW model with NS application example.
-
-- Secure services running within this SPE
-
- - Secure Storage Service (PSA Protected Storage API - 1.0.0)
- - Attestation (PSA Attestation API 1.0.0)
- - Crypto Service (PSA API 1.0-beta-3)
- - TF-M Audit Log
- - Platform Service
- - Internal Trusted Storage (PSA API 1.0.0)
-
-- PSA IPC support
-
-- Support for Armv8-M mainline and baseline and Dual-core Cortex-M systems.
-
-- Testcases running baremetal and with RTX to test the functionality.
-
-- BL2 bootloader for image authentication based on SHA256 and RSA-3072
- digital signature.
-
-- Build system based on CMake, supporting ARMCLANG and GNU Arm.
-
-- Support for integrated CryptoCell-312 cryptographic hardware accelerator
- on Musca-B1 platform.
-
-- Meets requirements for Updatable RoT for PSA Functional API, Level 1 and
- Level 2 Certifications in the feature list.
-
-Platforms supported
-===================
-Current release has been tested on:
-
- - Cortex M33 based SSE-200 system:
-
- - `FPGA image loaded on MPS2 board.
- `__
- - `Fast model FVP_MPS2_AEMv8M.
- `__
- - `Musca-A test chip board.
- `__
- - `Musca-B1 test chip board.
- `__
- - `Musca-S1 test chip board.`
- - `FPGA image loaded on MPS3 board.
- `__
- - `Arm DesignStart FPGA on AWS Cloud.
- `__
-
- - Cortex M23 based IoT Kit system:
-
- - `FPGA image loaded on MPS2 board.
- `__
-
-Other supported platforms:
-
- - Dual Core Cortex-M system:
-
- - `Cypress PSoc64.
- `__
-
-Platform Limitations
-====================
-- The PSA Arch Tests need to be split into several binaries to load onto
- Musca-A board because of low memory available to the NS world to use.
-
-- The Regression tests on MPS3 AN524 FPGA takes about 40 minutes to complete.
- This is because AN524 uses QSPI Flash for runtime memory as the RAM is small.
- The slow speed of QSPI device causes the tests to run slowly.
-
-- Warm reset of eFlash is not permitted on Musca-B1 due to HW bug
- https://community.arm.com/developer/tools-software/oss-platforms/w/docs/426/musca-b1-warm-reset-of-eflash
- As TF-M is executed in place from eFlash on Musca-B1, there is good chance
- that a warm reset of the board will have unexpected (even non-deterministic)
- effects on code execution. Hence the PSA Arch FF tests, which rely of warm
- reset of Musca-B1 were executed on RAM FS using "-DSST_RAM_FS=ON" config.
-
-Known issues
-============
-Some open issues exist and will not be fixed in this release.
-
-.. list-table::
-
- * - AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
- cause boot failure. This is known issue for AN521 FVP. This will cause
- the system to not boot after a warm reset during PSA Arch FF testing.
- - Issue : https://developer.trustedfirmware.org/T692
-
- * - PSA Arch Crypto tests have several known failures.
- - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md
-
- * - There are 2 additional failures for PSA-Arch Crypto tests with CC-312
- other than the known failures. This is due to limitation of CC-312
- implementation as it does not support MD_NONE hashing mode causing the
- additional failures.
- - The issue details are captured here : https://developer.trustedfirmware.org/T691
-
- * - PS test case 2002 and 1002 does not fail on Musca-B1 flash when
- run for second time without erasing flash. The WRITE_ONCE assets created
- by SST module should not be updatable but after reboot, the update seems
- to happen and is not expected. This issue will happen on any platform
- using persistent storage for SST.
- - Issue created : https://developer.trustedfirmware.org/T693
-
- * - Boot up fails if there is unexpected data in flash on Musca-A. The boot
- is successful and the tests pass if all the associated (SST/ITS/NV
- Counter) flash areas are erased.
- - Issue created : https://developer.trustedfirmware.org/T694
-
- * - If the flash is not erased, boot fails on Musca-B1 when SST
- is using flash for Minsizerel config.
- - Issue created : https://developer.trustedfirmware.org/T695
-
- * - When SST/ITS are using Flash on Musca-B1, PSA Arch FF test fails due
- to known warm reset limitation in the platform. But after the failure,
- Musca-B1 boot fails to boot. This could be related to general issues of
- the SST module when Flash data is inconsistent.
- - Issue created : https://developer.trustedfirmware.org/T696
-
- * - The eflash driver on Musca-B1 can return random failures hence
- triggering random failures during PSA Arch ITS and PSA Arch PS tests.
- This happens when ITS/SST is configured to use flash.
- - Issue created : https://developer.trustedfirmware.org/T697
-
- * - Release build of PSA Arch Crypto tests have a different number of tests
- when built for AN521 FVP. This is an issue in the PSA Arch Crypto tests.
- - Issue created for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/1.1.rst b/docs/reference/releases/1.1.rst
deleted file mode 100644
index 83c45dfb54..0000000000
--- a/docs/reference/releases/1.1.rst
+++ /dev/null
@@ -1,126 +0,0 @@
-***********
-Version 1.1
-***********
-
-New Features
-============
-
-- Upgraded MCUBoot to v1.6.0., default is now the upstream MCUBoot instead of
- the TF-M fork.
-
-- TF-Fuzz tool for fuzz testing PSA APIs.
-
-- Updated Source code folder structure.
-
-- IAR compiler support.
-
-- LPCXpresso55S69-EVK board support.
-
-- Add Profile Small.
-
-- Enable Ninja CMake Generator.
-
-- FVP_SSE300_MPS2 platform support.
-
-- Rename SST(Secure STorage) to PS(Protected Storage) and partition moved from
- PSA Root of Trust to Application Root of Trust.
-
-- NUCLEO-L552ZE-Q and DISCO-L562QE platform support.
-
-- Restructure documentation to make it more user-friendly.
-
-- Enable Attestation service to use symmetric key algorithm.
-
-- Use CMSIS for testing from
- `tf-m-tests `__
- repository. This removes dependency on the external ``CMSIS_5`` repo.
-
-New Platforms supported
-=======================
-
-- Cortex-M33 based system:
-
- - `LPCXpresso55S69-EVK.
- `__
-
- - `NUCLEO-L552ZE-Q.
- `__
-
- - `DISCO-L562QE.
- `__
-
-- Cortex-M55 based SSE-300 system:
-
- - `Fast model FVP_SSE300_MPS2.
- `__
-
-
-New Platforms limitations
-=========================
-
-- LPCXpresso55S69-EVK doesn't support BL2.
-
-- LPCXpresso55S69-EVK doesn't support ARMCLANG and IARARM toolchain. Patch
- with support for IARARM is available at
- `review.trustedfirmware.org #4023 `__
-
-- FVP_SSE300_MPS2 doesn't support GNUARM and IARARM toolchain. Patch with
- support for IARARM is available at
- `review.trustedfirmware.org #4574 `__
-
-Known issues
-============
-
-Some open issues exist and will not be fixed in this release.
-
-.. list-table::
-
- * - | All the supported GNUARM toolchain versions generate corrupt veneer
- | code for Armv8-M baseline architecture, when the -Os optimization flag
- | is used. This affects the AN519 and AN539 platforms built with GNUARM
- | toolchain and Minsizerel build type.
- - Issue: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646
-
- * - | PSA Arch Crypto tests have several known failures.
- - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md
-
- * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
- | cause boot failure. This is known issue for AN521 FVP. This will cause
- | the system to not boot after a warm reset during PSA Arch FF testing.
- - Issue: https://developer.trustedfirmware.org/T692
-
- * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312
- | other than the known failures. This is due to limitation of CC-312
- | implementation as it does not support MD_NONE hashing mode causing the
- | additional failures.
- - Issue: https://developer.trustedfirmware.org/T691
-
- * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot
- | is successful and the tests pass if all the associated (PS/ITS/NV
- | Counter) flash areas are erased.
- - Issue: https://developer.trustedfirmware.org/T694
-
- * - | When PS/ITS are using Flash on Musca-B1, PSA Arch FF test fails due to
- | known warm reset limitation in the platform. There is an issue with
- | Musca-B1 QSPI flash that causes this failure. The fix is under
- | investigation.
- - Issue: https://developer.trustedfirmware.org/T696
-
-Issues fixed since 1.0
-======================
-
-.. list-table::
-
- * - | The eflash driver on Musca-B1 can return random failures hence
- | triggering random failures during PSA Arch ITS and PSA Arch PS tests.
- | This happens when ITS/SST is configured to use flash.
- - Issue: https://developer.trustedfirmware.org/T697
-
- * - | Release build of PSA Arch Crypto tests have a different number of tests
- | when built for AN521 FVP. This is an issue in the PSA Arch Crypto
- | tests.
- - Issue for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/1.2.0.rst b/docs/reference/releases/1.2.0.rst
deleted file mode 100644
index 1c28632b1e..0000000000
--- a/docs/reference/releases/1.2.0.rst
+++ /dev/null
@@ -1,142 +0,0 @@
-*************
-Version 1.2.0
-*************
-
-New features
-============
-
- - A new build system based on Modern CMake.
- - First implementation of level 3 isolation on Musca-B1 and AN521.
- - Remove MCUBoot fork from TF-M.
- - Move test and app code to tf-m-tests repo.
- - Add Profile Medium.
- - Migrate support to Mbed TLS v2.24.
- - New platforms added.
- See :ref:`docs/reference/releases/1.2.0:New platforms supported` for
- details.
- - New SPM HAL APIs including isolation API and logging API.
- - Update MCUboot version to 1.7.0-rc1.
- - Initial ITS/PS HAL for dynamic filesystem configuration.
- - Remove auto-generated files from the source tree.
-
-New security advisories
-=======================
-
-Stack sealing
--------------
-
-Refer to :doc:`Advisory TFMV-1`
-for more details.
-A common mitigation is included in this release.
-
-New platforms supported
-=======================
-
-- Cortex-M33 based system:
-
- - `Nordic nRF9160 DK (nordic_nrf/nrf9160dk_nrf9160).
- `_
- - `Nordic nRF5340 PDK (nordic_nrf/nrf5340pdk_nrf5340_cpuapp).
- `_
- - `Nordic nRF5340 DK (nordic_nrf/nrf5340dk_nrf5340_cpuapp).
- `_
-
-- Cortex-M23 based system:
-
- - `Nuvoton M2351.
- `_
-
-- Cortex-M55 based system:
-
- - `Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3).
- `_
-
-Tested platforms
-================
-
-The following platforms are successfully tested in this release.
-
- - AN519
- - AN521
- - Musca-B1
- - MPS2 SSE300
- - PSoC 64
- - M2351
- - nrf5340dk
- - nrf5340pdk
- - nrf9160dk
- - LPCXpresso55S69
- - NUCLEO-L552ZE-Q
- - STM32L562E-DK
-
-Known issues
-============
-
-Some open issues exist and will not be fixed in this release.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | PSA Arch Crypto tests have several known failures.
- - See this link for detailed analysis of the failures:
- https://developer.trustedfirmware.org/w/tf_m/release/psa_arch_crypto_test_failure_analysis_in_tf-m_v1.2_release/
-
-Issues fixed since 1.1
-======================
-
-Issues fixed by TF-M since v1.1 are listed below.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | The eflash driver on Musca-B1 can return random failures hence
- | triggering random failures during PSA Arch ITS and PSA Arch PS tests.
- | This happens when ITS/SST is configured to use flash.
- - https://developer.trustedfirmware.org/T697
-
-Issues closed since 1.1
-=======================
-
-The following issues are closed since v1.1. These issues are related to platform
-hardware limitations or 3rd-party tools and therefore won't be fixed by TF-M.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | All the supported GNUARM toolchain versions generate corrupt veneer
- | code for Armv8-M baseline architecture, when the -Os optimization flag
- | is used. This affects the Armv8-M baseline platforms built with GNUARM
- | toolchain and Minsizerel build type.
- | It relies on an official release of GNUARM toolchain to fix this issue.
- - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646
-
- * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
- | cause boot failure. This is a known issue for AN521 FVP. This will
- | cause the system to fail to boot after a warm reset during PSA Arch FF
- | testing.
- - https://developer.trustedfirmware.org/T692
-
- * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312
- | other than the known failures. This is due to limitation of CC-312
- | implementation as it does not support MD_NONE hashing mode causing the
- | additional failures.
- - https://developer.trustedfirmware.org/T691
-
- * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot
- | is successful and the tests pass if all the associated (PS/ITS/NV
- | Counter) flash areas are erased.
- - https://developer.trustedfirmware.org/T694
-
- * - | If the flash is not erased, boot fails on Musca-B1 when SST is using
- | flash for Minsizerel config.
- - https://developer.trustedfirmware.org/T695
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/1.3.0.rst b/docs/reference/releases/1.3.0.rst
deleted file mode 100644
index 80e3dd655b..0000000000
--- a/docs/reference/releases/1.3.0.rst
+++ /dev/null
@@ -1,173 +0,0 @@
-*************
-Version 1.3.0
-*************
-
-New major features
-==================
-
- - Support stateless RoT Service defined in FF-M 1.1 [1]_.
- - Support Second-Level Interrupt Handling (SLIH) defined in FF-M 1.1 [1]_.
- - Add Firmware Update (FWU) secure service, following Platform Security
- Architecture Firmware Update API [2]_.
- - Migrate to Mbed TLS v2.25.0.
- - Update MCUboot version to v1.7.2.
- - Add a TF-M generic threat model [3]_ .
- - Implement Fault Injection Handling library to mitigate physical attacks [4]_.
- - Add Profile Large [5]_.
- - Enable code sharing between boot loader and TF-M [6]_.
- - Support Armv8.1-M Privileged Execute Never (PXN) attribute and Thread
- reentrancy disabled (TRD) feature.
- - New platforms added.
- See :ref:`docs/reference/releases/1.3.0:New platforms supported` for
- details.
- - Add a TF-M security landing page [7]_.
- - Enhance dual-cpu non-secure mailbox reference implementation.
-
-New security advisories
-=======================
-
-Invoking secure functions from non-secure handler mode
-------------------------------------------------------
-
-Refer to :doc:`Advisory TFMV-2`
-for more details.
-The mitigation is included in this release.
-
-New platforms supported
-=======================
-
- - Cortex-M23 based system:
-
- - `Nuvoton M2354.
- `_
-
- - Cortex-M55 based system:
-
- - `FPGA image loaded on MPS3 board (AN547).
- `_
-
- - Secure Enclave system:
-
- - :doc:`Musca-B1 Secure Enclave. `
-
-Deprecated platforms
-====================
-
-The following platforms have been removed from TF-M code base.
-
- - SSE-200_AWS
- - AN539
-
-See :doc:`Platform deprecation and removal `
-for other platforms under deprecation process.
-
-Tested platforms
-================
-
-The following platforms are successfully tested in this release.
-
-- AN519
-- AN521
-- AN524
-- AN547
-- LPCXpresso55S69
-- MPS2 SSE300
-- Musca-B1
-- Musca-B1 Secure Enclave
-- Musca-S1
-- M2351
-- M2354
-- nrf5340dk
-- nrf9160dk
-- NUCLEO-L552ZE-Q
-- PSoC 64
-- STM32L562E-DK
-
-Known issues
-============
-
-Some open issues exist and will not be fixed in this release.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | PSA Arch Crypto test suite have several known failures.
- - See this `link `_
- for detailed analysis of the failures.
-
- * - | Protected Storage Regression test 4001 is stuck on SSE-300 in isolation
- | level 2 when PXN is enabled.
- - https://developer.trustedfirmware.org/T902
-
- * - | IPC Regression test fail when non-secure regression test is enabled and
- | secure regression test is disabled.
- - https://developer.trustedfirmware.org/T903
-
- * - | Panic test in PSA Arch IPC test suite generates inconsistent results
- | between Armclang and GNUARM.
- - https://developer.trustedfirmware.org/T909
-
-Issues fixed since 1.2.0
-========================
-
-Issues fixed by TF-M since v1.2.0 are listed below.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | Dual-cpu NS mailbox initialization shall be executed after CMSIS-RTOS
- | RTX kernel initialization
- - https://developer.trustedfirmware.org/T904
-
-Issues closed since 1.2.0
-=========================
-
-The following issues are closed since v1.2.0. These issues are related to
-platform hardware limitations or 3rd-party tools and therefore won't be fixed by
-TF-M.
-
-.. list-table::
-
- * - **Descriptions**
- - **Issue links**
-
- * - | ``psa_verify_rsa()`` fails when PSA Crypto processes RSASSA-PSS
- | algorithm in CryptoCell-312.
- | Mbed TLS implementation of ``psa_verify_rsa()`` always passes
- | ``MBEDTLS_MD_NONE`` to ``mbedtls_rsa_rsassa_pss_verify()``.
- | However, CryptoCell-312 doesn't support MD5 and uses other algorithms
- | instead. Therefore, Mbed TLS implementation may fail when input
- | algorithm doesn't match other parameters.
- - https://github.com/ARMmbed/mbedtls/issues/3990
-
- * - | Regression tests fail with GNU Arm Embedded toolchain version
- | 10-2020-q4-major.
- | The support for CMSE feature is broken in version 10-2020-q4-major. The
- | fix will be available in future release version.
- | A note is added in :ref:`docs/getting_started/tfm_sw_requirement:C compilers`.
- - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157
-
-Reference
-=========
-
- .. [1] `Arm Firmware Framework for M 1.1 Extensions `_
-
- .. [2] `PSA Firmware Update API `_
-
- .. [3] :doc:`TF-M generic threat model `
-
- .. [4] :doc:`TF-M physical attack mitigation `
-
- .. [5] :doc:`TF-M Profile Large design `
-
- .. [6] :doc:`Code sharing between independently linked XIP binaries `
-
- .. [7] :doc:`Security Handling `
-
---------------
-
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/reference/releases/index.rst b/docs/reference/releases/index.rst
deleted file mode 100644
index dc8aecbcd6..0000000000
--- a/docs/reference/releases/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Releases
-========
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/security.rst b/docs/reference/security.rst
deleted file mode 100644
index 67632a9750..0000000000
--- a/docs/reference/security.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-Security Handling
-=================
-
-Security Disclosures
---------------------
-
-Trusted Firmware-M(TF-M) disclose all security vulnerabilities, or are advised
-about, that are relevant to TF-M. TF-M encourage responsible disclosure of
-vulnerabilities and try the best to inform users about all possible issues.
-
-The TF-M vulnerabilities are disclosed as Security Advisories, all of which are
-listed at the bottom of this page.
-
-Found a Security Issue?
------------------------
-
-Although TF-M try to keep secure, it can only do so with the help of the
-community of developers and security researchers.
-
-.. warning::
- If any security vulnerability was found, please **do not**
- report it in the `issue tracker`_ or on the `mailing list`_. Instead, please
- follow the `TrustedFirmware.org security incident process`_.
-
-One of the goals of this process is to ensure providers of products that use
-TF-M have a chance to consider the implications of the vulnerability and its
-remedy before it is made public. As such, please follow the disclosure plan
-outlined in the `Security Incident Process`_. TF-M do the best to respond and
-fix any issues quickly.
-
-Afterwards, write-up all the findings about the TF-M source code is highly
-encouraged.
-
-Attribution
------------
-
-TF-M values researchers and community members who report vulnerabilities and
-TF-M policy is to credit the contributor's name in the published security advisory.
-
-Security Advisories
--------------------
-
-+------------+-----------------------------------------------------------------+
-| ID | Title |
-+============+=================================================================+
-| |TFMV-1| | NS world may cause the CPU to perform an unexpected return |
-| | operation due to unsealed stacks. |
-+------------+-----------------------------------------------------------------+
-| |TFMV-2| | Invoking Secure functions from handler mode may cause TF-M IPC |
-| | model to behave unexpectedly. |
-+------------+-----------------------------------------------------------------+
-
-.. _issue tracker: https://developer.trustedfirmware.org/project/view/2/
-.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-m
-
-.. |TFMV-1| replace:: :ref:`docs/reference/security_advisories/stack_seal_vulnerability:Advisory TFMV-1`
-.. |TFMV-2| replace:: :ref:`docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability:Advisory TFMV-2`
-
-.. _TrustedFirmware.org security incident process: https://developer.trustedfirmware.org/w/collaboration/security_center/
-
-.. _Security Incident Process: https://developer.trustedfirmware.org/w/collaboration/security_center/reporting/
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/reference/security_advisories/index.rst b/docs/reference/security_advisories/index.rst
deleted file mode 100644
index 85119084e2..0000000000
--- a/docs/reference/security_advisories/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Security Advisories
-===================
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/security_advisories/stack_seal_vulnerability.rst b/docs/reference/security_advisories/stack_seal_vulnerability.rst
deleted file mode 100644
index 2bf9d1a254..0000000000
--- a/docs/reference/security_advisories/stack_seal_vulnerability.rst
+++ /dev/null
@@ -1,113 +0,0 @@
-Advisory TFMV-1
-===============
-
-+----------------+-------------------------------------------------------------+
-| Title | NS world may cause the CPU to perform an unexpected return |
-| | operation due to unsealed stacks. |
-+================+=============================================================+
-| CVE ID | CVE-2020-16273 |
-+----------------+-------------------------------------------------------------+
-| Date | 16 October 2020 |
-+----------------+-------------------------------------------------------------+
-| Versions | All versions up to and including TF-M v1.1 |
-| Affected | |
-+----------------+-------------------------------------------------------------+
-| Configurations | All |
-+----------------+-------------------------------------------------------------+
-| Impact | Most likely a crash in secure world with a very low |
-| | likelihood of hijacking secure world execution flow via a |
-| | separate vulnerability. |
-+----------------+-------------------------------------------------------------+
-| Fix Version | commit `92e46a3abd0e328fac29ccd1cf161cd482397567`_ |
-+----------------+-------------------------------------------------------------+
-| Credit | Matvey Mukha |
-+----------------+-------------------------------------------------------------+
-
-Background
-----------
-
-When the Non-Secure world returns to Secure after a callback (FNC_RETURN) or
-Non-Secure interrupt handling (EXC_RETURN), the hardware pops the secure return
-address and RET_PSR from the respective secure stack. The hardware performs a
-set of integrity checks at this point and will raise a fault if the checks
-fail. There is a potential vulnerability if the NS attempts a wrong FNC_RETURN
-or EXC_RETURN and causes the PE to pop from the unexpected stack. Please
-refer to `ARMv8-M Secure stack sealing advisory notice`_ for more
-details on the vulnerability.
-
-To prevent such an attack, the architecture expects the secure software to
-`seal` the stacks. The `ARMv8-M ARM`_ states that the stack should be sealed
-with the special value, 0xFEF5EDA5 (informative IGJGL).
-
-Both the MSP_S and the PSP_S stacks need to be sealed to mitigate stack
-underflow attacks and this is not done currently in TF-M.
-
-Impact
-------
-
-This section analyses the impact of this vulnerability on the upstream
-TF-M implementation.
-
-All requests coming in from the Non-Secure world uses ARM_LIB_STACK as the
-PSP_S and then switches to MSP_S as part of SPM scheduling. The MSP_S is fully
-unwound when the scheduled partition is executing. All partitions run using
-the PSP_S and this stack can be separate for each partition or be a common
-stack depending on whether TF-M is in library mode or IPC mode. When the
-partition execution using PSP_S switches to non-secure world due to a
-non-secure interrupt or a non-secure callback invocation, the non-secure
-world on return back to secure can use a fake EXC_RETURN or FNC_RETURN
-operation to trigger an MSP_S stack underflow, and the CPU could fetch
-the return PC and PSR from the memory just above MSP_S stack (stack grows
-from higher to lower address).
-
-The memory above MSP_S is the ARM_LIB_STACK (as described by
-tfm_common_s.sct/ld), which because of overlaying or zero initialization
-is most likely to be initialized memory for most platforms. This is the stack
-used to run the initialization code of TF-M and usually there will some
-unused free space in the stack. Any underflow of MSP_S will be into this stack
-and hence is likely to be a deterministic crash given that this memory is
-initialized. In theory, a separate vulnerability that allows an attacker to
-control the memory above MSP_S in concert with this vulnerability could
-enable an attacker to hijack the secure world execution flow but the
-likelihood of that is very low.
-
-Through analysing TF-M specific initialization and execution flow, we have
-not found any scenario in TF-M in which Non-secure world can fake a return
-operation back to secure world and cause underflow of PSP_S.
-
-As described in the white paper, de-privileged interrupt handling is
-also vulnerable to this problem. The Library mode of TF-M uses de-privileged
-interrupt handling and does not allow non-secure interrupt to pre-empt the
-secure interrupt handling. But if the de-privileged handler makes a
-Non-Secure callback then there is a chance that Non-Secure world could
-return back to Secure world via a fake FNC_RETURN. Under certain
-conditions, this can force the CPU to use the 2 words on top of stack as
-return PC and PSR. Sealing the top of MSP_S before switching to PSP_S as
-part of de-privileged interrupt handling mitigates this vulnerability.
-
-The interrupt handling in IPC mode uses PSA signal to signal the partition
-and does not use de-privileged interrupt handling mechanism. The PSA signal
-gets handled by the partition when it is scheduled to run by the SPM. Hence
-during interrupt handling in IPC mode, there is no additional threat caused
-by this vulnerability, compared to regular partition execution.
-
-Conclusion
-----------
-
-Overall, from analysis of upstream TF-M implementation, the severity of this
-vulnerability is low, given that the values popped out from secure stack
-(either via underflow of MSP_S or from top of MSP_S stack in de-privileged
-interrupt handling) cannot be influenced by the Non Secure world. To mitigate
-the risk completely, the fix in TF-M is to follow the recommendation in
-`ARMv8-M ARM`_ which is to seal the base of both handler mode stack (MSP_S)
-and thread stacks (PSP_S) and, in case of library mode, also seal the top
-of MSP_S before handing control over to de-privileged interrupt handler.
-
-
-.. _ARMv8-M ARM: https://developer.arm.com/documentation/ddi0553/latest
-.. _ARMv8-M Secure stack sealing advisory notice: https://developer.arm.com/support/arm-security-updates/armv8-m-stack-sealing
-.. _92e46a3abd0e328fac29ccd1cf161cd482397567: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=92e46a3abd0e328fac29ccd1cf161cd482397567
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst b/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst
deleted file mode 100644
index 4a117243fe..0000000000
--- a/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst
+++ /dev/null
@@ -1,125 +0,0 @@
-Advisory TFMV-2
-===============
-
-+----------------+-------------------------------------------------------------+
-| Title | Invoking Secure functions from handler mode may cause TF-M |
-| | IPC model to behave unexpectedly. |
-+================+=============================================================+
-| CVE ID | CVE-2021-27562 |
-+----------------+-------------------------------------------------------------+
-| Date | Mar 5, 2021 |
-+----------------+-------------------------------------------------------------+
-| Versions | Affected All versions up to and including TF-M v1.2 |
-| Affected | |
-+----------------+-------------------------------------------------------------+
-| Configurations | IPC Model (TFM_PSA_API=ON) on Armv8-M |
-+----------------+-------------------------------------------------------------+
-| Impact | Most likely a crash in secure world or reset whole system, |
-| | with a very low likelihood of overwriting some memory |
-| | contents. |
-+----------------+-------------------------------------------------------------+
-| Fix Version | commit `e212ea1637a66255b44d0e7c19ebe9786ab56ccb`_ |
-+----------------+-------------------------------------------------------------+
-| Credit | Øyvind Rønningstad, |
-| | Senior SW Engineer from Nordic Semiconductor |
-+----------------+-------------------------------------------------------------+
-
-Background
-----------
-
-When a non-secure caller calls the secure function, the execution switches the
-security state via Secure Gateway (SG), then arrived at the TF-M secure entry
-if the SG is successful. After SG, TF-M invokes SVC to SPM at first because SPM
-handles requests from SPE and NSPE in a unified SVC handler. The TF-M SVC
-handler code relies on the 'SPSEL' bit in 'EXC_RETURN' to get the caller stack
-pointer:
-
-.. code-block:: asm
-
- ; Armv8m mainline as the example
- mrs r2, msp ; r2 = msp;
- tst lr, #4 ; EXC_RETURN.SPSEL == ?
- ite eq ; condition preparation
- moveq r0, r2 ; if (EXC_RETURN.SPSEL == 0) r0 = msp;
- movne r0, psp ; if (EXC_RETURN.SPSEL == 1) r0 = psp;
- mov r1, lr ; r1 = EXC_RETURN;
- bl tfm_core_svc_handler ; r0 = sp(context), r1 = EXC_RETURN, r2 = msp
-
-If NSPE calls the secure function in 'Handler mode', the TF-M secure entry runs
-in 'Handler mode' before invoking SVC because PE mode does not change during
-the transition from non-secure state to secure state via the successful SG.
-Main stack pointer (MSP) is always used in 'Handler mode', which is irrelevant
-to the value of SPSEL. However, the code above selects secure process stack
-pointer (PSP_S, S suffix here indicates the security state) for further SVC
-handling based on EXC_RETURN.SPSEL, hence the SVC handler accesses the wrong
-stack for handling the request in the NSPE caller in 'Handler mode' case.
-To prevent this vulnerability, TF-M secure SVC handler should fetch the right
-stack pointer register by checking both the PE mode and SPSEL bit. The handler
-should also prevent callers in non-secure `Handler mode` from calling TF-M
-SVC functionalities. The following section analysis impact of the IPC model.
-Library model is not vulnerable to this attack because it checks the PE mode
-in the TF-M secure entry.
-
-Impact
-------
-
-When the vulnerability is happening, PSP_S is the incorrect stack pointer
-fetched, the impact is decided by the content PSP_S is pointing to. The SVC
-handler gets the SVC number by referencing the memory at the 2 bytes subtracted
-position of member 'Return Address' in the PSP_S pointing context, and uses the
-caller saved registers in the context as parameters for the subsequent
-functions indicated by the SVC number. The PSP_S may point to the bottom
-(higher address) of secure thread stack if there is no ongoing secure function
-call, or it points to a preempted context caused by non-secure preempting
-secure execution.
-When PSP_S is pointing to the stack bottom when this issue happens, the caller
-context is pointing to the underflowed stack of which the top 2 words are stack
-seal, and the rest of the context is unpredictable. These underflowed content
-are ZERO initialized for most platforms, hence when fetching the SVC Number at
-memory address 'Return Address - 2', a 'MemFault' or 'HardFault' would happen.
-Even if a valid SVC number is returned, the stack seal values are part of the
-parameters for the subsequent functions that have parameters, which cannot pass
-the validation for the parameters.
-When PSP_S is pointing to a preempted context, the preempted place can be the
-TF-M secure entry area or internal thread space. If the preemption happens when
-the execution is in the TF-M secure entry area, the PSP_S will point to an NS
-preemption stack frame and hence will fail the context size validation through
-this entry into TF-M SVC Handler. In the other scenario that TF-M internal
-thread is preempted, there is a very remote chance that the exception stack
-frame will contain a context with a valid SVC Number with valid parameters.
-As a summary, the impacts of the vulnerability depend on whether an SVC number
-could be fetched from the incorrect stack and what operation the fetched SVC
-number corresponds to:
-
-- A memory access fault when fetching the SVC number from memory. This fault
- halts the whole system. A reset can recover the system back to normal.
-- The SVC number corresponds to the initialization process in TF-M. SPM
- initialization is called for the second time. This re-initialization process
- will fail and halt the whole system. A reset can recover the system back to
- normal.
-- The SVC number corresponds to the boot data fetching function. If the
- unpredictable data in stack triggers boot data fetching and passes the
- parameter validation under a very rare case, boot data is copied into an
- unpredictable memory address. One note here, the TF-M default boot data has
- no sensitive information.
-- The SVC number corresponds to the log output function. If the unpredictable
- data in stack triggers log output under a very rare case, secure data at
- unpredictable address might be printed out through the log interface.
-- The SVC number corresponds to other valid numbers other than above. The
- system resets because of parameter validation fail.
-
-Conclusion
-----------
-
-Overall, from the analysis of upstream TF-M implementation, the severity of
-this vulnerability is Medium, given that a software crash or system reset
-happen most of the time. The probability for causing secure data leakage via
-log output or tampering of secure memory with boot data is extremely low as the
-TF-M internal thread exception stack frame contents have to pass all the
-validations performed by SPM.
-
-.. _e212ea1637a66255b44d0e7c19ebe9786ab56ccb: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=e212ea1637a66255b44d0e7c19ebe9786ab56ccb
-
---------------
-
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/core_test_services_integration_guide.rst b/docs/reference/services/core_test_services_integration_guide.rst
deleted file mode 100644
index fb34795656..0000000000
--- a/docs/reference/services/core_test_services_integration_guide.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-###########################
-Core Test integration guide
-###########################
-
-************
-Introduction
-************
-
-The core test suites test some of the features of the TF-M core. There are
-multiple services that are used by the core test suites. The services are
-defined in the ``test/test_services`` folder.
-
-Currently there are two test suites, *interactive* and *positive*. The positive
-test suite can be run by building using non-secure regression tests using
-``-DTEST_NS``.
-
-The interactive test suite is only available by setting
-``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is
-enabled.
-
-In order to enable the IRQ test module of the postive testsuite, the non-secure
-regression testsuite must be enabled and ``-DTFM_IRQ_TEST=ON`` must be set.
-
-In order to enable the peripheral access test module of the positive testsuite,
-the non-secure regression testsuite must be enabled and
-``-DTFM_PERIPH_ACCESS_TEST=ON`` must be set.
-
-**************************
-Platform specific features
-**************************
-For certain test cases the core test services rely on platform functionality.
-The required features are:
-
-- Access to LEDs or registers that can be used as scratch registers for
- read/write access tests
-- Get a button state that can be pressed by the user to simulate a secure
- service with an arbitrarily long blocking execution.
-- Access to a timer that is able to interrupt the core running TF-M.
-
-The functionality that have to be implemented by the platform is described in
-``platform/include/tfm_plat_test.h``. For details see the documentation of the
-functions.
-
-It is the responsibility of the platform implementation to ensure that the
-resources needed for the core test services are properly linked to the service.
-This can be achieved by using the
-``TFM_LINK_SET__IN_PARTITION_SECTION(...)`` macros in
-``platform/include/tfm_plat_defs.h``. More details regarding the usage of these
-macros are available in the header file.
-
-It is possible that a platform implementation mocks the implementation of some
-or all of the functions, by returning the values expected by the test cases,
-without actually executing the action expected by the test. A platform can also
-set the corresponding control flag to ``OFF`` to skip a test case. For example,
-A platform can skip peripheral access test case by setting
-``TFM_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file.
-
-******************
-IRQ handling tests
-******************
-
-The IRQ handling test currently tests the following scenarios:
-
-- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``)
-- S code execution is interrupted by a secure IRQ, The handler is not the
- interrupted service (``IRQ_TEST_SCENARIO_2``)
-- S code execution is interrupted by a secure IRQ, The handler is the
- interrupted service (``IRQ_TEST_SCENARIO_3``)
-- S code waits for an interrupt (calling ``psa_wait()``), the handler is in
- the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()``
- returns (``IRQ_TEST_SCENARIO_4``)
-- S code waits for a non-secure interrupt to be triggered
- (``IRQ_TEST_SCENARIO_5``)
-
-The following test services participate in the test execution:
-
-- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ
- handler
-- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the
- IRQ handler
-
-All the test executions are initiated from the NS positive test suite. For each
-scenario the non-secure testcase calls the following secure functions in order:
-
-#. prepare_test_scenario for ``TFM_IRQ_TEST_1``
-#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2``
-#. prepare_test_scenario_ns
-#. execute_test_scenario for ``TFM_IRQ_TEST_1``
-#. execute_test_scenario for ``TFM_SP_CORE_TEST_2``
-#. execute_test_scenario_ns
-
-For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer
-with a convenient init value, and depending on the scenario, one of the
-services, or the NS code enters a busy wait waiting for the timer interrupt to
-be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the
-execute_test_scenario request of the NS code is only replied when the IRQ is
-handled, so no explicit busy wait is required. In all the other cases, handling
-of the irq is signalled to the waiting party by setting a variable in a
-non-secure memory location.
-
-For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for
-it to be triggered
-
-A platform can skip IRQ handling test by setting ``TFM_IRQ_TEST`` to
-``OFF`` in its cmake configuration file.
-
-The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*``
-(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to
-substitute empty string, and are used by the ``tools\generate_breakpoints.py``
-script in the `IRQ testing tool `_.
-
---------------
-
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/index.rst b/docs/reference/services/index.rst
deleted file mode 100644
index 30a2a8a078..0000000000
--- a/docs/reference/services/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Services
-=========
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_attestation_integration_guide.rst b/docs/reference/services/tfm_attestation_integration_guide.rst
deleted file mode 100644
index 2c43ea7bdc..0000000000
--- a/docs/reference/services/tfm_attestation_integration_guide.rst
+++ /dev/null
@@ -1,671 +0,0 @@
-#############################################
-Initial Attestation Service Integration Guide
-#############################################
-
-************
-Introduction
-************
-TF-M Initial Attestation Service allows the application to prove the device
-identity during an authentication process to a verification entity. The initial
-attestation service can create a token on request, which contains a fix set of
-device specific data.
-
-TF-M Initial Attestation Service by default enables asymmetric key algorithm
-based attestation (*asymmetric attestation* for short). Symmetric key algorithm
-based attestation (*symmetric attestation* for short) can be enabled instead by
-selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``.
-
- - In asymmetric attestation, device must contain an attestation key pair,
- which is unique per device. The token is signed with the private part of
- attestation key pair. The public part of the key pair is known by the
- verification entity. The public key is used to verify the token
- authenticity.
- - In symmetric attestation, device should contain a symmetric attestation
- key to generate the authentication tag of token content. The verification
- entity uses the same symmetric key to verify the token authenticity.
-
-The data items in the token used to verify the device integrity and assess its
-trustworthiness. Attestation key provisioning is out of scope for the
-attestation service and is expected to take part during manufacturing of the
-device.
-
-***************************************
-Claims in the initial attestation token
-***************************************
-The initial attestation token is formed of claims. A claim is a data item,
-which is represented in a key - value structure. The following fixed set of
-claims are included in the token:
-
- - **Auth challenge**: Input object from caller. Can be a single nonce from
- server or hash of nonce and attested data. It is intended to provide
- freshness to report and the caller has responsibility to arrange
- this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be
- eventually represented by the EAT standard claim nonce. Until such a
- time as that standard exists, the claim will be represented by a custom
- claim. Value is encoded as byte string.
-
- - **Instance ID**: It represents the unique identifier of the instance.
- In the PSA definition it is:
-
- - a hash of the public attestation key of the instance in asymmetric
- attestation.
- - hashes of the symmetric attestation key of the instance in symmetric
- attestation.
-
- The claim is modeled to be eventually represented by the EAT standard
- claim UEID of type GUID. Until such a time as that standard exists, the
- claim will be represented by a custom claim Value is encoded as byte
- string.
-
- - **Verification service indicator**: Optional, recommended claim. It
- is used by a Relying Party to locate a validation service for the
- token. The value is a text string that can be used to locate the service
- or a URL specifying the address of the service. The claim is modelled to
- be eventually represented by the EAT standard claim origination. Until
- such a time as that standard exists, the claim will be represented by
- a custom claim. Value is encoded as text string.
-
- - **Profile definition**: Optional, recommended claim. It contains the
- name of a document that describes the 'profile' of the token, being
- a full description of the claims, their usage, verification and token
- signing. The document name may include versioning. Custom claim with a
- value encoded as text string.
-
- - **Implementation ID**: Uniquely identifies the underlying immutable PSA
- RoT. A verification service can use this claim to locate the details of
- the verification process. Such details include the implementation's origin
- and associated certification state. Custom claim with a value encoded as
- byte string.
-
- - **Client ID**: The partition ID of that secure partition or non-secure
- thread who called the initial attestation API. Custom claim with a value
- encoded as a `signed` integer. Negative number represents non-secure
- caller, positive numbers represents secure callers, zero is invalid.
-
- - **Security lifecycle**: It represents the current lifecycle state of
- the instance. Custom claim with a value encoded as an integer.
-
- - **Hardware version**: Optional claim. Globally unique number in EAN-13
- format identifying the GDSII that went to fabrication, HW and ROM. It can
- be used to reference the security level of the PSA-ROT via a certification
- website. Custom claim with a value is encoded as text string.
-
- - **Boot seed**: It represents a random value created at system boot
- time that will allow differentiation of reports from different system
- sessions. The size is 32 bytes. Custom claim with a value is encoded as
- byte string.
-
- - **Software components**: Optional, but required in order to be compliant
- with the PSA-SM. It represents the software state of the system. The value
- of the claim is an array of CBOR map entries, with one entry per software
- component within the device. Each map contains multiple claims that
- describe evidence about the details of the software component.
-
- - **No software measurements**: Optional, but required if no software
- component claims are made. In the event that the implementation does not
- contain any software measurements then it is mandatory to include this
- claim to indicate this is a deliberate state. Custom claim with a value
- encoded as an unsigned integer set to 1.
-
-Each software component claim can include the following properties. Any property
-that is not optional must be included:
-
- - **Measurement type**: Optional claim. It represents the role of the
- software component. Value is encoded as short(!) text string.
-
- - **Measurement value**: It represents a hash of the invariant software
- component in memory at start-up time. The value must be a cryptographic
- hash of 256 bits or stronger. Value is encoded as byte string.
-
- - **Version**: Optional claim. It represents the issued software
- version. Value is encoded as text string.
-
- - **Signer ID**: Optional claim, but required in order to be compliant with
- the PSA-SM. It represents the hash of a signing authority public key.
- Value is encoded as byte string.
-
- - **Measurement description**: Optional claim. It represents the way in
- which the measurement value of the software component is computed. Value
- is encoded as text string containing an abbreviated description (name)
- of the measurement method.
-
-*********************************************
-Initial attestation token (IAT) data encoding
-*********************************************
-The initial attestation token is planned to be aligned with future version of
-`Entity Attestation Token `__
-format. The token is encoded according to the
-`CBOR `__ format and signed according to
-`COSE `__ standard.
-
-**************
-Code structure
-**************
-The PSA interface for the Initial Attestation Service is located in
-``interface/include``. The only header to be included by applications that want
-to use functions from the PSA API is ``psa/initial_attestation.h``.
-
-The TF-M Initial Attestation Service source files are located in
-``secure_fw/partitions/initial_attestation``.
-The CBOR library is located in ``lib/ext/qcbor`` folder.
-
-Service source files
-====================
-- CBOR library
- - ``lib/ext/qcbor`` This library is used to create a proper CBOR token.
- It can be used on 32-bit and 64-bit machines. It was designed to suite
- constrained devices with low memory usage and without dynamic memory
- allocation.
- It is a fork of this external `QCBOR library `__.
- - ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR
- library.
-
-- COSE library:
- - ``lib/ext/t_cose``: This library is used to sign a CBOR token and create
- the COSE header and signature around the initial attestation token. Only
- a subset of the `COSE `__ standard
- is implemented. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork)
- signature schemas are supported.
- - It is a fork of this external `t_cose library `__.
- - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose``
- library with available crypto library in the device.
- - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the
- exposed API and ports ``t_cose`` to the PSA Crypto API.
-- Initial Attestation Service:
- - ``attest_core.c`` : Implements core functionalities such as implementation
- of APIs, retrieval of claims and token creation.
- - ``attest_token_encode.c``: Implements the token creation functions such as
- start and finish token creation and adding claims to the token.
- - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from
- platform layer and register it to the TF-M Crypto service for further
- usage.
- - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the
- attestation service to the SPM implementation in TF-M project.
- - ``tfm_attest_secure_api.c``: Implements the secure API layer to allow
- other services in the secure domain to request functionalities
- from the attestation service using the PSA API interface.
- - ``tfm_attest_req_mngr.c``: Includes the initialization entry of
- attestation service and handles attestation service requests in IPC
- model.
- - ``attest_symmetric_key.c``: Get the symmetric initial attestation key
- from platform layer and register it into TF-M Crypto service for further
- usage. Also calculate the Instance ID value based on symmetric initial
- attestation key.
-
-Service interface definitions
-=============================
-- **Boot loader interface**: The attestation service might include data
- in the token about the distinct software components in the device. This data
- is provided by the boot loader and must be encoded in the TLV format,
- definition is described below in the boot loader interface paragraph. Possible
- claims in the boot status are describe above in the software components
- paragraph.
-- **Hardware abstraction layer**:
- - Headers are located in ``platform/include`` folder.
- - ``tfm_attest_hal.h``: Expose an API to get the following claims:
- security lifecycle, verification service indicator, profile definition.
- - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim.
- - ``tfm_plat_device_id.h``: Expose an API to get the following claims:
- implementation ID, hardware version.
-- **SPM interface**:
- - ``attestation.h``: Expose an API to bind attestation service to an SPM
- implementation.
-- **PSA interface**:
- - ``psa/initial_attestation.h``: Public API definition of initial
- attestation service.
-- **Crypto interface**:
- - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation
- to any cryptographic library.
- - ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from
- platform layer.
-
-PSA interface
-=============
-The TF-M Initial Attestation Service exposes the following PSA
-interface:
-
-.. code-block:: c
-
- psa_status_t
- psa_initial_attest_get_token(const uint8_t *auth_challenge,
- size_t challenge_size,
- uint8_t *token_buf,
- size_t token_buf_size,
- size_t *token_size);
-
- psa_status_t
- psa_initial_attest_get_token_size(size_t challenge_size,
- size_t *token_size);
-
- psa_status_t
- tfm_initial_attest_get_public_key(uint8_t *public_key,
- size_t public_key_buf_size,
- size_t *public_key_len,
- psa_ecc_family_t *elliptic_curve_type);
-
-The caller must allocate a large enough buffer, where the token is going to be
-created by Initial Attestation Service. The size of the created token is highly
-dependent on the number of software components in the system and the provided
-attributes of these. The ``psa_initial_attest_get_token_size()`` function can be
-called to get the exact size of the created token.
-
-System integrators might need to port these interfaces to a custom secure
-partition manager implementation (SPM). Implementations in TF-M project can be
-found here:
-
-- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface
- implementation for library model
-- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface
- implementation for IPC model
-- ``secure_fw/partitions/initial_attestation/tfm_attestation_secure_api.c``:
- secure interface implementation
-
-Secure Partition Manager (SPM) interface
-========================================
-The Initial Attestation Service defines the following interface towards the
-secure partition manager (SPM). System integrators **must** port this interface
-according to their SPM implementation.
-
-.. code:: c
-
- enum psa_attest_err_t
- attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len);
-
- enum psa_attest_err_t
- attest_get_caller_client_id(int32_t *caller_id);
-
-- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared
- memory area between boot loader and runtime software. It might be the case
- that only SPM has direct access to the shared memory area, therefore this
- function can be used to copy the service related data from shared memory to
- a local memory buffer. In TF-M implementation this function must be called
- during service initialization phase, because the shared memory region is
- deliberately overlapping with secure main stack to spare some memory and reuse
- this area during execution. If boot loader is not available in the system to
- provide attributes of software components then this function must be
- implemented in a way that just initialize service's memory buffer to:
-
- .. code-block:: c
-
- struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr;
- tlv_header->tlv_magic = 2016;
- tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header);
-
-- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread.
-- ``tfm_client.h``: Service relies on the following external definitions, which
- must be present or included in this header file:
-
- .. code-block:: c
-
- typedef struct psa_invec {
- const void *base;
- size_t len;
- } psa_invec;
-
- typedef struct psa_outvec {
- void *base;
- size_t len;
- } psa_outvec;
-
-Hardware abstraction layer
-==========================
-The following API definitions are intended to retrieve the platform specific
-claims. System integrators **must** implement these interface according to their
-SoC and software design. Detailed definition of the claims are above
-in the claims in the initial attestation token paragraph.
-
-- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the
- device.
-- ``tfm_attest_hal_get_verification_service()``: Get the verification
- service indicator for initial attestation.
-- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile
- definition document for initial attestation.
-- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random
- number during a boot cycle.
-- ``tfm_plat_get_implementation_id``: Get the implementation ID of the
- device.
-- ``tfm_plat_get_hw_version``: Get the hardware version of the device.
-
-Boot loader interface
-=====================
-It is **recommended** to have a secure boot loader in the boot chain, which is
-capable of measuring the runtime firmware components (calculates the hash value
-of firmware images) and provide other attributes of these (version, type, etc).
-If the used boot loader is not capable of sharing these information with the
-runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be
-set to OFF (see `Related compile time options`_).
-
-The shared data between boot loader and runtime software is TLV encoded. The
-definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``.
-The shared data is stored in a well known location in secure internal memory
-and this is a contract between boot loader and runtime SW.
-
-The structure of shared data must be the following:
-
-- At the beginning there must be a header: ``struct shared_data_tlv_header``
- This contains a magic number and a size field which covers the entire size
- of the shared data area including this header.
-
- .. code-block:: c
-
- struct shared_data_tlv_header {
- uint16_t tlv_magic;
- uint16_t tlv_tot_len;
- };
-
-- After the header there come the entries which are composed from an
- entry header structure: ``struct shared_data_tlv_entry`` and the data. In
- the entry header is a type field ``tlv_type`` which identify the consumer of
- the entry in the runtime software and specify the subtype of that data item.
-
- .. Note::
-
- There is a size field ``tlv_len`` which has different definitions in the
- upstream MCUboot repository and in its TF-M forked version:
-
- - Upstream MCUboot: Covers only the length of data but not the header
- size.
- - TF-M MCUboot: Covers the size of the entry header and the data
- together.
-
- This difference is handled by TF-M code based on which bootloader is used
- along with TF-M runtime.
-
- After the entry header structure comes the actual data.
-
- .. code-block:: c
-
- struct shared_data_tlv_entry {
- uint16_t tlv_type;
- uint16_t tlv_len;
- };
-
-- Arbitrary number and size of data entry can be in the shared memory
- area.
-
-The figure below gives of overview about the ``tlv_type`` field in the entry
-header. The ``tlv_type`` always composed from a major and minorbnumber. Major
-number identifies the addressee in runtime software, which the databentry is
-sent to. Minor number used to encode more info about the data entry. The actual
-definition of minor number could change per major number. In case of boot
-status data, which is going to be processed by initial attestation service
-the minor number is split further to two part: ``sw_module`` and ``claim``. The
-``sw_module`` identifies the SW component in the system which the data item
-belongs to and the ``claim`` part identifies the exact type of the data.
-
-``tlv_type`` description::
-
- |------------------------------------------------ |
- | tlv_type (16 bits) |
- |-------------------------------------------------|
- | tlv_major(4 bits) | tlv_minor(12 bits) |
- |-------------------------------------------------|
- | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) |
- |-------------------------------------------------|
- | MAJOR_CORE | TBD |
- |-------------------------------------------------|
-
-Overall structure of shared data::
-
- ---------------------------------------------------------------
- | Magic number(uint16_t) | Shared data total length(uint16_t) |
- ---------------------------------------------------------------
- | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
- ---------------------------------------------------------------
- | Raw data |
- ---------------------------------------------------------------
- | . |
- | . |
- | . |
- ---------------------------------------------------------------
- | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) |
- ---------------------------------------------------------------
- | Raw data |
- ---------------------------------------------------------------
-
-Crypto interface
-================
-
-Asymmetric key algorithm based attestation
-------------------------------------------
-Device **must** contain an asymmetric key pair. The private part of it is used
-to sign the initial attestation token. Current implementation supports only the
-ECDSA P256 signature over SHA256. The public part of the key pair is used to
-create the key identifier (kid) in the unprotected part of the COSE header. The
-kid is used by verification entity to look up the corresponding public key to
-verify the signature in the token. The `t_cose` part of the initial attestation
-service implements the signature generation and kid creation. But the actual
-calculation of token's hash and signature is done by the Crypto service in the
-device. System integrators might need to re-implement the following functions
-if they want to use initial attestation service with a different cryptographic
-library than Crypto service:
-
-- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value.
-- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key
- identifier.
-- ``t_cose_crypto_hash_start()``: Start a multipart hash operation.
-- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash
- operation.
-- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a
- message.
-
-Interface needed by verification code:
-
-- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value.
-
-Key handling
-^^^^^^^^^^^^
-The provisioning of the initial attestation key is out of scope of the service
-and this document. It is assumed that device maker provisions the unique
-asymmetric key pair during the manufacturing process. The following API is
-defined to retrieve the attestation key pair from platform layer. Software
-integrators **must** port this interface according to their SoC design and make
-sure that key pair is available by Crypto service:
-
-- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key
- pair from platform layer.
-
-In TF-M project the attestation key is retrieved by initial attestation service.
-The key is registered and unregistered to the Crypto service by attestation
-service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for
-further usage. See in ``attestation_key.c``. In other implementation if the
-attestation key is directly retrieved by the Crypto service then this key
-handling is not necessary.
-
-Symmetric key algorithm based attestation
------------------------------------------
-Device **must** contain a symmetric key to generate the authentication tag of
-the initial attestation token. A key identifier (kid) can be encoded in the
-unprotected part of the COSE header. It helps verification entity look up the
-symmetric key to verify the authentication tag in the token.
-
-The `t_cose` part of the initial attestation service implements the
-authentication tag generation. The authentication tag generation is done by the
-Crypto service. System integrators might need to re-implement the following
-functions if platforms provide a different cryptographic library than Crypto
-service:
-
-- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation
- operation.
-- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC
- operation.
-- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a
- message.
-
-Interface needed by verification code:
-
-- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification
- operation.
-- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of
- a message.
-
-It also requires the same hash operations as listed in asymmetric key algorithm
-based initial attestation above, in attestation test cases.
-
-Key handling
-^^^^^^^^^^^^
-The provisioning of the initial attestation key is out of scope of the service
-and this document. It is assumed that device maker provisions the symmetric key
-during the manufacturing process. The following API is defined to retrieve the
-symmetric attestation key from platform layer. Software integrators **must**
-port this interface according to their SoC design and make sure that key is
-available by Crypto service:
-
-- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key
- raw data.
-- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric
- initial attestation key. The key identifier can be used as ``kid`` parameter
- in COSE header. Optional.
-
-.. note:
-
- Asymmetric initial attestation and symmetric initial attestation may share
- the same HAL APIs in future development.
-
-Initial Attestation Service compile time options
-================================================
-There is a defined set of flags that can be used to compile in/out certain
-service features. The ``CommonConfig.cmake`` file sets the default values of
-those flags. The list of flags are:
-
-- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the
- attestation token. Default value: ON.
-- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from
- attestation test suite if it is OFF. Its default value depends on the build
- type. It is ON if build type is ``Debug``, otherwise OFF (different kinds
- of ``Release`` builds).
-- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE
- unprotected header. Key-id is calculated and added to the COSE header based
- on the value of this flag. Default value: OFF.
-- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded
- values found in ``platform/ext/common/template/attest_hal.c``. Default value
- is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet
- properly ported to it.
-- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation.
- Default value: OFF.
-
-Related compile time options
-----------------------------
-- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared
- data area between the boot loader and the runtime firmware when it's ON.
- Otherwise, when it's OFF does not check the content of the shared data area.
- Also assume that the TLV header is present and valid (the magic number is
- correct) and there are no other data entries. Its default value depends on
- the BL2 flag.
-
-***************************************************************************
-Comparison of asymmetric and symmetric algorithm based token authentication
-***************************************************************************
-The symmetric key based authentication requires a more complex infrastructure
-for key management. Symmetric keys must be kept secret because they are
-sensitive asset, like the private key in case of asymmetric cryptographic
-algorithms. The main difference is that private keys are only stored on
-device, with proper hardware protection against external access, but symmetric
-keys must be known by both party (device and verifier), so they must also be
-stored in a central server of a relying party (who verifies the tokens).
-If keys are revealed then devices can be impersonated. If the database with
-the symmetric keys becomes compromised then all corresponding devices become
-untrusted. Since a centralised database of symmetric keys may need to be network
-connected, this can be considered to be a valuable target for attackers. The
-advantage of ECDSA based token authentication is that sensitive assets is only
-stored one place (in the device) and only one unique key per device. So if a
-device is compromised then only that single device become untrusted. In this
-case, the database of the relying party contains the corresponding public keys,
-which are not considered to be a confidential assets, so they can be shared with
-anybody. This shows the main advantage of asymmetric based authentication,
-because verification of attestation tokens can be done by a third party,
-such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM)
-does not need to operate such a service.
-
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| | Symmetric | Asymmetric |
-+=========================+=========================================+=========================================+
-| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) |
-| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) |
-| | | - tfm_initial_attest_get_public_key(..) |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| Secrets are stored | Device and database | Device only |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| Verification database | Same symmetric key | Public keys |
-| contains | | |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| COSE authentication tag | COSE_Mac0 | COSE_Sign1 |
-| in the token | | |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning|
-| | symmetric key | service, cloud service provider, CM, DM |
-+-------------------------+-----------------------------------------+-----------------------------------------+
-
-************
-Verification
-************
-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. When the user builds TF-M with any of the
-``ConfigRegression*.cmake`` configurations then this test is executed
-automatically. 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):
-
- - Requirements of presence: optional or mandatory
- - Expected value: Value check can be disabled or expected value can be provided
- here.
-
-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
-that user has license for DS-5 and FVP models:
-
- - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
- for MPS2 AN521 platform. More info in
- :doc:`tfm_build_instruction `.
- - Lunch FVP model in DS-5. More info in
- :doc:`tfm_user_guide `.
- - Set a breakpoint in ``test/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:
-
- - For asymmetric initial attestation, the console prints
- ``ECDSA signature test of attest token``.
- - For symmetric initial attestation, the console prints
- ``Symmetric key algorithm based Initial Attestation test``.
-
- - At this point the token resides in the model memory and can be dumped to host
- computer.
- - The ADDRESS and SIZE attributes of the initial attestation token is stored in
- the ``completed_token`` local variable. Their value can be extracted in the
- ``(x)=Variables`` debug window.
- - Apply commands below in the ``Commands`` debug window to dump the token in
- binary format to the host computer:
-
- - For asymmetric initial attestation
- ``dump memory /iat_01.cbor +``
- - For symmetric initial attestation
- ``dump memory /iat_hmac_02.cbor +``
-
- - Execute commands below on the host computer to verify the token:
-
- - For asymmetric initial attestation
- ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem /iat_01.cbor``
- - For symmetric initial attestation
- ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key /iat_hmac_02.cbor``
-
- - Documentation of the iat-verifier can be found
- :doc:`here `.
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_audit_integration_guide.rst b/docs/reference/services/tfm_audit_integration_guide.rst
deleted file mode 100644
index 248f0f9fb1..0000000000
--- a/docs/reference/services/tfm_audit_integration_guide.rst
+++ /dev/null
@@ -1,134 +0,0 @@
-#######################################
-Audit Logging Service Integration Guide
-#######################################
-
-************
-Introduction
-************
-TF-M Audit logging service allows secure services in the system to log critical
-system events and information that have security implications. This is required
-to post analyse the system behaviour, system events and triage system issues
-offline. This offers a mitigation against the repudiation threat.
-
-The types of information that can be logged are the ID of the entity that
-originated a secure service request, or the relevant output or data
-associated to the authentication mechanism that the requesting service
-has performed on the entity that originated the request. The possible types of
-information that can be logged can be easily extended to accommodate various
-requirements from other secure services.
-
-***************************
-Current service limitations
-***************************
-
-- **Policy manager** - Currently, there is no policy manager implemented, which
- means that there are no restrictions on the entities which can add or remove
- items from the log. Also, the item replacement in the log is just replacing
- older elements first.
-
-- **Encryption** - Support for encryption and authentication is not available
- yet.
-
-- **Permanent storage** - Currently the Audit Logging service supports only a
- RAM based storage of the log, permanent storage is not supported yet.
-
-
-**************
-Code structure
-**************
-The PSA interfaces for the Audit logging service are located in
-``interface/include``.
-
-The TF-M Audit logging service source files are located in
-``secure_fw/partitions/audit_logging``.
-
-PSA interfaces
-==============
-The TF-M Audit logging service exposes the following PSA interfaces:
-
-.. code-block:: c
-
- enum psa_audit_err psa_audit_retrieve_record(const uint32_t record_index,
- const uint32_t buffer_size, const uint8_t *token, const uint32_t token_size,
- uint8_t *buffer, uint32_t *record_size);
-
- enum psa_audit_err psa_audit_get_info(uint32_t *num_records, uint32_t
- *size);
-
- enum psa_audit_err psa_audit_get_record_info(const uint32_t record_index,
- uint32_t *size);
-
- enum psa_audit_err psa_audit_delete_record(const uint32_t record_index,
- const uint8_t *token, const uint32_t token_size);
-
-The TF-M Audit logging service exposes an additional PSA interface which can
-only be called from secure services:
-
-.. code-block:: c
-
- enum psa_audit_err psa_audit_add_record(const struct psa_audit_record
- *record);
-
-Service source files
-====================
-
-- ``audit_core.c`` : This file implements core functionalities such as log
- management, record addition and deletion and extraction of record information.
-- ``audit_wrappers.c`` : This file implements TF-M compatible wrappers in case
- they are needed by the functions exported by the core.
-
-*********************************
-Audit logging service integration
-*********************************
-In this section, a brief description of each field of a log record is given,
-with an example on how to perform a logging request from a secure service.
-The secure service that requests the addition of a record to the log has to
-provide data as described by the ``psa_audit_record`` type, defined in
-``interface\include\psa_audit_defs.h``:
-
-.. code-block:: c
-
- /*!
- * \struct psa_audit_record
- *
- * \brief This structure contains the record that is added to the audit log
- * by the requesting secure service
- */
- struct psa_audit_record {
- uint32_t size; /*!< Size in bytes of the id and payload fields */
- uint32_t id; /*!< ID of the record */
- uint8_t payload[]; /*!< Flexible array member for payload */
- };
-
-Each field is described as follows:
-
-- ``size`` - This is the size, in bytes, of the ``id`` and ``payload[]`` fields
- that follow. Given that the ``payload[]`` field is optional, in the current
- implementation the minimum value to be provided in ``size`` is 4 bytes;
-- ``id`` - This field is meant to be used to store an ID of the log record from
- the requesting service
-- ``payload[]`` - The payload is an optional content which can be made
- of one or more Type-Length-Value entries as described by the following type:
-
-.. code-block:: c
-
- /*!
- * \struct audit_tlv_entry
- *
- * \brief TLV entry structure with a flexible
- * array member
- */
- struct audit_tlv_entry {
- enum audit_tlv_type type;
- uint32_t length;
- uint8_t value[];
- };
-
-The possible TLV types described by ``enum audit_tlv_type`` can be extended by
-system integrators modifying ``audit_core.h`` as needed. A logging request is
-performed by a secure service which calls the
-Secure-only API function ``psa_audit_add_record()``.
-
---------------
-
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_crypto_integration_guide.rst b/docs/reference/services/tfm_crypto_integration_guide.rst
deleted file mode 100644
index a124bdf491..0000000000
--- a/docs/reference/services/tfm_crypto_integration_guide.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-################################
-Crypto Service Integration Guide
-################################
-
-************
-Introduction
-************
-TF-M Crypto service allows application to use cryptography primitives such as
-symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
-authenticated encryption with associated data (AEAD).
-
-**************
-Code structure
-**************
-The PSA interfaces for the Crypto service are located in ``interface/include``.
-The only header to be included by applications that want to use functions from
-the PSA API is ``psa/crypto.h``.
-The TF-M Crypto service source files are located in
-``secure_fw/partitions/crypto``.
-
-PSA interfaces
-==============
-The TF-M Crypto service exposes the PSA interfaces detailed in the header
-``psa/crypto.h``. This header, in turn, includes several other headers which
-are not meant to be included directly by user applications. For a detailed
-description of the PSA API interface, please refer to the comments in the
-``psa/crypto.h`` header itself.
-
-Service source files
-====================
-- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
- operations
-- ``crypto_hash.c`` : This module handles requests for hashing operations
-- ``crypto_mac.c`` : This module handles requests for MAC operations
-- ``crypto_aead.c`` : This module handles requests for AEAD operations
-- ``crypto_key_derivation.c`` : This module handles requests for key derivation
- related operations
-- ``crypto_key.c`` : This module handles requests for key related operations
-- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
- cryptographic operations
-- ``crypto_init.c`` : This module provides basic functions to initialise the
- secure service during TF-M boot. When the service is built for IPC mode
- compatibility, this layer handles as well the connection requests and the
- proper dispatching of requests to the corresponding functions, and it holds
- the internal buffer used to allocate temporarily the IOVECs needed. The size
- of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define.
- This module also provides a static buffer which is used by the Mbed Crypto
- library for its own allocations. The size of this buffer is controlled by
- the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define
-- ``crypto_alloc.c`` : This module is required for the allocation and release of
- crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``,
- defined in this file, determines how many concurrent contexts are supported
- for multipart operations (8 for the current implementation). For multipart
- cipher/hash/MAC/generator operations, a context is associated to the handle
- provided during the setup phase, and is explicitly cleared only following a
- termination or an abort
-- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API
- client interface exposed to the Secure Processing Environment
-- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
- implements the PSA Crypto API client interface exposed to the Non-Secure
- Processing Environment.
-- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
- Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
- Small by default.
-
-****************************
-Crypto Backend configuration
-****************************
-
-The Crypto service can use either a hardware crypto accelerator backend like
-CC-312 or a software crypto library which by default is MbedTLS.
-
-If using MbedTLS as backend, then the library configuration is supplied using
-the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option.
-
-Platforms can specify an extra config file by setting the
-``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
-around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform
-configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with
-config changes due to TFM Profile.
-
-.. Note::
-
- The default entropy source configured for MbedTLS is
- MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness
- for production devices. It is required for production devices to select
- either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or
- provision a unique seed for the device during production and use the
- MBEDTLS_ENTROPY_NV_SEED option.
-
-**************************
-Crypto service integration
-**************************
-In this section, a brief description of the required flow of operation for the
-functionalities exported by the PSA Crypto interface is given, with particular
-focus on the TF-M Crypto service specific operations. For the details of the
-generic PSA Crypto interface operations, please refer directly to the header
-``psa/crypto.h``.
-
-Most of the PSA Crypto multipart APIs require an operation context to be
-allocated by the application and then to be passed as a pointer during the
-following API calls. These operation contexts are of four main types described
-below:
-
-- ``psa_key_derivation_operation_t`` - Operation context for key derivation
-- ``psa_hash_operation_t`` - Operation context for multipart hash operations
-- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
-- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
-
-The user applications are not allowed to make any assumption about the original
-types behind these typedefs, which are defined inside ``psa/crypto.h``.
-In the scope of the TF-M Crypto service, these types are regarded as handles to
-the corresponding implementation defined structures which are stored in the
-Secure world.
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_its_integration_guide.rst b/docs/reference/services/tfm_its_integration_guide.rst
deleted file mode 100644
index 6082e7369c..0000000000
--- a/docs/reference/services/tfm_its_integration_guide.rst
+++ /dev/null
@@ -1,318 +0,0 @@
-#######################################################
-TF-M Internal Trusted Storage Service Integration Guide
-#######################################################
-
-************
-Introduction
-************
-TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted
-Storage APIs.
-
-The service is backed by hardware isolation of the flash access domain and
-relies on hardware to isolate the flash area from access by the Non-secure
-Processing Environment, as well as the Application Root of Trust at higher
-levels of isolation.
-
-The current ITS service design relies on hardware abstraction provided by TF-M.
-The ITS service provides a non-hierarchical storage model, as a filesystem,
-where all the assets are managed by a linearly indexed list of metadata.
-
-The design addresses the following high level requirements as well:
-
-- **Confidentiality** - Resistance to unauthorised accesses through
- hardware/software attacks. Assumed to be provided by the internal flash
- device, backed by hardware isolation.
-
-- **Access Authentication** - Mechanism to establish requester's identity (a
- non-secure entity, secure entity, or a remote server).
-
-- **Integrity** - Resistance to tampering by attackers with physical access is
- assumed to be provided by the internal flash device itself, while resistance
- to tampering by Non-secure or App RoT attackers also requires hardware
- isolation.
-
-- **Reliability** - Resistance to power failure scenarios and incomplete write
- cycles.
-
-- **Configurability** - High level of configurability to scale up/down memory
- footprint to cater for a variety of devices with varying requirements.
-
-- **Performance** - Optimized to be used for resource constrained devices with
- very small silicon footprint, the PPA (power, performance, area) should be
- optimal.
-
-*******************************
-Current ITS 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. 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
- metadata in blocks which are always stored in the same flash location. That
- increases the number of writes in a specific flash location as every change in
- the storage area requires a metadata update.
-
-- **Protection against physical storage medium failure** - Complete handling of
- inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
- is not supported by the current design.
-
-- **Lifecycle management** - Currently, it does not support any subscription
- based keys and certificates required in a secure lifecycle management. Hence,
- an asset's validity time-stamp can not be invalidated based on the system
- time.
-
-- **Provisioning vs user/device data** - In the current design, all assets are
- treated in the same manner. In an alternative design, it may be required to
- create separate partitions for provisioning content and user/device generated
- content. This is to allow safe update of provisioning data during firmware
- updates without the need to wipe out the user/device generated data.
-
-**************
-Code Structure
-**************
-TF-M Internal Trusted Storage service code is located in
-``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows:
-
- - Core files
- - Flash filesystem interfaces
- - Flash interfaces
-
-The PSA ITS interfaces for the TF-M ITS service are located in
-``interface/include/psa``.
-
-PSA Internal Trusted Storage Interfaces
-=======================================
-
-The TF-M ITS service exposes the following mandatory PSA ITS interfaces
-version 1.0:
-
-.. code-block:: c
-
- psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
- psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
- psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
- psa_status_t psa_its_remove(psa_storage_uid_t uid);
-
-These PSA ITS interfaces and TF-M ITS types are defined and documented in
-``interface/include/psa/storage_common.h``,
-``interface/include/psa/internal_trusted_storage.h``, and
-``interface/include/tfm_its_defs.h``
-
-Core Files
-==========
-- ``tfm_its_req_mngr.c`` - Contains the ITS request manager implementation which
- handles all requests which arrive to the service. This layer extracts the
- arguments from the input and output vectors, and it calls the internal trusted
- storage layer with the provided parameters.
-
-- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted
- storage API implementations which are the entry points to the ITS service.
- Constructs a filesystem configuration using information from the ITS HAL,
- allocates a filesystem context for ITS and makes appropriate FS calls. Also
- handles requests from the PS partition with a separate FS config and context.
-
-- ``its_utils.c`` - Contains common and basic functionalities used across the
- ITS service code.
-
-Flash Filesystem Interface
-==========================
-- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used
- by the internal trusted storage service. The purpose of this abstraction is to
- have the ability to plug-in other filesystems or filesystem proxies
- (supplicant).
-
-- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for
- the required interfaces.
-
-- ``flash_fs/its_flash_fs_mblock.c`` - Contains the metadata block manipulation
- functions required to implement the ``its_flash_fs`` interfaces in
- ``flash_fs/its_flash_fs.c``.
-
-- ``flash_fs/its_flash_fs_dblock.c`` - Contains the data block manipulation
- functions required to implement the ``its_flash_fs`` interfaces in
- ``flash_fs/its_flash_fs.c``.
-
-The system integrator **may** replace this implementation with its own
-flash filesystem implementation or filesystem proxy (supplicant).
-
-Flash Interface
-===============
-The ITS filesystem flash interface is defined by ``struct its_flash_fs_ops_t``
-in ``flash_fs/its_flash_fs.h``.
-
-Implementations of the ITS filesystem flash interface for different types of
-storage can be found in the ```internal_trusted_storage/flash`` directory.
-
-- ``flash/its_flash.h`` - Helper header that includes the correct ITS flash
- interface implementation for the target, and abstracts the allocation of
- different flash device types.
-
-- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND
- flash device, on top of the CMSIS flash interface implemented by the target.
- This implementation writes entire block updates in one-shot, so the CMSIS
- flash implementation **must** be able to detect incomplete writes and return
- an error the next time the block is read.
-
-- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash
- device, on top of the CMSIS flash interface implemented by the target.
-
-- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated
- flash device using RAM, on top of the CMSIS flash interface implemented by the
- target.
-
-The CMSIS flash interface **must** be implemented for each target based on its
-flash controller.
-
-The ITS flash interface depends on target-specific definitions from
-``platform/ext/target//partition/flash_layout.h``.
-Please see the `Internal Trusted Storage Service HAL` section for details.
-
-*****************************
-ITS Service Integration Guide
-*****************************
-This section describes mandatory (i.e. **must** implement) or optional
-(i.e. **may** implement) interfaces which the system integrator has to take in
-to account in order to integrate the internal trusted storage service in a new
-platform.
-
-Flash Interface
-===============
-For ITS service operations, a contiguous set of blocks must be earmarked for
-the internal trusted storage area. The design requires either 2 blocks, or any
-number of blocks greater than or equal to 4. Total number of blocks can not be
-0, 1 or 3. This is a design choice limitation to provide power failure safe
-update operations.
-
-Maximum Asset Size
-==================
-An asset is stored in a contiguous space in a logical filesystem block. The
-maximum size of an asset can be up-to the size of the data block. Typically,
-each logical block corresponds to one physical flash erase sector (the smallest
-unit that can erased), but the ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` configuration
-below allows a number of contiguous erase sectors to form one logical block.
-
-Internal Trusted Storage Service HAL
-====================================
-The ITS service requires the platform to implement the ITS HAL, defined in
-``platform/include/tfm_hal_its.h``.
-
-The following C definitions in the HAL are mandatory, and must be defined by the
-platform in a header named ``flash_layout.h``:
-
-- ``TFM_HAL_ITS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
- ARM_DRIVER_FLASH object to use for ITS. It must have been allocated by the
- platform and will be declared extern in the HAL header.
-
-- ``TFM_HAL_ITS_PROGRAM_UNIT`` - Defines the size of the ITS flash device's
- physical program unit (the smallest unit of data that can be individually
- programmed to flash). It must be equal to
- ``TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
- compile time so that filesystem structures can be statically sized. Valid
- values are powers of two between 1 and the flash sector size, inclusive.
-
-The following C definitions in the HAL may optionally be defined by the platform
-in the ``flash_layout.h`` header:
-
-- ``TFM_HAL_ITS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
- flash area for ITS.
-
-- ``TFM_HAL_ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
- for ITS in bytes.
-
-- ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
- flash erase sectors that form a logical erase block in the filesystem. The
- typical value is ``1``, but it may be increased so that the maximum required
- asset size will fit in one logical block.
-
-If any of the above definitions are not provided by the platform, then the
-``tfm_hal_its_fs_info()`` HAL API must be implemented instead. This function is
-documented in ``tfm_hal_its.h``.
-
-The sectors reserved to be used for Internal Trusted Storage **must** be
-contiguous.
-
-Internal Trusted Storage Service Optional Platform Definitions
-==============================================================
-The following optional platform definitions may be defined in
-``flash_layout.h``:
-
-- ``ITS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
- RAM FS emulated flash implementation. The buffer must be at least as large as
- the area earmarked for the filesystem by the HAL.
-- ``ITS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
- the NAND flash implementation. The buffer must be at least as large as a
- logical filesystem block.
-- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data
- between blocks, in bytes. If not provided, defaults to 256. Increasing this
- value will increase the memory footprint of the service.
-
-More information about the ``flash_layout.h`` content, not ITS related, is
-available in :doc:`platform readme ` along with other
-platform information.
-
-ITS Service Build Definitions
-=============================
-The ITS service uses a set of C definitions to compile in/out certain features,
-as well as to configure certain service parameters. When using the TF-M build
-system, these definitions are controlled by build flags of the same name. The
-``config/config_default.cmake`` file sets the default values of those flags, but
-they can be overwritten based on platform capabilities by setting them in
-``platform/ext/target//config.cmake``. The list of ITS service
-build definitions is:
-
-- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
- to create an ITS flash layout. If this flag is set, ITS service will
- generate an empty and valid ITS flash layout to store assets. It will
- erase all data located in the assigned ITS memory area before generating
- the ITS layout. This flag is required to be set if the ITS memory area
- is located in a non-persistent memory. This flag can be set if the ITS
- memory area is located in a persistent memory without a valid ITS flash
- layout in it. That is the case when it is the first time in the device
- life that the ITS service is executed.
-- ``ITS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
- enable/disable the validation mechanism to check the metadata store in flash
- every time the flash data is read from flash. This validation is required
- if the flash is not hardware protected against data corruption.
-- ``ITS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
- the persistent storage device to store the FS in the Internal Trusted Storage
- service. This flag is ``OFF`` by default. The ITS regression tests write/erase
- storage multiple time, so enabling this flag can increase the life of flash
- memory when testing.
- If this flag is set to ``ON``, ITS_RAM_FS_SIZE must also be provided. This
- specifies the size of the block of RAM to be used to simulate the flash.
-
- .. Note::
- If this flag is disabled when running the regression tests, then it is
- recommended that the persistent storage area is erased before running the
- tests to ensure that all tests can run to completion. The type of persistent
- storage area is platform specific (eFlash, MRAM, etc.) and it is described
- in corresponding flash_layout.h
-
-- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
- ITS area. This size is used to define the temporary buffers used by ITS to
- read/write the asset content from/to flash. The memory used by the temporary
- buffers is allocated statically as ITS does not use dynamic memory allocation.
-- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
- ITS area. This number is used to dimension statically the filesystem metadata
- tables in RAM (fast access) and flash (persistent storage). The memory used by
- the filesystem metadata tables is allocated statically as ITS does not use
- dynamic memory allocation.
-- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer
- buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset
- data to be copied between the client and the filesystem in one iteration.
- Reducing the buffer size will decrease the RAM usage of the partition at the
- expense of latency, as data will be copied in multiple iterations. *Note:*
- when data is copied in multiple iterations, the atomicity property of the
- filesystem is lost in the case of an asynchronous power failure.
-
---------------
-
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
-*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/reference/services/tfm_platform_integration_guide.rst b/docs/reference/services/tfm_platform_integration_guide.rst
deleted file mode 100644
index 7858435ac7..0000000000
--- a/docs/reference/services/tfm_platform_integration_guide.rst
+++ /dev/null
@@ -1,113 +0,0 @@
-##################################
-Platform Service Integration Guide
-##################################
-
-************
-Introduction
-************
-TF-M Platform service is a trusted service which allows secure partitions and
-non-secure applications to interact with some platform-specific components.
-There are a number of features which requires some interaction with
-platform-specific components which are at the same time essential for the
-security of the system.
-Therefore, those components need to be handled by a secure partition which is
-part of the trusted compute base.
-
-These platform-specific components include system reset, power management,
-Debug, GPIO, etc.
-
-************************
-TF-M Platform interfaces
-************************
-The TF-M interfaces for the Platform service are located in
-``interface/include/``.
-The TF-M Platform service source files are located in
-``secure_fw/partitions/platform``.
-
-*********************
-TF-M Platform service
-*********************
-The Platform service interfaces and types are defined and documented in
-``interface/include/tfm_platform_api.h``
-
-- ``platform_sp.h/c`` : These files define and implement functionalities related
- to the platform service
-- ``tfm_platform_secure_api.c`` : This file implements ``tfm_platform_api.h``
- functions to be called from the secure partitions. This is the entry point
- when the secure partitions request an action to the Platform service
- (e.g system reset).
-
-************
-Platform HAL
-************
-
-The Platform Service relies on a platform-specific implementation to
-perform some functionalities. Mandatory functionality (e.g. system reset)
-that are required to be implemented for a platform to be supported by TF-M have
-their dedicated HAL API functions. Additional platform-specific services can be
-provided using the IOCTL function call.
-
-For API specification, please check: ``platform/include/tfm_platform_system.h``
-
-An implementation is provided in all the supported platforms. Please, check
-``platform/ext/target//services/src/tfm_platform_system.c``
-for examples.
-
-The API **must** be implemented by the system integrators for their targets.
-
-IOCTL
-=====
-
-A single entry point to platform-specific code across the HAL is provided by the
-IOCTL service and HAL function:
-
-.. code-block:: c
-
- enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request,
- psa_invec *in_vec,
- psa_outvec *out_vec);
-
-A request type is provided by the client, with additional parameters contained
-in the optional ``in_vec`` parameter. An optional output buffer can be passed to
-the service in ``out_vec``.
-An IOCTL request type not supported on a particular platform should return
-``TFM_PLATFORM_ERR_NOT_SUPPORTED``
-
-Non-Volatile counters
-=====================
-
-The Platform Service provides an abstracted service for exposing the NV counters
-to the secure world. The following operations are supported:
-
-- Increment a counter.
-- Read a counter value to a preallocated buffer.
-
-.. code-block:: c
-
- enum tfm_platform_err_t
- tfm_platform_nv_counter_increment(uint32_t counter_id);
-
- enum tfm_platform_err_t
- tfm_platform_nv_counter_read(uint32_t counter_id,
- uint32_t size, uint8_t *val);
-
-The range of counters id is defined in :
-``platform/include/tfm_plat_nv_counters.h``
-
-For Level 2,3 isolation implementations, secure partitions in the
-Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a
-dependency for access to the NV counter API.
-
-***************************
-Current Service Limitations
-***************************
-- **system reset** - The system reset functionality is only supported in
- isolation level 1. Currently the mechanism by which PSA-RoT services should
- run in privileged mode in level 3 is not in place due to an ongoing work in
- TF-M Core. So, the ``NVIC_SystemReset`` call performed by the service is
- expected to generate a memory fault when it tries to access the ``SCB->AIRCR``
- register in level 3 isolation.
-
---------------
-
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_ps_integration_guide.rst b/docs/reference/services/tfm_ps_integration_guide.rst
deleted file mode 100644
index 049f4b6d3a..0000000000
--- a/docs/reference/services/tfm_ps_integration_guide.rst
+++ /dev/null
@@ -1,392 +0,0 @@
-###########################################
-Protected Storage Service Integration Guide
-###########################################
-
-************
-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 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 design addresses the following high level requirements as well:
-
-- **Confidentiality** - Resistance to unauthorised accesses through
- hardware/software attacks.
-
-- **Access Authentication** - Mechanism to establish requester's identity (a
- non-secure entity, secure entity, or a remote server).
-
-- **Integrity** - Resistant to tampering by either the normal users of a product,
- package, or system or others with physical access to it. If the content of the
- protected storage is changed maliciously, the service is able to detect it.
-
-- **Reliability** - Resistant to power failure scenarios and incomplete write
- cycles.
-
-- **Configurability** - High level configurability to scale up/down memory
- footprint to cater for a variety of devices with varying security
- requirements.
-
-- **Performance** - Optimized to be used for resource constrained devices with
- very small silicon footprint, the PPA (power, performance, area) should be
- optimal.
-
-******************************
-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.
-
-- **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
- metadata in blocks which are always stored in the same flash location. That
- increases the number of writes in a specific flash location as every change in
- the storage area requires a metadata update.
-
-- **PSA internal trusted storage API** - In the current design, the service does
- not use the PSA Internal Trusted Storage API to write the rollback protection
- values stored in the internal storage.
-
-- **Protection against physical storage medium failure** - Complete handling of
- inherent failures of storage mediums (e.g. bad blocks in a NAND based device)
- is not supported by the current design.
-
-- **Key diversification** - In a more robust design, each asset would be
- encrypted through a different key.
-
-- **Lifecycle management** - Currently, it does not support any subscription
- based keys and certificates required in a secure lifecycle management. Hence,
- an asset's validity time-stamp can not be invalidated based on the system
- time.
-
-- **Provisioning vs user/device data** - In the current design, all assets are
- treated in the same manner. In an alternative design, it may be required to
- create separate partitions for provisioning content and user/device generated
- content. This is to allow safe update of provisioning data during firmware
- updates without the need to wipe out the user/device generated data.
-
-**************
-Code Structure
-**************
-Protected storage service code is located in
-``secure_fw/partitions/protected_storage/`` and is divided as follows:
-
- - Core files
- - Cryptographic interfaces
- - Non-volatile (NV) counters interfaces
-
-The PSA PS interfaces for PS service are located in ``interface/include/psa``
-
-PSA Protected Storage Interfaces
-================================
-
-The PS service exposes the following mandatory PSA PS interfaces, version 1.0:
-
-.. code-block:: c
-
- psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags);
- psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length);
- psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
- psa_status_t psa_ps_remove(psa_storage_uid_t uid);
- uint32_t psa_ps_get_support(void);
-
-For the moment, it does not support the extended version of those APIs.
-
-These PSA PS interfaces and PS TF-M types are defined and documented in
-``interface/include/psa/protected_storage.h``,
-``interface/include/psa/storage_common.h`` and
-``interface/include/tfm_ps_defs.h``
-
-Core Files
-==========
-- ``tfm_ps_req_mngr.c`` - Contains the PS request manager implementation which
- handles all requests which arrive to the service. This layer extracts the
- arguments from the input and output vectors, and it calls the protected
- storage layer with the provided parameters.
-
-- ``tfm_protected_storage.c`` - Contains the TF-M protected storage API
- implementations which are the entry points to the PS service.
-
-- ``ps_object_system.c`` - Contains the object system implementation to manage
- all objects in PS area.
-
-- ``ps_object_table.c`` - Contains the object system table implementation which
- complements the object system to manage all object in the PS area.
- The object table has an entry for each object stored in the object system
- and keeps track of its version and owner.
-
-- ``ps_encrypted_object.c`` - Contains an implementation to manipulate
- encrypted objects in the PS object system.
-
-- ``ps_utils.c`` - Contains common and basic functionalities used across the
- PS service code.
-
-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 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
-`.
-
-The ITS service implementation in
-``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``,
-constructs a filesystem configuration for Protected Storage based on
-target-specific definitions from the Protected Storage HAL. Please see the
-`Protected Storage Service HAL` section for details of these.
-
-Cryptographic Interface
-=======================
-- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for
- the protected storage service.
-
-- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic
- operations with calls to the TF-M Crypto service.
-
-Non-volatile (NV) Counters Interface
-====================================
-The current PS service provides rollback protection based on NV
-counters.
-PS defines and implements the following NV counters functionalities:
-
-- ``nv_counters/ps_nv_counters.h`` - Abstracts PS non-volatile
- counters operations. This API detaches the use of NV counters from the TF-M NV
- counters implementation, provided by the platform, and provides a mechanism to
- compile in a different API implementation for test purposes. A PS test suite
- **may** provide its own custom implementation to be able to test different PS
- service use cases.
-
-- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces
- based on TF-M NV counters implementation provided by the platform.
-
-****************************
-PS Service Integration Guide
-****************************
-This section describes mandatory (i.e. **must** implement) or optional
-(i.e. **may** implement) interfaces which the system integrator have to take
-in to account in order to integrate the protected storage service in a new
-platform.
-
-Maximum Asset Size
-==================
-An asset is stored in a contiguous space in a block/sector. The maximum
-size of an asset can be up-to the size of the data block/sector minus the object
-header size (``PS_OBJECT_HEADER_SIZE``) which is defined in
-``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the
-``PS_ENCRYPTION`` flag status.
-
-Protected Storage Service HAL
-=============================
-The PS service requires the platform to implement the PS HAL, defined in
-``platform/include/tfm_hal_ps.h``.
-
-The following C definitions in the HAL are mandatory, and must be defined by the
-platform in a header named ``flash_layout.h``:
-
-- ``TFM_HAL_PS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash
- ARM_DRIVER_FLASH object to use for PS. It must have been allocated by the
- platform and will be declared extern in the HAL header.
-
-- ``TFM_HAL_PS_PROGRAM_UNIT`` - Defines the size of the PS flash device's
- physical program unit (the smallest unit of data that can be individually
- programmed to flash). It must be equal to
- ``TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at
- compile time so that filesystem structures can be statically sized. Valid
- values are powers of two between 1 and the flash sector size, inclusive.
-
-The following C definitions in the HAL may optionally be defined by the platform
-in the ``flash_layout.h`` header:
-
-- ``TFM_HAL_PS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated
- flash area for PS.
-
-- ``TFM_HAL_PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area
- for PS in bytes.
-
-- ``TFM_HAL_PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical
- flash erase sectors that form a logical erase block in the filesystem. The
- typical value is ``1``, but it may be increased so that the maximum required
- asset size will fit in one logical block.
-
-If any of the above definitions are not provided by the platform, then the
-``tfm_hal_ps_fs_info()`` HAL API must be implemented instead. This function is
-documented in ``tfm_hal_ps.h``.
-
-The sectors reserved to be used for Protected Storage **must** be contiguous
-sectors starting at ``TFM_HAL_PS_FLASH_AREA_ADDR``.
-
-The design requires either 2 blocks, or any number of blocks greater than or
-equal to 4. Total number of blocks can not be 0, 1 or 3. This is a design choice
-limitation to provide power failure safe update operations.
-
-Protected Storage Service Optional Platform Definitions
-=======================================================
-The following optional platform definitions may be defined in
-``flash_layout.h``:
-
-- ``PS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the
- RAM FS emulated flash implementation. The buffer must be at least as large as
- the area earmarked for the filesystem by the HAL.
-- ``PS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using
- the NAND flash implementation. The buffer must be at least as large as a
- logical filesystem block.
-
-More information about the ``flash_layout.h`` content, not PS related, is
-available in :doc:`platform readme ` along with other
-platform information.
-
-TF-M NV Counter Interface
-=========================
-To have a platform independent way to access the NV counters, TF-M defines a
-platform NV counter interface. For API specification, please check:
-``platform/include/tfm_plat_nv_counters.h``
-
-The system integrators **may** implement this interface based on the target
-capabilities and set the ``PS_ROLLBACK_PROTECTION`` flag to compile in
-the rollback protection code.
-
-Secret Platform Unique Key
-==========================
-The encryption policy relies on a secret hardware unique key (HUK) per device.
-It is system integrator's responsibility to provide an implementation which
-**must** be a non-mutable target implementation.
-For API specification, please check:
-``platform/include/tfm_plat_crypto_keys.h``
-
-A stub implementation is provided in
-``platform/ext/common/template/crypto_keys.c``
-
-Non-Secure Identity Manager
-===========================
-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:`NS client identification documentation `
-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 `
-provides further details of non-secure implementation requirements for TF-M.
-
-Cryptographic Interface
-=======================
-The reference encryption policy is built on AES-GCM, and it **may** be replaced
-by a vendor specific implementation.
-
-The PS service abstracts all the cryptographic requirements and specifies the
-required cryptographic interface in
-``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h``
-
-The PS service cryptographic operations are implemented in
-``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using
-calls to the TF-M Crypto service.
-
-PS Service Build Definitions
-============================
-The PS service uses a set of C definitions to compile in/out certain features,
-as well as to configure certain service parameters. When using the TF-M build
-system, these definitions are controlled by build flags of the same name. The
-``config/config_default.cmake`` file sets the default values of those flags, but
-they can be overwritten based on platform capabilities by setting them in
-``platform/ext/target//config.cmake``. The list of PS service build
-definitions is:
-
-- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption
- option to encrypt the protected storage data.
-- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required
- to create a PS flash layout. If this flag is set, PS service will
- generate an empty and valid PS flash layout to store assets. It will
- erase all data located in the assigned PS memory area before generating
- the PS layout. This flag is required to be set if the PS memory area
- is located in a non-persistent memory. This flag can be set if the PS
- memory area is located in a persistent memory without a valid PS flash
- layout in it. That is the case when it is the first time in the device
- life that the PS service is executed.
-- ``PS_VALIDATE_METADATA_FROM_FLASH``- this flag allows to
- enable/disable the validation mechanism to check the metadata store in flash
- every time the flash data is read from flash. This validation is required
- if the flash is not hardware protected against malicious writes. In case
- the flash is protected against malicious writes (i.e embedded flash, etc),
- this validation can be disabled in order to reduce the validation overhead.
-- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable
- rollback protection in protected storage service. This flag takes effect only
- if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on.
-- ``PS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of
- the persistent storage device to store the FS in the Protected Storage
- service. This flag is ``OFF`` by default. The PS regression tests write/erase
- storage multiple time, so enabling this flag can increase the life of flash
- memory when testing.
- If this flag is set to ``ON``, PS_RAM_FS_SIZE must also be provided. This
- specifies the size of the block of RAM to be used to simulate the flash.
-
- .. Note::
- If this flag is disabled when running the regression tests, then it is
- recommended that the persistent storage area is erased before running the
- tests to ensure that all tests can run to completion. The type of persistent
- storage area is platform specific (eFlash, MRAM, etc.) and it is described
- in corresponding flash_layout.h
-
-- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
- PS area. This size is used to define the temporary buffers used by PS to
- read/write the asset content from/to flash. The memory used by the temporary
- buffers is allocated statically as PS does not use dynamic memory allocation.
-- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
- PS area. This number is used to dimension statically the object table size in
- RAM (fast access) and flash (persistent storage). The memory used by the
- 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
- 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
- overridden to ``OFF`` when building the regression tests. In this case,
- the PS rollback protection test suite will not be built, as it relies
- on extra functionality provided by the virtual NV counters to simulate
- different rollback scenarios. The remainder of the PS test suites will
- run using the hardware NV counters. Please note that running the tests in
- this configuration will quickly increase the hardware NV counter values,
- which cannot be decreased again.
- Overriding this flag from its default value of ``OFF`` when not
- building the regression tests is not currently supported.
-
---------------
-
-*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
-*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/reference/services/tfm_psa_proxy_integration_guide.rst b/docs/reference/services/tfm_psa_proxy_integration_guide.rst
deleted file mode 100644
index 2c5a389cc2..0000000000
--- a/docs/reference/services/tfm_psa_proxy_integration_guide.rst
+++ /dev/null
@@ -1,83 +0,0 @@
-#####################################
-PSA Proxy Partition Integration Guide
-#####################################
-
-************
-Introduction
-************
-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 `.
-
-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
-``psa_write`` is used to give back the results to the caller.) By default this
-memory is allocated from BSS, but if that is not accessible to the Secure
-Enclave other memory area can be used. To communicate with the Secure Enclave
-the mailbox solution is used, and Proxy uses the Non-secure side of mailbox.
-(The secure side of the mailbox is handled by the Secure Enclave.)
-
-***************************************
-Current PSA Proxy partition limitations
-***************************************
-- Client IDs are not forwarded to Secure Enclave. For Non-secure clients this
- is straightforward, but for calls coming from other secure partitions the IDs
- must be translated to a negative value. The reason is all clients on Host
- are treated as non-secure from Secure Enclave's point of view. (This is the
- cause why Protected Storage messages also forwarded. Protected Storage uses
- Internal Trusted Storage partition to manage the PS flash area. But as client
- IDs are not forwarded the ITS partition running on Secure Enclave can not
- know whether should work on ITS or PS flash.)
-- Sending of the mailbox messages is a blocking call in Proxy, so control is
- not given back to Host's SPM while waiting for Secure Enclave's answer.
-- Only one message can be put into the mailbox at a time.
-- Current platform partition provides Non Volatile (NV) counter, System Reset,
- and IOCTL services. But while NV counters and System Reset shall be provided
- by the Secure Enclave, IOCTL probably shall be provided by Host, as the
- underlaying HW probably placed in Host subsystem. So the current platform
- partition should be split into two halves by conditional compilation, and
- Proxy should forward only the calls provided by Secure Enclave.
-- PSA Proxy can only get the IPC parameters by PSA read, so the parameters need
- to be copied to a shared memory, because the partition cannot forward the
- original pointers. This copy might be omitted on platforms where Secure
- Enclave has access to all Host memory areas, if all security risks are
- addressed. Note that IOVECs shall be verified by Host's SPM and sent to SE
- with the mailbox message.
-
-**************
-Code Structure
-**************
-PSA Proxy partition code is located in ``secure_fw/partitions/psa_proxy/``.
-As Proxy can be treated as an alternative implementation of all the PSA RoT
-services, the Secure and Non-secure interface implementations of the forwarded
-services are reused without modification.
-
-Files
-=====
-- ``psa_proxy.c`` - Handles IPC messages and manages communication with the
- Secure Enclave.
-
-- ``psa_proxy_shared_mem_mngr.c`` - Responsible to manage the shared memory
- area used to share the input and output parameters with Secure Enclave.
-
-*****************
-Integration Guide
-*****************
-- Non-secure mailbox interface must be provided.
-- Shared memory must be configured:
- - If Secure Enclave can access TF-M's BSS section it is enough to set the
- area's size by the ``SHARED_BUFFER_SIZE`` macro.
- - If a special memory region must be used as the shared memory the
- ``PSA_PROXY_SHARED_MEMORY_BASE`` and ``PSA_PROXY_SHARED_MEMORY_SIZE``
- macros must be set. (Not just for compilation but for linking as well,
- becuase these macros used in the linker script/scatter file too.)
-- If memories are mapped to different addresses for Host and Secure Enclave
- address translation can be turned on by setting
- ``PSA_PROXY_ADDR_TRANSLATION`` macro and implementing the interface defined
- by ``platform/include/tfm_plat_psa_proxy_addr_trans.h`` header.
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/reference/services/tfm_secure_partition_addition.rst b/docs/reference/services/tfm_secure_partition_addition.rst
deleted file mode 100644
index 9343aab2d4..0000000000
--- a/docs/reference/services/tfm_secure_partition_addition.rst
+++ /dev/null
@@ -1,467 +0,0 @@
-#######################
-Adding Secure Partition
-#######################
-
-***********************
-Terms and abbreviations
-***********************
-This document uses the following terms and abbreviations.
-
-.. table:: term table
- :widths: auto
-
- ================== ==================================
- **Term** **Meaning**
- ================== ==================================
- FF Firmware Framework
- ID Identifier
- IPC Interprocess communication
- IPC model The secure IPC framework
- irqs Interrupt requests
- Library model The secure function call framework
- MMIO Memory Mapped I/O
- PSA Platform Security Architecture
- RoT Root of Trust
- SID RoT Service ID
- SP Secure Partition
- SPM Secure Partition Manager
- TF-M Trusted firmware M
- ================== ==================================
-
-************
-Introduction
-************
-Secure Partition is an execution environment that provides the following
-functions to Root of Trust (RoT) Services:
-
-- Access to resources, protection of its own code and data.
-- Mechanisms to interact with other components in the system.
-
-Each Secure Partition is a single thread of execution and the smallest unit of
-isolation.
-
-This document mainly describes how to add a secure partition in TF-M and
-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
- model.
-
- The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to
- `PSA Firmware Framework specification`_ for details.
-
-*******
-Process
-*******
-The main steps to add a secure partition are as follows:
-
-- `Add source folder`_
-- `Add manifest`_
-- `Add configuration`_
-- `Implement the RoT services`_
-
-Add source folder
-=================
-Add a source folder under ``/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
-- CMake configuration files
-- Source code files
-
-Add manifest
-============
-Each Secure Partition must have resource requirements declared in a manifest
-file. The Secure Partition Manager (SPM) uses the manifest file to assemble and
-allocate resources within the SPE. The manifest includes the following:
-
-- A Secure Partition name.
-- A list of implemented RoT Services.
-- Access to other RoT Services.
-- Memory requirements.
-- Scheduling hints.
-- Peripheral memory-mapped I/O regions and interrupts.
-
-.. Note::
- 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:
-
-.. code-block:: yaml
-
- {
- "psa_framework_version": 1.0,
- "name": "TFM_SP_EXAMPLE",
- "type": "PSA-ROT",
- "priority": "HIGH",
- "entry_point": "example_main",
- "stack_size": "0x0200",
- "services" : [
- {
- "name": "ROT_A",
- "sid": "0x0000F000",
- "non_secure_clients": true,
- "version": 1,
- "version_policy": "STRICT"
- }
- ],
- "mmio_regions": [
- {
- "name": "TFM_PERIPHERAL_A",
- "permission": "READ-WRITE"
- }
- ],
- "irqs": [
- {
- "source": "TFM_A_IRQ",
- "signal": "SPM_CORE_A_IRQ",
- "tfm_irq_priority": 64,
- }
- ],
- "linker_pattern": {
- "object_list": [
- "*EXAMPLE.*"
- ]
- }
- }
-
-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
-``/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.
-
-.. code-block:: c
-
- #define name id-value
-
-Here is the Secure Partition ID table used in TF-M.
-
-.. table:: PID table
- :widths: auto
-
- =============================== =================
- **Partition name** **Partition ID**
- =============================== =================
- Reserved 0-255
- TFM_SP_PS 256
- TFM_SP_ITS 257
- TFM_SP_AUDIT_LOG 258
- TFM_SP_CRYPTO 259
- TFM_SP_PLATFORM 260
- TFM_SP_INITIAL_ATTESTATION 261
- TFM_SP_CORE_TEST 262
- TFM_SP_CORE_TEST_2 263
- TFM_SP_SECURE_TEST_PARTITION 264
- TFM_SP_IPC_SERVICE_TEST 265
- TFM_SP_IPC_CLIENT_TEST 266
- TFM_IRQ_TEST_1 267
- TFM_SP_PS_TEST 268
- =============================== =================
-
-About where to add the definition, please refer to the chapter `Add
-configuration`_.
-
-RoT Service ID (SID) Distribution
----------------------------------
-An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit
-number that is associated with a symbolic name in the Secure Partition
-manifest. The bits [31:12] uniquely identify the vendor of the RoT Service.
-The remaining bits [11:0] can be used at the discretion of the vendor.
-
-Here is the RoT Service ID table used in TF-M.
-
-.. table:: SID table
- :widths: auto
-
- =========================== ====================== ========================
- **Services** **Vendor ID(20 bits)** **Function ID(12 bits)**
- =========================== ====================== ========================
- audit_logging 0x00000 0x000-0x01F
- initial_attestation 0x00000 0x020-0x03F
- platform 0x00000 0x040-0x05F
- protected_storage 0x00000 0x060-0x06F
- internal_trusted_storage 0x00000 0x070-0x07F
- crypto 0x00000 0x080-0x09F
- firmware_update 0x00000 0x0A0-0x0BF
- test_secure_service 0x0000F 0x000-0x01F
- core_test 0x0000F 0x020-0x03F
- core_test_2 0x0000F 0x040-0x05F
- tfm_ipc_client 0x0000F 0x060-0x07F
- tfm_ipc_service 0x0000F 0x080-0x09F
- tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF
- tfm_ps_test_service 0x0000F 0x0C0-0x0DF
- =========================== ====================== ========================
-
-mmio_regions
-------------
-This attribute is a list of MMIO region objects which the Secure Partition
-needs access to. TF-M only supports the ``named_region`` current. Please refer
-to PSA FF for more details about it. The user needs to provide a name macro to
-indicate the variable of the memory region.
-
-TF-M uses the below structure to indicate a peripheral memory.
-
-.. code-block:: c
-
- struct platform_data_t {
- uint32_t periph_start;
- uint32_t periph_limit;
- int16_t periph_ppc_bank;
- int16_t periph_ppc_loc;
- };
-
-.. Note::
- This structure is not expected by TF-M, it's only that the current
- 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:
-
-.. 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.
-
-The ``signal`` must be the upper case of the secure function name.
-
-.. code-block:: yaml
-
- "secure_functions": [
- {
- "name": "TFM_EXAMPLE_A",
- "signal": "EXAMPLE_A_FUNC",
- "sid": "0x00000000",
- "non_secure_clients": true,
- "version": 1,
- "version_policy": "STRICT"
- },
-
-Add configuration
-=================
-The following configuration tasks are required for the newly added secure
-partition:
-
-Add CMake configure files
--------------------------
-- CMakeLists.txt, which is the compilation configuration for this module.
-
-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``.
-Please refer to the source code of TF-M for more detail.
-
-Update manifest list
---------------------
-The ``/tools/tfm_manifest_list.yaml`` is used to collect
-necessary information of secure partition.
-
-- ``name``: The name string of the secure partition.
-- ``short_name``: should be the same as the ``name`` in the secure partition
- manifest file.
-- ``manifest``: the relative path of the manifest file to TF-M root.
-- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC
- model.
-- ``conditional``: Optional. Configure control macro for this partition.
-- ``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`_.
-
-Reference configuration example:
-
-.. code-block:: yaml
-
- {
- "name": "Example Service",
- "short_name": "TFM_SP_EXAMPLE",
- "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml",
- "tfm_partition_ipc": true,
- "conditional": "TFM_PARTITION_EXAMPLE",
- "version_major": 0,
- "version_minor": 1,
- "pid": 256
- }
-
-.. Note::
- The manifest configuration can be placed in a different external manifest
- list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be
- set to the path of the external manifest list.
-
-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
-``/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.
-
-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
-
-.. code-block:: c
-
- void example_main(void)
- {
- psa_signal_t signals = 0;
-
- while (1) {
- signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK);
- if (signals & ROT_A_SIGNAL) {
- rot_A();
- } else {
- /* Should not come here */
- psa_panic();
- }
- }
- }
-
-Service implementation
-----------------------
-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
-"Hello World" when called.
-
-.. code-block:: c
-
- 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";
-
- 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);
- break;
- 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);
- }
- }
- 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();
- break;
- }
- }
-
-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
-``/test/suites/example/non_secure/example_ns_interface_testsuite.c``.
-
-.. code-block:: c
-
- static void tfm_example_test_1001(struct test_result_t *ret)
- {
- char str1[] = "str1";
- char str2[] = "str2";
- char str3[128], str4[128];
- struct psa_invec invecs[2] = {{str1, sizeof(str1)},
- {str2, sizeof(str2)}};
- struct psa_outvec outvecs[2] = {{str3, sizeof(str3)},
- {str4, sizeof(str4)}};
- psa_handle_t handle;
- psa_status_t status;
- uint32_t version;
-
- version = psa_version(ROT_A_SID);
- TEST_LOG("TFM service support version is %d.\r\n", version);
- handle = psa_connect(ROT_A_SID, ROT_A_VERSION);
- status = psa_call(handle, PSA_IPC_CALL, invecs, 2, outvecs, 2);
- if (status >= 0) {
- TEST_LOG("psa_call is successful!\r\n");
- } else {
- TEST_FAIL("psa_call is failed!\r\n");
- return;
- }
-
- TEST_LOG("outvec1 is: %s\r\n", outvecs[0].base);
- TEST_LOG("outvec2 is: %s\r\n", outvecs[1].base);
- psa_close(handle);
- ret->val = TEST_PASSED;
- }
-
-Once the test and service has been implemented, the project can be built and
-executed. The user should see the "Hello World" message in the console as
-received by the testsuite.
-
-Further Notes
--------------
-
-- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM
- provides APIs and checking between isolation boundaries, a free accessing
- of memory can cause program panic.
-- In the IPC model, the memory checking inside partition runtime is
- unnecessary. SPM handles the checking while memory accessing APIs are
- called.
-- In the IPC model, the client ID had been included in the message structure
- and secure partition can get it when calling psa_get() function. The secure
- partition does not need to call ``tfm_core_get_caller_client_id()`` to get
- the caller client ID anymore.
-- In the IPC model, SPM will check the security policy and partition
- dependence between client and service. So the service does not need to
- validate the secure caller anymore.
-
-*********
-Reference
-*********
-
-| `PSA Firmware Framework specification`_
-
-.. _PSA Firmware Framework specification: https://pages.arm.com/psa-
- resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
-
---------------
-
-*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/releases/1.0.rst b/docs/releases/1.0.rst
new file mode 100644
index 0000000000..48903f5013
--- /dev/null
+++ b/docs/releases/1.0.rst
@@ -0,0 +1,144 @@
+***********
+Version 1.0
+***********
+
+New Features
+============
+- First major release.
+
+- A Secure FW with support for PSA Level 1 and 2 isolation on Armv8-M
+ using TrustZone extension and Dual-core Cortex-M config.
+
+- The PSA Firmware Framework (PSA FF)/Dev API interfaces exposed by the
+ Secure FW to NS side.
+
+- A secure FW model with NS application example.
+
+- Secure services running within this SPE
+
+ - Secure Storage Service (PSA Protected Storage API - 1.0.0)
+ - Attestation (PSA Attestation API 1.0.0)
+ - Crypto Service (PSA API 1.0-beta-3)
+ - TF-M Audit Log
+ - Platform Service
+ - Internal Trusted Storage (PSA API 1.0.0)
+
+- PSA IPC support
+
+- Support for Armv8-M mainline and baseline and Dual-core Cortex-M systems.
+
+- Testcases running baremetal and with RTX to test the functionality.
+
+- BL2 bootloader for image authentication based on SHA256 and RSA-3072
+ digital signature.
+
+- Build system based on CMake, supporting ARMCLANG and GNU Arm.
+
+- Support for integrated CryptoCell-312 cryptographic hardware accelerator
+ on Musca-B1 platform.
+
+- Meets requirements for Updatable RoT for PSA Functional API, Level 1 and
+ Level 2 Certifications in the feature list.
+
+Platforms supported
+===================
+Current release has been tested on:
+
+ - Cortex M33 based SSE-200 system:
+
+ - `FPGA image loaded on MPS2 board.
+ `__
+ - `Fast model FVP_MPS2_AEMv8M.
+ `__
+ - `Musca-A test chip board.
+ `__
+ - `Musca-B1 test chip board.
+ `__
+ - `Musca-S1 test chip board.`
+ - `FPGA image loaded on MPS3 board.
+ `__
+ - `Arm DesignStart FPGA on AWS Cloud.
+ `__
+
+ - Cortex M23 based IoT Kit system:
+
+ - `FPGA image loaded on MPS2 board.
+ `__
+
+Other supported platforms:
+
+ - Dual Core Cortex-M system:
+
+ - `Cypress PSoc64.
+ `__
+
+Platform Limitations
+====================
+- The PSA Arch Tests need to be split into several binaries to load onto
+ Musca-A board because of low memory available to the NS world to use.
+
+- The Regression tests on MPS3 AN524 FPGA takes about 40 minutes to complete.
+ This is because AN524 uses QSPI Flash for runtime memory as the RAM is small.
+ The slow speed of QSPI device causes the tests to run slowly.
+
+- Warm reset of eFlash is not permitted on Musca-B1 due to HW bug
+ https://community.arm.com/developer/tools-software/oss-platforms/w/docs/426/musca-b1-warm-reset-of-eflash
+ As TF-M is executed in place from eFlash on Musca-B1, there is good chance
+ that a warm reset of the board will have unexpected (even non-deterministic)
+ effects on code execution. Hence the PSA Arch FF tests, which rely of warm
+ reset of Musca-B1 were executed on RAM FS using "-DSST_RAM_FS=ON" config.
+
+Known issues
+============
+Some open issues exist and will not be fixed in this release.
+
+.. list-table::
+
+ * - AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
+ cause boot failure. This is known issue for AN521 FVP. This will cause
+ the system to not boot after a warm reset during PSA Arch FF testing.
+ - Issue : https://developer.trustedfirmware.org/T692
+
+ * - PSA Arch Crypto tests have several known failures.
+ - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md
+
+ * - There are 2 additional failures for PSA-Arch Crypto tests with CC-312
+ other than the known failures. This is due to limitation of CC-312
+ implementation as it does not support MD_NONE hashing mode causing the
+ additional failures.
+ - The issue details are captured here : https://developer.trustedfirmware.org/T691
+
+ * - PS test case 2002 and 1002 does not fail on Musca-B1 flash when
+ run for second time without erasing flash. The WRITE_ONCE assets created
+ by SST module should not be updatable but after reboot, the update seems
+ to happen and is not expected. This issue will happen on any platform
+ using persistent storage for SST.
+ - Issue created : https://developer.trustedfirmware.org/T693
+
+ * - Boot up fails if there is unexpected data in flash on Musca-A. The boot
+ is successful and the tests pass if all the associated (SST/ITS/NV
+ Counter) flash areas are erased.
+ - Issue created : https://developer.trustedfirmware.org/T694
+
+ * - If the flash is not erased, boot fails on Musca-B1 when SST
+ is using flash for Minsizerel config.
+ - Issue created : https://developer.trustedfirmware.org/T695
+
+ * - When SST/ITS are using Flash on Musca-B1, PSA Arch FF test fails due
+ to known warm reset limitation in the platform. But after the failure,
+ Musca-B1 boot fails to boot. This could be related to general issues of
+ the SST module when Flash data is inconsistent.
+ - Issue created : https://developer.trustedfirmware.org/T696
+
+ * - The eflash driver on Musca-B1 can return random failures hence
+ triggering random failures during PSA Arch ITS and PSA Arch PS tests.
+ This happens when ITS/SST is configured to use flash.
+ - Issue created : https://developer.trustedfirmware.org/T697
+
+ * - Release build of PSA Arch Crypto tests have a different number of tests
+ when built for AN521 FVP. This is an issue in the PSA Arch Crypto tests.
+ - Issue created for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/releases/1.1.rst b/docs/releases/1.1.rst
new file mode 100644
index 0000000000..83c45dfb54
--- /dev/null
+++ b/docs/releases/1.1.rst
@@ -0,0 +1,126 @@
+***********
+Version 1.1
+***********
+
+New Features
+============
+
+- Upgraded MCUBoot to v1.6.0., default is now the upstream MCUBoot instead of
+ the TF-M fork.
+
+- TF-Fuzz tool for fuzz testing PSA APIs.
+
+- Updated Source code folder structure.
+
+- IAR compiler support.
+
+- LPCXpresso55S69-EVK board support.
+
+- Add Profile Small.
+
+- Enable Ninja CMake Generator.
+
+- FVP_SSE300_MPS2 platform support.
+
+- Rename SST(Secure STorage) to PS(Protected Storage) and partition moved from
+ PSA Root of Trust to Application Root of Trust.
+
+- NUCLEO-L552ZE-Q and DISCO-L562QE platform support.
+
+- Restructure documentation to make it more user-friendly.
+
+- Enable Attestation service to use symmetric key algorithm.
+
+- Use CMSIS for testing from
+ `tf-m-tests `__
+ repository. This removes dependency on the external ``CMSIS_5`` repo.
+
+New Platforms supported
+=======================
+
+- Cortex-M33 based system:
+
+ - `LPCXpresso55S69-EVK.
+ `__
+
+ - `NUCLEO-L552ZE-Q.
+ `__
+
+ - `DISCO-L562QE.
+ `__
+
+- Cortex-M55 based SSE-300 system:
+
+ - `Fast model FVP_SSE300_MPS2.
+ `__
+
+
+New Platforms limitations
+=========================
+
+- LPCXpresso55S69-EVK doesn't support BL2.
+
+- LPCXpresso55S69-EVK doesn't support ARMCLANG and IARARM toolchain. Patch
+ with support for IARARM is available at
+ `review.trustedfirmware.org #4023 `__
+
+- FVP_SSE300_MPS2 doesn't support GNUARM and IARARM toolchain. Patch with
+ support for IARARM is available at
+ `review.trustedfirmware.org #4574 `__
+
+Known issues
+============
+
+Some open issues exist and will not be fixed in this release.
+
+.. list-table::
+
+ * - | All the supported GNUARM toolchain versions generate corrupt veneer
+ | code for Armv8-M baseline architecture, when the -Os optimization flag
+ | is used. This affects the AN519 and AN539 platforms built with GNUARM
+ | toolchain and Minsizerel build type.
+ - Issue: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646
+
+ * - | PSA Arch Crypto tests have several known failures.
+ - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md
+
+ * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
+ | cause boot failure. This is known issue for AN521 FVP. This will cause
+ | the system to not boot after a warm reset during PSA Arch FF testing.
+ - Issue: https://developer.trustedfirmware.org/T692
+
+ * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312
+ | other than the known failures. This is due to limitation of CC-312
+ | implementation as it does not support MD_NONE hashing mode causing the
+ | additional failures.
+ - Issue: https://developer.trustedfirmware.org/T691
+
+ * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot
+ | is successful and the tests pass if all the associated (PS/ITS/NV
+ | Counter) flash areas are erased.
+ - Issue: https://developer.trustedfirmware.org/T694
+
+ * - | When PS/ITS are using Flash on Musca-B1, PSA Arch FF test fails due to
+ | known warm reset limitation in the platform. There is an issue with
+ | Musca-B1 QSPI flash that causes this failure. The fix is under
+ | investigation.
+ - Issue: https://developer.trustedfirmware.org/T696
+
+Issues fixed since 1.0
+======================
+
+.. list-table::
+
+ * - | The eflash driver on Musca-B1 can return random failures hence
+ | triggering random failures during PSA Arch ITS and PSA Arch PS tests.
+ | This happens when ITS/SST is configured to use flash.
+ - Issue: https://developer.trustedfirmware.org/T697
+
+ * - | Release build of PSA Arch Crypto tests have a different number of tests
+ | when built for AN521 FVP. This is an issue in the PSA Arch Crypto
+ | tests.
+ - Issue for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/releases/1.2.0.rst b/docs/releases/1.2.0.rst
new file mode 100644
index 0000000000..832474db69
--- /dev/null
+++ b/docs/releases/1.2.0.rst
@@ -0,0 +1,142 @@
+*************
+Version 1.2.0
+*************
+
+New features
+============
+
+ - A new build system based on Modern CMake.
+ - First implementation of level 3 isolation on Musca-B1 and AN521.
+ - Remove MCUBoot fork from TF-M.
+ - Move test and app code to tf-m-tests repo.
+ - Add Profile Medium.
+ - Migrate support to Mbed TLS v2.24.
+ - New platforms added.
+ See :ref:`docs/releases/1.2.0:New platforms supported` for
+ details.
+ - New SPM HAL APIs including isolation API and logging API.
+ - Update MCUboot version to 1.7.0-rc1.
+ - Initial ITS/PS HAL for dynamic filesystem configuration.
+ - Remove auto-generated files from the source tree.
+
+New security advisories
+=======================
+
+Stack sealing
+-------------
+
+Refer to :doc:`Advisory TFMV-1`
+for more details.
+A common mitigation is included in this release.
+
+New platforms supported
+=======================
+
+- Cortex-M33 based system:
+
+ - `Nordic nRF9160 DK (nordic_nrf/nrf9160dk_nrf9160).
+ `_
+ - `Nordic nRF5340 PDK (nordic_nrf/nrf5340pdk_nrf5340_cpuapp).
+ `_
+ - `Nordic nRF5340 DK (nordic_nrf/nrf5340dk_nrf5340_cpuapp).
+ `_
+
+- Cortex-M23 based system:
+
+ - `Nuvoton M2351.
+ `_
+
+- Cortex-M55 based system:
+
+ - `Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3).
+ `_
+
+Tested platforms
+================
+
+The following platforms are successfully tested in this release.
+
+ - AN519
+ - AN521
+ - Musca-B1
+ - MPS2 SSE300
+ - PSoC 64
+ - M2351
+ - nrf5340dk
+ - nrf5340pdk
+ - nrf9160dk
+ - LPCXpresso55S69
+ - NUCLEO-L552ZE-Q
+ - STM32L562E-DK
+
+Known issues
+============
+
+Some open issues exist and will not be fixed in this release.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | PSA Arch Crypto tests have several known failures.
+ - See this link for detailed analysis of the failures:
+ https://developer.trustedfirmware.org/w/tf_m/release/psa_arch_crypto_test_failure_analysis_in_tf-m_v1.2_release/
+
+Issues fixed since 1.1
+======================
+
+Issues fixed by TF-M since v1.1 are listed below.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | The eflash driver on Musca-B1 can return random failures hence
+ | triggering random failures during PSA Arch ITS and PSA Arch PS tests.
+ | This happens when ITS/SST is configured to use flash.
+ - https://developer.trustedfirmware.org/T697
+
+Issues closed since 1.1
+=======================
+
+The following issues are closed since v1.1. These issues are related to platform
+hardware limitations or 3rd-party tools and therefore won't be fixed by TF-M.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | All the supported GNUARM toolchain versions generate corrupt veneer
+ | code for Armv8-M baseline architecture, when the -Os optimization flag
+ | is used. This affects the Armv8-M baseline platforms built with GNUARM
+ | toolchain and Minsizerel build type.
+ | It relies on an official release of GNUARM toolchain to fix this issue.
+ - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646
+
+ * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will
+ | cause boot failure. This is a known issue for AN521 FVP. This will
+ | cause the system to fail to boot after a warm reset during PSA Arch FF
+ | testing.
+ - https://developer.trustedfirmware.org/T692
+
+ * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312
+ | other than the known failures. This is due to limitation of CC-312
+ | implementation as it does not support MD_NONE hashing mode causing the
+ | additional failures.
+ - https://developer.trustedfirmware.org/T691
+
+ * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot
+ | is successful and the tests pass if all the associated (PS/ITS/NV
+ | Counter) flash areas are erased.
+ - https://developer.trustedfirmware.org/T694
+
+ * - | If the flash is not erased, boot fails on Musca-B1 when SST is using
+ | flash for Minsizerel config.
+ - https://developer.trustedfirmware.org/T695
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/releases/1.3.0.rst b/docs/releases/1.3.0.rst
new file mode 100644
index 0000000000..e246ad0439
--- /dev/null
+++ b/docs/releases/1.3.0.rst
@@ -0,0 +1,173 @@
+*************
+Version 1.3.0
+*************
+
+New major features
+==================
+
+ - Support stateless RoT Service defined in FF-M 1.1 [1]_.
+ - Support Second-Level Interrupt Handling (SLIH) defined in FF-M 1.1 [1]_.
+ - Add Firmware Update (FWU) secure service, following Platform Security
+ Architecture Firmware Update API [2]_.
+ - Migrate to Mbed TLS v2.25.0.
+ - Update MCUboot version to v1.7.2.
+ - Add a TF-M generic threat model [3]_ .
+ - Implement Fault Injection Handling library to mitigate physical attacks [4]_.
+ - Add Profile Large [5]_.
+ - Enable code sharing between boot loader and TF-M [6]_.
+ - Support Armv8.1-M Privileged Execute Never (PXN) attribute and Thread
+ reentrancy disabled (TRD) feature.
+ - New platforms added.
+ See :ref:`docs/releases/1.3.0:New platforms supported` for
+ details.
+ - Add a TF-M security landing page [7]_.
+ - Enhance dual-cpu non-secure mailbox reference implementation.
+
+New security advisories
+=======================
+
+Invoking secure functions from non-secure handler mode
+------------------------------------------------------
+
+Refer to :doc:`Advisory TFMV-2`
+for more details.
+The mitigation is included in this release.
+
+New platforms supported
+=======================
+
+ - Cortex-M23 based system:
+
+ - `Nuvoton M2354.
+ `_
+
+ - Cortex-M55 based system:
+
+ - `FPGA image loaded on MPS3 board (AN547).
+ `_
+
+ - Secure Enclave system:
+
+ - :doc:`Musca-B1 Secure Enclave. `
+
+Deprecated platforms
+====================
+
+The following platforms have been removed from TF-M code base.
+
+ - SSE-200_AWS
+ - AN539
+
+See :doc:`Platform deprecation and removal `
+for other platforms under deprecation process.
+
+Tested platforms
+================
+
+The following platforms are successfully tested in this release.
+
+- AN519
+- AN521
+- AN524
+- AN547
+- LPCXpresso55S69
+- MPS2 SSE300
+- Musca-B1
+- Musca-B1 Secure Enclave
+- Musca-S1
+- M2351
+- M2354
+- nrf5340dk
+- nrf9160dk
+- NUCLEO-L552ZE-Q
+- PSoC 64
+- STM32L562E-DK
+
+Known issues
+============
+
+Some open issues exist and will not be fixed in this release.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | PSA Arch Crypto test suite have several known failures.
+ - See this `link `_
+ for detailed analysis of the failures.
+
+ * - | Protected Storage Regression test 4001 is stuck on SSE-300 in isolation
+ | level 2 when PXN is enabled.
+ - https://developer.trustedfirmware.org/T902
+
+ * - | IPC Regression test fail when non-secure regression test is enabled and
+ | secure regression test is disabled.
+ - https://developer.trustedfirmware.org/T903
+
+ * - | Panic test in PSA Arch IPC test suite generates inconsistent results
+ | between Armclang and GNUARM.
+ - https://developer.trustedfirmware.org/T909
+
+Issues fixed since 1.2.0
+========================
+
+Issues fixed by TF-M since v1.2.0 are listed below.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | Dual-cpu NS mailbox initialization shall be executed after CMSIS-RTOS
+ | RTX kernel initialization
+ - https://developer.trustedfirmware.org/T904
+
+Issues closed since 1.2.0
+=========================
+
+The following issues are closed since v1.2.0. These issues are related to
+platform hardware limitations or 3rd-party tools and therefore won't be fixed by
+TF-M.
+
+.. list-table::
+
+ * - **Descriptions**
+ - **Issue links**
+
+ * - | ``psa_verify_rsa()`` fails when PSA Crypto processes RSASSA-PSS
+ | algorithm in CryptoCell-312.
+ | Mbed TLS implementation of ``psa_verify_rsa()`` always passes
+ | ``MBEDTLS_MD_NONE`` to ``mbedtls_rsa_rsassa_pss_verify()``.
+ | However, CryptoCell-312 doesn't support MD5 and uses other algorithms
+ | instead. Therefore, Mbed TLS implementation may fail when input
+ | algorithm doesn't match other parameters.
+ - https://github.com/ARMmbed/mbedtls/issues/3990
+
+ * - | Regression tests fail with GNU Arm Embedded toolchain version
+ | 10-2020-q4-major.
+ | The support for CMSE feature is broken in version 10-2020-q4-major. The
+ | fix will be available in future release version.
+ | A note is added in :ref:`docs/getting_started/tfm_sw_requirement:C compilers`.
+ - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157
+
+Reference
+=========
+
+ .. [1] `Arm Firmware Framework for M 1.1 Extensions `_
+
+ .. [2] `PSA Firmware Update API `_
+
+ .. [3] :doc:`TF-M generic threat model `
+
+ .. [4] :doc:`TF-M physical attack mitigation `
+
+ .. [5] :doc:`TF-M Profile Large design `
+
+ .. [6] :doc:`Code sharing between independently linked XIP binaries `
+
+ .. [7] :doc:`Security Handling `
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/releases/index.rst b/docs/releases/index.rst
new file mode 100644
index 0000000000..dc8aecbcd6
--- /dev/null
+++ b/docs/releases/index.rst
@@ -0,0 +1,12 @@
+Releases
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/releases/release_process.rst b/docs/releases/release_process.rst
new file mode 100644
index 0000000000..8b6d1965b1
--- /dev/null
+++ b/docs/releases/release_process.rst
@@ -0,0 +1,42 @@
+Release Cadence and Process
+===========================
+
+Project Release Cadence
+-----------------------
+
+The project currently aims to do a release once every 4 months which will be
+tagged on the master branch. There will be a code freeze (stop merging
+non-essential changes) up to 3 weeks prior to the target release date. The
+release candidates will start appearing after this and only bug fixes or
+updates required for the release will be merged. The maintainers are free
+to use their judgement on what changes are essential for the release.
+
+The release testing will be performed on release candidates and depending on
+issues found, additional release candidates may be created to fix the issues.
+
+::
+
+ |<------------4 months----------->|
+ |<--upto 3 weeks-->| |<--upto 3 weeks-->|
+ +----------------------------------------------------- ----------> time
+ | | | |
+ code freeze ver w.x code freeze ver y.z
+
+Although this document specifies the release cadence, this does not preclude
+an adhoc release for specific project requirements.
+
+Release Version Scheme
+----------------------
+
+Trusted Firmware-M uses a semantic versioning scheme. A version number is
+compiled as a dot separated set of numbers:
+
+**TF-Mv..**
+
+- : Major release version for significant feature and API changes.
+- : Minor release version for incremental features and API changes.
+- : Used only for backporting **critical bug fix/security patches**.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/security/index.rst b/docs/security/index.rst
new file mode 100644
index 0000000000..22bdcba82a
--- /dev/null
+++ b/docs/security/index.rst
@@ -0,0 +1,12 @@
+Security
+========
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ */index
+ *
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/security/security.rst b/docs/security/security.rst
new file mode 100644
index 0000000000..bab72f2fa4
--- /dev/null
+++ b/docs/security/security.rst
@@ -0,0 +1,65 @@
+Security Handling
+=================
+
+Security Disclosures
+--------------------
+
+Trusted Firmware-M(TF-M) disclose all security vulnerabilities, or are advised
+about, that are relevant to TF-M. TF-M encourage responsible disclosure of
+vulnerabilities and try the best to inform users about all possible issues.
+
+The TF-M vulnerabilities are disclosed as Security Advisories, all of which are
+listed at the bottom of this page.
+
+Found a Security Issue?
+-----------------------
+
+Although TF-M try to keep secure, it can only do so with the help of the
+community of developers and security researchers.
+
+.. warning::
+ If any security vulnerability was found, please **do not**
+ report it in the `issue tracker`_ or on the `mailing list`_. Instead, please
+ follow the `TrustedFirmware.org security incident process`_.
+
+One of the goals of this process is to ensure providers of products that use
+TF-M have a chance to consider the implications of the vulnerability and its
+remedy before it is made public. As such, please follow the disclosure plan
+outlined in the `Security Incident Process`_. TF-M do the best to respond and
+fix any issues quickly.
+
+Afterwards, write-up all the findings about the TF-M source code is highly
+encouraged.
+
+Attribution
+-----------
+
+TF-M values researchers and community members who report vulnerabilities and
+TF-M policy is to credit the contributor's name in the published security advisory.
+
+Security Advisories
+-------------------
+
++------------+-----------------------------------------------------------------+
+| ID | Title |
++============+=================================================================+
+| |TFMV-1| | NS world may cause the CPU to perform an unexpected return |
+| | operation due to unsealed stacks. |
++------------+-----------------------------------------------------------------+
+| |TFMV-2| | Invoking Secure functions from handler mode may cause TF-M IPC |
+| | model to behave unexpectedly. |
++------------+-----------------------------------------------------------------+
+
+.. _issue tracker: https://developer.trustedfirmware.org/project/view/2/
+.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-m
+
+.. |TFMV-1| replace:: :ref:`docs/security/security_advisories/stack_seal_vulnerability:Advisory TFMV-1`
+.. |TFMV-2| replace:: :ref:`docs/security/security_advisories/svc_caller_sp_fetching_vulnerability:Advisory TFMV-2`
+
+.. _TrustedFirmware.org security incident process: https://developer.trustedfirmware.org/w/collaboration/security_center/
+
+.. _Security Incident Process: https://developer.trustedfirmware.org/w/collaboration/security_center/reporting/
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/security/security_advisories/index.rst b/docs/security/security_advisories/index.rst
new file mode 100644
index 0000000000..85119084e2
--- /dev/null
+++ b/docs/security/security_advisories/index.rst
@@ -0,0 +1,12 @@
+Security Advisories
+===================
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/security/security_advisories/stack_seal_vulnerability.rst b/docs/security/security_advisories/stack_seal_vulnerability.rst
new file mode 100644
index 0000000000..2bf9d1a254
--- /dev/null
+++ b/docs/security/security_advisories/stack_seal_vulnerability.rst
@@ -0,0 +1,113 @@
+Advisory TFMV-1
+===============
+
++----------------+-------------------------------------------------------------+
+| Title | NS world may cause the CPU to perform an unexpected return |
+| | operation due to unsealed stacks. |
++================+=============================================================+
+| CVE ID | CVE-2020-16273 |
++----------------+-------------------------------------------------------------+
+| Date | 16 October 2020 |
++----------------+-------------------------------------------------------------+
+| Versions | All versions up to and including TF-M v1.1 |
+| Affected | |
++----------------+-------------------------------------------------------------+
+| Configurations | All |
++----------------+-------------------------------------------------------------+
+| Impact | Most likely a crash in secure world with a very low |
+| | likelihood of hijacking secure world execution flow via a |
+| | separate vulnerability. |
++----------------+-------------------------------------------------------------+
+| Fix Version | commit `92e46a3abd0e328fac29ccd1cf161cd482397567`_ |
++----------------+-------------------------------------------------------------+
+| Credit | Matvey Mukha |
++----------------+-------------------------------------------------------------+
+
+Background
+----------
+
+When the Non-Secure world returns to Secure after a callback (FNC_RETURN) or
+Non-Secure interrupt handling (EXC_RETURN), the hardware pops the secure return
+address and RET_PSR from the respective secure stack. The hardware performs a
+set of integrity checks at this point and will raise a fault if the checks
+fail. There is a potential vulnerability if the NS attempts a wrong FNC_RETURN
+or EXC_RETURN and causes the PE to pop from the unexpected stack. Please
+refer to `ARMv8-M Secure stack sealing advisory notice`_ for more
+details on the vulnerability.
+
+To prevent such an attack, the architecture expects the secure software to
+`seal` the stacks. The `ARMv8-M ARM`_ states that the stack should be sealed
+with the special value, 0xFEF5EDA5 (informative IGJGL).
+
+Both the MSP_S and the PSP_S stacks need to be sealed to mitigate stack
+underflow attacks and this is not done currently in TF-M.
+
+Impact
+------
+
+This section analyses the impact of this vulnerability on the upstream
+TF-M implementation.
+
+All requests coming in from the Non-Secure world uses ARM_LIB_STACK as the
+PSP_S and then switches to MSP_S as part of SPM scheduling. The MSP_S is fully
+unwound when the scheduled partition is executing. All partitions run using
+the PSP_S and this stack can be separate for each partition or be a common
+stack depending on whether TF-M is in library mode or IPC mode. When the
+partition execution using PSP_S switches to non-secure world due to a
+non-secure interrupt or a non-secure callback invocation, the non-secure
+world on return back to secure can use a fake EXC_RETURN or FNC_RETURN
+operation to trigger an MSP_S stack underflow, and the CPU could fetch
+the return PC and PSR from the memory just above MSP_S stack (stack grows
+from higher to lower address).
+
+The memory above MSP_S is the ARM_LIB_STACK (as described by
+tfm_common_s.sct/ld), which because of overlaying or zero initialization
+is most likely to be initialized memory for most platforms. This is the stack
+used to run the initialization code of TF-M and usually there will some
+unused free space in the stack. Any underflow of MSP_S will be into this stack
+and hence is likely to be a deterministic crash given that this memory is
+initialized. In theory, a separate vulnerability that allows an attacker to
+control the memory above MSP_S in concert with this vulnerability could
+enable an attacker to hijack the secure world execution flow but the
+likelihood of that is very low.
+
+Through analysing TF-M specific initialization and execution flow, we have
+not found any scenario in TF-M in which Non-secure world can fake a return
+operation back to secure world and cause underflow of PSP_S.
+
+As described in the white paper, de-privileged interrupt handling is
+also vulnerable to this problem. The Library mode of TF-M uses de-privileged
+interrupt handling and does not allow non-secure interrupt to pre-empt the
+secure interrupt handling. But if the de-privileged handler makes a
+Non-Secure callback then there is a chance that Non-Secure world could
+return back to Secure world via a fake FNC_RETURN. Under certain
+conditions, this can force the CPU to use the 2 words on top of stack as
+return PC and PSR. Sealing the top of MSP_S before switching to PSP_S as
+part of de-privileged interrupt handling mitigates this vulnerability.
+
+The interrupt handling in IPC mode uses PSA signal to signal the partition
+and does not use de-privileged interrupt handling mechanism. The PSA signal
+gets handled by the partition when it is scheduled to run by the SPM. Hence
+during interrupt handling in IPC mode, there is no additional threat caused
+by this vulnerability, compared to regular partition execution.
+
+Conclusion
+----------
+
+Overall, from analysis of upstream TF-M implementation, the severity of this
+vulnerability is low, given that the values popped out from secure stack
+(either via underflow of MSP_S or from top of MSP_S stack in de-privileged
+interrupt handling) cannot be influenced by the Non Secure world. To mitigate
+the risk completely, the fix in TF-M is to follow the recommendation in
+`ARMv8-M ARM`_ which is to seal the base of both handler mode stack (MSP_S)
+and thread stacks (PSP_S) and, in case of library mode, also seal the top
+of MSP_S before handing control over to de-privileged interrupt handler.
+
+
+.. _ARMv8-M ARM: https://developer.arm.com/documentation/ddi0553/latest
+.. _ARMv8-M Secure stack sealing advisory notice: https://developer.arm.com/support/arm-security-updates/armv8-m-stack-sealing
+.. _92e46a3abd0e328fac29ccd1cf161cd482397567: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=92e46a3abd0e328fac29ccd1cf161cd482397567
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst b/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst
new file mode 100644
index 0000000000..4a117243fe
--- /dev/null
+++ b/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst
@@ -0,0 +1,125 @@
+Advisory TFMV-2
+===============
+
++----------------+-------------------------------------------------------------+
+| Title | Invoking Secure functions from handler mode may cause TF-M |
+| | IPC model to behave unexpectedly. |
++================+=============================================================+
+| CVE ID | CVE-2021-27562 |
++----------------+-------------------------------------------------------------+
+| Date | Mar 5, 2021 |
++----------------+-------------------------------------------------------------+
+| Versions | Affected All versions up to and including TF-M v1.2 |
+| Affected | |
++----------------+-------------------------------------------------------------+
+| Configurations | IPC Model (TFM_PSA_API=ON) on Armv8-M |
++----------------+-------------------------------------------------------------+
+| Impact | Most likely a crash in secure world or reset whole system, |
+| | with a very low likelihood of overwriting some memory |
+| | contents. |
++----------------+-------------------------------------------------------------+
+| Fix Version | commit `e212ea1637a66255b44d0e7c19ebe9786ab56ccb`_ |
++----------------+-------------------------------------------------------------+
+| Credit | Øyvind Rønningstad, |
+| | Senior SW Engineer from Nordic Semiconductor |
++----------------+-------------------------------------------------------------+
+
+Background
+----------
+
+When a non-secure caller calls the secure function, the execution switches the
+security state via Secure Gateway (SG), then arrived at the TF-M secure entry
+if the SG is successful. After SG, TF-M invokes SVC to SPM at first because SPM
+handles requests from SPE and NSPE in a unified SVC handler. The TF-M SVC
+handler code relies on the 'SPSEL' bit in 'EXC_RETURN' to get the caller stack
+pointer:
+
+.. code-block:: asm
+
+ ; Armv8m mainline as the example
+ mrs r2, msp ; r2 = msp;
+ tst lr, #4 ; EXC_RETURN.SPSEL == ?
+ ite eq ; condition preparation
+ moveq r0, r2 ; if (EXC_RETURN.SPSEL == 0) r0 = msp;
+ movne r0, psp ; if (EXC_RETURN.SPSEL == 1) r0 = psp;
+ mov r1, lr ; r1 = EXC_RETURN;
+ bl tfm_core_svc_handler ; r0 = sp(context), r1 = EXC_RETURN, r2 = msp
+
+If NSPE calls the secure function in 'Handler mode', the TF-M secure entry runs
+in 'Handler mode' before invoking SVC because PE mode does not change during
+the transition from non-secure state to secure state via the successful SG.
+Main stack pointer (MSP) is always used in 'Handler mode', which is irrelevant
+to the value of SPSEL. However, the code above selects secure process stack
+pointer (PSP_S, S suffix here indicates the security state) for further SVC
+handling based on EXC_RETURN.SPSEL, hence the SVC handler accesses the wrong
+stack for handling the request in the NSPE caller in 'Handler mode' case.
+To prevent this vulnerability, TF-M secure SVC handler should fetch the right
+stack pointer register by checking both the PE mode and SPSEL bit. The handler
+should also prevent callers in non-secure `Handler mode` from calling TF-M
+SVC functionalities. The following section analysis impact of the IPC model.
+Library model is not vulnerable to this attack because it checks the PE mode
+in the TF-M secure entry.
+
+Impact
+------
+
+When the vulnerability is happening, PSP_S is the incorrect stack pointer
+fetched, the impact is decided by the content PSP_S is pointing to. The SVC
+handler gets the SVC number by referencing the memory at the 2 bytes subtracted
+position of member 'Return Address' in the PSP_S pointing context, and uses the
+caller saved registers in the context as parameters for the subsequent
+functions indicated by the SVC number. The PSP_S may point to the bottom
+(higher address) of secure thread stack if there is no ongoing secure function
+call, or it points to a preempted context caused by non-secure preempting
+secure execution.
+When PSP_S is pointing to the stack bottom when this issue happens, the caller
+context is pointing to the underflowed stack of which the top 2 words are stack
+seal, and the rest of the context is unpredictable. These underflowed content
+are ZERO initialized for most platforms, hence when fetching the SVC Number at
+memory address 'Return Address - 2', a 'MemFault' or 'HardFault' would happen.
+Even if a valid SVC number is returned, the stack seal values are part of the
+parameters for the subsequent functions that have parameters, which cannot pass
+the validation for the parameters.
+When PSP_S is pointing to a preempted context, the preempted place can be the
+TF-M secure entry area or internal thread space. If the preemption happens when
+the execution is in the TF-M secure entry area, the PSP_S will point to an NS
+preemption stack frame and hence will fail the context size validation through
+this entry into TF-M SVC Handler. In the other scenario that TF-M internal
+thread is preempted, there is a very remote chance that the exception stack
+frame will contain a context with a valid SVC Number with valid parameters.
+As a summary, the impacts of the vulnerability depend on whether an SVC number
+could be fetched from the incorrect stack and what operation the fetched SVC
+number corresponds to:
+
+- A memory access fault when fetching the SVC number from memory. This fault
+ halts the whole system. A reset can recover the system back to normal.
+- The SVC number corresponds to the initialization process in TF-M. SPM
+ initialization is called for the second time. This re-initialization process
+ will fail and halt the whole system. A reset can recover the system back to
+ normal.
+- The SVC number corresponds to the boot data fetching function. If the
+ unpredictable data in stack triggers boot data fetching and passes the
+ parameter validation under a very rare case, boot data is copied into an
+ unpredictable memory address. One note here, the TF-M default boot data has
+ no sensitive information.
+- The SVC number corresponds to the log output function. If the unpredictable
+ data in stack triggers log output under a very rare case, secure data at
+ unpredictable address might be printed out through the log interface.
+- The SVC number corresponds to other valid numbers other than above. The
+ system resets because of parameter validation fail.
+
+Conclusion
+----------
+
+Overall, from the analysis of upstream TF-M implementation, the severity of
+this vulnerability is Medium, given that a software crash or system reset
+happen most of the time. The probability for causing secure data leakage via
+log output or tampering of secure memory with boot data is extremely low as the
+TF-M internal thread exception stack frame contents have to pass all the
+validations performed by SPM.
+
+.. _e212ea1637a66255b44d0e7c19ebe9786ab56ccb: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=e212ea1637a66255b44d0e7c19ebe9786ab56ccb
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/security/threat_models/TF-M-block-diagram.png b/docs/security/threat_models/TF-M-block-diagram.png
new file mode 100644
index 0000000000..e5d0371e26
Binary files /dev/null and b/docs/security/threat_models/TF-M-block-diagram.png differ
diff --git a/docs/security/threat_models/generic_threat_model.rst b/docs/security/threat_models/generic_threat_model.rst
new file mode 100644
index 0000000000..5659c243ea
--- /dev/null
+++ b/docs/security/threat_models/generic_threat_model.rst
@@ -0,0 +1,1130 @@
+#######################################
+Trusted Firmware-M Generic Threat Model
+#######################################
+
+************
+Introduction
+************
+
+This document introduces a generic thread model of Trusted Firmware-M (TF-M).
+This generic thread model provides an overall analysis of TF-M implementation
+and identifies general threats and mitigation.
+
+.. note::
+
+ If you think a security vulnerability is found, please follow
+ Trustedfirmware.org [Security-Incident-Process]_ to contact TF-M security
+ team.
+
+Scope
+=====
+
+TF-M supports diverse models and topologies. It also implements multiple
+isolation levels. Each case may focus on different target of evaluation (TOE)
+and identify different assets and threats.
+TF-M implementation consists of several secure services, defined as
+Root of Trust (RoT) service. Those RoT services belong to diverse RoT
+(Application RoT or PSA RoT) and access different assets and hardware. Therefore
+each RoT service may require a dedicated threat model.
+
+The analysis on specific models, topologies or RoT services may be covered in
+dedicated thread model documents. Those threat models are out of the scope of
+this document.
+
+Methodology
+===========
+
+The threat modeling in this document follows the process listed below to
+build up the threat model.
+
+- Target of Evaluation (TOE)
+- Assets identification
+- Data Flow Diagram (DFD)
+- Threats Prioritization
+- Threats identification
+
+TOE is the entity on which threat modeling is performed. The logic behind this
+process is to firstly investigate the TOE which could be a system, solution or
+use case. This first step helps to identify the assets to be protected in TOE.
+
+According to TOE and assets, Trust Boundaries can be determined. The Data Flow
+Diagram (DFD) across Trust Boundaries is then defined to help identify the
+threats.
+
+Those threats should be prioritized based on a specific group of principals and
+metrics. The principals and metrics should also be specified.
+
+********************
+Target of Evaluation
+********************
+
+A typical TF-M system diagram from a high-level overview is shown below. TF-M is
+running in the Secure Processing Environment (SPE) and NS software is running in
+Non-secure Processing Environment (NSPE). For more details, please refer to
+Platform Security Architecture Firmware Framework for M (FF-M) [FF-M]_.
+
+.. figure:: TF-M-block-diagram.png
+
+The TOE in this general model is the SPE, including TF-M and other components
+running in SPE.
+
+The TOE can vary in different TF-M models, RoT services and usage scenarios.
+Refer to dedicated thread models for the specific TOE definitions.
+
+********************
+Asset identification
+********************
+
+In this threat model, assets include the general items listed below:
+
+- Hardware Root of Trust data, e.g.
+
+ - Hardware Unique Key (HUK)
+ - Root authentication key
+ - Other embedded root keys
+
+- Software RoT data, e.g.
+
+ - Secure Partition Manager (SPM) code and data
+ - Secure partition code and data
+ - NSPE data stored in SPE
+ - Data generated in SPE as requested by NSPE
+
+- Availability of entire RoT service
+
+- Secure logs, including event logs
+
+Assets may vary in different use cases and implementations. Additional assets
+can be defined in an actual usage scenario and a dedicated threat model.
+
+For example, in a network camera use case, the following data can be defined as
+assets too:
+
+- Certificate for connecting to cloud
+- Session keys for encryption/decryption in the communication with cloud
+- Keys to encrypt/decrypt the videos and photos
+
+*****************
+Data Flow Diagram
+*****************
+
+The Trust Boundary isolates SPE from NSPE, according to the TOE definition in
+`Target of Evaluation`_. The Trust Boundary mapped to block diagram is shown
+in the figure below. Other modules inside SPE stay in the same TOE as TF-M does.
+
+Valid Data flows across the Trust Boundary are also shown in the figure below.
+This thread model only focuses on the data flows related to TF-M.
+
+.. figure:: overall-DFD.png
+
+More details of data flows are listed below.
+
+.. _data-flow-table:
+
+.. table:: TF-M Data Flows between NSPE and SPE
+
+ +-----------+----------------------------------------------------------------+
+ | Data flow | Description |
+ +===========+================================================================+
+ | ``DF1`` | TF-M initializes NS entry and activates NSPE. |
+ | | |
+ | | - On single Armv8-M core platforms, TF-M will hand over the |
+ | | control to Non-secure state. |
+ | | - On dual-cpu platforms, Secure core starts NS core booting. |
+ +-----------+----------------------------------------------------------------+
+ | ``DF2`` | NSPE requests TF-M RoT services. |
+ | | |
+ | | - In TF-M Library model, NS invokes Secure Function calls |
+ | | - In TF-M IPC model, NS invokes PSA Client calls based on IPC |
+ | | protocol defined in [FF-M]_. |
+ | | |
+ | | In single Armv8-M core scenarios, SG instruction is executed |
+ | | in Non-secure Callable region to trigger a transition from |
+ | | Non-secure state to Secure state. |
+ | | |
+ | | On dual-cpu platforms, non-secure core sends PSA Client calls |
+ | | to secure core via mailbox. |
+ +-----------+----------------------------------------------------------------+
+ | ``DF3`` | Secure Partitions fetch input data from NS and write back |
+ | | output data to NS. |
+ | | |
+ | | In TF-M IPC model, as required in [FF-M]_, Secure Partitions |
+ | | should not directly access NSPE memory. Instead, RoT services |
+ | | relies on TF-M SPM to access NSPE memory. |
+ +-----------+----------------------------------------------------------------+
+ | ``DF4`` | TF-M returns RoT service results to NSPE after NS request to |
+ | | RoT service is completed. |
+ | | |
+ | | In single Armv8-M core scenarios, it also trigger a transition |
+ | | from Secure state back to Non-secure state. |
+ | | |
+ | | On dual-cpu platforms, secure core returns the result to |
+ | | non-secure core via mailbox. |
+ +-----------+----------------------------------------------------------------+
+ | ``DF5`` | Non-secure interrupts preempt SPE execution in single Armv8-M |
+ | | core scenarios. |
+ +-----------+----------------------------------------------------------------+
+ | ``DF6`` | Secure interrupts preempt NSPE execution in single Armv8-M |
+ | | core scenarios. |
+ +-----------+----------------------------------------------------------------+
+
+.. note::
+
+ All the other data flows across the Trusted Boundary besides the valid ones
+ mentioned above should be prohibited by default.
+ Proper isolation must be configured to prevent NSPE directly accessing SPE.
+
+ Threats irrelevant to data flows in
+ :ref:`TF-M Data Flows between NSPE and SPE ` may be specified
+ in `Miscellaneous threats`_.
+
+Data flows inside SPE (informative)
+===================================
+
+Since all the SPE components stay in the TOE within the same Trust Boundary in
+this threat model, the data flows between SPE components are not covered in this
+threat model. Instead, those data flows and corresponding threats will be
+identified in the dedicated threat model documents of TF-M RoT services and
+usage scenarios.
+
+Those data flows inside SPE include following examples:
+
+- Data flows between TF-M and BL2
+- Data flows between RoT services and SPM
+- Data flows between RoT services and corresponding secure hardware and assets,
+ such as secure storage device, crypto hardware accelerator and Hardware Unique
+ Key (HUK).
+
+*********************
+Threat identification
+*********************
+
+Threat priority
+===============
+
+Threat priority is indicated by the score calculated via Common Vulnerability
+Scoring System (CVSS) Version 3.1 [CVSS]_. The higher the threat scores, the
+greater severity the threat is with and the higher the priority is.
+
+CVSS scores can be mapped to qualitative severity ratings defined in CVSS 3.1
+specification [CVSS_SPEC]_. This threat model follows the same mapping between
+CVSS scores and threat priority rating.
+
+As a generic threat model, this document focuses on *Base Score* which reflects
+the constant and general severity of a threat according to its intrinsic
+characteristics.
+
+The *Impacted Component* defined in [CVSS_SPEC]_ refers to the assets listed in
+`Asset identification`_.
+
+Threats and mitigation list
+===========================
+
+This section lists generic threats and corresponding mitigation, based on the
+the analysis of data flows in `Data Flow Diagram`_.
+
+Threats are identified following ``STRIDE`` model. Please refer to [STRIDE]_ for
+more details.
+
+The field ``CVSS Score`` reflects the threat priority defined in
+`Threat priority`_. The field ``CVSS Vector String`` contains the textual
+representation of the CVSS metric values used to score the threat. Refer to
+[CVSS_SPEC]_ for more details of CVSS vector string.
+
+.. note::
+
+ A generic threat may have different behaviors and therefore require different
+ mitigation, in diverse TF-M models and usage scenarios.
+
+ This threat model document focuses on general analysis of the following
+ threats. For the details in a specific configuration and usage scenario,
+ please refer to the dedicated threat model document.
+
+NS entry initialization
+-----------------------
+
+This section identifies threats on ``DF1`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-GENERIC-NS-INIT-T-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-T-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | The NS image can be tampered by an attacker |
+ +---------------+------------------------------------------------------------+
+ | Justification | An attack may tamper the NS image to inject malicious code |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | By default TF-M relies on MCUBoot to validate NS image. |
+ | | The validation of NS image integrity and authenticity is |
+ | | completed in secure boot before jumping to NS entry or |
+ | | booting up NS core. |
+ | | Refer to [SECURE-BOOT]_ for more details. |
+ | | |
+ | | The validation may vary in diverse vendor platforms |
+ | | specific Chain of Trust (CoT) implementation. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 3.5 (Low) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INIT-T-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-T-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may replace the current NS image with an older |
+ | | version. |
+ +---------------+------------------------------------------------------------+
+ | Justification | The attacker downgrades the NS image with an older version |
+ | | which has been deprecated due to known security issues. |
+ | | |
+ | | The older version image can pass the image signature |
+ | | validation and its vulnerabilities can be exploited by |
+ | | attackers. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M relies on MCUBoot to perform anti-rollback |
+ | | protection. |
+ | | |
+ | | TF-M defines a non-volatile counter API to support |
+ | | anti-rollback. Each platform must implement it using |
+ | | specific trusted hardware non-volatile counters. |
+ | | For more details, refer to [ROLLBACK-PROTECT]_. |
+ | | |
+ | | The anti-rollback protection implementation can vary on |
+ | | diverse platforms. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 3.5 (Low) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INIT-T-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-T-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | If SPE doesn't complete isolation configuration before |
+ | | NSPE starts, NSPE can access secure regions which it is |
+ | | disallowed to. |
+ +---------------+------------------------------------------------------------+
+ | Justification | Secure data can be tampered or disclosed if NSPE is |
+ | | activated and accesses secure regions before isolation |
+ | | configuration is completed by SPE. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering/Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | SPE must complete and enable proper isolation to protect |
+ | | secure regions from being accessed by NSPE, before jumping |
+ | | to NS entry or booting up NS core. |
+ | | |
+ | | TF-M executes isolation configuration at early stage of |
+ | | secure initialization before NS initialization starts. |
+ | | |
+ | | On dual-cpu platform, platform specific initialization |
+ | | must halt NS core until isolation is completed, as defined |
+ | | in [DUAL-CPU-BOOT]_. |
+ | | |
+ | | TF-M defines isolation configuration HALs for platform |
+ | | implementation. The specific isolation configuration |
+ | | depends on platform specific implementation. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 9.0 (Critical) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INIT-T-I-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-T-I-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | If SPE doesn't complete isolation configuration before |
+ | | NSPE starts, NSPE can control devices or peripherals which |
+ | | it is disallowed to. |
+ +---------------+------------------------------------------------------------+
+ | Justification | On some platforms, devices and peripherals can be |
+ | | configured as Secure state in runtime. If security status |
+ | | configuration of those device and peripherals are not |
+ | | properly completed before NSPE starts, NSPE can control |
+ | | those device and peripherals and may be able to tamper |
+ | | data or access secure data. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering/Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | SPE must complete and enable proper configuration and |
+ | | isolation to protect critical devices and peripherals from |
+ | | being accessed by NSPE, before jumping to NS entry or |
+ | | booting up NS core. |
+ | | |
+ | | TF-M executes isolation configuration of devices and |
+ | | peripherals at early stage of secure initialization before |
+ | | NS initialization starts. |
+ | | |
+ | | The specific isolation configuration depends on platform |
+ | | specific implementation. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 9.0 (Critical) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INIT-I-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-I-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | If SPE leaves some SPE information in non-secure memory |
+ | | or shared registers when NSPE starts, NSPE may access |
+ | | those SPE information. |
+ +---------------+------------------------------------------------------------+
+ | Justification | If NSPE can access those SPE information from shared |
+ | | registers or non-secure memory, secure information may be |
+ | | disclosed. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | SPE must clean up the secure information from shared |
+ | | registers before NS starts. |
+ | | |
+ | | TF-M invalidates registers not banked before handing over |
+ | | the system to NSPE on single Armv8-M platform. |
+ | | |
+ | | On dual-cpu platforms, shared registers are implementation |
+ | | defined, such as Inter-Processor Communication registers. |
+ | | Dual-cpu platforms must not store any data which may |
+ | | disclose secure information in the shared registers. |
+ | | |
+ | | SPE must avoid storing SPE information in non-secure |
+ | | memory. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.3 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INIT-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INIT-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may block NS to boot up |
+ +---------------+------------------------------------------------------------+
+ | Justification | An attacker may block NS to boot up, such as by corrupting |
+ | | NS image, to stop the whole system from performing normal |
+ | | functionalities. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | No SPE information will be disclosed and TF-M won't be |
+ | | directly impacted. |
+ | | |
+ | | It relies on NSPE and platform specific implementation to |
+ | | mitigate this threat. It is out of scope of this threat |
+ | | model. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.0 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+NSPE requests TF-M secure service
+---------------------------------
+
+This section identifies threats on ``DF2`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-S-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-S-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may pretend as a secure client |
+ | | to access secure data which NSPE must not directly access. |
+ +---------------+------------------------------------------------------------+
+ | Justification | [FF-M]_ defines ``Client ID`` to distinguish clients which |
+ | | request RoT services. Secure clients are assigned with |
+ | | positive IDs and non-secure clients are assigned with |
+ | | negative ones. |
+ | | |
+ | | A malicious NS application may provide a positive |
+ | | ``Client ID`` to pretend as a secure client to access |
+ | | secure data. |
+ +---------------+------------------------------------------------------------+
+ | Category | Spoofing |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M checks the ``Client ID`` from NSPE. If the NS |
+ | | ``Client ID`` is not a valid one, TF-M will report this as |
+ | | a security error. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 8.4 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-T-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-T-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker in NSPE may tamper the service request input |
+ | | or output vectors between check and use |
+ | | (Time-Of-Check-to-Time-Of-Use (TOCTOU)). |
+ +---------------+------------------------------------------------------------+
+ | Justification | If SPE validates the content in input/output vectors |
+ | | locally in NSPE memory, an attacker in NSPE can have a |
+ | | chance to tamper the content after the validation |
+ | | successfully passes. Then SPE will provide RoT service |
+ | | according to the corrupted parameters and it may cause |
+ | | further security issues. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | In TF-M implementation, the validation of NS input/output |
+ | | vectors are only executed after those vectors are copied |
+ | | from NSPE into SPE. It prevents an attack from NSPE to |
+ | | tamper those parameters after validation in TF-M. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 7.8 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:H/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-T-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-T-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may request to tamper data |
+ | | belonging to SPE. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A malicious NS application may request SPE RoT services to |
+ | | write malicious value to SPE data. The malicious NS |
+ | | application may try to tamper SPE assets, such as keys, or |
+ | | modify configurations in SPE. The SPE data belongs to |
+ | | components in SPE and must not be accessed by NSPE. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M executes memory access check to all the RoT service |
+ | | requests. If a request doesn't have enough permission to |
+ | | access the target memory region, TF-M will refuse this |
+ | | request and assert a security error. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 7.1 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-R-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-R-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A NS application may repudiate that it has requested |
+ | | services from a RoT service. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A malicious NS application may call a RoT service to |
+ | | access critical data in SPE, which it is disallowed to, |
+ | | via a non-public vulnerability. It may refuse to admit |
+ | | that it has accessed that data. |
+ +---------------+------------------------------------------------------------+
+ | Category | Repudiation |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M implements an event logging secure service to record |
+ | | the critical events, such as the access to critical data. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 0.0 (None) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may request to read data |
+ | | belonging to SPE. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A malicious NS application may request SPE RoT services to |
+ | | copy SPE data to NS memory. The SPE data belongs to |
+ | | components in SPE and must not be disclosed to NSPE, such |
+ | | as root keys. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M executes memory access check to all the RoT service |
+ | | requests. If a request doesn't have enough permission to |
+ | | access the target memory region, TF-M will refuse this |
+ | | request and assert a security error. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 7.1 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-T-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-T-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may request to control secure |
+ | | device and peripherals, on which it doesn't have the |
+ | | permission. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A malicious NS application may request RoT services to |
+ | | control secure device and peripherals, on which it doesn't |
+ | | have the permission. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering/Information disclose |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M performs client check to validate whether the client |
+ | | has the permission to access the secure device and |
+ | | peripherals. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 9.0 (Critical) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | A Malicious NS applications may frequently call secure |
+ | | services to block secure service requests from other NS |
+ | | applications. |
+ +---------------+------------------------------------------------------------+
+ | Justification | TF-M runs on IoT devices with constrained resource. Even |
+ | | though multiple outstanding NS PSA Client calls can be |
+ | | supported in system, the number of NS PSA client calls |
+ | | served by TF-M simultaneously are still limited. |
+ | | |
+ | | Therefore, if a malicious NS application or multiple |
+ | | malicious NS applications continue calling TF-M secure |
+ | | services frequently, it may block other NS applications to |
+ | | request secure service from TF-M. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M is unable to manage behavior of NS applications. |
+ | | Assets are not disclosed and TF-M is neither directly |
+ | | impacted in this threat. |
+ | | |
+ | | It relies on NS OS to enhance scheduling policy and |
+ | | prevent a single NS application to occupy entire CPU time. |
+ | | It is beyond the scope of this threat model. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.0 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-REQUEST-SERVICE-D-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-REQUEST-SERVICE-D-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may provide invalid NS memory |
+ | | addresses as the addresses of input and output data in RoT |
+ | | service requests. |
+ +---------------+------------------------------------------------------------+
+ | Justification | SPE may be unable to achieve full knowledge of NS memory |
+ | | mapping. SPE may fail to capture those invalid NS memory |
+ | | addresses during memory access check since those invalid |
+ | | addresses may not be included in isolation configuration. |
+ | | |
+ | | In that case, SPE will access those invalid NS memory |
+ | | addresses later to read or write data. It may trigger a |
+ | | system error to crash the whole system immediately. |
+ | | |
+ | | The malicious NS application may be blocked by NS MPU from |
+ | | directly accessing that invalid NS memory address. But it |
+ | | may manipulate SPE to access that address instead. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M executes memory access check to the memory addresses |
+ | | in all the NS requests. |
+ | | |
+ | | On single Armv8-M core platforms, TF-M invokes ``TT`` |
+ | | instructions to execute memory address check. If a NS |
+ | | memory area is not matched in any valid SAU or MPU region, |
+ | | it will be marked as invalid and any access permission is |
+ | | disallowed. Therefore, SPM will reject any NS request |
+ | | containing invalid NS memory addresses and reports it as |
+ | | as a security error. |
+ | | |
+ | | On dual-core platforms, TF-M implements a default memory |
+ | | access check. If a NS memory area is not found in any |
+ | | memory region configured for isolation, it will be marked |
+ | | as invalid and therefore SPM will reject the corresponding |
+ | | NS request. It will be reported as a security error. |
+ | | |
+ | | Dual-core platforms may implement platform specific memory |
+ | | check to replace the default one. It relies on platform |
+ | | specific implementation to capture invalid memory address. |
+ | | It is out of the scope of this document. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 3.2 (Low) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:N/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+RoT services read and write NS data
+-----------------------------------
+
+This section identifies threats on ``DF3`` defined in `Data Flow Diagram`_.
+
+According to [FF-M]_, in TF-M IPC model, RoT services should rely on TF-M SPM to
+obtain NS input data and send response data back to NS memory.
+
+In Library model, RoT services directly read and write NS memory to simplify the
+implementation and decrease latency.
+
+.. _TFM-GENERIC-SECURE-SERVICE-RW-T-1:
+
+.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may tamper NS input data while the RoT service |
+ | | is processing those data. |
+ +---------------+------------------------------------------------------------+
+ | Justification | A RoT service may access NS input data multiple times |
+ | | during its data processing. For example, it may validate |
+ | | or authenticate the NS input data before it performs |
+ | | further processing. |
+ | | |
+ | | If the NS input data remains in NSPE memory during the RoT |
+ | | service execution, an attacker may tamper the NS input |
+ | | data in NSPE memory after the validation passes. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | In TF-M IPC model, RoT services request SPM to read and |
+ | | write NS data. TF-M SPM follows [FF-M]_ to copy the NS |
+ | | input data into SPE memory region owned by the RoT |
+ | | service, before the RoT service processes the data. |
+ | | Therefore, the NS input data is protected during the RoT |
+ | | service execution from being tampered. |
+ | | |
+ | | In TF-M Library model, RoT services can directly access NS |
+ | | memory. If a RoT service accesses NS input data multiple |
+ | | times during data processing, it is required to review and |
+ | | confirm Library model implementation of the RoT service |
+ | | copies NS input data into SPE memory area before it |
+ | | processes the data. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 3.2 (Low) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. _TFM-GENERIC-SECURE-SERVICE-RW-T-2:
+
+.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-2
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-2** |
+ +---------------+------------------------------------------------------------+
+ | Description | A malicious NS application may embed secure memory |
+ | | addresses into a structure in RoT service request input |
+ | | vectors, to tamper secure memory which the NS application |
+ | | must not access. |
+ +---------------+------------------------------------------------------------+
+ | Justification | [FF-M]_ limits the total number of input/output vectors to |
+ | | 4. If a RoT service requires more input/output vectors, it |
+ | | may define a parameter structure which embeds multiple |
+ | | input/output buffers addresses. |
+ | | |
+ | | However, as a potential security risk, a malicious NS |
+ | | application can put secure memory addresses into a valid |
+ | | parameter structure to bypass TF-M validation on those |
+ | | memory addresses. |
+ | | |
+ | | The parameter structure can pass TF-M memory access check |
+ | | since itself is valid. However, if the RoT service parses |
+ | | the structure and directly write malicious data from NSPE |
+ | | to the secure memory addresses in parameter structure, the |
+ | | secure data will be tampered. |
+ +---------------+------------------------------------------------------------+
+ | Category | Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | It should be avoided to embed memory addresses into a |
+ | | single input/output vector. If more than 4 memory |
+ | | addresses are required in a RoT service request, it is |
+ | | recommended to split this request into two or multiple |
+ | | service calls and therefore each service call requires no |
+ | | more than 4 input/output vectors. |
+ | | |
+ | | In TF-M IPC model, RoT services request SPM to read and |
+ | | write NS data. SPM will validate the target addresses and |
+ | | can detect the invalid addresses to mitigate this threat. |
+ | | |
+ | | In TF-M Library model, RoT services can directly access NS |
+ | | memory. It is required to review and confirm Library model |
+ | | implementation of RoT service request doesn't embed memory |
+ | | addresses. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 7.1 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-SECURE-SERVICE-RW-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-SECURE-SERVICE-RW-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | Similar to TFM-GENERIC-SECURE-SERVICE-RW-T-2_, a malicious |
+ | | NS application can embed secure memory addresses in a |
+ | | parameter structure in RoT service request input vectors, |
+ | | to read secure data which the NS application must not |
+ | | access. |
+ +---------------+------------------------------------------------------------+
+ | Justification | Similar to the description in |
+ | | TFM-GENERIC-SECURE-SERVICE-RW-T-2_, the secure memory |
+ | | addresses hidden in the RoT service input/output vector |
+ | | structure may bypass TF-M validation. Without a proper |
+ | | check, the RoT service may copy secure data to NSPE |
+ | | according to the secure memory addresses in structure, |
+ | | secure information can be disclosed. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | It should be avoided to embed memory addresses into a |
+ | | single input/output vector. If more than 4 memory |
+ | | addresses are required in a RoT service request, it is |
+ | | recommended to split this request into two or multiple |
+ | | service calls and therefore each service call requires no |
+ | | more than 4 input/output vectors. |
+ | | |
+ | | In TF-M IPC model, RoT services request SPM to read and |
+ | | write NS data. SPM will validate the target addresses and |
+ | | can detect the invalid addresses to mitigate this threat. |
+ | | |
+ | | In TF-M Library model, RoT services can directly access NS |
+ | | memory. It is required to review and confirm Library model |
+ | | implementation of RoT service request doesn't embed memory |
+ | | addresses. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 7.1 (High) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+TF-M returns secure service result
+----------------------------------
+
+This section identifies threats on ``DF4`` defined in `Data Flow Diagram`_.
+
+When RoT service completes the request from NSPE, TF-M returns the success or
+failure error code to NS application.
+
+In single Armv8-M core scenario, TF-M writes the return code value in the
+general purpose register and returns to Non-secure state.
+
+On dual-cpu platforms, TF-M writes the return code to NSPE mailbox message queue
+via mailbox.
+
+.. table:: TFM-GENERIC-RETURN-CODE-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-RETURN-CODE-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | SPE may leave secure data in the registers not banked |
+ | | after the SPE completes PSA Client calls and executes |
+ | | ``BXNS`` to switch Armv8-M back to Non-secure state. |
+ +---------------+------------------------------------------------------------+
+ | Justification | If SPE doesn't clean up the secure data in registers not |
+ | | banked before switching into NSPE in Armv8-M core, NSPE |
+ | | can read the SPE context from those registers. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | In single Armv8-M core scenario, TF-M cleans general |
+ | | purpose registers not banked before switching into NSPE to |
+ | | prevent NSPE probing secure context from the registers. |
+ | | |
+ | | Current TF-M implementation doesn't support FPU in SPE. |
+ | | TF-M build will stop if FPU is enabled on platform. |
+ | | Therefore, FPU registers doesn't contain data that needs |
+ | | to be protected from NSPE. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.3 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+NS interrupts preempts SPE execution
+------------------------------------
+
+This section identifies threats on ``DF5`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-GENERIC-NS-INTERRUPT-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INTERRUPT-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | Shared registers may contain secure data when NS |
+ | | interrupts occur. |
+ +---------------+------------------------------------------------------------+
+ | Justification | The secure data in shared registers should be cleaned up |
+ | | before NSPE can access shared registers. Otherwise, secure |
+ | | data leakage may occur. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | In single Armv8-M core scenario, Armv8-M architecture |
+ | | automatically cleans up the registers not banked before |
+ | | switching to Non-secure state while taking NS interrupts. |
+ | | |
+ | | Current TF-M implementation doesn't support FPU in SPE. |
+ | | TF-M build will stop if FPU is enabled on platform. |
+ | | Therefore, FPU registers doesn't contain data that needs |
+ | | to be protected from NSPE. |
+ | | |
+ | | On dual-cpu platforms, shared registers are implementation |
+ | | defined, such as Inter-Processor Communication registers. |
+ | | Dual-cpu platforms must not store any data which may |
+ | | disclose secure information in the shared registers. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.3 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-NS-INTERRUPT-D-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-NS-INTERRUPT-D-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | An attacker may trigger spurious NS interrupts frequently |
+ | | to block SPE execution. |
+ +---------------+------------------------------------------------------------+
+ | Justification | In single Armv8-M core scenario, an attacker may inject a |
+ | | malicious NS application or hijack a NS hardware to |
+ | | frequently trigger spurious NS interrupts to keep |
+ | | preempting SPE and block SPE to perform normal secure |
+ | | execution. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | It is out of scope of TF-M. |
+ | | |
+ | | Assets protected by TF-M won't be leaked. TF-M won't be |
+ | | directly impacted. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.0 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+Secure interrupts preempts NSPE execution
+-----------------------------------------
+
+This section identifies threats on ``DF6`` defined in `Data Flow Diagram`_.
+
+.. table:: TFM-GENERIC-S-INTERRUPT-I-1
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-S-INTERRUPT-I-1** |
+ +---------------+------------------------------------------------------------+
+ | Description | Shared registers may contain secure data when Armv8-M core |
+ | | switches back to Non-secure state on Secure interrupt |
+ | | return. |
+ +---------------+------------------------------------------------------------+
+ | Justification | Armv8-M architecture doesn't automatically clean up shared |
+ | | registers while returning to Non-secure state during |
+ | | Secure interrupt return. |
+ | | |
+ | | If SPE leaves critical data in the Armv8-M registers not |
+ | | banked, NSPE can read secure context from those registers |
+ | | and secure data leakage may occur. |
+ +---------------+------------------------------------------------------------+
+ | Category | Information disclosure |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M saves NPSE context in general purpose register R4~R11 |
+ | | into secure stack during secure interrupt entry. |
+ | | After secure interrupt handling completes, TF-M unstacks |
+ | | NSPE context from secure stack to overwrite secure context |
+ | | in R4~R11 before secure interrupt return. |
+ | | |
+ | | Armv8-M architecture will automatically unstack NSPE |
+ | | context from non-secure stack to overwrite other registers |
+ | | not banked, such as R0~R3 and R12, during secure interrupt |
+ | | return, before NSPE software can access those registers. |
+ | | |
+ | | Current TF-M implementation doesn't support FPU in SPE. |
+ | | TF-M build will stop if FPU is enabled on platform. |
+ | | Therefore, FPU registers doesn't contain data that needs |
+ | | to be protected from NSPE. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.3 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+Miscellaneous threats
+---------------------
+
+This section collects threats irrelevant to the valid TF-M data flows shown
+above.
+
+.. table:: TFM-GENERIC-STACK-SEAL
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-STACK_SEAL** |
+ +---------------+------------------------------------------------------------+
+ | Description | Armv8-M processor Secure software Stack Sealing |
+ | | vulnerability. |
+ +---------------+------------------------------------------------------------+
+ | Justification | On Armv8-M based processors with TrustZone, if Secure |
+ | | software does not properly manage the Secure stacks when |
+ | | the stacks are created, or when performing non-standard |
+ | | transitioning between states or modes, for example, |
+ | | creating a fake exception return stack frame to |
+ | | de-privilege an interrupt, it is possible for Non-secure |
+ | | world software to manipulate the Secure Stacks, and |
+ | | potentially influence Secure control flow. |
+ | | |
+ | | Refer to [STACK-SEAL]_ for details. |
+ +---------------+------------------------------------------------------------+
+ | Category | Elevation of privilege |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M has implemented common mitigation against stack seal |
+ | | vulnerability. |
+ | | |
+ | | Refer to [ADVISORY-TFMV-1]_ for details on analysis and |
+ | | mitigation in TF-M. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 5.3 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:L/I:L/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+.. table:: TFM-GENERIC-SVC-CALL-SP-FETCH
+ :widths: 10 50
+
+ +---------------+------------------------------------------------------------+
+ | Index | **TFM-GENERIC-SVC-CALL-SP-FETCH** |
+ +---------------+------------------------------------------------------------+
+ | Description | Invoking Secure functions from handler mode may cause TF-M |
+ | | IPC model to behave unexpectedly. |
+ +---------------+------------------------------------------------------------+
+ | Justification | On Armv8-M based processors with TrustZone, if NSPE calls |
+ | | a secure function via Secure Gateway (SG) from non-secure |
+ | | Handler mode , TF-M selects secure process stack by |
+ | | mistake for SVC handling. |
+ | | It will most likely trigger a crash in secure world or |
+ | | reset the whole system, with a very low likelihood of |
+ | | overwriting some memory contents. |
+ +---------------+------------------------------------------------------------+
+ | Category | Denial of service/Tampering |
+ +---------------+------------------------------------------------------------+
+ | Mitigation | TF-M has enhanced implementation to mitigate this |
+ | | vulnerability. |
+ | | |
+ | | Refer to [ADVISORY-TFMV-2]_ for details on analysis and |
+ | | mitigation in TF-M. |
+ +---------------+------------------------------------------------------------+
+ | CVSS Score | 4.5 (Medium) |
+ +---------------+------------------------------------------------------------+
+ | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:L |
+ | String | |
+ +---------------+------------------------------------------------------------+
+
+***************
+Version control
+***************
+
+.. table:: Version control
+
+ +---------+--------------------------------------------------+---------------+
+ | Version | Description | TF-M version |
+ +=========+==================================================+===============+
+ | v0.1 | Initial draft | TF-M v1.1 |
+ +---------+--------------------------------------------------+---------------+
+ | v1.0 | First version | TF-M v1.2.0 |
+ +---------+--------------------------------------------------+---------------+
+
+*********
+Reference
+*********
+
+.. [Security-Incident-Process] `Security Incident Process `_
+
+.. [FF-M] `Arm® Platform Security Architecture Firmware Framework 1.0 `_
+
+.. [DUAL-CPU-BOOT] :doc:`Booting a dual core system `
+
+.. [CVSS] `Common Vulnerability Scoring System Version 3.1 Calculator `_
+
+.. [CVSS_SPEC] `CVSS v3.1 Specification Document `_
+
+.. [STRIDE] `The STRIDE Threat Model `_
+
+.. [SECURE-BOOT] :doc:`Secure boot `
+
+.. [ROLLBACK-PROTECT] :doc:`Rollback protection in TF-M secure boot `
+
+.. [STACK-SEAL] `Armv8-M processor Secure software Stack Sealing vulnerability `_
+
+.. [ADVISORY-TFMV-1] :doc:`Advisory TFMV-1 `
+
+.. [ADVISORY-TFMV-2] :doc:`Advisory TFMV-2 `
+
+--------------------
+
+*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.*
diff --git a/docs/security/threat_models/index.rst b/docs/security/threat_models/index.rst
new file mode 100644
index 0000000000..227d4d41e1
--- /dev/null
+++ b/docs/security/threat_models/index.rst
@@ -0,0 +1,12 @@
+Threat Models
+=============
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/security/threat_models/overall-DFD.png b/docs/security/threat_models/overall-DFD.png
new file mode 100644
index 0000000000..39cf4c8549
Binary files /dev/null and b/docs/security/threat_models/overall-DFD.png differ
diff --git a/docs/technical_references/code_sharing.rst b/docs/technical_references/code_sharing.rst
new file mode 100644
index 0000000000..45aec7e01f
--- /dev/null
+++ b/docs/technical_references/code_sharing.rst
@@ -0,0 +1,368 @@
+######################################################
+Code sharing between independently linked XIP binaries
+######################################################
+
+:Authors: Tamas Ban
+:Organization: Arm Limited
+:Contact: tamas.ban@arm.com
+:Status: Draft
+
+**********
+Motivation
+**********
+Cortex-M devices are usually constrained in terms of flash and RAM. Therefore,
+it is often challenging to fit bigger projects in the available memory. The PSA
+specifications require a device to both have a secure boot process in place at
+device boot-up time, and to have a partition in the SPE which provides
+cryptographic services at runtime. These two entities have some overlapping
+functionality. Some cryptographic primitives (e.g. hash calculation and digital
+signature verification) are required both in the bootloader and the runtime
+environment. In the current TF-M code base, both firmware components use the
+mbed-crypto library to implement these requirements. During the build process,
+the mbed-crpyto library is built twice, with different configurations (the
+bootloader requires less functionality) and then linked to the corresponding
+firmware component. As a result of this workflow, the same code is placed in the
+flash twice. For example, the code for the SHA-256 algorithm is included in
+MCUboot, but the exact same code is duplicated in the SPE cryptography
+partition. In most cases, there is no memory isolation between the bootloader
+and the SPE, because both are part of the PRoT code and run in the secure
+domain. So, in theory, the code of the common cryptographic algorithms could be
+reused among these firmware components. This could result in a big reduction in
+code footprint, because the cryptographic algorithms are usually flash hungry.
+Code size reduction can be a good opportunity for very constrained devices,
+which might need to use TF-M Profile Small anyway.
+
+*******************
+Technical challenge
+*******************
+Code sharing in a regular OS environment is easily achievable with dynamically
+linked libraries. However, this is not the case in Cortex-M systems where
+applications might run bare-metal, or on top of an RTOS, which usually lacks
+dynamic loading functionality. One major challenge to be solved in the Cortex-M
+space is how to share code between independently linked XIP applications that
+are tied to a certain memory address range to be executable and have absolute
+function and global data memory addresses. In this case, the code is not
+relocatable, and in most cases, there is no loader functionality in the system
+that can perform code relocation. Also, the lack of an MMU makes the address
+space flat, constant and not reconfigurable at runtime by privileged code.
+
+One other difficulty is that the bootloader and the runtime use the same RAM
+area during execution. The runtime firmware is executed strictly after the
+bootloader, so normally, it can reuse the whole secure RAM area, as it would be
+the exclusive user. No attention needs to be paid as to where global data is
+placed by the linker. The bootloader does not need to retain its state. The low
+level startup of the runtime firmware can freely overwrite the RAM with its data
+without corrupting bootloader functionality. However, with code sharing between
+bootloader and runtime firmware, these statements are no longer true. Global
+variables used by the shared code must either retain their value or must be
+reinitialised during low level startup of the runtime firmware. The startup code
+is not allowed to overwrite the shared global variables with arbitrary data. The
+following design proposal provides a solution to these challenges.
+
+**************
+Design concept
+**************
+The bootloader is sometimes implemented as ROM code (BL1) or stored in a region
+of the flash which is lockable, to prevent tampering. In a secure system, the
+bootloader is immutable code and thus implements a part of the Root of Trust
+anchor in the device, which is trusted implicitly. The shared code is primarily
+part of the bootloader, and is reused by the runtime SPE firmware at a later
+stage. Not all of the bootloader code is reused by the runtime SPE, only some
+cryptographic functions.
+
+Simplified steps of building with code sharing enabled:
+
+ - Complete the bootloader build process to have a final image that contains
+ the absolute addresses of the shared functions, and the global variables
+ used by these functions.
+ - Extract the addresses of the functions and related global variables that are
+ intended to be shared from the bootloader executable.
+ - When building runtime firmware, provide the absolute addresses of the shared
+ symbols to the linker, so that it can pick them up, instead of instantiating
+ them again.
+
+The execution flow looks like this:
+
+.. code-block:: bash
+
+ SPE MCUboot func1() MCUboot func2() MCUboot func3()
+ |
+ | Hash()
+ |------------->|
+ |----------------->|
+ |
+ Return |
+ Return |<-----------------|
+ |<-------------|
+ |
+ |
+ |----------------------------------------------------->|
+ |
+ Function pointer in shared global data() |
+ |<-----------------------------------------------------|
+ |
+ | Return
+ |----------------------------------------------------->|
+ |
+ Return |
+ |<-----------------------------------------------------|
+ |
+ |
+
+The execution flow usually returns from a shared function back to the SPE with
+an ordinary function return. So usually, once a shared function is called in the
+call path, all further functions in the call chain will be shared as well.
+However, this is not always the case, as it is possible for a shared function to
+call a non-shared function in SPE code through a global function pointer.
+
+For shared global variables, a dedicated data section must be allocated in the
+linker configuration file. This area must have the same memory address in both
+MCUboot's and the SPE's linker files, to ensure the integrity of the variables.
+For simplicity's sake, this section is placed at the very beginning of the RAM
+area. Also, the RAM wiping functionality at the end of the secure boot flow
+(that is intended to remove any possible secrets from the RAM) must not clear
+this area. Furthermore, it must be ensured that the linker places shared globals
+into this data section. There are two way to achieve this:
+
+ - Put a filter pattern in the section body that matches the shared global
+ variables.
+ - Mark the global variables in the source code with special attribute
+ `__attribute__((section()))`
+
+RAM memory layout in MCUboot with code sharing enabled:
+
+.. code-block:: bash
+
+ +------------------+
+ | Shared symbols |
+ +------------------+
+ | Shared boot data |
+ +------------------+
+ | Data |
+ +------------------+
+ | Stack (MSP) |
+ +------------------+
+ | Heap |
+ +------------------+
+
+RAM memory layout in SPE with code sharing enabled:
+
+.. code-block:: bash
+
+ +-------------------+
+ | Shared symbols |
+ +-------------------+
+ | Shared boot data |
+ +-------------------+
+ | Stack (MSP) |
+ +-------------------+
+ | Stack (PSP) |
+ +-------------------+
+ | Partition X Data |
+ +-------------------+
+ | Partition X Stack |
+ +-------------------+
+ .
+ .
+ .
+ +-------------------+
+ | Partition Z Data |
+ +-------------------+
+ | Partition Z Stack |
+ +-------------------+
+ | PRoT Data |
+ +-------------------+
+ | Heap |
+ +-------------------+
+
+Patching mbedTLS
+================
+In order to share some global function pointers from mbed-crypto that are
+related to dynamic memory allocation, their scope must be extended from private
+to global. This is needed because some compiler toolchain only extract the
+addresses of public functions and global variables, and extraction of addresses
+is a requirement to share them among binaries. Therefore, a short patch was
+created for the mbed-crypto library, which "globalises" these function pointers:
+
+`lib/ext/mbedcrypto/0005-Enable-crypto-code-sharing-between-independent-binar.patch`
+
+The patch need to manually applied in the mbedtls repo, if code sharing is
+enabled. The patch has no effect on the functional behaviour of the
+cryptographic library, it only extends the scope of some variables.
+
+*************
+Tools support
+*************
+All the currently supported compilers provide a way to achieve the above
+objectives. However, there is no standard way, which means that the code sharing
+functionality must be implemented on a per compiler basis. The following steps
+are needed:
+
+ - Extraction of the addresses of all global symbols.
+ - The filtering out of the addresses of symbols that aren't shared. The goal is
+ to not need to list all the shared symbols by name. Only a simple pattern
+ has to be provided, which matches the beginning of the symbol's name.
+ Matching symbols will be shared. Examples are in :
+ `bl2/src/shared_symbol_template.txt`
+ - Provision of the addresses of shared symbols to the linker during the SPE
+ build process.
+ - The resolution of symbol collisions during SPE linking. Because mbed-crypto
+ is linked to both firmware components as a static library, the external
+ shared symbols will conflict with the same symbols found within it. In order
+ to prioritize the external symbol, the symbol with the same name in
+ mbed-crypto must be marked as weak in the symbol table.
+
+The above functionalities are implemented in the toolchain specific CMake files:
+
+ - `toolchain_ARMCLANG.cmake`
+ - `toolchain_GNUARM.cmake`
+
+By the following two functions:
+
+ - `compiler_create_shared_code()`: Extract and filter shared symbol addresses
+ from MCUboot.
+ - `compiler_link_shared_code()`: Link shared code to the SPE and resolve symbol
+ conflict issues.
+
+ARMCLANG
+========
+The toolchain specific steps are:
+
+ - Extract all symbols from MCUboot: add `-symdefs` to the compiler command line
+ - Filter shared symbols: call CMake script `FilterSharedSymbols.cmake`
+ - Weaken duplicated (shared) symbols in the mbed-crypto static library that are
+ linked to the SPE: `arm-none-eabi-objcopy`
+ - Link shared code to SPE: Add the filtered output of `-symdefs` to the SPE
+ source file list.
+
+GNUARM
+======
+The toolchain specific steps are:
+
+ - Extract all symbols from MCUboot: `arm-none-eabi-nm`
+ - Filter shared symbols: call CMake script: `FilterSharedSymbols.cmake`
+ - Strip unshared code from MCUboot: `arm-none-eabi-strip`
+ - Weaken duplicated (shared) symbols in the mbed-crypto static library that are
+ linked to the SPE: `arm-none-eabi-objcopy`
+ - Link shared code to SPE: Add `-Wl -R ` to the
+ compiler command line
+
+IAR
+===
+Functionality currently not implemented, but the toolchain supports doing it.
+
+**************************
+Memory footprint reduction
+**************************
+Build type: MinSizeRel
+Platform: mps2/an521
+Version: TF-Mv1.2.0 + code sharing patches
+MCUboot image encryption support is disabled.
+
++------------------+-------------------+-------------------+-------------------+
+| | ConfigDefault | ConfigProfile-M | ConfigProfile-S |
++------------------+----------+--------+----------+--------+----------+--------+
+| | ARMCLANG | GNUARM | ARMCLANG | GNUARM | ARMCLANG | GNUARM |
++------------------+----------+--------+----------+--------+----------+--------+
+| CODE_SHARING=OFF | 122268 | 124572 | 75936 | 75996 | 50336 | 50224 |
++------------------+----------+--------+----------+--------+----------+--------+
+| CODE_SHARING=ON | 113264 | 115500 | 70400 | 70336 | 48840 | 48988 |
++------------------+----------+--------+----------+--------+----------+--------+
+| Difference | 9004 | 9072 | 5536 | 5660 | 1496 | 1236 |
++------------------+----------+--------+----------+--------+----------+--------+
+
+If MCUboot image encryption support is enabled then saving could be up to
+~13-15KB.
+
+.. Note::
+
+ Code sharing on Musca-B1 was tested only with SW only crypto, so crypto
+ hardware acceleration must be turned off: -DCRYPTO_HW_ACCELERATOR=OFF
+
+
+*************************
+Useability considerations
+*************************
+Functions that only use local variables can be shared easily. However, functions
+that rely on global variables are a bit tricky. They can still be shared, but
+all global variables must be placed in the shared symbol section, to prevent
+overwriting and to enable the retention of their values.
+
+Some global variables might need to be reinitialised to their original values by
+runtime firmware, if they have been used by the bootloader, but need to have
+their original value when runtime firmware starts to use them. If so, the
+reinitialising functionality must be implemented explicitly, because the low
+level startup code in the SPE does not initialise the shared variables, which
+means they retain their value after MCUboot stops running.
+
+If a bug is discovered in the shared code, it cannot be fixed with a firmware
+upgrade, if the bootloader code is immutable. If this is the case, disabling
+code sharing might be a solution, as the new runtime firmware could contain the
+fixed code instead of relying on the unfixed shared code. However, this would
+increase code footprint.
+
+API backward compatibility also can be an issue. If the API has changed in newer
+version of the shared code. Then new code cannot rely on the shared version.
+The changed code and all the other shared code where it is referenced from must
+be ignored and the updated version of the functions must be compiled in the
+SPE binary. The mbedTLS library is API compatible with its current version
+(``v2.24.0``) since the ``mbedtls-2.7.0 release`` (2018-02-03).
+
+To minimise the risk of incompatibility, use the same compiler flags to build
+both firmware components.
+
+The artifacts of the shared code extraction steps must be preserved so as to
+remain available if new SPE firmware (that relies on shared code) is built and
+released. Those files are necessary to know the address of shared symbols when
+linking the SPE.
+
+************************
+How to use code sharing?
+************************
+Considering the above, code sharing is an optional feature, which is disabled
+by default. It can be enabled from the command line with a compile time switch:
+
+ - `TFM_CODE_SHARING`: Set to `ON` to enable code sharing.
+
+With the default settings, only the common part of the mbed-crypto library is
+shared, between MCUboot and the SPE. However, there might be other device
+specific code (e.g. device drivers) that could be shared. The shared
+cryptography code consists mainly of the SHA-256 algorithm, the `bignum` library
+and some RSA related functions. If image encryption support is enabled in
+MCUboot, then AES algorithms can be shared as well.
+
+Sharing code between the SPE and an external project is possible, even if
+MCUboot isn't used as the bootloader. For example, a custom bootloader can also
+be built in such a way as to create the necessary artifacts to share some of its
+code with the SPE. The same artifacts must be created like the case of MCUboot:
+
+ - `shared_symbols_name.txt`: Contains the name of the shared symbols. Used by
+ the script that prevents symbol collision.
+ - `shared_symbols_address.txt`: Contains the type, address and name of shared
+ symbols. Used by the linker when linking runtime SPE.
+ - `shared_code.axf`: GNUARM specific. The stripped version of the firmware
+ component, only contains the shared code. It is used by the linker when
+ linking the SPE.
+
+.. Note::
+
+ The artifacts of the shared code extraction steps must be preserved to be
+ able to link them to any future SPE version.
+
+When an external project is sharing code with the SPE, the `SHARED_CODE_PATH`
+compile time switch must be set to the path of the artifacts mentioned above.
+
+********************
+Further improvements
+********************
+This design focuses only on sharing the cryptography code. However, other code
+could be shared as well. Some possibilities:
+
+- Flash driver
+- Serial driver
+- Image metadata parsing code
+- etc.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst b/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst
new file mode 100644
index 0000000000..0a88ab3674
--- /dev/null
+++ b/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst
@@ -0,0 +1,136 @@
+##########################
+Booting a Dual-Core System
+##########################
+
+:Authors: Chris Brand
+:Organization: Cypress Semiconductor Corporation
+:Contact: chris.brand@cypress.com
+:Status: Accepted
+
+*******************
+System Architecture
+*******************
+There are many possibly ways to design a dual core system. Some important
+considerations from a boot perspective are:
+
+- Which core has access to which areas of Flash?
+
+ - It is possible that the secure core has no access to the Flash from which
+ the non-secure core will boot, in which case the non-secure core will
+ presumably have a separate root of trust and perform its own integrity
+ checks on boot.
+
+- How does the non-secure core behave on power-up? Is it held in reset,
+ does it jump to a set address, …?
+
+- What are the performance characteristics of the two core?
+
+ - There could be a great disparity in performance
+
+**********************
+TF-M Twin Core Booting
+**********************
+In an effort to make the problem manageable, as well as to provide a system
+with good performance, that is flexible enough to work for a variety of dual
+core systems, the following design decisions have been made:
+
+- TF-M will (for now) only support systems where the secure core has full
+ access to the Flash that the non-secure core will boot from
+
+ - This keeps the boot flow as close as possible to the single core design,
+ with the secure core responsible for maintaining the chain of trust for
+ the entire system, and for upgrade of the entire system
+
+- The secure code will make a platform-specific call immediately after setting
+ up hardware protection to (potentially) start the non-secure core running
+
+ - This is the earliest point at which it is safe to allow the non-secure
+ code to start running, so starting it here ensures system integrity while
+ also giving the non-secure code the maximum amount of time to perform its
+ initialization
+
+ - Note that this is after the bootloader has validated the non-secure image,
+ which is the other key part to maintain security
+
+ - This also means that only tfm_s and tfm_ns have to change, and not mcuboot
+
+- Both the secure and non-secure code will make platform-specific calls to
+ establish a synchronization point. This will be after both sides have done
+ any initialization that is required, including setting up inter-core
+ communications. On a single core system, this would be the point at which the
+ secure code jumps to the non-secure code, and at the very start of the
+ non-secure code.
+
+- After completing initialization on the secure core (at the point where on a
+ single core system, it would jump to the non-secure code), the main thread on
+ the secure core will be allowed to die
+
+ - The scheduler has been started at this point, and an idle thread exists.
+ Any additional work that is only required in the dual core case will be
+ interrupt-driven.
+
+- Because both cores may be booting in parallel, executing different
+ initialization code, at different speeds, the design must be resilient if
+ either core attempts to communicate with the other before the latter is ready.
+ For example, the client (non-secure) side of the IPC mechanism must be able
+ to handle the situation where it has to wait for the server (secure) side to
+ finish setting up the IPC mechanism.
+
+ - This relates to the synchronization calls mentioned above. It means that
+ those calls cannot utilise the IPC mechanism, but must instead use some
+ platform-specific mechanism to establish this synchronization. This could
+ be as simple as setting aside a small area of shared memory and having
+ both sides set a “ready” flag, but may well also involve the use of
+ interrupts.
+
+ - This also means that the synchronization call must take place after the
+ IPC mechanism has been set up but before any attempt (by either side) to
+ use it.
+
+*************
+API Additions
+*************
+Three new HAL functions are required:
+
+.. code-block:: c
+
+ void tfm_spm_hal_boot_ns_cpu(uintptr_t start_addr);
+
+- Called on the secure core from ``tfm_core_init()`` after hardware protections
+ have been configured.
+
+- Performs the necessary actions to start the non-secure core running the code
+ at the specified address.
+
+.. code-block:: c
+
+ void tfm_spm_hal_wait_for_ns_cpu_ready(void);
+
+- Called on the secure core from the end of ``tfm_core_init()`` where on a
+ single core system the secure code calls into the non-secure code.
+
+- Flags that the secure core has completed its initialization, including setting
+ up the IPC mechanism.
+
+- Waits, if necessary, for the non-secure core to flag that it has completed its
+ initialisation
+
+.. code-block:: c
+
+ void tfm_ns_wait_for_s_cpu_ready(void);
+
+- Called on the non-secure core from ``main()`` after the dual-core-specific
+ initialization (on a single core system, this would be the start of the
+ non-secure code), before the first use of the IPC mechanism.
+
+- Flags that the non-secure side has completed its initialization.
+
+- Waits, if necessary, for the secure core to flag that it has completed its
+ initialization.
+
+For all three, an empty implementation will be provided with a weak symbol so
+that platforms only have to provide the new functions if they are required.
+
+---------------
+
+Copyright (c) 2019 Cypress Semiconductor Corporation
diff --git a/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
new file mode 100644
index 0000000000..2bb3762aee
--- /dev/null
+++ b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
@@ -0,0 +1,767 @@
+################################################################
+Communication Prototype Between NSPE And SPE In Dual Core System
+################################################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+This document proposes a generic prototype of the communication between NSPE
+(Non-secure Processing Environment) and SPE (Secure Processing Environment) in
+TF-M on a dual core system.
+
+The dual core system should satisfy the following requirements
+
+- NSPE and SPE are properly isolated and protected following PSA
+- An Arm M-profile core locates in SPE and acts as the Secure core
+- An Inter-Processor Communication hardware module in system for communication
+ between NSPE core and SPE core
+- TF-M runs on the Secure core with platform specific drivers support.
+
+Scope
+=====
+
+This design document focuses on the dual core communication design inside TF-M.
+Some changes to TF-M core/Secure Partition Manager (SPM) are listed to support
+the dual core communication. This document only discuss about the implementation
+in TF-M Inter-Process Communication (IPC) model.
+The TF-M non-secure interface library depends on mailbox and NS RTOS
+implementation. The related changes to TF-M non-secure interface library are not
+discussed in detail in this document.
+
+Some requirements to mailbox functionalities are defined in this document. The
+detailed mailbox design or implementations is not specified in this document.
+Please refer to mailbox dedicate document [1]_.
+
+Organization of the document
+============================
+
+- `Overall workflow in dual core communication`_ provides an overall workflow of
+ dual core communication between NSPE and SPE.
+- `Requirements on mailbox communication`_ lists general requirements of
+ mailbox, from the perspective of dual core communication.
+- `PSA client call handling flow in TF-M`_ discusses about the detailed sequence
+ and key modules of handling PSA client call in TF-M.
+- `Summary of changes to TF-M core/SPM`_ summarizes the potential changes to
+ TF-M core/SPM to support dual core communication.
+
+*******************************************
+Overall workflow in dual core communication
+*******************************************
+
+The overall workflow in dual-core scenario can be described as follows
+
+1. Non-secure application calls TF-M non-secure interface library to request
+ Secure service. The TF-M non-secure interface library translates the Secure
+ service into PSA Client calls.
+2. TF-M non-secure interface library notifies TF-M of the PSA client call
+ request, via mailbox. Proper generic mailbox APIs in HAL should be defined
+ so that TF-M non-secure interface library can co-work with diverse platform
+ specific Inter-Processor Communication implementations.
+3. Inter-Processor Communication interrupt handler and mailbox handling in TF-M
+ deal with the inbound mailbox event(s) and deliver the PSA client call
+ request to TF-M SPM.
+4. TF-M SPM processes the PSA client call request. The PSA client call is
+ eventually handled in target Secure Partition or corresponding handler.
+5. After the PSA Client call is completed, the return value is returned to NSPE
+ via mailbox.
+6. TF-M non-secure interface library fetches return value from mailbox.
+7. The return value is returned to non-secure application.
+
+The interfaces between NSPE app and TF-M NSPE interface library are unchanged
+so the underlying platform specific details are transparent to NSPE
+application.
+
+Step 3 ~ step 5 are covered in `PSA client call handling flow in TF-M`_ in
+detail.
+
+*************************************
+Requirements on mailbox communication
+*************************************
+
+The communication between NSPE and SPE relies on mailbox communication
+implementation. The mailbox functionalities are eventually implemented by
+platform specific Inter-Processor Communication drivers.
+This section lists some general requirements on mailbox communication between
+NSPE and SPE.
+
+Data transferred between NPSE and SPE
+=====================================
+
+A mailbox message should contain the information and parameters of a PSA client
+call. After SPE is notified by a mailbox event, SPE fetches the parameters from
+NSPE for PSA Client call processing.
+The mailbox design document [1]_ defines the structure of the mailbox message.
+
+The information and parameters of PSA Client call in the mailbox message include
+
+- PSA Client API
+
+- Parameters required in PSA Client call. The parameters can include the
+ following, according to PSA client call type
+
+ - Service ID (SID)
+ - Handle
+ - Request type
+ - Input vectors and the lengths
+ - Output vectors and the lengths
+ - Requested version of secure service
+
+- NSPE Client ID. Optional. The NSPE Client ID is required when NSPE RTOS
+ enforces non-secure task isolation.
+
+The mailbox implementation may define additional members in mailbox message to
+accomplish mailbox communication between NSPE and SPE.
+
+When the PSA Client call is completed in TF-M, the return result, such as
+PSA_SUCCESS or a handle, should be returned from SPE to NSPE via mailbox.
+
+Mailbox synchronization between NSPE and SPE
+============================================
+
+Synchronization and protection between NSPE and SPE accesses to shared mailbox
+objects and variables should be implemented.
+
+When a core accesses shared mailbox objects or variables, proper mechanisms
+should protect concurrent operations from the other core.
+
+Support of multiple ongoing NS PSA client calls (informative)
+=============================================================
+
+If the support of multiple ongoing NS PSA client calls in TF-M is required
+in dual-core systems, an optional queue can be maintained in TF-M core to store
+multiple mailbox objects received from NSPE.
+To identify NS PSA client calls, additional fields can be added in TF-M SPM
+objects to store the NS PSA Client request identification.
+
+Note that when just a single outstanding PSA client call is allowed, multiple
+NSPE OS threads can run concurrently and call PSA client functions. The first
+PSA client call will be processed first, and any other OS threads will be
+blocked from submitting PSA client calls until the first is completed.
+
+*************************************
+PSA client call handling flow in TF-M
+*************************************
+
+This section provides more details about the flow of PSA client call handing in
+TF-M.
+
+The sequence of handling PSA Client call request in TF-M is listed as below
+
+1. Platform specific Inter-Processor Communication interrupt handler is
+ triggered after the mailbox event is asserted by NSPE. The interrupt handler
+ should assert a PendSV.
+2. In the top half of PendSV handler, the scheduler selects the next thread to
+ run and executes normal context switch if necessary.
+3. In the bottom half of PendSV handler, mailbox handling deals with the mailbox
+ message(s) which contain(s) the PSA client call information and parameters.
+ Then the PSA client call request is dispatched to dedicated PSA client call
+ handler in TF-M SPM.
+4. After the PSA client call is completed, the return value is transmitted to
+ NSPE via mailbox.
+
+Several key modules in the whole process are covered in detail in following
+sections.
+
+- `Inter-Processor Communication interrupt handler`_ discusses about the
+ Inter-Processor Communication interrupt handler
+- `TF-M Remote Procedure Call (RPC) layer`_ introduces TF-M Remote Procedure
+ Call layer to support dual-core communication.
+- `PendSV handler`_ specifies the mailbox tasks in PendSV handler.
+- `Return value replying routine in TF-M`_ proposes the routine to reply the
+ return value to NSPE.
+
+Inter-Processor Communication interrupt handler
+===============================================
+
+Platform specific driver should implement the Inter-Processor Communication
+interrupt handler to deal with the Inter-Processor Communication interrupt
+asserted by NSPE.
+The platform specific interrupt handler should complete the interrupt
+operations, such as interrupt EOI or acknowledge.
+
+The interrupt handler should call SPE mailbox API(s) to deal with the inbound
+mailbox event. The SPE mailbox may assert a PendSV.
+
+Platform specific driver should put Inter-Processor Communication interrupt into
+a proper exception priority, according to system and application requirements.
+The proper priority setting should guarantee that
+
+- TF-M can respond to a PSA client call request in time according to system and
+ application requirements.
+- Other exceptions, which are more latency sensitive or require higher
+ priorities, are not blocked by Inter-Processor Communication interrupt ISR.
+
+The exception priority setting is IMPLEMENTATION DEFINED.
+
+TF-M Remote Procedure Call (RPC) layer
+======================================
+
+This design brings up a concept of Remote Procedure Call layer in TF-M.
+
+The RPC layer sits between TF-M SPM and mailbox implementation. The purpose of
+RPC layer is to decouple mailbox implementation and TF-M SPM and enhance the
+generality of entire dual-core communication.
+
+The RPC layer provides a set of APIs to TF-M SPM to handle and reply PSA client
+call from NSPE in dual-core scenario. Please refer to
+`TF-M RPC definitions to TF-M SPM`_ for API details.
+It hides the details of specific mailbox implementation from TF-M SPM. It avoids
+modifying TF-M SPM to fit mailbox development and changes.
+It can keep a unified PSA client call process in TF-M SPM in both single
+Armv8-M scenario and dual core scenario.
+
+The RPC layer defines a set callback functions for mailbox implementation to
+hook its specific mailbox operations. When TF-M SPM invokes RPC APIs to deal
+with NSPE PSA client call, RPC layer eventually calls the callbacks to execute
+mailbox operations.
+RPC layer also defines a set of PSA client call handler APIs for mailbox
+implementation. RPC specific client call handlers parse the PSA client call
+parameters and invoke common TF-M PSA client call handlers. Please refer to
+`TF-M RPC definitions for mailbox`_ for the details.
+
+PendSV handler
+==============
+
+The mailbox handling should be added to PendSV handler in current TF-M single
+Armv8-M implementation in IPC model. Mailbox handling processes the inbound
+mailbox event(s) in the bottom half of PendSV handler. The top half of PendSV
+contains the original scheduling.
+
+Mailbox handling must be executed after the original scheduling to make sure
+that the status of sleeping secure service has been updated in scheduling when
+mailbox handling triggers the sleeping secure service.
+
+A compile flag can be defined to disable mailbox handling in PendSV handler in
+single Armv8-M scenario during building.
+
+This section only discusses about the mailbox handling in the bottom half of
+PendSV handler. The TF-M scheduling and context switch should keep unchanged as
+current single Armv8-M implementation.
+
+Mailbox handling in bottom half of PendSV handler
+-------------------------------------------------
+
+PendSV handler should call RPC API ``tfm_rpc_client_call_handler()`` to check
+and handle PSA client call request from NSPE. ``tfm_rpc_client_call_handler()``
+invokes request handling callback function to eventually execute specific
+mailbox message handling operations. The mailbox APIs are defined in mailbox
+design document [1]_.
+
+The handling process in mailbox operation consists of the following steps.
+
+1. SPE mailbox fetches the PSA client call parameters from NSPE mailbox.
+ Proper protection and synchronization should be implemented in mailbox to
+ guarantee that the operations are not interfered by NSPE mailbox operations
+ or Inter-Processor Communication interrupt handler.
+ If a queue is maintained inside TF-M core, SPE mailbox can fetch multiple
+ PSA client calls together into the queue, to save the time of synchronization
+ between two cores.
+
+2. SPE mailbox parses the PSA client call paramters copied from NSPE, including
+ the PSA client call type.
+
+3. The PSA client call request is dispatched to the dedicated TF-M RPC PSA
+ client call handler. The PSA client call request is processed in the
+ corresponding handler.
+
+ - For ``psa_framework_version()`` and ``psa_version()``, the PSA client call
+ can be completed in the handlers ``tfm_rpc_psa_framework_version()`` and
+ ``tfm_rpc_psa_version()`` respectively.
+
+ - For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the handlers
+ ``tfm_rpc_psa_connect()``, ``tfm_rpc_psa_call()`` and
+ ``tfm_rpc_psa_close()`` create the PSA message and trigger target Secure
+ partition respectively. The target Secure partition will be woken up to
+ handle the PSA message.
+
+The dual-core scenario and single Armv8-M scenario in TF-M IPC implementation
+should share the same PSA client call routines inside TF-M SPM. The current
+handler definitions can be adjusted to be more generic for dual-core scenario
+and single Armv8-M implementation. Please refer to
+`Summary of changes to TF-M core/SPM`_ for details.
+
+If there are multiple NSPE PSA client call requests pending, SPE mailbox can
+process mailbox messages one by one.
+
+Implementation details in PendSV handler
+----------------------------------------
+
+Some more details should be taken care of in actual implementation.
+
+- PendSV priority should be configured as low enough, to prevent blocking or
+ preempting other latency sensitive interrupts.
+- All the mailbox implementations inside PendSV handler must not directly
+ execute context switch.
+- To simplify the interrupt handling inside TF-M, the mailbox handling
+ implementation inside PendSV handle should avoid triggering additional
+ Inter-Processor Communication interrupts in TF-M, unless it is explicitly
+ required in mailbox design.
+- If Inter-Processor Communication interrupt handler and PendSV handler access
+ shared mailbox objects, proper protection and synchronization should be
+ implemented in both handlers. For example, the Inter-Processor Communication
+ interrupt can be temporarily disabled on secure core while PendSV handler
+ accesses mailbox objects in TF-M.
+
+Return value replying routine in TF-M
+=====================================
+
+Diverse PSA client calls can be implemented with different return value replying
+routines.
+
+- `Replying routine for psa_framework_version() and psa_version()`_ describes
+ the routine for ``psa_framework_version()`` and ``psa_version()``.
+- `Replying routine for psa_connect(), psa_call() and psa_close()`_ describes
+ the routine for ``psa_connect()``, ``psa_call()`` and ``psa_close()``.
+
+Replying routine for psa_framework_version() and psa_version()
+--------------------------------------------------------------
+
+For ``psa_framework_version()`` and ``psa_version()``, the return value can be
+directly returned from the dedicated TF-M RPC PSA client call handlers.
+Therefore, the return value can be directly replied in mailbox handling process.
+
+A compile flag should be defined to enable replying routine via mailbox in
+dual-core scenario during building.
+
+The mailbox reply functions must not trigger context switch inside PendSV
+handler.
+
+Replying routine for psa_connect(), psa_call() and psa_close()
+--------------------------------------------------------------
+
+For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the PSA client call
+is completed in the target Secure Partition. The target Secure Partition calls
+``psa_reply()`` to reply the return value to TF-M SPM. In the SVC handler of
+``psa_reply()`` in TF-M SPM, TF-M SPM should call TF-M RPC API
+``tfm_rpc_client_call_reply()`` to return the value to NSPE via mailbox.
+``tfm_rpc_client_call_reply()`` invokes reply callbacks to execute specific
+mailbox reply operations. The mailbox reply functions must not trigger context
+switch inside SVC handler.
+
+If an error occurs in the handlers, the TF-M RPC handlers,
+``tfm_rpc_psa_call()``, ``tfm_rpc_psa_connect()`` and ``tfm_rpc_psa_close()``,
+may terminate and return the error, without triggering the target Secure
+Partition. The mailbox implementation should return THE error code to NSPE.
+
+A compile flag should be defined to enable replying routine via mailbox in
+dual-core scenario during building.
+
+***********************************
+Summary of changes to TF-M core/SPM
+***********************************
+
+This section discusses the general changes related to NSPE and SPE
+communication to current TF-M core/SPM implementations.
+
+The detailed mailbox implementations are not covered in this section. Please
+refer to mailbox dedicated document [1]_.
+The platform specific implementations are also not covered in this section,
+including the Inter-Processor Communication interrupt or its interrupt handler.
+
+Common PSA client call handlers
+===============================
+
+Common PSA client call handlers should be extracted from current PSA client
+call handlers implementation in TF-M.
+Common PSA client call handlers are shared by both TF-M RPC layer in dual-core
+scenario and SVCall handlers in single Armv8-M scenario.
+
+TF-M RPC layer
+==============
+
+This section describes the TF-M RPC data types and APIs.
+
+- `TF-M RPC definitions to TF-M SPM`_ lists the data types and APIs to be
+ invoked by TF-M SPM.
+- `TF-M RPC definitions for mailbox`_ lists the data types and APIs to be
+ referred by mailbox implementation
+
+TF-M RPC definitions to TF-M SPM
+--------------------------------
+
+TFM_RPC_SUCCESS
+^^^^^^^^^^^^^^^
+
+``TFM_RPC_SUCCESS`` is a general return value to indicate that the RPC operation
+succeeds.
+
+.. code-block:: c
+
+ #define TFM_RPC_SUCCESS (0)
+
+TFM_RPC_INVAL_PARAM
+^^^^^^^^^^^^^^^^^^^
+
+``TFM_RPC_INVAL_PARAM`` is a return value to indicate that the input parameters
+are invalid.
+
+.. code-block:: c
+
+ #define TFM_RPC_INVAL_PARAM (INT32_MIN + 1)
+
+TFM_RPC_CONFLICT_CALLBACK
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently one and only one mailbox implementation is supported in dual core
+communication. This flag indicates that callback functions from one mailbox
+implementation are already registered and no more implementations are accepted.
+
+.. code-block:: c
+
+ #define TFM_RPC_CONFLICT_CALLBACK (INT32_MIN + 2)
+
+``tfm_rpc_client_call_handler()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M PendSV handler calls this function to handle NSPE PSA client call request.
+
+.. code-block:: c
+
+ void tfm_rpc_client_call_handler(void);
+
+Usage
+~~~~~
+
+``tfm_rpc_client_call_handler()`` invokes callback function ``handle_req()`` to
+execute specific mailbox handling.
+Please note that ``tfm_rpc_client_call_handler()`` doesn't return the status of
+underlying mailbox handling.
+
+``tfm_rpc_client_call_reply()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M ``psa_reply()`` handler calls this function to reply PSA client call return
+result to NSPE.
+
+.. code-block:: c
+
+ void tfm_rpc_client_call_reply(const void *owner, int32_t ret);
+
+Parameters
+~~~~~~~~~~
+
++-----------+--------------------------------------------------------------+
+| ``owner`` | A handle to identify the owner of the PSA client call return |
+| | value. |
++-----------+--------------------------------------------------------------+
+| ``ret`` | PSA client call return result value. |
++-----------+--------------------------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_client_call_reply()`` invokes callback function ``reply()`` to execute
+specific mailbox reply.
+Please note that ``tfm_rpc_client_call_reply()`` doesn't return the status of
+underlying mailbox reply process.
+
+``tfm_rpc_set_caller_data()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function sets the private data of the NS caller in TF-M message to identify
+the caller after PSA client call is completed.
+
+.. code-block:: c
+
+ void tfm_rpc_set_caller_data(struct tfm_msg_body_t *msg, int32_t client_id);
+
+Parameters
+~~~~~~~~~~
+
++---------------+-----------------------------------------------------+
+| ``msg`` | TF-M message to be set with NS caller private data. |
++---------------+-----------------------------------------------------+
+| ``client_id`` | The client ID of the NS caller. |
++---------------+-----------------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_set_caller_data()`` invokes callback function ``get_caller_data()`` to
+fetch the private data of caller of PSA client call and set it into TF-M message
+structure.
+
+TF-M RPC definitions for mailbox
+--------------------------------
+
+PSA client call parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This data structure holds the parameters used in a PSA client call. The
+parameters are passed from non-secure core to secure core via mailbox.
+
+.. code-block:: c
+
+ struct client_call_params_t {
+ uint32_t sid;
+ psa_handle_t handle;
+ int32_t type;
+ const psa_invec *in_vec;
+ size_t in_len;
+ psa_outvec *out_vec;
+ size_t out_len;
+ uint32_t version;
+ };
+
+Mailbox operations callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This structures contains the callback functions for specific mailbox operations.
+
+.. code-block:: c
+
+ struct tfm_rpc_ops_t {
+ void (*handle_req)(void);
+ void (*reply)(const void *owner, int32_t ret);
+ const void * (*get_caller_data)(int32_t client_id);
+ };
+
+``tfm_rpc_register_ops()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function registers underlying mailbox operations into TF-M RPC callbacks.
+
+.. code-block:: c
+
+ int32_t tfm_rpc_register_ops(const struct tfm_rpc_ops_t *ops_ptr);
+
+Parameters
+~~~~~~~~~~
+
++-------------+----------------------------------------------+
+| ``ops_ptr`` | Pointer to the specific operation structure. |
++-------------+----------------------------------------------+
+
+Return
+~~~~~~
+
++----------------------+-----------------------------------------+
+| ``TFM_RPC_SUCCESS`` | Operations are successfully registered. |
++----------------------+-----------------------------------------+
+| ``Other error code`` | Fail to register operations. |
++----------------------+-----------------------------------------+
+
+Usage
+~~~~~
+
+Mailbox should register TF-M RPC callbacks during mailbox initialization, before
+enabling secure services for NSPE.
+
+Currently one and only one underlying mailbox communication implementation is
+allowed in runtime.
+
+``tfm_rpc_unregister_ops()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function unregisters underlying mailbox operations from TF-M RPC callbacks.
+
+.. code-block:: c
+
+ void tfm_rpc_unregister_ops(void);
+
+Usage
+~~~~~
+
+Currently one and only one underlying mailbox communication implementation is
+allowed in runtime.
+
+``tfm_rpc_psa_framework_version()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M RPC handler for psa_framework_version().
+
+.. code-block:: c
+
+ uint32_t tfm_rpc_psa_framework_version(void);
+
+Return
+~~~~~~
+
++-------------+---------------------------------------------------------+
+| ``version`` | The version of the PSA Framework implementation that is |
+| | providing the runtime services. |
++-------------+---------------------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_psa_framework_version()`` invokes common ``psa_framework_version()``
+handler in TF-M.
+
+``tfm_rpc_psa_version()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M RPC handler for psa_version().
+
+.. code-block:: c
+
+ uint32_t tfm_rpc_psa_version(const struct client_call_params_t *params,
+ bool ns_caller);
+
+Parameters
+~~~~~~~~~~
+
++---------------+-----------------------------------+
+| ``params`` | Base address of parameters. |
++---------------+-----------------------------------+
+| ``ns_caller`` | Whether the caller is non-secure. |
++---------------+-----------------------------------+
+
+Return
+~~~~~~
+
++----------------------+------------------------------------------------------+
+| ``PSA_VERSION_NONE`` | The RoT Service is not implemented, or the caller is |
+| | not permitted to access the service. |
++----------------------+------------------------------------------------------+
+| ``> 0`` | The minor version of the implemented RoT Service. |
++----------------------+------------------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_psa_version()`` invokes common ``psa_version()`` handler in TF-M.
+The parameters in params should be prepared before calling
+``tfm_rpc_psa_version()``.
+
+``tfm_rpc_psa_connect()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M RPC handler for ``psa_connect()``.
+
+.. code-block:: c
+
+ psa_status_t tfm_rpc_psa_connect(const struct client_call_params_t *params,
+ bool ns_caller);
+
+Parameters
+~~~~~~~~~~
+
++---------------+-----------------------------------+
+| ``params`` | Base address of parameters. |
++---------------+-----------------------------------+
+| ``ns_caller`` | Whether the caller is non-secure. |
++---------------+-----------------------------------+
+
+Return
+~~~~~~
+
++-------------------------+---------------------------------------------------+
+| ``PSA_SUCCESS`` | Success. |
++-------------------------+---------------------------------------------------+
+| ``PSA_CONNECTION_BUSY`` | The SPM cannot make the connection at the moment. |
++-------------------------+---------------------------------------------------+
+| ``Does not return`` | The RoT Service ID and version are not supported, |
+| | or the caller is not permitted to access the |
+| | service. |
++-------------------------+---------------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_psa_connect()`` invokes common ``psa_connect()`` handler in TF-M.
+The parameters in params should be prepared before calling
+``tfm_rpc_psa_connect()``.
+
+``tfm_rpc_psa_call()``
+^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M RPC handler for ``psa_call()``.
+
+.. code-block:: c
+
+ psa_status_t tfm_rpc_psa_call(const struct client_call_params_t *params,
+ bool ns_caller);
+
+Parameters
+~~~~~~~~~~
+
++---------------+-----------------------------------+
+| ``params`` | Base address of parameters. |
++---------------+-----------------------------------+
+| ``ns_caller`` | Whether the caller is non-secure. |
++---------------+-----------------------------------+
+
+Return
+~~~~~~
+
++---------------------+---------------------------------------------+
+| ``PSA_SUCCESS`` | Success. |
++---------------------+---------------------------------------------+
+| ``Does not return`` | The call is invalid, or invalid parameters. |
++---------------------+---------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_psa_call()`` invokes common ``psa_call()`` handler in TF-M.
+The parameters in params should be prepared before calling
+``tfm_rpc_psa_call()``.
+
+``tfm_rpc_psa_close()``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M RPC ``psa_close()`` handler
+
+.. code-block:: c
+
+ void tfm_rpc_psa_close(const struct client_call_params_t *params,
+ bool ns_caller);
+
+Parameters
+~~~~~~~~~~
+
++---------------+-----------------------------------+
+| ``params`` | Base address of parameters. |
++---------------+-----------------------------------+
+| ``ns_caller`` | Whether the caller is non-secure. |
++---------------+-----------------------------------+
+
+Return
+~~~~~~
+
++---------------------+---------------------------------------------+
+| ``void`` | Success. |
++---------------------+---------------------------------------------+
+| ``Does not return`` | The call is invalid, or invalid parameters. |
++---------------------+---------------------------------------------+
+
+Usage
+~~~~~
+
+``tfm_rpc_psa_close()`` invokes common ``psa_close()`` handler in TF-M.
+The parameters in params should be prepared before calling
+``tfm_rpc_psa_close()``.
+
+Other modifications
+===================
+
+The following mandatory changes are also required.
+
+- One or more compile flag(s) should be defined to select corresponding
+ execution routines in dual-core scenario or single Armv8-M scenario during
+ building.
+- PendSV priority should be configured in TF-M initialization.
+
+Some optional changes or optimizations are listed below.
+
+- The PSA client call handlers of ``psa_connect()``, ``psa_call()`` and
+ ``psa_close()`` can be optimized to skip asserting PendSV in dual-core
+ scenario.
+
+*********
+Reference
+*********
+
+.. [1] :doc:`Mailbox Design in TF-M on Dual-core System <./mailbox_design_on_dual_core_system>`
+
+----------------
+
+*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.*
+
+*Copyright (c) 2020 Cypress Semiconductor Corporation.*
diff --git a/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png b/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png
new file mode 100644
index 0000000000..79f5654465
Binary files /dev/null and b/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png differ
diff --git a/docs/technical_references/dual-cpu/index.rst b/docs/technical_references/dual-cpu/index.rst
new file mode 100644
index 0000000000..f302748333
--- /dev/null
+++ b/docs/technical_references/dual-cpu/index.rst
@@ -0,0 +1,12 @@
+Dual-CPU
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst b/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst
new file mode 100644
index 0000000000..60ac467d0f
--- /dev/null
+++ b/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst
@@ -0,0 +1,1475 @@
+##########################################
+Mailbox Design in TF-M on Dual-core System
+##########################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+This document proposes a generic design of the mailbox communication for Trusted
+Firmware-M (TF-M) on a dual-core system. The mailbox functionalities transfer
+PSA Client requests and results between Non-secure Processing Environment (NSPE)
+and Secure Processing Environment (SPE).
+
+The dual-core system should satisfy the following requirements
+
+- NSPE and SPE are properly isolated and protected following PSA specifications.
+- An Arm M-profile core locates in SPE and acts as the Secure core.
+- TF-M runs on the Secure core with platform specific drivers support.
+- Inter-Processor Communication hardware module in system for communication
+ between Secure core and Non-secure core. Mailbox communication calls the
+ Inter-Processor Communication to transfer notifications.
+- Non-secure memory shared by NSPE and SPE.
+
+Scope
+=====
+
+This design document focuses on the mailbox functionalities in NSPE and SPE on a
+dual-core system. The mailbox functionalities include the initialization of
+mailbox in NSPE and SPE, and the transfer of PSA Client requests and replies
+between NSPE and SPE.
+
+Data types and mailbox APIs are defined in this document.
+
+Some details of interactions between mailbox and other modules are specified in
+other documents.
+Communication prototype design [1]_ defines a general communication prototype
+between NSPE and SPE on a dual-core system. It describes how TF-M interacts with
+mailbox functionalities and the general requirements on mailbox.
+Dual-core booting sequence [2]_ describes a synchronization step of mailbox
+between NSPE and SPE during system booting.
+
+Organization of the document
+============================
+
+- `Mailbox architecture`_ provides an overview on the mailbox architecture.
+- `Mailbox communication for PSA Client calls`_ discusses about the mailbox
+ communication for PSA Client calls.
+- `Mailbox initialization`_ introduces the initialization of mailbox.
+- `Mailbox APIs and data structures`_ lists mailbox data types and APIs.
+
+********************
+Mailbox architecture
+********************
+
+The mailbox consists of two parts sitting in NSPE and SPE respectively.
+NSPE mailbox provides mailbox functionalities in NSPE and SPE mailbox provides
+mailbox functionalities in TF-M in SPE.
+
+PSA Client APIs called in NSPE are implemented by NSPE mailbox functions on
+dual-core systems, to send PSA Client request and receive the result. The
+implementation can vary in diverse NSPE OSs or use cases.
+
+TF-M provides a reference implementation of NSPE mailbox. The NSPE mailbox
+delivers the PSA Client requests to SPE mailbox. After the PSA Client result is
+replied from SPE, NSPE mailbox fetches the result and returns it to PSA Client
+APIs.
+
+NSPE mailbox objects are managed by NSPE mailbox in non-secure memory to hold
+PSA Client call parameters, return result and other mailbox data.
+NSPE mailbox relies on platform specific Inter-Process Communication to process
+notifications between NSPE and SPE.
+
+The SPE mailbox in TF-M receives PSA Client requests from NSPE mailbox. It
+parses the requests and invokes TF-M Remote Procedure Call (RPC) layer.
+RPC layer delivers the requests to TF-M core/Secure Partition Manager (SPM).
+After the PSA Client call is completed, TF-M core/SPM invokes RPC layer to
+return results to NSPE, via SPE mailbox.
+SPE mailbox objects are managed by SPE mailbox in secure memory.
+SPE mailbox relies on platform specific Inter-Process Communication to process
+notifications between SPE and NSPE.
+
+The architecture is showed in following figure.
+
+.. figure:: dual_core_mailbox_arch.png
+
+******************************************
+Mailbox communication for PSA Client calls
+******************************************
+
+This section describes the transfer of PSA Client request and reply between NSPE
+and SPE via mailbox.
+
+Mailbox objects
+===============
+
+This section lists the mailbox objects required in NSPE and SPE.
+
+NSPE mailbox objects are managed by NSPE mailbox in non-secure memory. But NSPE
+mailbox objects can be accessed by both NSPE mailbox and SPE mailbox.
+
+SPE mailbox objects are managed by SPE mailbox in secure memory. SPE mailbox
+objects should be protected from NSPE accesses by system specific isolation.
+
+NSPE Mailbox queue
+------------------
+
+NSPE mailbox maintains a mailbox queue in non-secure memory. Please refer to the
+structure definition in `NSPE mailbox queue structure`_.
+
+NSPE mailbox queue contains one or more slots. The number of slots should be
+aligned with that in SPE mailbox queue.
+
+Each slot in NSPE mailbox queue consists of a pair of a mailbox message
+structure and a mailbox reply structure. Each slot might contain additional
+fields, such as identification of non-secure task which initiates the PSA Client
+request. Each slot serves a PSA Client call from non-secure task.
+
+The parameters of PSA Client request are hosted in the mailbox message inside
+the slot. `Mailbox messages`_ describes the details of mailbox message.
+
+The mailbox reply structure is used to receive the PSA Client result from SPE.
+`Mailbox replies`_ describes the details of mailbox reply.
+
+Mailbox messages
+----------------
+
+A mailbox message contains the parameters of a PSA Client request from a
+non-secure task. Please refer to the structure definition in
+`Mailbox message structure`_.
+
+Inside PSA Client API implementation, NSPE mailbox selects an empty mailbox
+queue slot for the PSA Client request. The parameters of that PSA Client request
+are organized into the mailbox message belonging to the selected slot.
+SPE mailbox will parse those parameters from the mailbox message.
+
+More fields can be defined in mailbox message to transfer additional information
+from NSPE to SPE for processing in TF-M.
+
+Mailbox replies
+---------------
+
+A mailbox reply structure in non-secure memory receives the PSA Client result
+replied from SPE mailbox. Please refer to the structure definition in
+`Mailbox reply structure`_.
+
+SPE Mailbox queue
+-----------------
+
+SPE mailbox maintains a mailbox queue to store SPE mailbox objects.
+Please refer to the structure definition in `SPE mailbox queue structure`_.
+
+SPE mailbox queue contains one or more slots. The number of slots should be
+aligned with that in NSPE mailbox queue. After SPE is notified that a PSA Client
+request is pending, SPE mailbox can assign an empty slot, copy the corresponding
+PSA Client call parameters from non-secure memory to that slot and parse the
+parameters.
+
+Each slot in SPE mailbox queue can contain the following fields
+
+- An optional field to hold mailbox message content copied from non-secure
+ memory.
+- Index of NSPE mailbox queue slot containing the mailbox message.
+- A handle to the mailbox message. Optional. Identify the owner slot of PSA
+ Client result when multiple mailbox messages are under processing.
+
+More fields can be defined in the slot structure to support mailbox processing
+in SPE.
+
+Overall workflow
+================
+
+The overall workflow of transferring PSA Client requests and results between
+NSPE and SPE via mailbox is shown below.
+
+#. Non-secure task initiates a service request by calling PSA Developer APIs,
+ which eventually invoke PSA Client APIs.
+ PSA Client APIs call NSPE mailbox functions to transmit PSA Client call to
+ SPE.
+
+#. NSPE mailbox assigns an empty slot from NSPE mailbox queue for that PSA
+ client call.
+
+#. NSPE mailbox prepares the parameters of PSA Client call in the dedicated
+ mailbox message inside the assigned slot.
+
+#. After the mailbox message is ready, NSPE mailbox invokes platform specific
+ Inter-Processor Communication driver to notify SPE.
+ The notification mechanism of Inter-Processor Communication is platform
+ specific.
+
+#. After the notification is completed, non-secure task waits for the reply from
+ SPE.
+
+#. Platform specific Inter-Processor Communication interrupt for mailbox is
+ asserted in SPE. The interrupt handler activates SPE mailbox to process the
+ request(s).
+
+#. During mailbox processing in TF-M, the handling routine can include the
+ following steps:
+
+ #. SPE mailbox checks and validates NSPE mailbox queue status.
+ #. SPE mailbox fetches PSA Client call parameters from NSPE mailbox queue.
+ #. SPE mailbox parses the parameters.
+ #. SPE mailbox invokes the TF-M RPC APIs to deliver the PSA Client
+ request to TF-M SPM.
+ #. The PSA Client call is handled in TF-M SPM and target Secure Partition if
+ necessary.
+
+ If multiple ongoing mailbox messages are pending in the SPE, SPE mailbox can
+ process mailbox messages one by one.
+
+#. After the PSA Client call is completed, TF-M RPC layer notifies SPE mailbox
+ to reply PSA Client result to NSPE.
+
+#. SPE mailbox writes the PSA Client result to the dedicated mailbox reply
+ structure in non-secure memory. The related SPE mailbox objects should be
+ invalidated or cleaned.
+
+#. SPE mailbox notifies NSPE by invoking Inter-Processor Communication driver to
+ send a notification to NSPE.
+ The notification mechanism of Inter-Processor Communication is platform
+ specific.
+
+#. NSPE mailbox is activated to handle the PSA Client result in the mailbox
+ reply structure. Related mailbox objects should be invalidated or cleaned by
+ NSPE mailbox after the return results is extracted out.
+
+#. NSPE mailbox returns the result to PSA Client API implementation.
+ The result is eventually returned to the non-secure task.
+
+The following sections discuss more details of key steps in above sequence.
+
+Mailbox notifications between NSPE and SPE
+==========================================
+
+As shown in `Overall workflow`_, NSPE mailbox asserts mailbox notification to
+trigger SPE to handle PSA Client request. SPE mailbox asserts mailbox
+notification to notify NSPE that PSA Client result is written. The notification
+implementation is based on platform specific Inter-Processor Communication.
+
+It is recommended to assign one independent set of Inter-Processor Communication
+channel to each notification routine respectively, to implement a *full-duplex*
+notification mechanism between NSPE and SPE.
+If both notification routines share the same Inter-Processor Communication
+channel, proper synchronization should be implemented to prevent conflicts
+between two notification routines.
+
+In SPE, the Inter-Processor Communication interrupt handler should deal with the
+incoming notification from NSPE and activate the subsequent mailbox handling in
+SPE. Communication prototype design [1]_ defines the behavior of Inter-Processor
+Communication interrupt handler.
+
+NSPE can implement an interrupt handler or a polling of notification status to
+handle Inter-Processor Communication notification from SPE.
+
+Implement PSA Client API with NSPE Mailbox
+==========================================
+
+PSA Client APIs are implemented with NSPE mailbox API
+``tfm_ns_mailbox_client_call()``.
+
+The pseudo code below shows a reference implementation of
+``psa_framework_version()``.
+
+.. code-block:: c
+
+ uint32_t psa_framework_version(void)
+ {
+ ...
+ int32_t ret;
+
+ ret = tfm_ns_mailbox_client_call(...);
+ if (ret != MAILBOX_SUCCESS) {
+ version = PSA_VERSION_NONE;
+ }
+
+ ...
+ }
+
+``tfm_ns_mailbox_client_call()`` implementation can vary according to usage
+scenario. TF-M reference implementation provides implementations for NS OS and
+NS bare metal environment respectively. Refer to
+`TF-M reference implementation of NSPE mailbox`_ for details.
+
+As PSA Firmware Framework-M (FF-M) requests, a PSA Client API function should be
+blocked until the result is returned. To comply with FF-M, NSPE mailbox requires
+proper mechanism(s) to keep current caller waiting for PSA Client result or an
+empty mailbox queue slot.
+
+.. note::
+
+ ``tfm_ns_mailbox_client_call()`` may trap the current exception in sleep and
+ therefore it must not be called in interrupt service routine.
+
+Refer to `Mailbox APIs and data structures`_ for details of
+``tfm_ns_mailbox_client_call()``.
+
+TF-M reference implementation of NSPE mailbox
+=============================================
+
+TF-M NS interface provides a reference implementation of NS mailbox.
+
+This reference implementation defines several NS mailbox HAL APIs. Please refer
+to `NSPE mailbox HAL APIs`_ for details.
+
+Integration with NSPE
+---------------------
+
+TF-M reference implementation provides several mailbox build flags to control
+the integration with NS software.
+
+ .. _mailbox_os_flag:
+
+ - ``TFM_MULTI_CORE_NS_OS``
+
+ When integrating NS mailbox with NS OS, such as NS RTOS, that flag can be
+ selected to enable NS OS support in NS mailbox, such as thread management
+ to fulfill thread wait and wake-up.
+ Please refer to `NSPE mailbox RTOS abstraction APIs`_ for NS OS support
+ details.
+
+ With NS OS support, multiple outstanding PSA Client calls can be supported
+ in NS mailbox when number of mailbox queue slots configured in
+ ``NUM_MAILBOX_QUEUE_SLOT`` is greater than 1.
+
+ If ``TFM_MULTI_CORE_NS_OS`` is enabled, when a NS client starts a PSA Client
+ call:
+
+ - ``tfm_ns_mailbox_client_call()`` selects an empty NSPE mailbox queue slot
+ to organize received PSA client call parameters into a mailbox message.
+
+ - Then it sends those parameters to SPE mailbox and waits for results from
+ SPE. During waiting for the result, the NS client thread may be switched
+ out by NS OS scheduler.
+
+ - When the result arrives, the NS client thread will be woken up inside
+ NS mailbox interrupt handler.
+
+ - The result is then written back to NS client finally.
+
+ When that flag is disabled, NS mailbox runs as being integrated with NS bare
+ metal environment. NS mailbox simply loops mailbox message status while
+ waiting for results.
+
+ .. _mailbox_os_thread_flag:
+
+ - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD``
+
+ When ``TFM_MULTI_CORE_NS_OS`` is enabled, this flag can be selected to
+ enable another NS mailbox thread model which relies on a NS mailbox
+ dedicated thread.
+
+ - It requires NS OS to create a dedicated thread to perform NS mailbox
+ functionalities. This dedicated thread invokes
+ ``tfm_ns_mailbox_thread_runner()`` to handle PSA Client calls.
+ ``tfm_ns_mailbox_thread_runner()`` constructs mailbox messages and sends
+ them to SPE mailbox.
+
+ - ``tfm_ns_mailbox_client_call()`` sends PSA Client calls to the dedicated
+ mailbox thread. It doesn't directly deal with mailbox messages.
+
+ - It also relies on NS OS to provide thread management and inter-thread
+ communication. Please refer to `NSPE mailbox RTOS abstraction APIs`_ for
+ details.
+
+ - It also requires dual-cpu platform to implement NS Inter-Processor
+ Communication interrupts. The interrupt handler invokes
+ ``tfm_ns_mailbox_wake_reply_owner_isr()`` to deal with PSA Client call
+ replies and notify the waiting threads.
+
+Multiple outstanding PSA Client call feature
+--------------------------------------------
+
+Multiple outstanding PSA Client call feature can enable dual-cpu platform to
+issue multiple PSA Client calls in NS OS and those PSA Client calls can be
+served simultaneously.
+
+Without this feature, only a single PSA Client call can be issued and served.
+A new PSA Client call cannot be started until the previous one is completed.
+
+When multiple outstanding PSA Client call feature is enabled, while a NS
+application is waiting for its PSA Client result, another NS application can be
+switched in by NS OS to prepare another PSA Client call or deal with its PSA
+client result. It can decrease the CPU idle time of waiting for PSA Client call
+completion.
+
+If multiple NS applications request secure services in NS OS, it is recommended
+to enable this feature.
+
+To implement this feature in NS OS:
+
+ - Platform should set the number of mailbox queue slots in
+ ``NUM_MAILBOX_QUEUE_SLOT`` in platform's ``config.cmake``.
+ It will use more data area with multiple mailbox queue slots.
+
+ NSPE and SPE share the same ``NUM_MAILBOX_QUEUE_SLOT`` value.
+
+ - Enable ``TFM_MULTI_CORE_NS_OS``
+
+ For more details, refer to
+ :ref:`TFM_MULTI_CORE_NS_OS`.
+
+ ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` can be enabled to select another NS
+ mailbox working model.
+ See :ref:`TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD` for
+ details.
+
+Critical section protection between cores
+=========================================
+
+Proper protection should be implemented to protect the critical accesses to
+shared mailbox resources. The critical sections can include atomic reading and
+modifying NSPE mailbox queue status, slot status and other critical operations.
+
+The implementation should protect a critical access to those shared mailbox
+resource from corruptions caused by accesses from the peer core. SPE mailbox
+also accesses NSPE mailbox queue. Therefore, it is essential to implement
+synchronization or protection on NSPE mailbox queue between Secure core and
+Non-secure core. NSPE mailbox and SPE mailbox define corresponding critical
+section protection APIs respectively. The implementation of those APIs can be
+platform specific. Please see more details in `NSPE mailbox APIs`_ and
+`SPE mailbox APIs`_.
+
+It is recommended to rely on both hardware and software to implement the
+synchronization and protection.
+
+Protection of local mailbox objects can be implemented as static functions
+inside NSPE mailbox and SPE mailbox.
+
+Mailbox handling in TF-M
+========================
+
+According to communication prototype design [1]_, mailbox implementation should
+invoke ``tfm_rpc_register_ops()`` to hook its operations to TF-M RPC module
+callbacks during initialization. Mailbox message handling should call TF-M RPC
+PSA Client call handlers to deliver PSA Client request to TF-M SPM.
+
+If multiple outstanding NS PSA Client calls should be supported, TF-M SPM can
+store the mailbox message handle in a specific field in PSA message structure to
+identify the mailbox message, while creating a PSA message. While replying the
+PSA Client result, TF-M SPM can extract the mailbox message handle from PSA
+message and pass it back to mailbox reply function. SPE mailbox can identify
+which mailbox message is completed according to the handle and write the result
+to corresponding NSPE mailbox queue slot.
+
+Platform specific Inter-Processor Communication interrupt handler in SPE should
+call ``tfm_mailbox_msg_irq_handler()`` to notify SPE mailbox to deal with
+received PSA Client call(s) from NSPE. ``tfm_mailbox_msg_irq_handler()`` will
+assert PendSV. Please refer to `tfm_mailbox_msg_irq_handler()`_ for details.
+
+**********************
+Mailbox initialization
+**********************
+
+It should be guaranteed that NSPE mailbox should not initiate PSA Client request
+until SPE mailbox initialization completes.
+Refer to dual-core booting sequence [2]_ for more details on the synchronization
+between NSPE and SPE during booting.
+
+In current design, the base address of NSPE mailbox queue should be pre-defined
+and shared between NSPE mailbox and SPE mailbox.
+
+SPE mailbox initialization
+==========================
+
+The SPE mailbox queue memory should be allocated before calling
+``tfm_mailbox_init()``. ``tfm_mailbox_init()`` initializes the memory and
+variables.
+``tfm_mailbox_init()`` calls ``tfm_mailbox_hal_init()`` to perform platform
+specific initialization. The base address of NSPE mailbox queue can be
+received via ``tfm_mailbox_hal_init()``.
+
+SPE mailbox dedicated Inter-Processor Communication initialization can also be
+enabled during SPE mailbox initialization.
+
+After SPE mailbox initialization completes, SPE notifies NSPE that SPE mailbox
+functionalities are ready.
+
+NSPE mailbox initialization
+===========================
+
+The NSPE mailbox queue memory should be allocated before calling
+``tfm_ns_mailbox_init()``. ``tfm_ns_mailbox_init()`` initializes the memory and
+variables.
+``tfm_ns_mailbox_init()`` calls ``tfm_ns_mailbox_hal_init()`` to perform
+platform specific initialization. The base address of NSPE mailbox queue can be
+passed to SPE mailbox via ``tfm_ns_mailbox_hal_init()``.
+
+NSPE mailbox dedicated Inter-Processor Communication initialization can also be
+enabled during NSPE mailbox initialization.
+
+********************************
+Mailbox APIs and data structures
+********************************
+
+Data types
+==========
+
+Constants
+---------
+
+``MAILBOX_SUCCESS``
+^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_SUCCESS`` is a generic return value to indicate success of mailbox
+operation.
+
+.. code-block:: c
+
+ #define MAILBOX_SUCCESS (0)
+
+``MAILBOX_QUEUE_FULL``
+^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_QUEUE_FULL`` is a return value from mailbox function if mailbox queue
+is full.
+
+.. code-block:: c
+
+ #define MAILBOX_QUEUE_FULL (INT32_MIN + 1)
+
+``MAILBOX_INVAL_PARAMS``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_INVAL_PARAMS`` is a return value from mailbox function if any
+parameter is invalid.
+
+.. code-block:: c
+
+ #define MAILBOX_INVAL_PARAMS (INT32_MIN + 2)
+
+``MAILBOX_NO_PERMS``
+^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_NO_PERMS`` is a return value from mailbox function if the caller
+doesn't own a proper permission to execute the operation.
+
+.. code-block:: c
+
+ #define MAILBOX_NO_PERMS (INT32_MIN + 3)
+
+``MAILBOX_NO_PEND_EVENT``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_NO_PEND_EVENT`` is a return value from mailbox function if the
+expected event doesn't occur yet.
+
+.. code-block:: c
+
+ #define MAILBOX_NO_PEND_EVENT (INT32_MIN + 4)
+
+``MAILBOX_CHAN_BUSY``
+^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_CHAN_BUSY`` is a return value from mailbox function if the underlying
+Inter-Processor Communication resource is busy.
+
+.. code-block:: c
+
+ #define MAILBOX_CHAN_BUSY (INT32_MIN + 5)
+
+``MAILBOX_CALLBACK_REG_ERROR``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_CALLBACK_REG_ERROR`` is a return value from mailbox function if the
+registration of mailbox callback functions failed.
+
+.. code-block:: c
+
+ #define MAILBOX_CALLBACK_REG_ERROR (INT32_MIN + 6)
+
+``MAILBOX_INIT_ERROR``
+^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_INIT_ERROR`` is a return value from mailbox function if the mailbox
+initialization failed.
+
+.. code-block:: c
+
+ #define MAILBOX_INIT_ERROR (INT32_MIN + 7)
+
+``MAILBOX_GENERIC_ERROR``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MAILBOX_GENERIC_ERROR`` indicates mailbox generic errors which cannot be
+indicated by the codes above.
+
+.. code-block:: c
+
+ #define MAILBOX_GENERIC_ERROR (INT32_MIN + 8)
+
+PSA Client API types
+^^^^^^^^^^^^^^^^^^^^
+
+The following constants define the PSA Client API type values shared between
+NSPE and SPE
+
+.. code-block:: c
+
+ #define MAILBOX_PSA_FRAMEWORK_VERSION (0x1)
+ #define MAILBOX_PSA_VERSION (0x2)
+ #define MAILBOX_PSA_CONNECT (0x3)
+ #define MAILBOX_PSA_CALL (0x4)
+ #define MAILBOX_PSA_CLOSE (0x5)
+
+Mailbox message structure
+-------------------------
+
+``psa_client_params_t`` lists the parameters passed from NSPE to SPE required by
+a PSA Client call.
+
+.. code-block:: c
+
+ struct psa_client_params_t {
+ union {
+ struct {
+ uint32_t sid;
+ } psa_version_params;
+
+ struct {
+ uint32_t sid;
+ uint32_t minor_version;
+ } psa_connect_params;
+
+ struct {
+ psa_handle_t handle;
+ int32_t type;
+ const psa_invec *in_vec;
+ size_t in_len;
+ psa_outvec *out_vec;
+ size_t out_len;
+ } psa_call_params;
+
+ struct {
+ psa_handle_t handle;
+ } psa_close_params;
+ };
+ };
+
+The following structure describe a mailbox message and its members.
+
+- ``call_type`` indicates the PSA Client API type.
+- ``params`` stores the PSA Client call parameters.
+- ``client_id`` records the client ID of the non-secure client. Optional.
+ It is used to identify the non-secure tasks in TF-M when NSPE OS enforces
+ non-secure task isolation.
+
+.. code-block:: c
+
+ struct mailbox_msg_t {
+ uint32_t call_type;
+ struct psa_client_params_t params;
+
+ int32_t client_id;
+ };
+
+Mailbox reply structure
+-----------------------
+
+This structure describes a mailbox reply structure, which is managed by NSPE
+mailbox in non-secure memory.
+
+.. code-block:: c
+
+ struct mailbox_reply_t {
+ int32_t return_val;
+ const void *owner;
+ int32_t *reply;
+ uint8_t *woken_flag;
+ };
+
+Mailbox queue status bitmask
+----------------------------
+
+``mailbox_queue_status_t`` defines a bitmask to indicate a status of slots in
+mailbox queues.
+
+.. code-block:: c
+
+ typedef uint32_t mailbox_queue_status_t;
+
+NSPE mailbox queue structure
+----------------------------
+
+``ns_mailbox_slot_t`` defines a non-secure mailbox queue slot.
+
+.. code-block:: c
+
+ /* A single slot structure in NSPE mailbox queue */
+ struct ns_mailbox_slot_t {
+ struct mailbox_msg_t msg;
+ struct mailbox_reply_t reply;
+ };
+
+``ns_mailbox_queue_t`` describes the NSPE mailbox queue and its members in
+non-secure memory.
+
+- ``empty_slots`` is the bitmask of empty slots.
+- ``pend_slots`` is the bitmask of slots whose PSA Client call is not replied
+ yet.
+- ``replied_slots`` is the bitmask of slots whose PSA Client result is returned
+ but not extracted yet.
+- ``queue`` is the NSPE mailbox queue of slots.
+- ``is_full`` indicates whether NS mailbox queue is full.
+
+.. code-block:: c
+
+ struct ns_mailbox_queue_t {
+ mailbox_queue_status_t empty_slots;
+ mailbox_queue_status_t pend_slots;
+ mailbox_queue_status_t replied_slots;
+
+ struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];
+
+ bool is_full;
+ };
+
+SPE mailbox queue structure
+---------------------------
+
+``secure_mailbox_slot_t`` defines a single slot structure in SPE mailbox queue.
+
+- ``ns_slot_idx`` records the index of NSPE mailbox slot containing the mailbox
+ message under processing. SPE mailbox determines the reply structure address
+ according to this index.
+- ``msg_handle`` contains the handle to the mailbox message under processing.
+ The handle can be delivered to TF-M SPM while creating PSA message to identify
+ the mailbox message.
+
+.. code-block:: c
+
+ /* A handle to a mailbox message in use */
+ typedef int32_t mailbox_msg_handle_t;
+
+ struct secure_mailbox_slot_t {
+ uint8_t ns_slot_idx;
+ mailbox_msg_handle_t msg_handle;
+ };
+
+``secure_mailbox_queue_t`` describes the SPE mailbox queue in secure memory.
+
+- ``empty_slots`` is the bitmask of empty slots.
+- ``queue`` is the SPE mailbox queue of slots.
+- ``ns_queue`` stores the address of NSPE mailbox queue structure.
+- ``cur_proc_slot_idx`` indicates the index of mailbox queue slot currently
+ under processing.
+
+.. code-block:: c
+
+ struct secure_mailbox_queue_t {
+ mailbox_queue_status_t empty_slots;
+
+ struct secure_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];
+ /* Base address of NSPE mailbox queue in non-secure memory */
+ struct ns_mailbox_queue_t *ns_queue;
+ uint8_t cur_proc_slot_idx;
+ };
+
+NSPE mailbox APIs
+=================
+
+NSPE mailbox interface APIs
+---------------------------
+
+APIs defined in this section are called by NS software and PSA Client APIs
+implementations.
+
+``tfm_ns_mailbox_init()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function initializes NSPE mailbox.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue);
+
+**Parameters**
+
++-----------+-----------------------------------------+
+| ``queue`` | The base address of NSPE mailbox queue. |
++-----------+-----------------------------------------+
+
+**Return**
+
++---------------------+------------------------------------------+
+| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
++---------------------+------------------------------------------+
+| Other return codes | Initialization fails with an error code. |
++---------------------+------------------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_init()`` invokes ``tfm_ns_mailbox_hal_init()`` to complete
+platform specific mailbox and Inter-Processor Communication initialization.
+The non-secure memory area for NSPE mailbox queue structure should be statically
+or dynamically pre-allocated before calling ``tfm_ns_mailbox_init()``.
+
+``tfm_ns_mailbox_client_call()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function sends the PSA Client request to SPE, waits and fetches PSA Client
+result.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_client_call(uint32_t call_type,
+ const struct psa_client_params_t *params,
+ int32_t client_id,
+ int32_t *reply);
+
+**Parameters**
+
++---------------+--------------------------------------------------+
+| ``call_type`` | Type of PSA Client call |
++---------------+--------------------------------------------------+
+| ``params`` | Address of PSA Client call parameters structure. |
++---------------+--------------------------------------------------+
+| ``client_id`` | ID of non-secure task. |
++---------------+--------------------------------------------------+
+| ``reply`` | The NS client task private buffer written with |
+| | PSA Client result |
++---------------+--------------------------------------------------+
+
+**Return**
+
++---------------------+--------------------------------------------+
+| ``MAILBOX_SUCCESS`` | PSA Client call is completed successfully. |
++---------------------+--------------------------------------------+
+| Other return code | Operation failed with an error code. |
++---------------------+--------------------------------------------+
+
+**Usage**
+
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
+``tfm_ns_mailbox_client_call()`` will forward PSA Client calls to the dedicated
+mailbox thread via NS OS message queue.
+Otherwise, ``tfm_ns_mailbox_client_call()`` directly deals with PSA Client calls
+and perform NS mailbox functionalities.
+
+``tfm_ns_mailbox_thread_runner()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function handles PSA Client call inside a dedicated NS mailbox thread.
+It constructs mailbox messages and transmits them to SPE mailbox.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_thread_runner(void *args);
+
+**Parameters**
+
++----------+-------------------------------------------------------------+
+| ``args`` | The pointer to the structure of PSA Client call parameters. |
++----------+-------------------------------------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_thread_runner()`` should be executed inside the dedicated
+mailbox thread.
+
+.. note::
+
+ ``tfm_ns_mailbox_thread_runner()`` is implemented as an empty function when
+ ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled.
+
+``tfm_ns_mailbox_wake_reply_owner_isr()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function wakes up the owner task(s) of the returned PSA Client result(s).
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_wake_reply_owner_isr(void);
+
+**Return**
+
++---------------------------+--------------------------------------------+
+| ``MAILBOX_SUCCESS`` | The tasks of replied mailbox messages were |
+| | found and wake-up signals were sent. |
++---------------------------+--------------------------------------------+
+| ``MAILBOX_NO_PEND_EVENT`` | No replied mailbox message is found. |
++---------------------------+--------------------------------------------+
+| Other return codes | Operation failed with an error code |
++---------------------------+--------------------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_wake_reply_owner_isr()`` should be called from platform
+specific Inter-Processor Communication interrupt handler.
+
+.. note::
+
+ ``tfm_ns_mailbox_wake_reply_owner_isr()`` is implemented as a dummy function
+ when ``TFM_MULTI_CORE_NS_OS`` is disabled.
+
+NSPE mailbox HAL APIs
+---------------------
+
+The HAL APIs defined in this section should be implemented by platform-specific
+implementation.
+
+This section describes a *reference design* of NSPE mailbox HAL APIs. Developers
+can define and implement different APIs.
+
+``tfm_ns_mailbox_hal_init()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function executes platform-specific NSPE mailbox initialization.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);
+
+**Parameters**
+
++-----------+-----------------------------------------+
+| ``queue`` | The base address of NSPE mailbox queue. |
++-----------+-----------------------------------------+
+
+**Return**
+
++---------------------+------------------------------------------+
+| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
++---------------------+------------------------------------------+
+| Other return codes | Initialization fails with an error code. |
++---------------------+------------------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_hal_init()`` performs platform specific mailbox and
+Inter-Processor Communication initialization. ``tfm_ns_mailbox_hal_init()`` can
+also share the address of NSPE mailbox queue with SPE mailbox via platform
+specific implementation.
+
+``tfm_ns_mailbox_hal_notify_peer()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function invokes platform specific Inter-Processor Communication drivers to
+send notification to SPE.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_hal_notify_peer(void);
+
+**Return**
+
++---------------------+---------------------------------------+
+| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
++---------------------+---------------------------------------+
+| Other return codes | Operation fails with an error code. |
++---------------------+---------------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_hal_notify_peer()`` should be implemented by platform specific
+Inter-Processor Communication drivers.
+
+``tfm_ns_mailbox_hal_notify_peer()`` should not be exported outside NSPE
+mailbox.
+
+``tfm_ns_mailbox_hal_enter_critical()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function enters the critical section of NSPE mailbox queue access.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_hal_enter_critical(void);
+
+**Usage**
+
+NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical()`` before entering
+critical section of NSPE mailbox queue.
+``tfm_ns_mailbox_hal_enter_critical()`` implementation is platform specific.
+
+``tfm_ns_mailbox_hal_enter_critical()`` should not be called in any interrupt
+service routine.
+
+``tfm_ns_mailbox_hal_exit_critical()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function exits the critical section of NSPE mailbox queue access.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_hal_exit_critical(void);
+
+**Usage**
+
+NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical()`` after exiting
+critical section of NSPE mailbox queue.
+``tfm_ns_mailbox_hal_exit_critical()`` implementation is platform specific.
+
+``tfm_ns_mailbox_hal_exit_critical()`` should not be called in any interrupt
+service routine.
+
+``tfm_ns_mailbox_hal_enter_critical_isr()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function enters the critical section of NSPE mailbox queue access in an
+IRQ handler.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_hal_enter_critical(void);
+
+**Usage**
+
+NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical_isr()`` before entering
+critical section of NSPE mailbox queue in an IRQ handler.
+``tfm_ns_mailbox_hal_enter_critical_isr()`` implementation is platform specific.
+
+``tfm_ns_mailbox_hal_exit_critical_isr()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function exits the critical section of NSPE mailbox queue access in an IRQ
+handler
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_hal_exit_critical_isr(void);
+
+**Usage**
+
+NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical_isr()`` after exiting
+critical section of NSPE mailbox queue in an IRQ handler.
+``tfm_ns_mailbox_hal_exit_critical_isr()`` implementation is platform specific.
+
+NSPE mailbox RTOS abstraction APIs
+----------------------------------
+
+The APIs defined in this section should be implemented by RTOS-specific
+implementation when ``TFM_MULTI_CORE_NS_OS`` is enabled.
+
+.. note::
+
+ If ``TFM_MULTI_CORE_NS_OS`` is set to ``OFF``, the following APIs are defined
+ as dummy functions or empty functions.
+
+``tfm_ns_mailbox_os_lock_init()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function initializes the multi-core lock for synchronizing PSA client
+call(s). The actual implementation depends on the non-secure use scenario.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_os_lock_init(void);
+
+**Return**
+
++---------------------------+---------------------------+
+| ``MAILBOX_SUCCESS`` | Initialization succeeded. |
++---------------------------+---------------------------+
+| ``MAILBOX_GENERIC_ERROR`` | Initialization failed. |
++---------------------------+---------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_init()`` invokes this function to initialize the lock.
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
+``tfm_ns_mailbox_os_lock_init()`` is defined as a dummy one.
+
+``tfm_ns_mailbox_os_lock_acquire()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function acquires the multi-core lock for synchronizing PSA client call(s).
+The actual implementation depends on the non-secure use scenario.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_os_lock_acquire(void);
+
+**Return**
+
++---------------------------+--------------------------------+
+| ``MAILBOX_SUCCESS`` | Succeeded to acquire the lock. |
++---------------------------+--------------------------------+
+| ``MAILBOX_GENERIC_ERROR`` | Failed to acquire the lock. |
++---------------------------+--------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_client_call()`` invokes this function to acquire the lock when
+``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
+``tfm_ns_mailbox_os_lock_acquire()`` is defined as a dummy one.
+
+``tfm_ns_mailbox_os_lock_release()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function releases the multi-core lock for synchronizing PSA client call(s).
+The actual implementation depends on the non-secure use scenario.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_os_lock_release(void);
+
+**Return**
+
++---------------------------+--------------------------------+
+| ``MAILBOX_SUCCESS`` | Succeeded to release the lock. |
++---------------------------+--------------------------------+
+| ``MAILBOX_GENERIC_ERROR`` | Failed to release the lock. |
++---------------------------+--------------------------------+
+
+**Usage**
+
+``tfm_ns_mailbox_client_call()`` invokes this function to release the lock when
+``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled,
+``tfm_ns_mailbox_os_lock_release()`` is defined as a dummy one.
+
+``tfm_ns_mailbox_os_get_task_handle()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function gets the handle of the current non-secure task executing mailbox
+functionalities.
+
+.. code-block:: c
+
+ void *tfm_ns_mailbox_os_get_task_handle(void);
+
+**Return**
+
++-------------+-----------------------------------------------------------+
+| Task handle | The non-secure task handle waiting for PSA Client result. |
++-------------+-----------------------------------------------------------+
+
+``tfm_ns_mailbox_os_wait_reply()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function performs use scenario and NS OS specific waiting mechanism to wait
+for the reply of the specified mailbox message to be returned from SPE.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_os_wait_reply(void);
+
+**Usage**
+
+The PSA Client API implementations call ``tfm_ns_mailbox_os_wait_reply()`` to
+fall into sleep to wait for PSA Client result.
+
+``tfm_ns_mailbox_os_wake_task_isr()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function wakes up the dedicated task which is waiting for PSA Client
+result, via RTOS-specific wake-up mechanism.
+
+.. code-block:: c
+
+ void tfm_ns_mailbox_hal_wait_reply(const void *task_handle);
+
+**Parameters**
+
++-----------------+----------------------------------------+
+| ``task_handle`` | The handle to the task to be woken up. |
++-----------------+----------------------------------------+
+
+``tfm_ns_mailbox_os_mq_create()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function creates and initializes a NS OS message queue.
+
+.. code-block:: c
+
+ void *tfm_ns_mailbox_os_mq_create(ize_t msg_size, uint8_t msg_count);
+
+**Parameters**
+
++---------------+------------------------------------------+
+| ``msg_size`` | The maximum message size in bytes. |
++---------------+------------------------------------------+
+| ``msg_count`` | The maximum number of messages in queue. |
++---------------+------------------------------------------+
+
+**Return**
+
++----------------------+-----------------------------------------------------+
+| message queue handle | The handle of the message queue created, or NULL in |
+| | case of error. |
++----------------------+-----------------------------------------------------+
+
+**Usage**
+
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
+``tfm_ns_mailbox_os_mq_create()`` is defined as a dummy one.
+
+``tfm_ns_mailbox_os_mq_send()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function sends PSA Client call request via NS OS message queue.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_os_mq_send(void *mq_handle,
+ const void *msg_ptr);
+
+**Parameters**
+
++---------------+----------------------------------------+
+| ``mq_handle`` | The handle of message queue. |
++---------------+----------------------------------------+
+| ``msg_ptr`` | The pointer to the message to be sent. |
++---------------+----------------------------------------+
+
+**Return**
+
++---------------------+-------------------------------------+
+| ``MAILBOX_SUCCESS`` | The message is successfully sent. |
++---------------------+-------------------------------------+
+| Other return code | Operation fails with an error code. |
++---------------------+-------------------------------------+
+
+**Usage**
+
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
+``tfm_ns_mailbox_os_mq_send()`` is defined as a dummy one.
+
+``tfm_ns_mailbox_os_mq_receive()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function receives PSA Client call requests via NS OS message queue.
+
+.. code-block:: c
+
+ int32_t tfm_ns_mailbox_os_mq_receive(void *mq_handle,
+ void *msg_ptr);
+
+**Parameters**
+
++---------------+---------------------------------------------------+
+| ``mq_handle`` | The handle of message queue. |
++---------------+---------------------------------------------------+
+| ``msg_ptr`` | The pointer to buffer for message to be received. |
++---------------+---------------------------------------------------+
+
+**Return**
+
++---------------------+-------------------------------------+
+| ``MAILBOX_SUCCESS`` | A message is successfully received. |
++---------------------+-------------------------------------+
+| Other return code | Operation fails with an error code. |
++---------------------+-------------------------------------+
+
+**Usage**
+
+The buffer size must be large enough to contain the request whose size is set
+in ``msg_size `` in ``tfm_ns_mailbox_os_mq_create()``.
+
+If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled,
+``tfm_ns_mailbox_os_mq_receive()`` is defined as a dummy one.
+
+.. note::
+
+ The function caller should be blocked until a PSA Client call request is
+ received from message queue, unless a fatal error occurs.
+
+SPE mailbox APIs
+================
+
+SPE mailbox interface APIs
+--------------------------
+
+The APIs defined in this section are called in TF-M routines and platform
+specific secure interrupt handler.
+
+``tfm_mailbox_handle_msg()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function completes the handling of mailbox messages from NSPE.
+
+.. code-block:: c
+
+ int32_t tfm_mailbox_handle_msg(void);
+
+**Return**
+
++---------------------+---------------------------------------+
+| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
++---------------------+---------------------------------------+
+| Other return codes | Operation fails with an error code. |
++---------------------+---------------------------------------+
+
+**Usage**
+
+``tfm_mailbox_handle_msg()`` is registered to RPC callback function
+``handle_req``.
+
+``tfm_mailbox_handle_msg()`` executes the following tasks:
+
+- Check NSPE mailbox queue status.
+- Copy mailbox message(s) from NSPE. Optional.
+- Checks and validations if necessary
+- Parse mailbox message
+- Call TF-M RPC APIs to pass PSA Client request to TF-M SPM.
+
+``tfm_mailbox_reply_msg()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function replies the PSA Client result to NSPE.
+
+.. code-block:: c
+
+ int32_t tfm_mailbox_reply_msg(mailbox_msg_handle_t handle, int32_t reply);
+
+**Parameters**
+
++------------+-----------------------------------------------------------------+
+| ``handle`` | The handle to mailbox message related to the PSA Client result. |
++------------+-----------------------------------------------------------------+
+| ``reply`` | The PSA Client result value to be replied. |
++------------+-----------------------------------------------------------------+
+
+**Return**
+
++---------------------+---------------------------------------+
+| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
++---------------------+---------------------------------------+
+| Other return codes | Operation fails with an error code. |
++---------------------+---------------------------------------+
+
+**Usage**
+
+``tfm_mailbox_reply_msg()`` is registered to RPC callback ``reply``.
+It is invoked inside handler of ``psa_reply()`` to return the PSA Client result
+to NSPE.
+
+``handle`` determines which mailbox message in SPE mailbox queue contains the
+PSA Client call. If ``handle`` is set as ``MAILBOX_MSG_NULL_HANDLE``, the return
+result is replied to the mailbox message in the first SPE mailbox queue slot.
+
+``tfm_mailbox_init()``
+^^^^^^^^^^^^^^^^^^^^^^
+
+This function initializes SPE mailbox.
+
+.. code-block:: c
+
+ int32_t tfm_mailbox_init(void);
+
+**Return**
+
++---------------------+-------------------------------------------+
+| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
++---------------------+-------------------------------------------+
+| Other return codes | Initialization failed with an error code. |
++---------------------+-------------------------------------------+
+
+**Usage**
+
+``tfm_mailbox_init()`` invokes ``tfm_mailbox_hal_init()`` to execute platform
+specific initialization.
+
+``tfm_mailbox_msg_irq_handler()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A general IRQ handler to deal with notification from NSPE mailbox.
+
+.. code-block:: c
+
+ void tfm_mailbox_msg_irq_handler(void);
+
+**Usage**
+
+``tfm_mailbox_msg_irq_handler()`` is called in platform-specific Inter-Processor
+Communication interrupt handler when a notification from NSPE mailbox arrives.
+
+SPE mailbox HAL APIs
+--------------------
+
+``tfm_mailbox_hal_notify_peer()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function invokes platform specific Inter-Processor Communication drivers to
+send notification to NSPE.
+
+.. code-block:: c
+
+ int32_t tfm_mailbox_hal_notify_peer(void);
+
+**Return**
+
++---------------------+---------------------------------------+
+| ``MAILBOX_SUCCESS`` | The operation completes successfully. |
++---------------------+---------------------------------------+
+| Other return codes | Operation fails with an error code. |
++---------------------+---------------------------------------+
+
+**Usage**
+
+``tfm_mailbox_hal_notify_peer()`` should be implemented by platform specific
+Inter-Processor Communication drivers.
+
+``tfm_mailbox_hal_notify_peer()`` should not be exported outside SPE mailbox.
+
+
+``tfm_mailbox_hal_init()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function is implemented by platform support in TF-M. It completes platform
+specific mailbox initialization, including receiving the the address of NSPE
+mailbox queue and Inter-Processor Communication initialization.
+
+.. code-block:: c
+
+ int32_t tfm_mailbox_hal_init(struct secure_mailbox_queue_t *s_queue);
+
+**Parameters**
+
++-------------+----------------------------------------+
+| ``s_queue`` | The base address of SPE mailbox queue. |
++-------------+----------------------------------------+
+
+**Return**
+
++---------------------+-------------------------------------------+
+| ``MAILBOX_SUCCESS`` | Initialization succeeds. |
++---------------------+-------------------------------------------+
+| Other return codes | Initialization failed with an error code. |
++---------------------+-------------------------------------------+
+
+``tfm_mailbox_hal_enter_critical()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function enters the critical section of NSPE mailbox queue access in SPE.
+
+.. code-block:: c
+
+ void tfm_mailbox_hal_enter_critical(void);
+
+**Usage**
+
+SPE mailbox invokes ``tfm_mailbox_hal_enter_critical()`` before entering
+critical section of NSPE mailbox queue.
+``tfm_mailbox_hal_enter_critical()`` implementation is platform specific.
+
+``tfm_mailbox_hal_enter_critical()`` can be called in an interrupt service
+routine.
+
+``tfm_mailbox_hal_exit_critical()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This function exits from the critical section of NSPE mailbox queue access in
+SPE.
+
+.. code-block:: c
+
+ void tfm_mailbox_hal_exit_critical(void);
+
+**Usage**
+
+SPE mailbox invokes ``tfm_mailbox_hal_exit_critical()`` when exiting from
+critical section of NSPE mailbox queue.
+``tfm_mailbox_hal_exit_critical()`` implementation is platform specific.
+
+``tfm_mailbox_hal_exit_critical()`` can be called in an interrupt service
+routine.
+
+*********
+Reference
+*********
+
+.. [1] :doc:`Communication prototype between NSPE and SPE in Dual-core systems <./communication_prototype_between_nspe_and_spe_in_dual_core_systems>`
+
+.. [2] :doc:`Booting a Dual-core system `
+
+--------------------
+
+*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.*
diff --git a/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst b/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst
new file mode 100644
index 0000000000..9ea9afdfe2
--- /dev/null
+++ b/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst
@@ -0,0 +1,513 @@
+################################################################
+Memory Access Check of Trusted Firmware-M in Multi-Core Topology
+################################################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+:Status: Accepted
+
+************
+Introduction
+************
+
+TF-M memory access check functions ``tfm_core_has_read_access_to_region()`` and
+``tfm_core_has_write_access_to_region()`` check whether an access has proper
+permission to read or write the target memory region.
+
+On single Armv8-M core platform, TF-M memory access check implementation relies
+on `Armv8-M Security Extension`_ (CMSE) intrinsic
+``cmse_check_address_range()``.
+The secure core may not implement CMSE on multi-core platforms. Even if CMSE is
+implemented on a multi-core platform, additional check on system-level security
+and memory access management units are still necessary since CMSE intrinsics and
+TT instructions are only aware of MPU/SAU/IDAU inside the core.
+
+As a result, TF-M in multi-core topology requires a dedicated access check
+process which can work without CMSE support. This document discuss about the
+design of the memory access check in multi-core topology.
+
+.. _Armv8-M Security Extension: https://developer.arm.com/architectures/cpu-architecture/m-profile/docs/100720/0100/secure-software-guidelines/armv8m-security-extension
+
+**************
+Overall Design
+**************
+
+Memory Access Check Policy
+==========================
+
+The policies vary in diverse Isolation Levels.
+
+When TF-M works in Isolation Level 1, the access check in multi-core topology
+checks
+
+- Memory region is valid according to system settings
+- Non-secure client call request should not access secure memory.
+- Secure services should not directly access non-secure memory. According to PSA
+ Firmware Framework, Secure services should call Secure Partition APIs to ask
+ TF-M SPM to fetch non-secure input/output buffer for them.
+- Whether read/write attribute match between access and memory region
+
+When TF-M works in Isolation Level 2, the access check in multi-core topology
+checks:
+
+- Memory region is valid according to system settings
+- Non-secure client call request should not access secure memory.
+- Secure services should not directly access non-secure memory. According to PSA
+ Firmware Framework, Secure services should call Secure Partition APIs to ask
+ TF-M SPM to fetch non-secure input/outputs buffer for them.
+- Whether read/write attribute match between access and memory region
+- Unprivileged secure access should not access privileged secure memory region
+
+The check policy in Isolation Level 3 will be defined according to TF-M future
+implementation.
+
+The above policies will be adjusted according to TF-M implementation and PSA
+specs.
+
+General Check Process in TF-M Core
+==================================
+
+In multi-core topology, ``tfm_core_has_read_access_to_region()`` and
+``tfm_core_has_write_access_to_region()`` are still invoked to keep an uniform
+interface to TF-M Core/SPM.
+
+Multi-core topology specific implementations of
+``tfm_core_has_read_access_to_region()`` and
+``tfm_core_has_write_access_to_region()`` are similar to those in single Armv8-M
+scenario.
+Both functions set corresponding flags according to the parameters and
+invoke static function ``has_access_to_region()`` to execute the check process.
+Both implementations should be placed in multi-core topology specific files
+separated from single Armv8-M access check.
+
+A reference code of ``tfm_core_has_read_access_to_region()`` implementation is
+shown below.
+
+.. code-block:: c
+
+ int32_t tfm_core_has_read_access_to_region(const void *p, size_t s,
+ bool ns_caller,
+ uint32_t privileged)
+ {
+ uint8_t flags = MEM_CHECK_MPU_READ;
+
+ if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) {
+ flags |= MEM_CHECK_MPU_UNPRIV;
+ }
+
+ if (ns_caller) {
+ flags |= MEM_CHECK_NONSECURE;
+ }
+
+ return has_access_to_region(p, s, flags);
+ }
+
+
+A reference code of ``tfm_core_has_write_access_to_region()`` implementation is
+shown below.
+
+.. code-block:: c
+
+ int32_t tfm_core_has_write_access_to_region(void *p, size_t s,
+ bool ns_caller,
+ uint32_t privileged)
+ {
+ uint8_t flags = MEM_CHECK_MPU_READWRITE;
+
+ if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) {
+ flags |= MEM_CHECK_MPU_UNPRIV;
+ }
+
+ if (ns_caller) {
+ flags |= MEM_CHECK_NONSECURE;
+ }
+
+ return has_access_to_region(p, s, flags);
+ }
+
+
+The flags ``MEM_CHECK_MPU_READ``, ``MEM_CHECK_MPU_UNPRIV``,
+``MEM_CHECK_MPU_READWRITE`` and ``MEM_CHECK_NONSECURE`` above will be described
+in the section `Access Permission Flags`_.
+
+The prototype of static function ``has_access_to_region()`` follows that in
+single Armv8-M. The multi-core topology specific ``has_access_to_region()``
+executes a general process to check if the access can access the target region.
+
+During the check process, ``has_access_to_region()`` invokes three HAL APIs
+``tfm_spm_hal_get_mem_security_attr()``, ``tfm_spm_hal_get_ns_access_attr()``
+and ``tfm_spm_hal_get_secure_access_attr()`` to retrieve the attributes of
+target memory region. ``has_access_to_region()`` compares the access permission
+with memory region attributes and determines whether the access is allowed to
+access the region according to policy described in `Memory Access Check Policy`_
+above.
+
+| ``tfm_spm_hal_get_mem_security_attr()`` retrieves the security attributes of
+ the target memory region.
+| ``tfm_spm_hal_get_secure_access_attr()`` retrieves secure access attributes of
+ the target memory region.
+| ``tfm_spm_hal_get_ns_access_attr()`` retrieves non-secure access attributes of
+ the target memory region.
+| All three functions are implemented by multi-core platform support. The
+ definitions are specified in the section `HAL APIs`_ below.
+
+The pseudo code of ``has_access_to_region()`` is shown below.
+
+.. code-block:: c
+ :linenos:
+ :emphasize-lines: 19,36,46
+
+ static int32_t has_access_to_region(const void *p, size_t s, uint8_t flags)
+ {
+ struct security_attr_info_t security_attr;
+ struct mem_attr_info_t mem_attr;
+
+ /* The memory access check should be executed inside TF-M PSA RoT */
+ if (not in privileged level) {
+ abort;
+ }
+
+ if (memory region exceeds memory space limitation) {
+ return TFM_ERROR_GENERIC;
+ }
+
+ /* Set initial value */
+ security_attr_init(&security_attr);
+
+ /* Retrieve security attributes of memory region */
+ tfm_spm_hal_get_mem_security_attr(p, s, &security_attr);
+
+ if (!security_attr.is_valid) {
+ /* Invalid memory region */
+ return TFM_ERROR_GENERIC;
+ }
+
+ /* Compare according to current Isolation Level */
+ if (Parameter flags mismatch security attributes) {
+ return TFM_ERROR_GENERIC;
+ }
+
+ /* Set initial value */
+ mem_attr_init(&mem_attr);
+
+ if (security_attr.is_secure) {
+ /* Retrieve access attributes of secure memory region */
+ tfm_spm_hal_get_secure_access_attr(p, s, &mem_attr);
+
+ if (Not in Isolation Level 1) {
+ /* Secure MPU must be enabled in Isolation Level 2 and 3 */
+ if (!mem_attr->is_mpu_enabled) {
+ abort;
+ }
+ }
+ } else {
+ /* Retrieve access attributes of non-secure memory region. */
+ tfm_spm_hal_get_ns_access_attr(p, s, &mem_attr);
+ }
+
+ if (!mem_attr.is_valid) {
+ /* Invalid memory region */
+ return TFM_ERROR_GENERIC;
+ }
+
+ /*
+ * Compare according to current Isolation Level and non-secure/secure
+ * access.
+ */
+ if (access flags matches MPU attributes) {
+ return TFM_SUCCESS;
+ }
+
+ return TFM_ERROR_GENERIC;
+ }
+
+.. note::
+ It cannot be guaranteed that TF-M provides a comprehensive memory access
+ check on non-secure memory for NSPE client call If non-secure memory
+ protection or isolation is required in a multi-core system, NSPE software
+ should implement and execute the check functionalities in NSPE, rather than
+ relying on TF-M access check.
+
+ For example, all the access from NSPE client calls to non-secure memory are
+ classified as unprivileged in current TF-M implementation. Multi-core access
+ check may skip the privileged/unprivileged permission check for non-secure
+ access.
+
+ If a multi-core system enforces the privileged/unprivileged isolation and
+ protection of non-secure area, NSPE software should execute the corresponding
+ check functionalities before submitting the NSPE client call request to SPE.
+
+
+*******************
+Data Types and APIs
+*******************
+
+Data Types
+==========
+
+Access Permission Flags
+-----------------------
+
+The following flags are defined to indicate the access permission attributes.
+Each flag is mapped to the corresponding CMSE macro. Please refer to
+`ARMv8-M Security Extensions: Requirements on Development Tools
+`_
+for details of each CMSE macro.
+
+``MEM_CHECK_MPU_READWRITE``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mapped to CMSE macro ``CMSE_MPU_READWRITE`` to indicate that the access requires
+both read and write permission to the target memory region.
+
+.. code-block:: c
+
+ #define MEM_CHECK_MPU_READWRITE (1 << 0x0)
+
+
+``MEM_CHECK_MPU_UNPRIV``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mapped to CMSE macro ``CMSE_MPU_UNPRIV`` to indicate that it is an unprivileged
+access.
+
+.. code-block:: c
+
+ #define MEM_CHECK_MPU_UNPRIV (1 << 0x2)
+
+
+``MEM_CHECK_MPU_READ``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Mapped to CMSE macro ``CMSE_MPU_READ``. It indicates that it is a read-only
+access to target memory region.
+
+.. code-block:: c
+
+ #define MEM_CHECK_MPU_READ (1 << 0x3)
+
+
+``MEM_CHECK_NONSECURE``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Mapped to CSME macro ``CMSE_NONSECURE`` to indicate that it is a access from
+non-secure client call request.
+If this flag is unset, it indicates the access is required from SPE.
+
+.. code-block:: c
+
+ #define MEM_CHECK_AU_NONSECURE (1 << 0x1)
+ #define MEM_CHECK_MPU_NONSECURE (1 << 0x4)
+ #define MEM_CHECK_NONSECURE (MEM_CHECK_AU_NONSECURE | \
+ MEM_CHECK_MPU_NONSECURE)
+
+
+Security Attributes Information
+-------------------------------
+
+The structure ``security_attr_info_t`` contains the security attributes
+information of the target memory region.
+``tfm_spm_hal_get_mem_security_attr()`` implementation should fill the structure
+fields according to the platform specific secure isolation setting.
+
+.. code-block:: c
+
+ struct security_attr_info_t {
+ bool is_valid;
+ bool is_secure;
+ };
+
+| ``is_valid`` indicates whether the target memory region is valid according to
+ platform resource assignment and security isolation configurations.
+| ``is_secure`` indicates the target memory region is secure or non-secure. The
+ value is only valid when ``is_valid`` is ``true``.
+
+
+Memory Attributes Information
+-----------------------------
+
+The structure ``mem_attr_info_t`` contains the memory access attributes
+information of the target memory region.
+``tfm_spm_hal_get_secure_access_attr()`` and
+``tfm_spm_hal_get_ns_access_attr()`` implementations should fill the structure
+fields according to the memory protection settings.
+
+.. code-block:: c
+
+ struct mem_attr_info_t {
+ bool is_mpu_enabled;
+ bool is_valid;
+ bool is_xn;
+ bool is_priv_rd_allow;
+ bool is_priv_wr_allow;
+ bool is_unpriv_rd_allow;
+ bool is_unpriv_wr_allow;
+ };
+
+| ``is_mpu_enabled`` indicates whether the MPU and other management unit are
+ enabled and work normally.
+| ``is_valid`` indicates whether the target memory region is valid according to
+ platform resource assignment and memory protection configurations.
+| ``is_xn`` indicates whether the target memory region is Execute Never. This
+ field is only valid when ``is_valid`` is ``true``.
+| ``is_priv_rd_allow`` and ``is_priv_wr_allow`` indicates whether the target
+ memory region allows privileged read/write. Both the fields are valid only
+ when ``is_valid`` is ``true``.
+| ``is_unpriv_rd_allow`` and ``is_unpriv_wr_allow`` indicates whether the target
+ memory region allows unprivileged read/write. Both the fields are valid only
+ when ``is_valid`` is ``true``.
+
+
+HAL APIs
+========
+
+``tfm_spm_hal_get_mem_security_attr()``
+---------------------------------------
+
+``tfm_spm_hal_get_mem_security_attr()`` retrieves the current active security
+configuration information and fills the ``security_attr_info_t``.
+
+.. code-block:: c
+
+ void tfm_spm_hal_get_mem_security_attr(const void *p, size_t s,
+ struct security_attr_info_t *p_attr);
+
++--------------------------------------------------------------------+
+|**Paramters** |
++-------------+------------------------------------------------------+
+|``p`` |Base address of the target memory region |
++-------------+------------------------------------------------------+
+|``s`` |Size of the target memory region |
++-------------+------------------------------------------------------+
+|``p_attr`` |Pointer to the ``security_attr_info_t`` to be filled |
++-------------+------------------------------------------------------+
+|**Return** |
++-------------+------------------------------------------------------+
+|``void`` |None |
++-------------+------------------------------------------------------+
+
+The implementation should be decoupled from TF-M current isolation level or
+access check policy.
+
+All the fields in ``security_attr_info_t`` should be explicitly set in
+``tfm_spm_hal_get_mem_security_attr()``.
+
+If the target memory region crosses boundaries of different security regions or
+levels in security isolation configuration,
+``tfm_spm_hal_get_mem_security_attr()`` should determine whether the memory
+region violates current security isolation.
+It is recommended to mark the target memory region as invalid in such case, even
+if the adjoining regions or levels may have the same security configuration.
+
+If the target memory region is not explicitly specified in memory security
+configuration, ``tfm_spm_hal_get_mem_security_attr()`` can return the following
+values according to actual use case:
+
+- Either set ``is_valid = false``
+- Or set ``is_valid = true`` and set ``is_secure`` according to platform
+ specific policy.
+
+
+``tfm_spm_hal_get_secure_access_attr()``
+----------------------------------------
+
+``tfm_spm_hal_get_secure_access_attr()`` retrieves the secure memory protection
+configuration information and fills the ``mem_attr_info_t``.
+
+.. code-block:: c
+
+ void tfm_spm_hal_get_secure_access_attr(const void *p, size_t s,
+ struct mem_attr_info_t *p_attr);
+
++--------------------------------------------------------------------+
+|**Paramters** |
++-------------+------------------------------------------------------+
+|``p`` |Base address of the target memory region |
++-------------+------------------------------------------------------+
+|``s`` |Size of the target memory region |
++-------------+------------------------------------------------------+
+|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled |
++-------------+------------------------------------------------------+
+|**Return** |
++-------------+------------------------------------------------------+
+|``void`` |None |
++-------------+------------------------------------------------------+
+
+The implementation should be decoupled from TF-M current isolation level or
+access check policy.
+
+All the fields in ``mem_attr_info_t`` should be explicitly set in
+``tfm_spm_hal_get_secure_access_attr()``, according to current active memory
+protection configuration. It is recommended to retrieve the attributes from
+secure MPU and other hardware memory protection unit(s). But the implementation
+can be simplified by checking system-level memory region layout setting.
+
+If the target memory region is not specified in current active secure memory
+protection configuration, ``tfm_spm_hal_get_secure_access_attr()`` can select
+the following values according to actual use case.
+
+- Either directly set ``is_valid`` to ``false``
+- Or set ``is_valid`` to ``true`` and set other fields according to other memory
+ assignment information, such as system-level memory region layout.
+
+If secure memory protection unit(s) is *disabled* and the target memory
+region is a valid area according to platform resource assignment,
+``tfm_spm_hal_get_secure_access_attr()`` must set ``is_mpu_enabled`` to
+``false`` and set other fields according to current system-level memory region
+layout.
+
+
+``tfm_spm_hal_get_ns_access_attr()``
+------------------------------------
+
+``tfm_spm_hal_get_ns_access_attr()`` retrieves the non-secure memory protection
+configuration information and fills the ``mem_attr_info_t``.
+
+.. code-block:: c
+
+ void tfm_spm_hal_get_ns_access_attr(const void *p, size_t s,
+ struct mem_attr_info_t *p_attr);
+
++--------------------------------------------------------------------+
+|**Paramters** |
++-------------+------------------------------------------------------+
+|``p`` |Base address of the target memory region |
++-------------+------------------------------------------------------+
+|``s`` |Size of the target memory region |
++-------------+------------------------------------------------------+
+|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled |
++-------------+------------------------------------------------------+
+|**Return** |
++-------------+------------------------------------------------------+
+|``void`` |None |
++-------------+------------------------------------------------------+
+
+The implementation should be decoupled from TF-M current isolation level or
+access check policy.
+
+Since non-secure core runs asynchronously, the non-secure MPU setting may be
+modified by NSPE OS and the attributes of the target memory region can be
+unavailable during ``tfm_spm_hal_get_ns_access_attr()`` execution in TF-M.
+When the target memory region is not specified in non-secure MPU,
+``tfm_spm_hal_get_ns_access_attr()`` can set the fields according to other
+memory setting information, such as system-level memory region layout.
+
+If non-secure memory protection unit(s) is *disabled* and the target memory
+region is a valid area according to platform resource assignment,
+``tfm_spm_hal_get_ns_access_attr()`` can set the following fields in
+``mem_attr_info_t`` to default values:
+
+- ``is_mpu_enabled = false``
+- ``is_valid = true``
+- ``is_xn = true``
+- ``is_priv_rd_allow = true``
+- ``is_unpriv_rd_allow = true``
+
+``is_priv_wr_allow`` and ``is_unpriv_wr_allow`` can be set according to current
+system-level memory region layout, such as whether it is in code section or data
+section.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/enum_implicit_casting.rst b/docs/technical_references/enum_implicit_casting.rst
new file mode 100644
index 0000000000..01c8ce73f0
--- /dev/null
+++ b/docs/technical_references/enum_implicit_casting.rst
@@ -0,0 +1,190 @@
+################################################
+Fixing implicit casting for C enumeration values
+################################################
+
+:Authors: Hugues de Valon
+:Organization: Arm Limited
+:Contact: hugues.devalon@arm.com
+:Status: Accepted
+
+********
+Abstract
+********
+
+C enumerations provide a nice way to increase readability by creating new
+enumerated types but the developer should take extra care when mixing
+enumeration and integer values.
+This document investigates C enumerations safety and proposes strategies on how
+to fix the implicit casting of the enumeration values of TF-M with other types.
+
+**************************
+C99 Standard point of view
+**************************
+
+In TF-M many implicit casts are done between integer types (``uint32_t``,
+``int32_t``, ``size_t``, etc), enumerated types (``enum foobar``) and
+enumeration constants (``FOOBAR_ENUM_1``).
+
+According to the C99 standard [1]_:
+
+ **§6.2.5, 16**:
+ An enumeration comprises a set of named integer constant values. Each
+ distinct enumeration constitutes a different numerated type.
+
+ **§6.7.2.2, 2**:
+ The expression that defines the value of an enumeration constant shall be an
+ integer constant expression that has a value representable as an int.
+
+ **§6.7.2.2, 3**:
+ The identifiers in an enumerator list are declared as constants that have
+ type int and may appear wherever such are permitted.
+
+ **§6.7.2.2, 4**:
+ Each enumerated type shall be compatible with char, a signed integer type,
+ or an unsigned integer type. The choice of type is implementation-defined,
+ but shall be capable of representing the values of all the members of the
+ enumeration.
+
+From these four quotes from the C99 standard [1]_, the following conclusions can
+be made:
+
+* an enumeration defines a new type and should be treated as such
+* the enumeration constants must only contains value representable as an ``int``
+* the enumeration constants have type ``int``
+* the actual type of the enumeration can be between ``char``, signed and
+ unsigned ``int``. The compiler chooses the type it wants among those that can
+ represent all declared constants of the enumeration.
+
+Example::
+
+ enum french_cities {
+ MARSEILLE,
+ PARIS,
+ LILLE,
+ LYON
+ };
+
+In that example, ``MARSEILLE``, ``PARIS``, ``LILLE`` and ``LYON`` are
+enumeration constants of type ``int`` and ``enum french_cities`` is a enumerated
+type which can be of actual type ``char``, ``unsigned int`` or ``int``
+(the compiler chooses!).
+
+For these reasons, doing an implicit cast between an enumeration and another
+type is the same as doing an implicit cast between two different types. From a
+defensive programming point of view, it should be checked that the destination
+type can represent the values from the origin type. In this specific case it
+means four things for enumerations:
+
+* it is always safe to assign an enumeration constant to an int, but might be
+ better to cast to show intent.
+* when casting an enumeration constant to another type, it should be checked
+ that the constant can fit into the destination type.
+* when casting from an integer type (``uint32_t``, ``int32_t``, etc) to an
+ enumeration type, it should be checked that the integer's value is one of the
+ enumeration constants. The comparison needs to be done on the biggest type of
+ the two so that no information is lost. C integer promotion should
+ automatically do that for the programmer (check §6.3.1.8, 1 for the rules).
+* when casting from an enumeration type to an integer type, it should be checked
+ that the enumeration type value fits into the integer type. The value of a
+ variable which has the type of an enumeration type is not limited to the
+ enumeration constants of the type. An enumeration constant will always fit
+ into an ``int``.
+
+*****************
+Strategies to fix
+*****************
+
+0. Replace the enumerated type with an integer type and replace the enumeration
+ constant with preprocessor constants.
+1. Whenever possible, try to use matching types to avoid implicit casting.
+ It happens, for example, for arithmetic operations, function calls and
+ function returns. This strategy always have the lowest performance impact.
+2. When using an enumeration constant in an arithmetic operation with another
+ type, verify that the constant can fit in the other type and cast it.
+3. When converting an integer to an enumeration type, use a conversion function
+ to check if the integer matches an enumeration constant. To not impact
+ performance too much, this function should be an inline function. If it does
+ not match, use (or add) the error constant or return an error value.
+4. When converting an enumeration type to an integer, use a conversion function
+ to check that the integer type can contain the enumeration value.
+
+************************
+Design proposal for TF-M
+************************
+
+In TF-M, an action will be taken for all enumerated types and enumeration
+constants that are used for implicit casting. The goal of this proposal is to
+remove all implicit casting of enumeration values in TF-M.
+
+The following enumerated types will be removed and replaced with preprocessor
+constants (strategy 0). These enumerated types are not used in TF-M
+but only the constants they declare.
+
+* ``enum spm_part_state_t``
+* ``enum spm_part_flag_mask_t``
+* ``enum tfm_partition_priority``
+
+The following enumerated types will be kept because they are used in the
+prototypes of functions and are useful for debugging. Whenever possible,
+strategy 1 will be applied to remove implicit casting related with those
+enumerations but dynamic conversions will be used if the first option would
+create too much change in the code base.
+
+* ``enum tfm_status_e``: the return type of the following functions will be
+ changed to return the ``enum tfm_status_e`` type. These functions are already
+ returning the enumeration constants, but implicitly casted to an integer type
+ like ``int32_t``.
+
+ * ``int32_t check_address_range``
+ * ``int32_t has_access_to_region``
+ * ``int32_t tfm_core_check_sfn_parameters``
+ * ``int32_t tfm_start_partition``
+ * ``int32_t tfm_return_from_partition``
+ * ``int32_t tfm_check_sfn_req_integrity``
+ * ``int32_t tfm_core_check_sfn_req_rules``
+ * ``int32_t tfm_spm_sfn_request_handler``
+ * ``int32_t tfm_spm_sfn_request_thread_mode``
+* ``enum tfm_buffer_share_region_e``: the following function prototypes will be
+ changed:
+
+ * ``tfm_spm_partition_set_share(uint32_t partition_idx, uint32_t share)`` -> ``tfm_spm_partition_set_share(uint32_t partition_idx, enum tfm_buffer_share_region_e share)``
+* ``enum tfm_memory_access_e``
+* ``enum attest_memory_access_t``
+* ``enum engine_cipher_mode_t``
+* ``mbedtls_cipher_type_t``
+
+The following enumerated types are used for error code values of Secure service
+calls. They should be kept as they are part of the interface and might be used
+by external parties in Non-Secure code. For the Initial Attestation service,
+the enumeration is defined in the PSA Attestation API specifications.
+
+* ``enum psa_attest_err_t``
+* ``enum psa_audit_err``
+* ``enum tfm_platform_err_t``
+
+Implicit casting related with these enumerations is happening in two locations
+of TF-M and need conversion functions in those locations, because the types can
+not be changed:
+
+* In the Non-Secure Client library, all of the Secure Service functions
+ implicitly cast the ``uint32_t`` returned by ``tfm_ns_lock_dispatch`` to
+ these enumerated types. Strategy 3 is needed here.
+* In all of the veneer functions, there is an implicit cast from the ``int32_t``
+ value returned by the SVC request function (``tfm_core_*_request``) to these
+ enumerated types. Strategy 3 is needed here as well. The implicit cast will
+ eventually be removed if all of the services are using the Uniform Signatures
+ Prototypes so that the veneer functions all return ``psa_status_t`` which is
+ an ``int32_t``.
+
+If the interface of those services can be changed, these enumerations could be
+removed and replaced with the ``psa_status_t`` type to remove the implicit
+casting.
+
+.. [1] C99 standard: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf
+
+
+--------------
+
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
+
diff --git a/docs/technical_references/ff_isolation.rst b/docs/technical_references/ff_isolation.rst
new file mode 100644
index 0000000000..41dd4fc0fb
--- /dev/null
+++ b/docs/technical_references/ff_isolation.rst
@@ -0,0 +1,401 @@
+##############
+FF-M Isolation
+##############
+
+:Organization: Arm Limited
+:Contact: tf-m@lists.trustedfirmware.org
+
+This document analyzes the isolation rules of implementing ``FF-M 1.0``
+isolation and introduces the reference implementation in TF-M, which
+complies the rules by operating the hardware and software resources.
+
+.. note::
+ Reference the document :doc:`Glossary ` for terms
+ and abbreviations.
+
+************
+Introduction
+************
+This chapter describes the definitions from ``FF-M`` and analyzes
+the possible implementation keypoints.
+
+Isolation Levels
+================
+There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level
+number has more isolation boundaries.
+
+The definition for Isolation Level 1:
+
+- L1.1 NPSE needs protection from nobody.
+- L1.2 SPE needs protection from NSPE.
+
+The definition for Isolation Level 2:
+
+- L2.1 NPSE needs protection from nobody.
+- L2.2 Application Root of Trust (ARoT) needs protection from NSPE.
+- L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT.
+
+The definition for Isolation Level 3:
+
+- L3.1 NPSE needs protection from nobody.
+- L3.2 Secure Partition needs protection from NSPE and other Secure Partitions.
+- L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure
+ Partitions.
+
+.. important::
+ The PSA RoT Services can be implemented directly within the SPM, or as RoT
+ Services within one or more PSA RoT Secure Partitions. But if the PSA RoT
+ Services needs to be accessed by NSPE or Application RoT of Trust Services
+ must be implemented in a Secure Partitions (Please refer to chapter 2.4 -
+ "RoT Services" of `PSA Firmware_Framework for M`_).
+ The implementation in this design treats the PSA RoT Secure Partition in the
+ PSA RoT domain to follow `L3.3` above and relax `L3.2` for PSA RoT Secure
+ Partition under isolation level 3.
+
+Isolation Rules
+===============
+The essence of isolation is to protect the assets of one protection domain from
+being accessed from other domains. The isolation levels define where the
+isolation boundaries should be placed, the isolation rules define the strength
+of the isolation the boundaries should offer.
+
+.. note::
+ In general, assets include not only ROM/RAM and peripherals. For the detail
+ information about the memory assets and peripheral, please
+ refer to `PSA Firmware_Framework for M`_.
+
+Memory Asset Class
+------------------
+There are 3 memory asset classes defined in `PSA Firmware_Framework for M`_:
+
+- Code
+- Constant data
+- Private data
+
+There are 6 isolation rules for protecting assets. Here lists the simplified
+description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the
+original description:
+
+- I1. Only Code is executable.
+- I2. Only private data is writable.
+- I3. If domain A needs protection from domain B, then Private data in domain A
+ cannot be accessed by domain B.
+- I4. (Optional) If domain A needs protection from domain B, then Code and
+ Constant data in domain A is not readable or executable by domain B.
+- I5. (Optional) Code in a domain is not executable by any other domain.
+- I6. (Optional) All assets in a domain are private to that domain and cannot be
+ accessed by any other domain, with the following exception:
+ The domain containing the SPM can only access Private data and Constant data
+ assets of other domains when required to implement the PSA Firmware Framework
+ API.
+
+ The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply
+ the isolation, while ``I4`` to ``I6`` are optional rules to enhance the
+ isolation boundaries.
+
+ .. important::
+ There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists
+ the asset types and allowed access method. Preventing executable access on
+ constant data costs more hardware resources, so the requirement in the table
+ about constant data can be regarded as a recommendation instead of a
+ mandatory item under some hardware resource-constrained cases.
+
+Hardware Infrastructure
+=======================
+To implement a secure system, the hardware security framework (TrustZone or
+multiple-core e.g.) and their auxiliary components (SAU e.g.) are required
+to ensure the isolation between SPE and NSPE. The requirements:
+
+.. important::
+ The interface between secure and non-secure states needs to be fully
+ enumerated and audited to prove the integrity of the secure state
+ isolation.
+
+Besides this SPE and NSPE isolation mechanism, the following analyzes the
+implementation rules to find out the hardware requirements for isolation inside
+SPE domains:
+
+- I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each
+ type has the specific access rules.
+- I3: The private data access from the prevented domain needs to be blocked.
+- I4: All the assets access from the prevented domain needs to be blocked.
+- I5: Code execution from all other domains (even the domain not prevented
+ from) needs to be blocked.
+- I6: All the assets access from all other domains (includes non-prevented
+ domain) needs to be blocked, but, SPM is an exception, which can access the
+ private data and constant data of the current domain.
+
+The above items list the requirements for memory access, here are two more
+points:
+
+- If the memory device or the peripheral are shared between multiple hosts
+ (Such as multiple CPU or DMA, etc), specific hardware protection units need
+ to be available for validating accesses to that device or peripheral.
+- The MMIO range for Secure Partitions is not allowed to be overlapped, which
+ means each partition should have exclusive memory-mapped region if they
+ require a peripheral device. The memory-mapped region is regarded as
+ the private data so access to this area needs to be validated.
+
+************************
+Reference Implementation
+************************
+This chapter describes the isolation implementation inside SPE by using the
+Armv8m architecture component - Memory Protection Unit (MPU). The MPU can
+isolate CPU execution and data access.
+
+.. note::
+ Previous version M-profile architecture MPU setting is similar in concept but
+ the difference in practical register formats, which is not described in this
+ document.
+
+The MPU protects memory assets by regions. Each region represents a memory
+range with specific access attributes.
+
+.. note::
+ The maximum numbers of MPU regions are platform-specific.
+
+The SPM is running under the privileged mode for handling access from services.
+The MPU region for SPM needs to be available all the time since SPM controls
+the MPU setting while scheduling.
+
+Since partitions are scheduled by SPM, the MPU regions corresponding to the
+partitions can be configured dynamically while scheduling. Since there is only
+one running at a time and all others are deactivated, the SPM needs to set up
+necessary regions for each asset type in one partition only.
+
+There is re-usable code like the C-Runtime and RoT Service API which are same
+across different partitions. TF-M creates a Secure Partition Runtime Library
+(SPRTL) as a specific library shared by the Secure Partition. Please refer to
+:doc:`Secure Partition Runtime Library `
+for more detail.
+
+.. note::
+ Enable SPRTL makes it hard to comply with the rules I4, I5 and I6,
+ duplicating the library code can be one solution but it is not "shared"
+ library anymore.
+
+As mentioned in the last chapter, MMIO needs extra MPU regions as private data.
+
+MPU Region Access Permission
+============================
+The following content would mention the memory access permission to represent
+the corresponded asset classes.
+
+These access permissions are available on Armv8m MPU:
+
+- Privileged Read-Only (RO)
+- All RO
+- Privileged Read-Write (RW)
+- All RW
+- Execution Never (XN)
+
+And one more Armv8.1M access permssion:
+
+- Privileged Execution Never (PXN)
+
+The available regions type list:
+
+======== =========== =============== ========================================
+Type Attributes Privilege Level Asset
+======== =========== =============== ========================================
+P_RO RO Privileged PRoT Code
+P_ROXN RO + XN Privileged PRoT Constant Data
+P_RWXN RW + XN Privileged PRoT Private Data/Peripheral
+A_RO RO Any privilege Partition/SPRTL Code
+A_ROXN RO + XN Any privilege Partition/SPRTL Constant Data
+A_RWXN RW + XN Any privilege Partition/SPRTL Private Data/Peripheral
+A_ROPXN RO + PXN Any privilege Armv8.1M Partition/SPRTL Code
+======== =========== =============== ========================================
+
+Example Image Layout
+====================
+The secure firmware image contains components such as partitions, SPM and the
+shared code and data. Each component may have different class assets. There
+would be advantages if placing the assets from all components with the same
+access attributes into one same region:
+
+- The data relocating or clearing when booting can be done in one step instead
+ of breaking into fragments.
+- Assets with statically assigned access attribute can share the same MPU
+ region which saves regions.
+
+Take the TF-M existing implementation image layout as an example::
+
+ Level 1 Level 2 Level 3
+ Boundaries Boundaries Boundaries
+ +------------+----------+------------------------------------+
+ | | | PRoT SPM Code |
+ | | PRoT +------------------------------------+
+ | | Code | PRoT Service Code |
+ | Code +----------+------------------------------------+
+ | (ROM) | | Partition 1 Code |
+ | | +------------------------------------+
+ | | ARoT | Partition N Code |
+ | | Code +------------------------------------+
+ | | | SPRTL Code |
+ +------------+----------+------------------------------------+
+ Check [4] for more details between Code and Constant Data.
+ +------------+----------+------------------------------------+
+ | | PRoT | PRoT SPM Constant Data |
+ | | Constant +------------------------------------+
+ | | Data | PRoT Service Constant Data |
+ | Constant +----------+------------------------------------+
+ | Data | ARoT | Partition 1 Constant Data |
+ | (ROM) | Constant +------------------------------------+
+ | | Data | Partition N Constant Data |
+ | | +------------------------------------+
+ | | | SPRTL Constant Data |
+ +------------+----------+------------------------------------+
+
+ +------------+----------+------------------------------------+
+ | | PRoT | PRoT SPM Private Data |
+ | | Private +------------------------------------+
+ | | Data | PRoT Service Private Data |
+ | Private +----------+------------------------------------+
+ | Data | | Partition 1 Private Data |
+ | (RAM) | ARoT +------------------------------------+
+ | | Private | Partition N Private Data |
+ | | Data +------------------------------------+
+ | | | SPRTL Private Data |
+ +------------+----------+------------------------------------+
+
+.. note::
+ 1. Multiple binaries image implementation could also reference this layout if
+ its hardware protection unit can cover the exact boundaries mentioned
+ above.
+ 2. Private data includes both initialized and non-initialized (ZI) sections.
+ Check chapter ``3.1.1`` of ``FF-M`` for the details.
+ 3. This diagram shows the boundaries but not orders. The order of regions
+ inside one upper region can be adjusted freely.
+ 4. As described in the ``important`` of `Memory Asset Class`_, the setting
+ between Code and Constant Data can be skipped if the executable access
+ method is not applied to constant data. In this case, the groups of Code
+ and Constant Data can be combined or even mixed -- but the boundary
+ between PRoT and ARoT are still required under level higher than 1.
+
+Example Region Numbers under Isolation Level 3
+==============================================
+The following table lists the required regions while complying the rules for
+implementing isolation level 3. The level 1 and level 2 can be exported by
+simplifying the items in level 3 table.
+
+.. important::
+ The table described below is trying to be shared between all supported
+ platforms in Trusted Firmware - M. It is obvious that some platforms have
+ special characteristics. In that case, the specific layout table for a
+ particular platform can be totally redesigned but need to fulfil the
+ isolation level requirements.
+
+- Care only the running partitions assets since deactivated partition does not
+ need regions.
+- `X` indicates the existence of this region can't comply with the rule.
+- An `ATTR + n` represent extra ``n`` regions are necessary.
+- Here assumes the rules with a greater number covers the requirements in the
+ rules with less number.
+
+Here lists the required regions while complying with the rules:
+
++------------------+-------------+-------------+-------------+-------------+
+| Region Purpose | I1 I2 I3 | I4 | I5 | I6 |
++==================+=============+=============+=============+=============+
+| PRoT SPM Code | A_RO | P_RO | P_RO | P_RO |
++------------------+ | | +-------------+
+| PRoT Service Code| | | | A_ROPXN |
++------------------+ +-------------+-------------+ |
+| Active Partition | | A_RO | A_ROPXN | |
+| Code | | | | |
++------------------+ +-------------+-------------+-------------+
+| SPRTL Code | | ``X`` | ``X`` | ``X`` |
++------------------+-------------+-------------+-------------+-------------+
+| PRoT SPM RO | A_ROXN | P_ROXN | P_ROXN | P_ROXN |
++------------------+ | | +-------------+
+| PRoT Service RO | | | | A_ROXN |
++------------------+ +-------------+-------------+ |
+| Active Partition | | A_ROXN | A_ROXN | |
+| RO | | | | |
++------------------+ +-------------+-------------+-------------+
+| SPRTL RO | | ``X`` | ``X`` | ``X`` |
++------------------+-------------+-------------+-------------+-------------+
+| PRoT SPM RW | P_RWXN | P_RWXN | P_RWXN | P_RWXN |
++------------------+ | | +-------------+
+| PRoT Service RW | | | | A_RWXN |
++------------------+-------------+-------------+-------------+ |
+| Active Partition | A_RWXN | A_RWXN | A_RWXN | |
+| RW | | | | |
++------------------+-------------+-------------+-------------+-------------+
+| SPRTL RW [5] | A_RWXN + 1 | ``X`` | ``X`` | ``X`` |
++------------------+-------------+-------------+-------------+-------------+
+| Partition Peri | A_RWXN + n | A_RWXN + n | A_RWXN + n | A_RWXN + n |
++------------------+-------------+-------------+-------------+-------------+
+| Total Numbers | [1] | [2] | [3] | [4] |
++------------------+-------------+-------------+-------------+-------------+
+
+.. note::
+ 1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while
+ n equals the maximum peripheral numbers needed by one partition. This is
+ the configuration chosen by the reference implementation.
+ 2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN,
+ the minimal result is `6`, and SPRTL can not be applied.
+ 3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
+ A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
+ is required.
+ 4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
+ A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
+ is required. To comply with this rule, the PSA RoT Service needs
+ to be implemented as Secure Partitions.
+ 5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM
+ can update this region with the activate partition's metadata for
+ implementing functions with owner SP's context, such as heap functions.
+ This region can be skipped if there is no metadata required (such as no
+ heap functionalities required).
+
+ The memory-mapped regions for peripherals have different memory access
+ attributes in general, they are standalone regions in MPU even their
+ attributes covers 'A_RWXN'.
+
+.. important::
+ The default memory map is not involved in this example, because it grants PSA
+ RoT domain program (especially SPM) the ability to access the place not
+ covered in an explicitly defined region. In a system lack of enough MPU
+ regions, the default memory map can be applied, in this case, the whole image
+ layout needs to be audited to find out if the uncovered region contains
+ garbage or gadget data which could provide an attack.
+
+Interfaces
+==========
+The isolation implementation is based on the HAL framework. The SPM relies on
+the HAL API to perform the necessary isolation related operations.
+
+The requirement the software need to do are these:
+
+- Create enough isolation protection at the early stage of system booting, just
+ need to focus on the SPM domain.
+- Create an isolation domain between secure and non-secure before the jump to
+ the non-secure world.
+- Create an isolation domain for each Secure Partition after the Secure
+ Partition is loaded and before jumping to its entry point. The isolation
+ domain should cover all the assets of the Secure Partition, include all its
+ memory, interrupts, and peripherals.
+- Switch isolation domains when scheduling different Secure Partitions.
+- It is also a requirement that the platform needs to help to check if the
+ caller of the PSA APIs is permitted to access some memory ranges.
+
+
+The design document
+:doc:`TF-M Hardware Abstraction Layer `
+gives a detail design, include the platform initialization, isolation
+interfaces. Please refer to it for more detail.
+
+Appendix
+========
+| `PSA Firmware_Framework for M`_
+
+.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html
+
+| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_
+
+.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/hardware_abstraction_layer.rst b/docs/technical_references/hardware_abstraction_layer.rst
new file mode 100644
index 0000000000..645426f617
--- /dev/null
+++ b/docs/technical_references/hardware_abstraction_layer.rst
@@ -0,0 +1,671 @@
+##########################
+Hardware Abstraction Layer
+##########################
+
+:Organization: Arm Limited
+:Contact: tf-m@lists.trustedfirmware.org
+
+:API Version: 0.9
+
+************
+Introduction
+************
+:term:`TF-M` :term:`HAL` abstracts the hardware-oriented and platform specific
+operations on the :term:`SPE` side and provides a set of APIs to the upper
+layers such as :term:`SPM`, :term:`RoT Service`.
+The :term:`HAL` aims to cover the platform different aspects whereas common
+architecturally defined aspects are done generically within the common
+:term:`SPE`.
+In some cases, although the operations are defined architecturally,
+it may not be possible to generalize implementations because lots of information
+is only known to platforms.
+It is more efficient to define a :term:`HAL` API for those architectural
+operations as well.
+
+.. note::
+ :term:`TBSA-M` provides the hardware requirements for security purposes.
+ :term:`TF-M` :term:`HAL` tries to reference :term:`TBSA-M` recommendations in
+ the interfaces from the software perspective only. Please reference
+ :term:`TBSA-M` for your security hardware design.
+
+Design Goals
+============
+:term:`TF-M` :term:`HAL` is designed to simplify the integration efforts on
+different platforms.
+
+:term:`TF-M` :term:`HAL` is designed to make it easy to use the hardware and
+develop the :term:`SPM` and :term:`RoT Service` which need to access the
+devices.
+
+:term:`TF-M` :term:`HAL` is designed to make the structure clearer and let the
+:term:`TF-M` mainly focus on :term:`PSA` implementation.
+
+********
+Overview
+********
+This section provides an overview of the abstraction layer structure.
+
+.. figure:: media/hal_structure.png
+
+Here lists a minimal set of necessary functionalities:
+
+ - **Isolation API**: Provides the necessary isolation functionalities required
+ by the :term:`PSA-FF-M` and :term:`TBSA-M`, and provides APIs to :term:`SPM`
+ to check the permissions of memory access.
+ - **Platform API**: Provides the platform initialization, platform-specific
+ memory information, system reset, etc.
+ - **Log dev API**: Provides the log system functions.
+ - **Interrupt API**: Provides the interrupt functions.
+
+.. note::
+ - There is a non-secure :term:`HAL` that focuses on the mailbox operation API
+ for Dual-core topology. For more information about it, please refer to
+ :doc:`Mailbox Design in TF-M on Dual-core System
+ `.
+ - The minimal set of :term:`TF-M` :term:`HAL` is sufficient for Secure
+ Partitions by using customized peripheral interfaces. To provide easier
+ portability for the Secure Partitions, a Secure Partition :term:`HAL` is
+ provided in this design too.
+ - The debug mechanisms give the external entity the corresponding right to
+ access the system assets. :term:`TF-M` ensures that the external entity is
+ permitted access to those assets. Currently, :term:`TF-M` only needs the
+ debug authentication. The whole debug mechanism and related :term:`HAL` will
+ be enhanced in the future. Please refer to the :doc:`Debug authentication
+ settings section ` for more detail.
+
+*****************
+Design Principles
+*****************
+As :term:`TF-M` runs on resource-constrained devices, the :term:`HAL` tries to
+avoid multiple level abstractions which cost more resources.
+
+Part of the :term:`HAL` interfaces does not focus on exact hardware operations
+such as power on/off or PIN manipulation.
+Instead, the :term:`HAL` abstracts higher-level interfaces to reserve the
+implementation flexibility for the platform vendors.
+
+The :term:`TF-M` :term:`HAL` should be easy to deprecate APIs and provide
+compatibilities.
+Any API incompatibility should be detected during building.
+
+:term:`TF-M` relies on the :term:`HAL` APIs to be implemented correctly and
+trusts the :term:`HAL` APIs.
+:term:`TFM` can provide assertions to detect common programming errors but
+essentially no further extensive checks will be provided.
+
+************
+Source Files
+************
+This section describes the source file of the :term:`TF-M` :term:`HAL`,
+including the header and c files.
+
+tfm_hal_defs.h
+==============
+This header file contains the definitions of common macros and types used by all
+:term:`HAL` APIs. Please refer to `Status Codes`_ for detailed definitions.
+
+tfm_hal_[module].[h/c]
+======================
+All other headers and c files are classified by the modules, such as isolation,
+platform, interrupt, devices, etc.
+
+.. note::
+ There are common files in the platform folder include the implemented
+ :term:`HAL` APIs. The platform vendors can use them directly but need to
+ implement all the sub APIs.
+
+************
+Status Codes
+************
+These are common status and error codes for all :term:`HAL` APIs.
+
+Types
+=====
+tfm_hal_status_t
+----------------
+This is a status code to be used as the return type of :term:`HAL` APIs.
+
+.. code-block:: c
+
+ enum tfm_hal_status_t {
+ TFM_HAL_ERROR_MEM_FAULT = SCHAR_MIN,
+ TFM_HAL_ERROR_MAX_VALUE,
+ TFM_HAL_ERROR_BAD_STATE,
+ TFM_HAL_ERROR_NOT_SUPPORTED,
+ TFM_HAL_ERROR_INVALID_INPUT,
+ TFM_HAL_ERROR_NOT_INIT,
+ TFM_HAL_ERROR_GENERIC,
+ TFM_HAL_SUCCESS = 0
+ };
+
+Error Codes
+===========
+Negative values indicate an error. Zero and positive values indicate success.
+
+Here is the general list. The detailed usages for each error code are described
+in the API introduction sections.
+
+TFM_HAL_SUCCESS
+---------------
+Status code to indicate general success.
+
+TFM_HAL_ERROR_GENERIC
+---------------------
+Status code to indicate an error that does not correspond to any defined failure
+cause.
+
+TFM_HAL_ERROR_NOT_INIT
+----------------------
+Status code to indicate that the module is not initialed.
+
+TFM_HAL_ERROR_INVALID_INPUT
+---------------------------
+Status code to indicate that the input is invalid.
+
+TFM_HAL_ERROR_NOT_SUPPORTED
+---------------------------
+Status code to indicate that the requested operation or a parameter is not
+supported.
+
+TFM_HAL_ERROR_BAD_STATE
+-----------------------
+Status code to indicate that the requested action cannot be performed in the
+current state.
+
+TFM_HAL_ERROR_MAX_VALUE
+-----------------------
+Status code to indicate that the current number has got the max value.
+
+TFM_HAL_ERROR_MEM_FAULT
+-----------------------
+Status code to indicate that the memory check failed.
+
+***************************
+API Definition for TF-M SPM
+***************************
+This section describes the APIs defined for :term:`TF-M` :term:`SPM`.
+
+Platform API
+============
+The platform API is a higher-level abstraction layer of the platform, other than
+a dedicated API set for the special hardware devices.
+
+APIs
+----
+tfm_hal_platform_init()
+^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ enum tfm_hal_status_t tfm_hal_platform_init(void)
+
+**Description**
+
+This API performs the platform-specific initialization.
+
+This API is called after architecture and platform common initialization has
+finished during system early startup.
+
+**Parameter**
+
+- ``void`` - None.
+
+**Return Values**
+
+- ``TFM_HAL_SUCCESS`` - Init success.
+- ``TFM_HAL_ERROR_GENERIC`` - Generic errors.
+
+tfm_hal_system_reset()
+^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ void tfm_hal_system_reset(void)
+
+**Description**
+
+This API performs a system reset.
+
+The platform can uninitialize some resources before reset.
+
+**Parameter**
+
+- ``void`` - None
+
+**Return Values**
+
+- ``void`` - None
+
+**Note**
+
+This API should not return.
+
+Isolation API
+=============
+The :term:`PSA-FF-M` defines three isolation levels and a memory access rule to
+provide diverse levels of securitiy. The isolation API provides the functions to
+implement these requirements.
+
+Memory Access Attributes
+------------------------
+The memory access attributes are encoded as bit fields, you can logic OR them to
+have a combination of the atrributes, for example
+``TFM_HAL_MEM_ATTR_UNPRIVILEGED | TFM_HAL_MEM_ATTR_READABLE`` is unprivileged
+readable. The data type is `uint32_t`.
+
+TFM_HAL_MEM_ATTR_EXECUTABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The memory is executable.
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_EXECUTABLE (1UL << 0)
+
+TFM_HAL_MEM_ATTR_READABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The memory is readable.
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_READABLE (1UL << 1)
+
+TFM_HAL_MEM_ATTR_WRITABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The memory is writable.
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_WRITABLE (1UL << 2)
+
+TFM_HAL_MEM_ATTR_UNPRIVILEGED
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The memory is unprivileged mode accessible.
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_UNPRIVILEGED (1UL << 3)
+
+TFM_HAL_MEM_ATTR_DEVICE
+^^^^^^^^^^^^^^^^^^^^^^^
+The memory is a MMIO device.
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_DEVICE (1UL << 4)
+
+TFM_HAL_MEM_ATTR_NS
+^^^^^^^^^^^^^^^^^^^
+The memory is accessible from :term:`NSPE`
+
+.. code-block:: c
+
+ #define TFM_HAL_MEM_ATTR_NS (1UL << 5)
+
+APIs
+----
+tfm_hal_set_up_static_boundaries()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ tfm_hal_status_t tfm_hal_set_up_static_boundaries(void)
+
+**Description**
+
+This API sets up the static isolation boundaries which are constant throughout
+the runtime of the system.
+
+The boundaries include:
+
+- The SPE boundary between the :term:`SPE` and the :term:`NSPE`
+- The PSA RoT isolation boundary between the PSA Root of Trust and the
+ Application Root of Trust which is for isolation level 2 and 3 only.
+
+Please refer to the :term:`PSA-FF-M` for the definitions of the isolation
+boundaries.
+
+**Return Values**
+
+- ``TFM_HAL_SUCCESS`` - the isolation boundaries have been set up.
+- ``TFM_HAL_ERROR_GENERIC`` - failed to set up the isolation boundaries.
+
+tfm_hal_mpu_update_partition_boundary
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start,
+ uintptr_t end);
+
+**Description**
+
+This API updates the partition isolation boundary for isolation level 3.
+Inside the partition isolation boundary is the private data of the running
+Secure Partition.
+This boundary is updated dynamically when :term:`SPM` switches Partitions in
+isolation level 3.
+
+The access permissions of the boundary is all privileged mode read-write.
+
+Platforms decide which :term:`MPU` region the paritition boundary uses.
+
+**Parameter**
+
+- ``start`` - start address of the partition boundary.
+- ``end`` - end address of the partition boundary.
+
+**Return Values**
+
+- ``TFM_HAL_SUCCESS`` - the isolation boundary has been set up.
+- ``TFM_HAL_ERROR_GENERIC`` - failed to set upthe isolation boundary.
+
+**Note**
+
+This API is only for platforms using :term:`MPU` as isolation hardwares.
+A generic API for all platforms will be introduced in future versions.
+
+tfm_hal_memory_has_access()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base,
+ size_t size,
+ uint32_t attr)
+
+**Description**
+
+This API checks if the memory region defined by ``base`` and ``size`` has the
+given access atrributes - ``attr``.
+
+The Attributes include :term:`NSPE` access, privileged mode, and read-write
+permissions.
+
+**Parameter**
+
+- ``base`` - The base address of the region.
+- ``size`` - The size of the region.
+- ``attr`` - The `Memory Access Attributes`_.
+
+**Return Values**
+
+- ``TFM_HAL_SUCCESS`` - The memory region has the access permissions.
+- ``TFM_HAL_ERROR_MEM_FAULT`` - The memory region does not have the access
+ permissions.
+- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs.
+- ``TFM_HAL_ERROR_GENERIC`` - An error occurred.
+
+Log API
+=======
+The log API is used by the :term:`TF-M` :doc:`log system `.
+The log device could be uart, memory, usb, etc.
+
+APIs
+----
+tfm_hal_output_partition_log()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ int32_t tfm_hal_output_partition_log(const unsigned char *str, uint32_t len)
+
+**Description**
+
+This API is called by Secure Partition to output logs.
+
+**Parameter**
+
+- ``str`` - The string to output.
+- ``len`` - Length of the string in bytes.
+
+**Return Values**
+
+- Positive values - Number of bytes output.
+- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized.
+- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` or
+ ``len`` is zero.
+
+**Note**
+
+None.
+
+tfm_hal_output_spm_log()
+^^^^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ int32_t tfm_hal_output_spm_log(const unsigned char *str, uint32_t len)
+
+**Description**
+
+This API is called by :term:`SPM` to output logs.
+
+**Parameter**
+
+- ``str`` - The string to output.
+- ``len`` - Length of the string in bytes.
+
+**Return Values**
+
+- Positive numbers - Number of bytes output.
+- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized.
+- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL``
+ or ``len`` is zero.
+
+**Note**
+
+Please check :doc:`TF-M log system ` for more
+information.
+
+************************************
+API Definition for Secure Partitions
+************************************
+The Secure Partition (SP) :term:`HAL` mainly focuses on two parts:
+
+ - Peripheral devices. The peripherals accessed by the :term:`TF-M` default
+ Secure Partitions.
+ - Secure Partition abstraction support. The Secure Partition data that must be
+ provided by the platform.
+
+The Secure Partition abstraction support will be introduced in the peripheral
+API definition.
+
+ITS and PS flash API
+====================
+There are two kinds of flash:
+
+ - Internal flash. Accessed by the PSA Internal Trusted Storage (ITS) service.
+ - External flash. Accessed by the PSA Protected Storage (PS) service.
+
+The ITS HAL for the internal flash device is defined in the ``tfm_hal_its.h``
+header and the PS HAL in the ``tfm_hal_ps.h`` header.
+
+Macros
+------
+Internal Trusted Storage
+^^^^^^^^^^^^^^^^^^^^^^^^
+TFM_HAL_ITS_FLASH_DRIVER
+~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for
+ITS. It must have been allocated by the platform and will be declared extern in
+the HAL header.
+
+TFM_HAL_ITS_PROGRAM_UNIT
+~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the size of the ITS flash device's physical program unit (the smallest
+unit of data that can be individually programmed to flash). It must be equal to
+TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile
+time so that filesystem structures can be statically sized.
+
+TFM_HAL_ITS_FLASH_AREA_ADDR
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the base address of the dedicated flash area for ITS.
+
+TFM_HAL_ITS_FLASH_AREA_SIZE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the size of the dedicated flash area for ITS in bytes.
+
+TFM_HAL_ITS_SECTORS_PER_BLOCK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the number of contiguous physical flash erase sectors that form a
+logical filesystem erase block.
+
+Protected Storage
+^^^^^^^^^^^^^^^^^
+TFM_HAL_PS_FLASH_DRIVER
+~~~~~~~~~~~~~~~~~~~~~~~
+Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for
+PS. It must have been allocated by the platform and will be declared extern in
+the HAL header.
+
+TFM_HAL_PS_PROGRAM_UNIT
+~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the size of the PS flash device's physical program unit (the smallest
+unit of data that can be individually programmed to flash). It must be equal to
+TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile
+time so that filesystem structures can be statically sized.
+
+TFM_HAL_PS_FLASH_AREA_ADDR
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the base address of the dedicated flash area for PS.
+
+TFM_HAL_PS_FLASH_AREA_SIZE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the size of the dedicated flash area for PS in bytes.
+
+TFM_HAL_PS_SECTORS_PER_BLOCK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines the number of contiguous physical flash erase sectors that form a
+logical filesystem erase block.
+
+Optional definitions
+--------------------
+The ``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` and
+``TFM_HAL_ITS_SECTORS_PER_BLOCK`` definitions are optional. If not defined, the
+platform must implement ``tfm_hal_its_fs_info()`` instead.
+
+Equivalently, ``tfm_hal_its_ps_info()`` must be implemented by the platform if
+``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` or
+``TFM_HAL_ITS_SECTORS_PER_BLOCK`` is not defined.
+
+Objects
+-------
+ARM_DRIVER_FLASH
+^^^^^^^^^^^^^^^^
+The ITS and PS HAL headers each expose a CMSIS Flash Driver instance.
+
+.. code-block:: c
+
+ extern ARM_DRIVER_FLASH TFM_HAL_ITS_FLASH_DRIVER
+
+ extern ARM_DRIVER_FLASH TFM_HAL_PS_FLASH_DRIVER
+
+The CMSIS Flash Driver provides the flash primitives ReadData(), ProgramData()
+and EraseSector() as well as GetInfo() to access flash device properties such
+as the sector size.
+
+Types
+-----
+tfm_hal_its_fs_info_t
+^^^^^^^^^^^^^^^^^^^^^
+Struct containing information required from the platform at runtime to configure
+the ITS filesystem.
+
+.. code-block:: c
+
+ struct tfm_hal_its_fs_info_t {
+ uint32_t flash_area_addr;
+ size_t flash_area_size;
+ uint8_t sectors_per_block;
+ };
+
+Each attribute is described below:
+
+ - ``flash_area_addr`` - Location of the block of flash to use for ITS
+ - ``flash_area_size`` - Number of bytes of flash to use for ITS
+ - ``sectors_per_block`` - Number of erase sectors per logical FS block
+
+tfm_hal_ps_fs_info_t
+^^^^^^^^^^^^^^^^^^^^^
+Struct containing information required from the platform at runtime to configure
+the PS filesystem.
+
+.. code-block:: c
+
+ struct tfm_hal_ps_fs_info_t {
+ uint32_t flash_area_addr;
+ size_t flash_area_size;
+ uint8_t sectors_per_block;
+ };
+
+Each attribute is described below:
+
+ - ``flash_area_addr`` - Location of the block of flash to use for PS
+ - ``flash_area_size`` - Number of bytes of flash to use for PS
+ - ``sectors_per_block`` - Number of erase sectors per logical FS block
+
+Functions
+---------
+tfm_hal_its_fs_info()
+^^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ enum tfm_hal_status_t tfm_hal_its_fs_info(struct tfm_hal_its_fs_info_t *fs_info);
+
+**Description**
+
+Retrieves the filesystem configuration parameters for ITS.
+
+**Parameter**
+
+- ``fs_info`` - Filesystem config information
+
+**Return values**
+
+- ``TFM_HAL_SUCCESS`` - The operation completed successfully
+- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter
+
+**Note**
+
+This function should ensure that the values returned do not result in a security
+compromise. The block of flash supplied must meet the security requirements of
+Internal Trusted Storage.
+
+tfm_hal_ps_fs_info()
+^^^^^^^^^^^^^^^^^^^^
+**Prototype**
+
+.. code-block:: c
+
+ enum tfm_hal_status_t tfm_hal_ps_fs_info(struct tfm_hal_ps_fs_info_t *fs_info);
+
+**Description**
+
+Retrieves the filesystem configuration parameters for PS.
+
+**Parameter**
+
+- ``fs_info`` - Filesystem config information
+
+**Return values**
+
+- ``TFM_HAL_SUCCESS`` - The operation completed successfully
+- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter
+
+**Note**
+
+This function should ensure that the values returned do not result in a security
+compromise.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/index.rst b/docs/technical_references/index.rst
new file mode 100644
index 0000000000..bd7c57203f
--- /dev/null
+++ b/docs/technical_references/index.rst
@@ -0,0 +1,15 @@
+Technical References
+====================
+
+.. toctree::
+ :maxdepth: 2
+ :titlesonly:
+ :glob:
+ :numbered:
+
+ */index
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/index.rst.in b/docs/technical_references/index.rst.in
new file mode 100644
index 0000000000..b5cf149af8
--- /dev/null
+++ b/docs/technical_references/index.rst.in
@@ -0,0 +1,30 @@
+Design Documents
+================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Accepted design documents
+ :glob:
+ :numbered:
+
+ @ACCEPTED_DD_LIST@
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Draft design documents
+ :glob:
+ :numbered:
+
+ @DRAFT_DD_LIST@
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Rejected design documents
+ :glob:
+ :numbered:
+
+ @REJECTED_DD_LIST@
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/media/hal_structure.png b/docs/technical_references/media/hal_structure.png
new file mode 100644
index 0000000000..0f4c4c0018
Binary files /dev/null and b/docs/technical_references/media/hal_structure.png differ
diff --git a/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png b/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png
new file mode 100644
index 0000000000..548e79d3d1
Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png differ
diff --git a/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png b/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png
new file mode 100644
index 0000000000..ac39cf258e
Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png differ
diff --git a/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png b/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png
new file mode 100644
index 0000000000..288bc534fb
Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png differ
diff --git a/docs/technical_references/media/symmetric_initial_attest/iat_decode.png b/docs/technical_references/media/symmetric_initial_attest/iat_decode.png
new file mode 100644
index 0000000000..e35183bacc
Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/iat_decode.png differ
diff --git a/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png b/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png
new file mode 100644
index 0000000000..893c62eedf
Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png differ
diff --git a/docs/technical_references/media/tfm_crypto_design.png b/docs/technical_references/media/tfm_crypto_design.png
new file mode 100644
index 0000000000..6e8d48b200
Binary files /dev/null and b/docs/technical_references/media/tfm_crypto_design.png differ
diff --git a/docs/technical_references/profiles/index.rst b/docs/technical_references/profiles/index.rst
new file mode 100644
index 0000000000..e856cf8078
--- /dev/null
+++ b/docs/technical_references/profiles/index.rst
@@ -0,0 +1,12 @@
+TF-M Profiles
+=============
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/profiles/tfm_profile_large.rst b/docs/technical_references/profiles/tfm_profile_large.rst
new file mode 100644
index 0000000000..2e0bc76de0
--- /dev/null
+++ b/docs/technical_references/profiles/tfm_profile_large.rst
@@ -0,0 +1,459 @@
+#######################################
+Trusted Firmware-M Profile Large Design
+#######################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+TF-M Profiles defines 3 profiles: Profile Small, Profile Medium and Profile
+Large. Each profile provides a predefined list of TF-M configurations to meet
+the security requirement of typical use cases with device hardware constraints.
+TF-M Profiles align with PSA specifications and certification requirements.
+
+As one of TF-M Profiles, Profile Large protects less resource-constrained Arm
+Cortex-M devices.
+
+Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to
+enable more secure features to support higher level of security required in more
+complex usage scenarios.
+
+ - Isolation level 3 enables additional isolation between
+ :term:`Application RoT` (App RoT) services.
+ - More crypto algorithms and cipher suites are selected to securely connect
+ devices to remote services offered by various major Cloud Service
+ Providers (CSP)
+ - Basic software countermeasures against physical attacks can be enabled.
+
+Profile Large can be aligned as a reference implementation with the requirements
+defined in PSA Certified Level 3 Lightweight Protection Profile [3]_.
+
+**************
+Overall design
+**************
+
+TF-M Profile Large defines the following feature set:
+
+ - Firmware Framework
+
+ - Inter-Process Communication (IPC) model [4]_
+ - Isolation level 3 [4]_
+
+ - Internal Trusted Storage (ITS)
+
+ - Crypto
+
+ - Support both symmetric ciphers and asymmetric ciphers
+ - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support
+ direct secure connection to major CSPs, including
+
+ - Authenticated Encryption with Associated Data (AEAD) algorithm
+ - Asymmetric key algorithm based signature and verification
+ - Public-key cryptography based key exchange
+ - Hash function
+ - HMAC for default Pseudorandom Function (PRF)
+
+ - Asymmetric digital signature and verification for Initial Attestation
+ Token (IAT)
+ - Asymmetric algorithms for firmware image signature verification
+ - Key derivation
+
+ - Initial Attestation
+
+ - Asymmetric key algorithm based Initial Attestation
+
+ - Secure boot
+
+ - Anti-rollback protection
+ - Multiple image boot
+
+ - Protected Storage (PS) if off-chip storage device is integrated
+
+ - Data confidentiality
+ - Data integrity
+ - Rollback protection
+
+ - Software countermeasures against physical attacks
+
+**************
+Design details
+**************
+
+More details of TF-M Profile Large design are described in following sections.
+
+Firmware framework
+==================
+
+Profile Large selects IPC model and isolation level 3 by default.
+
+Isolation level 3 supports additional isolation between App RoT services,
+compared to isolation level 2. It can protect :term:`RoT` services from each
+other when their vendors don't trust each other.
+
+Crypto service
+==============
+
+Profile Large supports direct connection to Cloud services via common protocols,
+such as TLS 1.2.
+
+In some usage scenarios, PSA RoT can be managed by device manufacturer or other
+vendors and is out of control of application developers.
+Profile Large selects alternative crypto algorithms for each crypto function to
+support multiple common cipher suites required by various major CSPs. Therefore,
+application developers can support services for diverse CSPs on same devices
+with Profile Large, without relying on PSA RoT upgrades of crypto.
+
+Devices meeting Profile Large should be in a position to offer at least two
+alternatives to every cryptographic primitive for symmetric, asymmetric and
+hash, and be able to use them for encryption, AEAD, signature and verification.
+
+It will cost more resource in Profile Large to support more crypto algorithms
+and cipher suites, compared to Profile Medium [2]_.
+
+Boot loader
+===========
+
+BL2 implementation can be device specific. Devices may implement diverse
+boot processes with different features and configurations.
+However, the boot loader must support anti-rollback protection. Boot loader must
+be able to prevent unauthorized rollback, to protect devices from being
+downgraded to earlier versions with known vulnerabilities.
+
+MCUBoot in TF-M is configured as multiple image boot by default in Profile
+Large. In multiple image boot, secure and non-secure images can be signed
+independently with different keys and they can be updated separately. It can
+support multiple vendors scenarios, in which non-secure and secure images are
+generated and updated by different vendors.
+Multiple image boot may cost larger memory footprint compared with single image
+boot.
+
+Boot loader can implement software countermeasures to mitigate physical attacks.
+
+Protected Storage
+=================
+
+PS service is required if an off-chip storage device is integrated and used on
+the platform.
+
+Anti-rollback protection in PS relies on non-volatile counter(s) provided by
+TF-M Platform :term:`Secure Partition` (SP).
+
+TF-M audit logging service
+==========================
+
+TF-M audit logging service allows secure services in the system to log TF-M
+events and information.
+
+TF-M audit logging service is not enabled in Profile Large since its IPC model
+dedicated interface is not ready yet.
+
+.. note ::
+
+ **Implementation note**
+
+ Please note that there is no dedicated PSA specification for Audit Logging
+ yet.
+ The design, interfaces and implementation of TF-M audit logging service may
+ change.
+
+Software countermeasures against physical attacks
+=================================================
+
+TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile
+Medium by default. It enables the following countermeasure techniques:
+
+ - Control flow monitor
+ - Failure loop hardening
+ - Complex constants
+ - Redundant variables and condition checks
+
+Refer to TF-M physical attack mitigation design document [6]_ for FIH library
+details.
+
+.. note ::
+
+ **TF-M FIH library is still under development**.
+
+ TF-M FIH library hardens TF-M critical execution steps to make physical
+ attacks more difficult, together with device hardware countermeasures.
+ It is not guaranteed that TF-M FIH library is able to mitigate all kinds of
+ physical attacks.
+
+.. note ::
+
+ **Implementation note**
+
+ TF-M FIH library doesn't cover platform specific critical configurations.
+ Platforms shall implement software countermeasures against physical attacks
+ to protect platform specific implementation.
+
+**************
+Implementation
+**************
+
+Overview
+========
+
+The basic idea is to add dedicated profile CMake configuration files under
+folder ``config/profile`` for TF-M Profile Large default configuration, the
+same as other TF-M Profiles do.
+
+The top-level Profile Large config file collects all the necessary configuration
+flags and set them to default values, to explicitly enable the features required
+in Profile Large and disable the unnecessary ones, during TF-M build.
+
+A platform/use case can provide a configuration extension file to overwrite
+Profile Large default setting and append other configurations.
+This configuration extension file can be added via parameter
+``TFM_EXTRA_CONFIG_PATH`` in build command line.
+
+The behaviour of the Profile Large build flow (particularly the order of
+configuration loading and overriding) can be found at
+:ref:`tfm_cmake_configuration`
+
+The details of configurations will be covered in each module in
+`Implementation details`_.
+
+Implementation details
+======================
+
+This section discusses the details of Profile Large implementation.
+
+Top-level configuration files
+-----------------------------
+
+The firmware framework configurations in ``config/profile/profile_large`` are
+shown below.
+
+.. table:: Config flags in Profile Large top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | Configs | Descriptions | Default value |
+ +============================================+====================================+====================================================================================================+
+ | ``TFM_ISOLATION_LEVEL`` | Select level 3 isolation | ``3`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PSA_API`` | Select IPC model | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``ITS_BUF_SIZE`` | ITS internal transient buffer size | ``64`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_CRYPTO`` | Enable Crypto service | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | MbedTLS config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | Enable Initial Attestation service | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_ | Enable PS service | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_PLATFORM`` | Enable TF-M Platform SP | ``ON`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+ | ``TFM_PARTITION_AUDIT_LOG`` | Disable TF-M audit logging service | ``OFF`` |
+ +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
+
+.. [a] PS service is enabled by default. Platforms without off-chip storage
+ devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
+ service. See `Protected Storage Secure Partition`_ for details.
+
+Crypto service configurations
+-----------------------------
+
+Crypto Secure Partition
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Large enables Crypto SP in top-level CMake config file and selects
+all the Crypto modules.
+
+MbedTLS configurations
+^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Large adds a dedicated MbedTLS config file
+``tfm_mbedcrypto_config_profile_large.h`` under
+``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one
+``tfm_mbedcrypto_config_default.h`` [7]_.
+
+Major MbedTLS configurations are set as listed below:
+
+ - Enable SHA256 and SHA512
+ - Enable generic message digest wrappers
+ - Enable AES
+ - Enable CCM mode, GCM mode and CBC mode for symmetric ciphers
+ - Disable other modes for symmetric ciphers
+ - Enable ECDH
+ - Enable ECDSA
+ - Enable RSA
+ - Select ECC curve ``secp256r1`` and ``secp384r1``
+ - Enable HMAC-based key derivation function
+ - Other configurations required by selected option above
+
+A device/use case can append an extra config header to the Profile Large default
+MbedTLS config file to override the default settings. This can be done by
+setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the
+platform config file ``platform/ext/config.cmake``.
+This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE``
+options, but is preferred as it keeps all configuration in cmake.
+
+Internal Trusted Storage configurations
+---------------------------------------
+
+ITS service is enabled in top-level Profile Large CMake config file by default.
+
+The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by
+default. A platform/use case can overwrite the buffer size in its specific
+configuration extension according to its actual requirement of assets and Flash
+attributes.
+
+Profile Large CMake config file won't touch the configurations of device
+specific Flash hardware attributes.
+
+Protected Storage Secure Partition
+----------------------------------
+
+Data confidentiality, integrity and anti-rollback protection are enabled by
+default in PS.
+
+If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform
+hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can
+be executed in hardware crypto accelerator.
+
+If platforms don't integrate any off-chip storage device, platforms can disable
+PS in platform specific configuration extension file via
+``platform/ext/config.cmake``.
+
+BL2 setting
+-----------
+
+Profile Large enables MCUBoot provided by TF-M by default. A platform can
+overwrite this configuration by disabling MCUBoot in its configuration extension
+file ``platform/ext/config.cmake``.
+
+If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
+default.
+
+If a device implements its own boot loader, the configurations are
+implementation defined.
+
+Software countermeasure against physical attacks
+------------------------------------------------
+
+Profile Large selects TF-M FIH library Profile Medium by specifying
+``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file.
+
+System integrators shall implement software countermeasures in platform specific
+implementations.
+
+Device configuration extension
+------------------------------
+
+To change default configurations and add platform specific configurations,
+a platform can add a platform configuration file at
+``platform/ext/config.cmake``
+
+Test configuration
+------------------
+
+Some cryptography tests are disabled due to the reduced MbedTLS config.
+Profile Large specific test configurations are also specified in Profile Large
+top-level CMake config file ``config/profile/profile_large``.
+
+.. table:: Profile Large crypto test configuration
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+===============+=========================================+
+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``ON`` | Test CBC cryptography mode |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``ON`` | Test GCM cryptography mode |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``ON`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_HKDF`` | ``ON`` | Test HMAC-based key derivation function |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
+ +--------------------------------------------+---------------+-----------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
+ +--------------------------------------------+---------------+-----------------------------------------+
+
+****************
+Platform support
+****************
+
+To enable Profile Large on a platform, the platform specific CMake file should
+be added into the platform support list in top-level Profile Large CMake config
+file.
+
+Building Profile Large
+======================
+
+To build Profile Large, argument ``TFM_PROFILE`` in build command line should be
+set to ``profile_large``.
+
+Take AN521 as an example:
+
+The following commands build Profile Large without test cases on **AN521** with
+build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_large \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ ../
+ cmake --build ./ -- install
+
+The following commands build Profile Large with regression test cases on
+**AN521** with build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_large \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ -DTEST_S=ON -DTEST_NS=ON \
+ ../
+ cmake --build ./ -- install
+
+More details of building instructions and parameters can be found TF-M build
+instruction guide [9]_.
+
+*********
+Reference
+*********
+
+.. [1] :doc:`Trusted Firmware-M Profile Small Design `
+
+.. [2] :doc:`Trusted Firmware-M Profile Medium Design `
+
+.. [3] `PSA Certified Level 3 Lightweight Protection Profile `_
+
+.. [4] `Arm Platform Security Architecture Firmware Framework 1.0 `_
+
+.. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 `_
+
+.. [6] :doc:`Physical attack mitigation in Trusted Firmware-M `
+
+.. [7] :doc:`Crypto design `
+
+.. [8] :doc:`ITS integration guide `
+
+.. [9] :doc:`TF-M build instruction `
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/profiles/tfm_profile_medium.rst b/docs/technical_references/profiles/tfm_profile_medium.rst
new file mode 100644
index 0000000000..b1ab1c1786
--- /dev/null
+++ b/docs/technical_references/profiles/tfm_profile_medium.rst
@@ -0,0 +1,477 @@
+########################################
+Trusted Firmware-M Profile Medium Design
+########################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+Compared with Profile Small, Profile Medium aims to securely connect devices to
+Cloud services with asymmetric cipher support.
+Profile Medium target devices need more resources for more cipher algorithms
+and higher isolation levels.
+
+For more descriptions and background of TF-M Profile, please refer to Profile
+Small design document [PROFILE-S]_.
+
+**************
+Overall design
+**************
+
+TF-M Profile Medium defines the following feature set:
+
+ - Firmware Framework
+
+ - Inter-Process Communication (IPC) model [PSA-FF-M]_
+ - Isolation level 2 [PSA-FF-M]_
+
+ - Internal Trusted Storage (ITS)
+
+ - Crypto
+
+ - Support both symmetric ciphers and asymmetric ciphers
+ - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for
+ IoT [RFC7925]_ and CoAP [RFC7252]_, including
+
+ - Authenticated Encryption with Associated Data (AEAD) algorithm
+ - Asymmetric key algorithm based signature and verification
+ - Public-key cryptography based key exchange
+ - Hash function
+ - HMAC for default Pseudorandom Function (PRF)
+
+ - Asymmetric digital signature and verification for Initial Attestation
+ Token (IAT)
+
+ - Initial Attestation
+
+ - Asymmetric key algorithm based Initial Attestation
+
+ - Lightweight boot
+
+ - Anti-rollback protection
+ - Multiple image boot
+
+ - Protected Storage (PS) if off-chip storage device is integrated
+
+ - Data confidentiality
+ - Data integrity
+ - Rollback protection
+
+**************
+Design details
+**************
+
+More details of TF-M Profile Medium design are described in following sections.
+
+Firmware framework
+==================
+
+Profile Medium with IPC model and isolation level 2 aims to support usage
+scenarios which require more complicated secure service model and additional
+protection to PSA RoT.
+
+Level 2 isolation
+-----------------
+
+Profile Medium selects isolation level 2 by default. In addition to isolation
+level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the
+Application Root of Trust (App RoT) in level 2 isolation.
+
+IPC model
+---------
+
+Profile Medium enables IPC model by default. IPC model can achieve a more
+flexible framework and higher levels of isolation, but may require more memory
+footprint and bring in longer latency, compared to Library model.
+
+TF-M IPC model implementation follows the PSA Firmware Framework for M
+(PSA-FF-M) [PSA-FF-M]_.
+
+Crypto service
+==============
+
+Compared to Profile Small, Profile Medium includes asymmetric cipher to support
+direct connection to Cloud services via common protocols, such as TLS/DTLS 1.2.
+
+As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default
+selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires:
+
+ - ECDHE_ECDSA as key exchange algorithm.
+ - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm.
+ Platforms can implement AES-128-CCM with truncated authentication tag to
+ achieve less network bandwidth [RFC7925]_.
+ - SHA256 as Hash function.
+ - HMAC as Message Authentication Code algorithm.
+
+Applications can also support TLS PSK [RFC4279]_ cipher suites, such as
+``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_.
+
+.. note ::
+
+ **Implementation note**
+
+ Developers can replace default algorithms with others or implement more
+ algorithms according to actual usage scenarios and device capabilities.
+
+ If a Crypto hardware accelerator is integrated, the cipher suites and
+ algorithms also depend on those accelerator features.
+
+More details of cipher suite are described below.
+
+Digital signature and verification
+----------------------------------
+
+ECDSA is selected by default in Profile Medium.
+ECDSA requires much shorter keys compared with RSA at the same security level.
+Therefore, ECDSA can cost less storage area for assets and less network
+bandwidth to setup a TLS connection.
+ECDSA is also preferred for forward compatibility of future TLS versions.
+
+As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More
+ECC curves can be added based on the requirements in production.
+
+If usage scenarios require RSA algorithm for backward compatibility and legacy
+applications, platforms can add RSA support or replace ECDSA with RSA. The
+cipher suite should be switched accordingly.
+
+AEAD algorithm
+--------------
+
+If Protected Storage (PS) is implemented, it is recommended to select the same
+AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite.
+
+Internal Trusted Storage
+========================
+
+The configuration of ITS is the same as those in Profile Small [PROFILE-S]_.
+
+Lightweight boot
+================
+
+BL2 implementation can be device specific. Devices may implement diverse
+boot processes with different features and configurations.
+However, the boot loader must support anti-rollback protection. Boot loader must
+be able to prevent unauthorized rollback, to protect devices from being
+downgraded to earlier versions with known vulnerabilities.
+
+MCUBoot in TF-M is configured as multiple image boot by default in Profile
+Medium. In multiple image boot, secure and non-secure images can be signed
+independently with different keys and they can be updated separately. It can
+support multiple vendors scenarios, in which non-secure and secure images are
+generated and updated by different vendors.
+Multiple image boot may require more storage area compared with single image
+boot.
+
+Protected Storage
+=================
+
+PS service is required if an off-chip storage device is integrated and used on
+the platform.
+
+TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and
+integrity. It is recommended to select the same AEAD algorithm as the one used
+for TLS/DTLS cipher suite.
+
+Anti-rollback protection in PS relies on non-volatile counter(s) provided by
+TF-M Platform Secure Partition (SP).
+
+TF-M audit logging service
+==========================
+
+TF-M audit logging service allows secure services in the system to log critical
+system events and information.
+
+TF-M audit logging service is not enabled in Profile Medium since its IPC model
+dedicated interface is not ready yet.
+
+.. note ::
+
+ **Implementation note**
+
+ Please note that there is no dedicated PSA specification for Audit Logging
+ yet.
+ The design, interfaces and implementation of TF-M audit logging service may
+ change.
+
+**************
+Implementation
+**************
+
+Overview
+========
+
+The basic idea is to add dedicated profile CMake configuration files under
+folder ``config/profile`` for TF-M Profile Medium default configuration, the
+same as Profile Small does.
+
+The top-level Profile Medium config file collects all the necessary
+configuration flags and set them to default values, to explicitly enable the
+features required in Profile Medium and disable the unnecessary ones, during
+TF-M build.
+
+A platform/use case can provide a configuration extension file to overwrite
+Profile Medium default setting and append other configurations.
+This configuration extension file can be added via parameter
+``TFM_EXTRA_CONFIG_PATH`` in build command line.
+
+The behaviour of the Profile Medium build flow (particularly the order of
+configuration loading and overriding) can be found at
+:ref:`tfm_cmake_configuration`
+
+The details of configurations will be covered in each module in
+`Implementation details`_.
+
+Implementation details
+======================
+
+This section discusses the details of Profile Medium implementation.
+
+Top-level configuration files
+-----------------------------
+
+The firmware framework configurations in ``config/profile/profile_medium`` are
+shown below.
+
+.. table:: Config flags in Profile Medium top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PSA_API`` | ``True`` | Select IPC model |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
+.. [1] PS service is enabled by default. Platforms without off-chip storage
+ devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
+ service. See `Protected Storage Secure Partition`_ for details.
+
+.. Note::
+
+ Where a configuration is the same as the default in
+ ``config/config_default.cmake``, it is omitted from the profile configuration
+ file.
+
+Test configuration
+^^^^^^^^^^^^^^^^^^
+
+Standard regression test configuration applies. This means that enabling
+regression testing via
+
+``-DTEST_S=ON -DTEST_NS=ON``
+
+Will enable testing for all enabled partitions. See above for details of enabled
+partitions. Because Profile Medium enables IPC mode, the IPC tests are also
+enabled.
+
+Some cryptography tests are disabled due to the reduced Mbed Crypto config.
+
+.. table:: TFM options in Profile Medium top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
+Device configuration extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To change default configurations and add platform specific configurations,
+a platform can add a platform configuration file at
+``platform/ext/config.cmake``
+
+Crypto service configurations
+-----------------------------
+
+Crypto Secure Partition
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Medium enables Crypto SP in top-level CMake config file and selects
+all the Crypto modules.
+
+Mbed Crypto configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Medium adds a dedicated Mbed Crypto config file
+``tfm_mbedcrypto_config_profile_medium.h`` at
+``/lib/ext/mbedcrypto/mbedcrypto_config``
+file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_.
+
+Major Mbed Crypto configurations are set as listed below:
+
+ - Enable SHA256
+ - Enable generic message digest wrappers
+ - Enable AES
+ - Enable CCM mode for symmetric ciphers
+ - Disable other modes for symmetric ciphers
+ - Enable ECDH
+ - Enable ECDSA
+ - Select ECC curve ``secp256r1``
+ - Other configurations required by selected option above
+
+Other configurations can be selected to optimize the memory footprint of Crypto
+module.
+
+A device/use case can append an extra config header to the Profile Medium
+default Mbed Crypto config file. This can be done by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
+config file ``platform/ext/config.cmake``. This cmake variable is
+a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
+it keeps all configuration in cmake.
+
+Internal Trusted Storage configurations
+---------------------------------------
+
+ITS service is enabled in top-level Profile Medium CMake config file by default.
+
+The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to
+32 bytes by default. A platform/use case can overwrite the buffer size in its
+specific configuration extension according to its actual requirement of assets
+and Flash attributes.
+
+Profile Medium CMake config file won't touch the configurations of device
+specific Flash hardware attributes [ITS-INTEGRATE]_.
+
+Protected Storage Secure Partition
+----------------------------------
+
+Data confidentiality, integrity and anti-rollback protection are enabled by
+default in PS.
+
+If PS is selected, AES-CCM is used as AEAD algorithm by default. It requires to
+enable PS implementation to select diverse AEAD algorithm.
+
+If platforms don't integrate any off-chip storage device, platforms can disable
+PS in platform specific configuration extension file via
+``platform/ext/config.cmake``.
+
+BL2 setting
+-----------
+
+Profile Medium enables MCUBoot provided by TF-M by default. A platform can
+overwrite this configuration by disabling MCUBoot in its configuration extension
+file ``platform/ext/config.cmake``.
+
+If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
+default in TF-M Profile Medium top-level CMake config file.
+
+If a device implements its own boot loader, the configurations are
+implementation defined.
+
+****************
+Platform support
+****************
+
+To enable Profile Medium on a platform, the platform specific CMake file should
+be added into the platform support list in top-level Profile Medium CMake config
+file.
+
+Building Profile Medium
+=======================
+
+To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be
+set to ``profile_medium``.
+
+Take AN521 as an example:
+
+The following commands build Profile Medium without test cases on **AN521** with
+build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_medium \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ ../
+ cmake --build ./ -- install
+
+The following commands build Profile Medium with regression test cases on
+**AN521** with build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_medium \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ -DTEST_S=ON -DTEST_NS=ON \
+ ../
+ cmake --build ./ -- install
+
+.. Note::
+
+ - For devices with more contrained memory and flash requirements, it is
+ possible to build with either only TEST_S enabled or only TEST_NS enabled.
+ This will decrease the size of the test images. Note that both test suites
+ must still be run to ensure correct operation.
+
+More details of building instructions and parameters can be found TF-M build
+instruction guide [TFM-BUILD]_.
+
+*********
+Reference
+*********
+
+.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 `_
+
+.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things `_
+
+.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design `
+
+.. [RFC7252] `The Constrained Application Protocol (CoAP) `_
+
+.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_
+
+.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS `_
+
+.. [CRYPTO-DESIGN] :doc:`Crypto design `
+
+.. [ITS-INTEGRATE] :doc:`ITS integration guide `
+
+.. [TFM-BUILD] :doc:`TF-M build instruction `
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/profiles/tfm_profile_small.rst b/docs/technical_references/profiles/tfm_profile_small.rst
new file mode 100644
index 0000000000..189b1a56a0
--- /dev/null
+++ b/docs/technical_references/profiles/tfm_profile_small.rst
@@ -0,0 +1,645 @@
+#######################################
+Trusted Firmware-M Profile Small Design
+#######################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+The capabilities and resources may dramatically vary on different IoT devices.
+Some IoT devices may have very limited memory resource. The program on those
+devices should keep small memory footprint and basic functionalities.
+On the other hand, some devices may consist of more memory and extended storage,
+to support stronger software capabilities.
+
+Diverse IoT use cases also require different levels of security and requirements
+on device resource. For example, use cases require different cipher
+capabilities. Selecting cipher suites can be sensitive to memory footprint on
+devices with constrained resource.
+
+Trusted Firmware-M (TF-M) defines 3 general profiles, Profile Small,
+Profile Medium and Profile Large, to provide different levels of security to fit
+diverse device capabilities and use cases.
+Each profile specifies a predefined list of features, targeting typical use
+cases with specific hardware constraints. Profiles can serve as reference
+designs, based on which developers can continue further development and
+configurations, according to use case.
+
+As one of the TF-M Profiles, TF-M Profile Small (Profile S) consists of
+lightweight TF-M framework and basic Secure Services to keep smallest memory
+footprint, supporting fundamental security features on devices with ultra
+constrained resource.
+
+This profile enables connecting with Edge Gateways and IoT Cloud Services
+supporting secure connection based solely on symmetric cryptography.
+
+This document summarizes and discusses the features specified in TF-M Profile
+Small.
+
+**************
+Overall design
+**************
+
+TF-M Profile Small defines the following features:
+
+ - Lightweight framework
+
+ - Library model
+ - Level 1 isolation
+ - Buffer sharing allowed
+ - Single secure context
+
+ - Crypto
+
+ - Symmetric cipher only
+ - Cipher suite for symmetric-key algorithms based protocols, such as
+ cipher suites defined in TLS pre-shared key (TLS-PSK) [1]_.
+
+ - Advanced Encryption Standard (AES) as symmetric crypto algorithm
+ - SHA256 as Hash function
+ - HMAC as Message Authentication Code algorithm
+
+ - Internal Trusted Storage (ITS)
+
+ - No encryption
+ - No rollback protection
+ - Decrease internal transient buffer size
+
+ - Initial Attestation
+
+ - Based on symmetric key algorithms
+
+ - Lightweight boot
+
+ - Single image boot
+ - Anti-rollback protection is enabled
+
+
+Protected Storage, audit logging and other Secure Services provided by TF-M are
+disabled by default.
+
+**************
+Design details
+**************
+
+More details of TF-M Profile Small design are discussed in following sections.
+
+Lightweight framework
+=====================
+
+Library model
+-------------
+
+Profile Small selects Library model in TF-M. Library model implements secure
+function calls, via which clients directly call secure services. It provides a
+more simple implementation of TF-M framework and may reduce memory footprint,
+compared with Inter-Process Communication (IPC) model [2]_.
+
+.. note ::
+
+ **Implementation note**
+
+ Please note that there is no public dedicated specification for Library
+ model.
+ The design, interfaces and implementation of Library model in TF-M may
+ change.
+
+Level 1 isolation
+-----------------
+
+So far, TF-M Library model only supports level 1 isolation [2]_, which isolates
+Secure Processing Environment (SPE) from Non-secure Processing Environment
+(NSPE). Neither level 2 nor level 3 isolation [2]_ is implemented in TF-M
+Library model.
+
+PSA Root of Trust (PSA RoT) and Application Root of Trust (ARoT) are isolated
+from each other in level 2 isolation.
+Individual secure partitions are isolated from each other even within a
+particular security domain (PSA RoT, ARoT), in level 3 isolation.
+
+Profile Small dedicated use cases with simple service model may not require
+level 2 or level 3 isolation. Devices which Profile Small aims at may be unable
+to implement stricter isolation, limited by hardware capabilities.
+
+Level 1 isolation reduces requirements enforced by hardware isolation and cost
+of software for management.
+
+.. note ::
+
+ **Security note**
+
+ If a device or a use case enforces level 2 or level 3 isolation, it is
+ suggested to apply other configurations, other than TF-M Profile Small.
+
+Buffer sharing allowed
+----------------------
+
+To simplify interface and reduce memory footprint, TF-M Library model directly
+handles client call input vectors from non-secure client buffers and later
+writes results back to those buffers, without keeping a copy in a transient
+buffer inside TF-M.
+
+.. note ::
+
+ **Security note**
+
+ There can be security vulnerabilities if non-secure client buffers are
+ directly shared between NSPE and SPE, such as Time-of-check to time-of-use
+ (TOCTOU) attack.
+
+ Developers need to check if this can meet the Security Functional
+ Requirements (SFR) of the integration of their devices.
+ Some SFRs are listed in a set of example Threat Models and Security Analyses
+ (TMSA) offered by PSA for common IoT use cases. [3]_
+
+Single secure context
+---------------------
+
+TF-M Library model only supports single secure context.
+
+It cannot support multiple contexts or the scheduling implemented in IPC model.
+It neither can support multiple outstanding PSA client calls.
+
+But correspondingly, it can save memory footprint and runtime complexity in
+context management and scheduling.
+
+.. note ::
+
+ **Security note**
+
+ Non-secure software should prevent triggering multiple outstanding PSA
+ client calls concurrently. Otherwise, it may crash current running secure
+ context.
+
+Crypto service
+==============
+
+TF-M Profile Small only requires symmetric crypto since symmetric algorithms
+require shorter keys and less computational burden, compared with asymmetric
+crypto.
+
+By default, TF-M Profile Small requires the same capabilities as defined in
+TLS-PSK, to support symmetric key algorithms based protocols.
+
+.. note ::
+
+ **Implementation note**
+
+ Please note that TF-M Profile Small doesn't require that TLS-PSK is
+ mandatory in applications. Instead, Profile Small only requires the same
+ capabilities as defined in TLS-PSK, such as one symmetric cipher algorithm
+ and one hash function.
+
+TF-M Profile Small selects TLS-PSK cipher suite TLS_PSK_WITH_AES_128_CCM [4]_
+as reference, which requires:
+
+ - AES-128-CCM (AES CCM mode with 128-bit key) as symmetric crypto algorithm
+ - SHA256 as Hash function
+ - HMAC as Message Authentication Code algorithm
+
+TLS_PSK_WITH_AES_128_CCM is selected since it requires small key length and less
+hardware capabilities, while keeping enough level of security.
+
+.. note ::
+
+ **Implementation note**
+
+ Developers can replace default algorithms with others or implement more
+ algorithms.
+
+ Proper symmetric key algorithms and cipher suites should be selected
+ according to device capabilities, the use case and the requirement of peers
+ in connection.
+
+ Refer to `Crypto service configuration`_ for implementation details of
+ configuring algorithms and cipher suites.
+
+.. note ::
+
+ **Security note**
+
+ It is recommended not to use MD5 or SHA-1 for message digests as they are
+ subject to collision attacks [5]_ [6]_.
+
+Secure Storage
+==============
+
+TF-M Profile Small assumes that extremely constrained devices only contain basic
+on-chip storage, without external or removable storage.
+As a result, TF-M Profile Small includes ITS service and disables Protected
+Storage service.
+
+Encryption and rollback protection
+----------------------------------
+
+Neither encryption nor rollback protection is enabled in current ITS
+implementation.
+
+It is expected that ITS relies solely on the physical inaccessibility property
+of on-chip storage, together with PSA isolation, without requiring additional
+cryptographic protection.
+
+Internal transient buffer
+-------------------------
+
+ITS implements a internal transient buffer [7]_ to hold the data read
+from/written to storage, especially for flash, to solve the alignment and
+security issues.
+
+The internal transient buffer is aligned to the flash device’s program unit.
+Copying data to it from the caller can align all write requests to the flash
+device’s program unit.
+The internal transient buffer can help protect Flash access from some attacks,
+such as TOCTOU attack.
+
+Although removing this internal buffer can save some memory consumption,
+typically 512 bytes, it may bring alignment or security issues.
+Therefore, to achieve a better trade-off between memory footprint and security,
+TF-M Profile Small optimizes the internal buffer size to 32 bytes by default.
+
+As discussed in `Crypto service`_, TF-M Profile Small requires AES-128 and
+SHA-256, which use 128-bit key and 256-bit key respectively.
+Besides, either long public/private keys or PKI-based certificates should be
+very rare as asymmetric crypto is not supported in Profile Small.
+Therefore, a 32-byte internal buffer should cover the assets in TF-M Profile
+Small use cases.
+
+The buffer size can be adjusted according to use case and device Flash
+attributes. Refer to `Internal Trusted Storage configurations`_ for more
+details.
+
+Initial Attestation
+===================
+
+Profile Small requires an Initial Attestation secure service based on symmetric
+key algorithms. Refer to PSA Attestation API document [8]_ for details of
+Initial Attestation based on symmetric key algorithms.
+
+It can heavily increase memory footprint to support Initial Attestation based on
+asymmetric key algorithms, due to asymmetric ciphers and related PKI modules.
+
+.. note ::
+
+ **Implementation note**
+
+ As pointed out by PSA Attestation API document [8]_, the use cases of
+ Initial Attestation based on symmetric key algorithms can be limited due to
+ the associated infrastructure costs for key management and operational
+ complexities. It may also restrict the ability to interoperate with
+ scenarios that involve third parties.
+
+ If asymmetric key algorithms based Initial Attestation is required in use
+ scenarios, it is recommended to select other TF-M Profiles which support
+ asymmetric key algorithms.
+
+.. note ::
+
+ **Implementation note**
+
+ It is recommended to utilize the same MAC algorithm supported in Crypto
+ service to complete the signing in ``COSE_Mac0``, to minimize memory
+ footprint.
+
+Lightweight boot
+================
+
+If MCUBoot provided by TF-M is enabled, single image boot [9]_ is selected by
+default in Profile Small.
+In case of single image boot, secure and non-secure images are handled as a
+single blob and signed together during image generation.
+
+However, secure and non-secure images must be updated together in single image
+boot. It may decrease the flexibility of image update and cost longer update
+process. Since the image sizes should usually be small with limited
+functionalities in Profile Small dedicated use case, the cost may still be
+reasonable.
+
+BL2 implementation can be device specific. Devices may implement diverse
+boot processes with different features and configurations.
+However, anti-rollback protection is required as a mandatory feature of boot
+loader. Boot loader should be able to prevent unauthorized rollback, to protect
+devices from being downgraded to earlier versions with known vulnerabilities.
+
+**************
+Implementation
+**************
+
+Overview
+========
+
+The basic idea is to add dedicated profile CMake configuration files under
+folder ``config/profile`` for TF-M Profile Small default configuration.
+
+The top-level Profile Small config file collects all the necessary
+configuration flags and set them to default values, to explicitly enable the
+features required in Profile Small and disable the unnecessary ones, during
+TF-M build.
+
+A platform/use case can provide a configuration extension file to overwrite
+Profile Small default setting and append other configurations.
+This configuration extension file can be added via parameter
+``TFM_EXTRA_CONFIG_PATH`` in build command line.
+
+The behaviour of the Profile Small build flow (particularly the order of
+configuration loading and overriding) can be found at
+:ref:`tfm_cmake_configuration`
+
+The details of configurations will be covered in each module in
+`Implementation details`_.
+
+Implementation details
+======================
+
+This section discusses the details of Profile Small implementation.
+
+Top-level configuration files
+-----------------------------
+
+The firmware framework configurations in ``config/profile/profile_small`` are
+shown below.
+
+.. table:: TFM options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
+.. note ::
+
+ **Implementation note**
+
+ The following sections focus on the feature selection via configuration
+ setting.
+ Dedicated optimization on memory footprint is not covered in this document.
+
+Test configuration
+^^^^^^^^^^^^^^^^^^
+
+Standard regression test configuration applies. This means that enabling
+regression testing via
+
+``-DTEST_S=ON -DTEST_NS=ON``
+
+Will enable testing for all enabled partitions. See above for details of enabled
+partitions. Because Profile Small does not enable IPC mode, the IPC tests are
+not enabled.
+
+Some cryptography tests are disabled due to the reduced Mbed Crypto config.
+
+.. table:: TFM options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
+Device configuration extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To change default configurations and add platform specific configurations,
+a platform can add a platform configuration file at
+``platform/ext/config.cmake``
+
+TF-M framework setting
+----------------------
+
+The top-level Profile Small CMake config file selects Library model and level 1
+isolation.
+
+Crypto service configuration
+----------------------------
+
+Crypto Secure Partition
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Small enables Crypto Secure Partition (SP) in its top-level CMake
+config file. Crypto SP modules not supported in TF-M Profile Small are disabled.
+The disabled modules are shown below.
+
+ - Disable asymmetric cipher
+
+Other modules and configurations [10]_ are kept as default values.
+
+Additional configuration flags with more fine granularity can be added to
+control building of specific crypto algorithms and corresponding test cases.
+
+Mbed Crypto configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TF-M Profile Small adds a dedicated Mbed Crypto config file
+``tfm_mbedcrypto_config_profile_small.h`` at
+``/lib/ext/mbedcrypto/mbedcrypto_config``
+file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_.
+
+Major Mbed Crypto configurations are set as listed below:
+
+ - Enable SHA256
+ - Enable generic message digest wrappers
+ - Enable AES
+ - Enable CCM mode for symmetric ciphers
+ - Disable other modes for symmetric ciphers
+ - Disable asymmetric ciphers
+ - Disable HMAC-based key derivation function (HKDF)
+
+Other configurations can be selected to optimize the memory footprint of Crypto
+module.
+
+A device/use case can append an extra config header to the Profile Small
+default Mbed Crypto config file. This can be done by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform
+config file ``platform/ext/config.cmake``. This cmake variable is
+a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as
+it keeps all configuration in cmake.
+
+Internal Trusted Storage configurations
+---------------------------------------
+
+ITS service is enabled in top-level Profile Small CMake config file.
+
+The internal transient buffer size ``ITS_BUF_SIZE`` [7]_ is set to 32 bytes by
+default. A platform/use case can overwrite the buffer size in its specific
+configuration extension according to its actual requirement of assets and Flash
+attributes.
+
+Profile Small CMake config file won't touch the configurations of device
+specific Flash hardware attributes [7]_.
+
+Initial Attestation secure service
+----------------------------------
+
+TF-M Profile Small provides a reference implementation of symmetric key
+algorithms based Initial Attestation, using HMAC SHA-256 as MAC algorithm in
+``COSE_Mac0`` structure. The implementation follows PSA Attestation API document
+[8]_.
+
+Profile Small top-level config file enables Initial Attestation secure service
+and selects symmetric key algorithms based Initial Attestation by default.
+
+ - Set ``TFM_PARTITION_INITIAL_ATTESTATION`` to ``ON``
+ - Set ``SYMMETRIC_INITIAL_ATTESTATION`` to ``ON``
+
+Symmetric and asymmetric key algorithms based Initial Attestation can share the
+same generations of token claims, except Instance ID claim.
+
+Profile Small may implement the procedure or rely on a 3rd-party tool to
+construct and sign ``COSE_Mac0`` structure.
+
+Details of symmetric key algorithms based Initial Attestation design will be
+covered in a dedicated document.
+
+Disabled secure services
+------------------------
+
+Audit logging, Protected Storage, and Platform Service are disabled by default
+in Profile Small top-level CMake config file.
+
+BL2 setting
+-----------
+
+Profile Small enables MCUBoot provided by TF-M by default. A platform can
+overwrite this configuration by disabling MCUBoot in its configuration extension
+file ``platform/ext/config.cmake``.
+
+If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M
+Profile Small top-level CMake config file.
+
+If a device implements its own boot loader, the configurations are
+implementation defined.
+
+.. table:: BL2 options in Profile Small top-level CMake config file
+ :widths: auto
+ :align: center
+
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | Configs | Default value | Descriptions |
+ +============================================+=====================================================================================================+=====================================+
+ | ``BL2`` | ``ON`` | Enable MCUBoot bootloader |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+ | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images |
+ +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
+
+****************
+Platform support
+****************
+
+Building Profile Small
+======================
+
+To build Profile Small, argument ``TFM_PROFILE`` in build command line should be
+set to ``profile_small``.
+
+Take AN521 as an example.
+
+The following commands build Profile Small without test cases on **AN521** with
+build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_small \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ ../
+ cmake --build ./ -- install
+
+The following commands build Profile Small with regression test cases on **AN521**
+with build type **MinSizeRel**, built by **Armclang**.
+
+.. code-block:: bash
+
+ cd
+ mkdir build && cd build
+ cmake -DTFM_PLATFORM=mps2/an521 \
+ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
+ -DTFM_PROFILE=profile_small \
+ -DCMAKE_BUILD_TYPE=MinSizeRel \
+ -DTEST_S=ON -DTEST_NS=ON \
+ ../
+ cmake --build ./ -- install
+
+.. Note::
+
+ - For devices with more contrained memory and flash requirements, it is
+ possible to build with either only TEST_S enabled or only TEST_NS enabled.
+ This will decrease the size of the test images. Note that both test suites
+ must still be run to ensure correct operation.
+
+More details of building instructions and parameters can be found TF-M build
+instruction guide [11]_.
+
+*********
+Reference
+*********
+
+.. [1] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_
+
+.. [2] `DEN0063 Arm Platform Security Architecture Firmware Framework 1.0 `_
+
+.. [3] `PSA analyze stage `_
+
+.. [4] `AES-CCM Cipher Suites for Transport Layer Security (TLS) `_
+
+.. [5] `Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms `_
+
+.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths `_
+
+.. [7] :doc:`ITS integration guide `
+
+.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) `_
+
+.. [9] :doc:`Secure boot `
+
+.. [10] :doc:`Crypto design `
+
+.. [11] :doc:`TF-M build instruction `
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/ps_key_management.rst b/docs/technical_references/ps_key_management.rst
new file mode 100644
index 0000000000..80a39be492
--- /dev/null
+++ b/docs/technical_references/ps_key_management.rst
@@ -0,0 +1,183 @@
+========================================
+Protected Storage service key management
+========================================
+
+:Author: Jamie Fox
+:Organization: Arm Limited
+:Contact: Jamie Fox
+:Status: Accepted
+
+Background
+==========
+The PSA Protected Storage API requires confidentiality for external storage to
+be provided by:
+
+ **cryptographic ciphers using device-bound keys**, a tamper resistant
+ enclosure, or an inaccessible deployment location, depending on the threat
+ model of the deployed system.
+
+A TBSA-M-compliant device must embed a Hardware Unique Key (HUK), which provides
+the root of trust (RoT) for confidentiality in the system. It must have at least
+128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted
+code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_
+
+In the current implementation, the Protected Storage (PS) service reads the HUK
+directly and imports it into the Crypto partition for further use. This has
+multiple drawbacks:
+
+- If there were a flaw in PS that allowed an attacker to obtain its key, then
+ the HUK would be exposed, and so the attacker would be able to decrypt not
+ just protected storage but also anything else encrypted with the HUK or a key
+ derived from the HUK.
+- Using the same key for two or more different cryptographic algorithms may
+ reduce the security provided by one or more of them.
+- It is not possible to re-key if the HUK is used directly, for example in the
+ case of a lost key.
+- It is incompatible with devices where the HUK is in an enclave and cannot be
+ read directly.
+
+Proposal
+========
+Each time the system boots, PS will request that the Crypto service uses a key
+derivation function (KDF) to derive a storage key from the HUK. The storage key
+could be kept in on-chip volatile memory private to the Crypto partition, or it
+could remain inside a secure element. Either way it will not be returned to PS.
+
+For each call to the PSA Protected Storage APIs, PS will make requests to the
+Crypto service to perform AEAD encryption and/or decryption operations using the
+storage key (providing a fresh nonce for each encryption).
+
+At no point will PS access the key material itself, only referring to the HUK
+and storage key by their handles in the Crypto service.
+
+Key derivation
+==============
+PS will make key derivation requests to the Crypto service with calls to the
+PSA Crypto APIs. In order to derive the storage key, the following calls will be
+made::
+
+ /* Open a handle to the HUK */
+ psa_open_key(PSA_KEY_LIFETIME_PERSISTENT,
+ TFM_CRYPTO_KEY_ID_HUK,
+ &huk_key_handle)
+
+ /* Set up a key derivation operation with the HUK as the input key */
+ psa_key_derivation(&ps_key_generator,
+ huk_key_handle,
+ TFM_CRYPTO_ALG_HUK_DERIVATION,
+ PS_KEY_SALT, PS_KEY_SALT_LEN_BYTES,
+ PS_KEY_LABEL, PS_KEY_LABEL_LEN_BYTES,
+ PS_KEY_LEN_BYTES)
+
+ /* Create the storage key from the key generator */
+ psa_generator_import_key(ps_key_handle,
+ PS_KEY_TYPE,
+ PSA_BYTES_TO_BITS(PS_KEY_LEN_BYTES),
+ &ps_key_generator)
+
+.. note:: ``TFM_CRYPTO_KEY_ID_HUK`` is a PSA Crypto key ID that is assumed in
+ this design to identify the hardware unique key.
+
+ ``ps_key_handle`` is a PSA Crypto key handle to a volatile key, set
+ up in the normal way. After the call to ``psa_generator_import_key``,
+ it contains the storage key.
+
+ ``PS_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract'
+ step of HKDF, which is redundant when the input key material is a
+ cryptographically strong key. [RFC5869]_ It must be constant so that
+ the same key can be derived each boot, to decrypt previously-stored
+ data.
+
+ ``PS_KEY_LABEL`` can be any string that is independent of the input
+ key material and different to the label used in any other derivation
+ from the same input key. It prevents two different contexts from
+ deriving the same output key from the same input key.
+
+In the call to ``psa_key_derivation()``, ``TFM_CRYPTO_ALG_HUK_DERIVATION`` is
+supplied as the key derivation algorithm argument. This indicates that the key
+derivation should be done from the HUK, and allows it to be implemented in a
+platform-defined way (e.g. using a crypto accelerator). The system integrator
+should choose the most optimal algorithm for the platform, or fall back to the
+software implementation if none is available.
+
+When implemented in software, the key derivation function used by the crypto
+service to derive the storage key will be HKDF, with SHA-256 as the underlying
+hash function. HKDF is suitable because:
+
+- It is simple and efficient, requiring only two HMAC operations when the length
+ of the output key material is less than or equal to the hash length (as is the
+ case here).
+- The trade-off is that HKDF is only suitable when the input key material has at
+ least as much entropy as required for the output key material. But this is the
+ case here, as the HUK has 128 bits of entropy, the same as required by PS.
+- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally
+ analysed. [HKDF]_
+- It is supported by the TF-M Crypto service.
+
+The choice of underlying hash function is fairly straightforward: it needs to be
+a modern standardised algorithm, considered to be secure and supported by TF-M
+Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in
+the family, SHA-256 is the simplest and provides more than enough output length.
+
+Keeping the storage key private to PS
+-------------------------------------
+The salt and label fields are not generally secret, so an Application RoT
+service could request the Crypto service to derive the same storage key from the
+HUK, which violates isolation between Application RoT partitions to some extent.
+This could be fixed in a number of ways:
+
+- Only PSA RoT partitions can request Crypto to derive keys from the HUK.
+
+ - But then either PS has to be in the PSA RoT or request a service in the PSA
+ RoT to do the derivation on its behalf.
+
+- PS has a secret (pseudo)random salt, accessible only to it, that it uses to
+ derive the storage key.
+
+ - Where would this salt be stored? It cannot be generated fresh each boot
+ because the storage key must stay the same across reboots.
+
+- The Crypto service appends the partition ID to the label, so that no two
+ partitions can derive the same key.
+
+ - Still need to make sure only PSA RoT partitions can directly access the HUK
+ or Secure Enclave. The label is not secret, so any actor that can access the
+ HUK could simply perform the derivation itself, rather than making a request
+ to the Crypto service.
+
+The third option would solve the issue with the fewest drawbacks, so this option
+is the one that is proposed.
+
+Key use
+=======
+To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same
+way as the current implementation, but ``ps_key_handle`` will refer to the
+storage key, rather than the imported HUK. For each encryption operation, the
+following call is made (and analogously for decryption)::
+
+ psa_aead_encrypt(ps_key_handle, PS_CRYPTO_ALG,
+ crypto->ref.iv, PS_IV_LEN_BYTES,
+ add, add_len,
+ in, in_len,
+ out, out_size, out_len)
+
+Future changes
+==============
+In the future, the client's partition ID and the asset's UID could be used to
+derive a key that is unique to that asset, each time the Protected Storage APIs
+are called (*key diversification*). To achieve this, the key derivation must use
+a ``label`` parameter that is unique to each client ID, UID pair.
+
+References
+==========
+.. [TBSA-M] Arm Platform Security Architecture Trusted Base System Architecture
+ for Armv6-M, Armv7-M and Armv8-M, version 1.0
+.. [HKDF] Hugo Krawczyk. 2010. Cryptographic extraction and key derivation: the
+ HKDF scheme. In Proceedings of the 30th annual conference on Advances in
+ cryptology (CRYPTO'10)
+.. [RFC5869] IETF RFC 5869: HMAC-based Extract-and-Expand Key Derivation
+ Function (HKDF)
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/secure_boot_hw_key_integration.rst b/docs/technical_references/secure_boot_hw_key_integration.rst
new file mode 100644
index 0000000000..186e4a649b
--- /dev/null
+++ b/docs/technical_references/secure_boot_hw_key_integration.rst
@@ -0,0 +1,166 @@
+HW crypto key integration in TF-M secure boot
+=============================================
+
+:Author: Tamas Ban
+:Organization: Arm Limited
+:Contact: Tamas Ban
+:Status: Accepted
+
+Abstract
+--------
+
+`PSA Trusted Boot and Firmware Update `__
+specification requires the support of at least one immutable root of trust
+public key (ROTPK) for firmware verification. This can be stored using a locked
+on-chip flash memory, a secure-element or on-chip OTP memory. It also beneficial
+to be able to provision these keys during the factory life-cycle of the device
+independently from any software components. The current key handling solution
+in TF-M secure boot does not supports this key provisioning process. MCUBoot
+requires compile time built-in public key(s) for image verification. This
+limitation does not fit well with a scenario with multiple vendors where
+multiple MCU software components might be deployed by different vendors in
+different points in the life-cycle of the device and they do not want to share
+the keys in-advance for embedding in the bootloader code. The goal of this
+document to propose a solution to decouple MCUBoot from public key(s) and
+enable the independent deployment of ROTPK.
+
+Existing key handling solution
+------------------------------
+
+MCUBoot code contains a compile-time built-in key array which can store any
+number of key(s) for firmware verification: ``bl2/ext/mcuboot/keys.c``. These
+public key(s) must be available when MCUBoot image is built. There is a script
+``bl2/ext/mcuboot/scipt/imgtool.py`` which can generate a new key pair, and
+extract the public key part in the expected ASN.1 format and encode it as C
+structure. The script is also capable of signing the image with the private key.
+In order to identify and validate the corresponding public key during image
+verification the hash of the public key is appended to the image manifest area
+(TLV encoded metadata). During image verification the bootloader retrieves the
+hash of the public key from the manifest area and compare against the on-the-fly
+calculated hash value of the built-in public keys. An exact match identifies and
+validates the public key which must be used for image verification.
+
+Current memory layout::
+
+ |----------------------|
+ | |
+ | MCUBoot code |
+ | |
+ | Full public key |
+ | |
+ |----------------------|
+ | |
+ | Image |
+ | |
+ |----------------------|
+ | Image Manifest(TLV) |
+ | |
+ | Hash of public key |
+ |----------------------|
+ | |
+ | Rest of memory |
+ | |
+
+Requirements
+------------
+
+- Multiple independent vendor scenario must be supported, when more than one
+ ROTPK is provisioned to the device.
+- The corresponding public key for image verification must be identifiable and
+ verifiable.
+- Key identity must be immutable and anchored to the device itself.
+- Key(s) can be provisioned independently from bootloader.
+
+Design proposal
+---------------
+HW key(s) might stored in OTP memory which is an expensive resource, so
+storing a large key (such as RSA) is inefficient. Therefore, it is assumed that
+only the hash of the ROTPK will be stored in the HW. If only the hash of the
+public key is stored in the HW then the whole public key must be transfered to
+the device, because it must be available during image verification. This
+transfer can be done in the same way as how the hash of the key is transfered
+to the device with the current solution. A new TLV type (TLV_KEY) can be
+introduced to carry the whole public key. The corresponding public key will be
+appended to the image itself in the manifest area. It has the drawback that the
+image will be bigger, but it is assumed that the additional cost of the bigger
+image (extra flash area + power for download) is less than the cost of the OTP
+area.
+
+The verification flow:
+
+ - Look up the TLV_KEY field to get the public key.
+ - Calculates its hash(SHA256) value.
+ - Get the hash of ROTPK from the platform layer (stored in HW)
+ - Compare the two hash values, if they match then the key can be used to
+ validate the image. In case of failure consider the images as unauthenticated.
+
+Proposed memory layout::
+
+ |----------------------|
+ | |
+ | MCUBoot code |
+ | |
+ | NO PUBLIC KEY |
+ | |
+ |----------------------|
+ | |
+ | Image |
+ | |
+ |----------------------|
+ | Image Manifest(TLV) |
+ | |
+ | Full public key |
+ |----------------------|
+ | |
+ | |
+ | Rest of memory |
+ | |
+ | |
+ |----------------------|
+ | Immutable memory |
+ | |
+ | Hash of public key |
+ |----------------------|
+ | |
+
+Platform support
+----------------
+
+A new platform API used by the bootloader must be introduced to retrieve the
+image corresponding hash of ROTPK:
+
+``enum tfm_plat_err_t tfm_plat_get_rotpk_hash(uint8_t image_id,
+uint8_t *rotpk_hash, uint32_t *rotpk_hash_size);``
+
+The mapping between image identity and public key can be hard-code in the
+platform layer. This simplifies the validation of the public key, because no
+look-up would be needed. It is assumed that the memory area of the ROTPK hash is
+not directly accessible, therefore a buffer is allocated by the caller to store
+the hash there.
+
+Compile time configurability
+----------------------------
+
+The solution must be compile time configurable in order to be able to switch
+between built-in key(s) and HW key(s) support, and also due to backwards
+compatibility.
+
+Tooling
+-------
+
+``bl2/ext/mcuboot/scipt/imgtool.py`` will be modified to include the whole
+public key to the TLV area (instead of the hash).
+
+Table to compare the current and proposed solution::
+
+ |---------|-----------------------|-------------------|--------------------|
+ | |Key format in manifest |Key in MCUBoot code| Key in HW |
+ |---------|-----------------------|-------------------|--------------------|
+ |Proposed | Full public key | No key embedded | Hash of public key |
+ |---------|-----------------------|-------------------|--------------------|
+ |Current | Hash of public key | Full public key | No key in HW |
+ |---------|-----------------------|-------------------|--------------------|
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/secure_boot_rollback_protection.rst b/docs/technical_references/secure_boot_rollback_protection.rst
new file mode 100644
index 0000000000..711fac321e
--- /dev/null
+++ b/docs/technical_references/secure_boot_rollback_protection.rst
@@ -0,0 +1,203 @@
+#######################################
+Rollback protection in TF-M secure boot
+#######################################
+
+:Author: Tamas Ban
+:Organization: Arm Limited
+:Contact: Tamas Ban
+:Status: Accepted
+
+Anti-rollback protection
+========================
+The goal of anti-rollback protection is to prevent downgrading of the device to
+an older version of its software, which has been deprecated due to security
+concerns.
+
+Elements of software upgrade
+============================
+During a software upgrade the following entities are involved:
+
+ - Boot loader
+ - Manifest data: Metadata of the software image: size, version, hash,
+ signature, etc.
+ - Software image: binary data, elf, etc.
+
+Validation of new image
+=======================
+Boot loader is responsible to authenticate the new image according to the
+required policies and decide whether the new image is fulfilling all the
+requirements. Boot loader verifies the image integrity (hash calculation) and
+the origination (signature validation), and might verify other requirements as
+well. If the new image is successfully authenticated then the boot loader is in
+charge to do the necessary steps (load to execute address, etc.) to enable the
+new image to be executed. During the validation process the image and the
+manifest data is checked.
+
+Manifest format in MCUBoot
+==========================
+MCUBoot has a custom manifest format, which is composed of two parts:
+
+ - Image header: Prepended to the beginning of the image.
+ It is integrity protected:
+ - TLV section: Appended to the end of the image. It is not integrity protected:
+
+ - Hash of public key, hash of image, signature of image
+
+.. code-block:: c
+
+ struct image_header {
+ uint32_t ih_magic;
+ uint32_t ih_load_addr;
+ uint16_t ih_hdr_size;
+ uint16_t _pad1;
+ uint32_t ih_img_size;
+ uint32_t ih_flags;
+ struct image_version ih_ver;
+ uint32_t _pad2;
+ };
+
+Security counter
+================
+The aim of a security counter is to have an independent (from the image version)
+counter in the image manifest to ensure anti-rollback protection. During
+software release the value of this counter must be increased if a security flaw
+was fixed in the current version. Later when this image is installed on the
+device then it is not allowed to go back to earlier versions. It is beneficial
+to handle this counter independently from image main version number:
+
+ - It does not need to increase with each software release
+ - It makes it possible to do software downgrade to some extent: if the security
+ counter has the same value in the older image then it is accepted.
+ - If the boot loader verifies multiple images then these can be handled
+ independently.
+
+However, as an alternative solution the image version number also could serve
+as the security counter of the image. Even the version number itself could be
+checked during the anti-rollback verification or the value of the security
+counter could be derived from the image main version. It is the responsibility
+of the software issuer to define which policy to apply.
+
+Implementation of security counter
+==================================
+The value of the security counter is a security critical data. Any change in
+its value has a security implication. Therefore it must be in the integrity
+protected part of the image manifest. Because the image header is almost fully
+utilized (few unused fields) and the change of image header structure could
+lead to compatibility issues between boot loader and runtime software, it is
+proposed to extend the integrity protection to some part of the TLV section.
+One of the unused fields in the image header can be used to store the size of
+the integrity protected area of the TLV section. This is necessary to know how
+to calculate properly the image hash and signature. With this extension of the
+integrity protected area other attributes that require integrity protection
+can easily be added to the image manifest.
+
+Trusted non-volatile (NV) counters
+==================================
+The Trusted Base System Architecture (TBSA-M) defines non-volatile (NV) counters
+or version counters as a counter with the following properties:
+
+ - It must only be possible to increment a version counter through a Trusted
+ access.
+ - It must only be possible to increment a version counter. It must not be
+ possible to decrement it.
+ - When a version counter reaches its maximum value, it must not roll over,
+ and no further changes must be possible.
+ - A version counter must be non-volatile, and the stored value must survive
+ a power down period up to the lifetime of the device.
+
+Trusted non-volatile counters can be used to store the value of security
+counters per updatable software image. Ideally all independently updatable
+software images should have a separate security counter. In current TF-M
+implementation the BL2 is not updatable and the secure and non-secure images
+are updated together as a single binary. Therefore, one counter is enough to
+implement rollback protection. In future the secure and non-secure binaries
+will be handled independently; at that time the introduction of a second
+counter will be necessary.
+
+Currently the NV counters can be manipulated through the interface described
+in ``tfm_plat_nv_counters.h``.
+
+NV counters and anti-rollback protection
+========================================
+Trusted non-volatile counters might not be supported by a hardware platform.
+In this case anti-rollback protection might still be feasible.
+
+The device threat model needs to consider the following aspects:
+
+ - What is the trust level of the boot loader towards the active software
+
+ - If the boot loader cannot protect the anti-rollback mechanism from the
+ secure image then the following threat is unmitigated: The content of the
+ memory area which holds the active image could be replaced with a valid but
+ an older version of the software with software only attack, i.e.: remote
+ code execution.
+ - If the boot loader does not trust the loaded image at all then security
+ counter must have a copy in NV counter area.
+
+ - Another aspect to consider is where the active image is stored
+
+ - Trusted memory: i.e. on-chip flash (eFlash). The threat that a malicious
+ actor can modify the content of trusted memory with HW attack is out of
+ scope for the current implementation. It is assumed that if an active image
+ and related manifest data is stored in trusted memory then the included
+ security counter cannot be compromised.
+ - Untrusted memory: i.e. external (off-chip) storage, where malicious actor
+ can physically access it so it is possible to modify its content, therefore
+ the value of included security counter is unreliable.
+
+If the active image is stored in untrusted storage and it is feasible to modify
+its content (i.e. replace the whole image to an older version including
+corresponding manifest) then the value of security counter must be copied to
+the NV counter area. During software validation the boot loader must compare
+the new image's security counters against the security counter stored in
+non-volatile counters.
+
+If the active image is stored in trusted memory and boot loader trusts in the
+active software then it is not mandatory to store the security counter to
+non-volatile counter area. During software validation the boot loader is
+allowed to compare the new image's security counters against active image's
+security counter.
+
+The evaluation of trusted and untrusted memory must be done per target platform
+during threat modelling.
+
+For the most robust implementation the following principles should be applied:
+
+ - Always use NV counters for storing security counter value if supported by
+ the hardware.
+ - Each software stage must not be able to decrease their corresponding NV
+ counter.
+
+Boot flow with anti-rollback protection
+=======================================
+During software upgrade as part of the image validation process the new and
+active image security counters must be compared. The new image can be accepted
+if its security counter has a greater or equal value than the active image
+security counter. From where to extract the active image security counter it
+can be platform dependent. It might read out directly from active image
+manifest data (only if it is in trusted memory) or the corresponding
+non-volatile counter is read.
+
+If non-volatile counters are used to save security counters then their value
+must be updated:
+
+ - If the boot loader does not support to revert previous images (just
+ overwrites the previously active image with the new one) in case of faulty
+ update then the non-volatile counter can be updated to be equal with the
+ new image security counter after successful authentication of the new image.
+ - If revert is supported then non-volatile counter can be updated just after
+ a test run of the new software when its health check is done. Just in case
+ of successful health check can the counter updated to avoid the prevention
+ of the revert. This might require a secondary restart of the device.
+
+Tool support
+============
+There is a Python script, ``imgtool.py`` which is used to prepare the new image
+for upgrade (add header, sign the image, append TLV section). This script must
+be modified to get an additional command line argument which serves as security
+counter. The security counter must be included in the integrity protected part
+of the TLV section.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/secure_enclave_solution.rst b/docs/technical_references/secure_enclave_solution.rst
new file mode 100644
index 0000000000..ce665ac229
--- /dev/null
+++ b/docs/technical_references/secure_enclave_solution.rst
@@ -0,0 +1,122 @@
+##############################################
+Secure Enclave solution for Trusted Firmware-M
+##############################################
+
+:Author: Mark Horvath
+:Organization: Arm Limited
+:Contact: Mark Horvath
+:Status: Draft
+
+********
+Abstract
+********
+
+This document summarizes the design goals and one possible implementation
+of the TF-M Secure Enclave solution.
+
+************
+Introduction
+************
+
+If a separate subsystem can provide the PSA Root of Trust (RoT) in a system
+then an additional physical separation exists between the most trusted and
+other domains. In such a system at least two subsystems are present, a Secure
+Enclave (SE) whose only task is to provide PSA RoT and an application core
+where any other application specific functionality can be placed. The latter
+core (or cores) are referred as *Host* in this document.
+
+The current design assumes that Host is a v8-m core with security extension.
+
+************
+Requirements
+************
+
+- Secure Enclave shall implement secure boot-flow (start-up first at reset and
+ validate its own and the Host image or images before release Host from reset)
+- Secure Enclave shall provide the PSA RoT services
+- Host shall provide not just the non-secure context but the Application RoT as
+ well
+- It shall be transparent to the (secure or non-secure) applications running on
+ host whether the RoT services are provided by the same subsystem or by a
+ Secure Enclave.
+
+.. Note::
+
+ In comparison, in a Dual Core system the whole secure context is placed on a
+ separate subsystem, while a Secure Enclave only implements the PSA RoT
+ security domain.
+
+***************
+Proposed design
+***************
+
+As the clients and the services are running on different cores only the IPC
+model can be used on both Secure Enclave and Host.
+
+Secure Enclave
+==============
+
+To provide the required functionality it is enough to run the current PSA RoT
+secure partitions on the Secure Enclave, so no need for non-secure context
+there. (It is enough if the Secure Enclave's architecture is v6-m, v7-m or v8-m
+without the security extension.)
+
+Secure Enclave can treat all clients running on Host as non-secure (even the
+services running on Host's secure side). This means that fom Secure Enclave's
+point of view all Host images, Host's RAM and shared memory between Host and
+Secure Enclave if present are treated as non-secure. (Just like in the Dual CPU
+solution.) But the clients need to be distinguished, otherwise some
+functionalities are not working, for example:
+- Protected Storage partition shall run on Host, but the PS area is handled by
+Internal Trusted Storage partition (running on Secure Enclave). ITS partition
+decides whether it should work on PS or ITS assets by checking the client ID.
+- If a secure partition on host creates a crypto key, no other client shall be
+able to destroy it.
+
+Communication
+=============
+
+To communicate between Host and Secure Enclave, the existing mailbox solution
+can be reused as it is.
+
+Host
+====
+
+On Host the current TF-M software architecture can be placed to provide
+non-secure context and Application RoT domain.
+
+One solution to forward a PSA RoT IPC message from a client running on Host to
+the Secure Enclave is to add a proxy partition to the secure side. This PSA
+Proxy partition can provide all the RoT services to the system by forwarding
+the messages over the mailbox solution.
+
+If the new partition's manifest contains all the PSA RoT service IDs SPM will
+deliver all IPC messages there. Then the messages just must be blindly copied
+into the mailbox. PSA proxy can use the non-secure interface of the mailbox,
+but it is placed on the secure side of Host. (From SE's point of view this is
+in fact the non-secure side of the mailbox as whole Host is treated as
+non-secure.)
+
+It is important to verify IOVECs before forwarding them to SE, otherwise a
+malicous actor could use SE to access a memory area otherwise unaccessable. If
+PSA proxy uses the current secure partition interface then this is ensured by
+Host's SPM.
+
+SE treats all clients of Host as non-secure, so all PSA messages shall have a
+negative client ID when pushed into SE's SPM. This is given for the clients on
+the non-secure side of Host, but the secure side clients of Host have positive
+client IDs. The straightforward solution is to translate the positive client
+IDs into a predefined negative range in PSA proxy, and push the translated
+values into the mailbox. Of course this range shall be reserved for this use
+only and no clients on non-secure side of Host shall have client ID from this
+range.
+
+To avoid blocking Host when a message is sent PSA Proxy shall handle the
+service requests in non-blocking mode. And to maximize bandwidth PSA Proxy
+shall be able to push new messages into the mailbox, while others still not
+answered. To achieve these the mailbox interrupts needs to be handled in the
+PSA Proxy partition.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/source_structure.rst b/docs/technical_references/source_structure.rst
new file mode 100644
index 0000000000..b2de0dda20
--- /dev/null
+++ b/docs/technical_references/source_structure.rst
@@ -0,0 +1,165 @@
+###################################
+Trusted Firmware-M Source Structure
+###################################
+
+:Organization: Arm Limited
+:Contact: tf-m@lists.trustedfirmware.org
+
+.. note::
+ Reference the document :doc:`Glossary ` for terms
+ and abbreviations.
+
+************
+Introduction
+************
+TF-M is designed to provide a user-friendly source structure to ease
+integration and service development. This document introduces the source
+structure and its design intention of TF-M.
+
+.. note::
+ - This document goes ahead of the implementation so the existing source
+ structure may be different from the description listed here. It is
+ recommended to refer to this document for ongoing code structure changes.
+ - By getting feedback from the practical implementation, this document is
+ updated continuously before it is detailed enough to be a user guide.
+
+****************
+Source Structure
+****************
+The description of the source structure is broken down into subsections, each
+subsection introduces one detailed folder.
+
+Root Directory
+==============
+This table describes the structure under the root directory with part of
+possible folders. Note that the ``Detailed`` field indicates if the folder is
+described in details here in this document:
+
+============= ==================================== ====================
+Folder name Purpose Detailed
+============= ==================================== ====================
+bl2 The 2nd stage bootloader. No.
+cmake Cmake files. No.
+configs Configuration system files. No.
+docs The documentations. No.
+lib The 3rd party library. No.
+**platform** Platform intermedia files. See `'platform'`_.
+**secure_fw** The secure firmware. See `'secure_fw'`_.
+tools Tools in scripts for building. No.
+============= ==================================== ====================
+
+'platform'
+==========
+The platform sources contain necessary platform sources or intermedia files
+pointing to the sources out of TF-M folder.
+
+========================= =============================================
+Folder name Purpose
+========================= =============================================
+common/\* Common HAL implementation.
+include/\* Platform public headers.
+ Vendor specific folders.
+========================= =============================================
+
+.. note::
+ The ``common`` folder contains the example implementation of the ``HAL`` API
+ bases on common ``system`` (CMSIS e.g.). The platform could reference to
+ sources in the ``common`` folder directly if applicable or apply a
+ customized HAL implementation.
+ A ``system`` can have a standalone folder under ``common``, depends on how
+ 'common' this system is. Each ``platform vendor`` is assigned with one
+ folder for usage. As the content of the ``vendor`` folder comes by the
+ contribution of vendors, the ``vendor`` manages the structure inside it.
+
+'secure_fw'
+===========
+This folder contains components needed by secure firmware, and the exported
+interfaces for application, service development and HAL integration:
+
+================= ===================================== ======================
+Folder name Purpose Detailed
+================= ===================================== ======================
+**include** Public headers of 'secure_fw'. See `'include'`_
+**partitions** Default services and supportings. See `'partitions'`_
+**spm** PSA-FF-M SPM implementation. [1] See `'spm'`_
+================= ===================================== ======================
+
+.. note::
+ 1. A PSA-FF-M complied SPM implementation.
+
+ The headers referenced by other modules are public headers and put under the
+ 'include' folder of the current module. Do not put headers not referenced by
+ other modules in this 'include' folder.
+
+'include'
+---------
+This folder holds headers for client, services and platform integration usage.
+
+=========================== ===================================================
+Folder name Purpose
+=========================== ===================================================
+psa/\* PSA FF Client API.
+=========================== ===================================================
+
+.. note::
+ TFM applies an explicit including policy. Each module's headers are put into
+ a specific folder which follows the pattern '\*/inc', this folder needs to be
+ added into the project's searching path if this project needs to include
+ headers in this folder. The 'inc' in a path indicates the end of
+ including-path. If there are subfolders under folder 'inc', apply a
+ hierarchy including.
+
+'partitions'
+------------
+This folder contains default services implemented as partitions and necessary
+partition runtime utilities provided by TF-M.
+
+================================= =============================================
+Folder name Purpose
+================================= =============================================
+lib/sprt/\* The SPRTL sources and intermedia files. [1]
+lib/sprt/shared\* Sources can be shared by out of SPRTL. [2]
+/\* Files for 'partition_x'.
+/include/\* RoT Service API headers of 'partition_x'. [3]
+/\* Files for 'partition_y'.
+/include/\* RoT Service API headers of 'partition_y'. [3]
+================================= =============================================
+
+.. note::
+ 1. The SPRTL sources and intermediate files. SPRTL contains sources from
+ other folders, such as necessary RoT Service API implementation from
+ 'partitions' folder.
+ 2. The sources here can be referenced by the building system out of SPRTL.
+ Generally, they are runtime and PSA APIs.
+ 3. Here takes 'partition_x' and 'partition_y' as an example, and showcases
+ a detailed structure of them. The `` contains the RoT Service
+ API for client calls. The folder name of this client-orient folder is
+ decided by the service developer.
+
+'spm'
+-----
+The SPM is the core component to provide a mechanism for providing secure
+services.
+
+=================================== ===========================================
+Folder name Purpose
+=================================== ===========================================
+include/\* SPM public headers.
+ffm/\* SPM logic complies with PSA-FF-M and
+ its necessary supporting functionalities,
+ such as the runtime API and the thread
+ operation, etc.
+cmsis_psa/\* CMSIS implementation for PSA-FF-M SPM. [1]
+cmsis_func/\* The library model implementation. [2]
+\* Implementation sources.
+=================================== ===========================================
+
+.. note::
+ 1. CMSIS is the first implementation system.
+ 2. This folder contains a function call based secure firmware implementation.
+ This model is the prototype model which would be updated after the PSA
+ model. Create a standalone folder to hold it.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/symmetric_initial_attest.rst b/docs/technical_references/symmetric_initial_attest.rst
new file mode 100644
index 0000000000..b53ab3c87d
--- /dev/null
+++ b/docs/technical_references/symmetric_initial_attest.rst
@@ -0,0 +1,601 @@
+#################################################
+Symmetric key algorithm based Initial Attestation
+#################################################
+
+:Authors: David Hu
+:Organization: Arm Limited
+:Contact: david.hu@arm.com
+
+************
+Introduction
+************
+
+This document proposes a design of symmetric key algorithm based Initial
+Attestation in TF-M.
+
+Symmetric key algorithm based Initial Attestation
+(*symmetric Initial Attestation* for short) signs and verifies Initial
+Attestation Token (IAT) with a symmetric cryptography signature scheme, such as
+HMAC.
+It can reduce TF-M binary size and memory footprint on ultra-constrained devices
+without integrating asymmetric ciphers.
+
+This proposal follows PSA Attestation API document [1]_.
+
+.. note ::
+
+ As pointed out by PSA Attestation API [1]_, the use cases of Initial
+ Attestation based on symmetric key algorithms can be limited due to
+ the associated infrastructure costs for key management and operational
+ complexities. It may also restrict the ability to interoperate with
+ scenarios that involve third parties.
+
+***************
+Design overview
+***************
+
+The symmetric Initial Attestation follows the existing IAT generation sequence
+for Initial Attestation based on asymmetric key algorithm
+(*asymmetric Initial Attestation* for short).
+
+As Profile Small design [2]_ requests, a configuration flag
+``SYMMETRIC_INITIAL_ATTESTATION`` selects symmetric initial attestation during
+build.
+
+The top-level design is shown in :ref:`overall-diagram-figure` below.
+
+.. _overall-diagram-figure:
+
+.. figure:: media/symmetric_initial_attest/overall_diagram.png
+ :align: center
+
+ Overall design diagram
+
+Symmetric Initial Attestation adds its own implementations of some steps in IAT
+generation in Initial Attestation secure service. More details are covered in
+`IAT generation in Initial Attestation secure service`_.
+
+The interfaces and procedures of Initial Attestation secure service are not
+affected. Refer to Initial Attestation Service Integration Guide [3]_ for
+details of the implementation of Initial Attestation secure service.
+
+Symmetric Initial Attestation invokes ``t_cose`` library to build up
+``COSE_Mac0`` structure.
+``COSE_Mac0`` support is added to ``t_cose`` library in TF-M since official
+``t_cose`` hasn't supported ``COSE_Mac0`` yet. The design of ``COSE_Mac0``
+support is covered in `COSE_Mac0 support in t_cose`_.
+
+.. note ::
+
+ The ``COSE_Mac0`` implementation in this proposal is a prototype only for
+ Proof of Concept so far. It may be replaced after ``t_cose`` officially
+ supports ``COSE_Mac0`` message.
+
+Several HAL APIs are defined to fetch platform specific assets required by
+Symmetric Initial Attestation. For example, ``tfm_plat_get_symmetric_iak()``
+fetches symmetric Initial Attestation Key (IAK). Those HAL APIs are summarized
+in `HAL APIs`_.
+
+Decoding and verification of symmetric Initial Attestation is also included in
+this proposal for regression test.
+The test suites and IAT decoding are discussed in `TF-M Test suite`_.
+
+``QCBOR`` library and Crypto service are also invoked. But this proposal doesn't
+require any modification to either ``QCBOR`` or Crypto service. Therefore,
+descriptions of ``QCBOR`` and Crypto service are skipped in this document.
+
+****************************************************
+IAT generation in Initial Attestation secure service
+****************************************************
+
+The sequence of IAT generation of symmetric Initial Attestation is shown in
+:ref:`ia-service-figure` below.
+
+.. _ia-service-figure:
+
+.. figure:: media/symmetric_initial_attest/ia_service_flow.png
+ :align: center
+
+ Symmetric IAT generation flow in Initial Attestation secure service
+
+In Initial Attestation secure service, symmetric Initial Attestation implements
+the following steps in ``attest_create_token()``, which are different from those
+of asymmetric Initial Attestation.
+
+ - Fetch and register IAK
+ - ``attest_token_start()``
+ - Instance ID claims
+ - ``attest_token_finish()``
+
+If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, symmetric Initial Attestation
+dedicated implementations of those steps are included in build.
+Otherwise, asymmetric Initial Attestation dedicated implementations are included
+instead.
+
+Symmetric Initial Attestation implementation resides a new file
+``attest_symmetric_key.c`` to handle symmetric IAK and Instance ID related
+operations.
+Symmetric Initial Attestation dedicated ``attest_token_start()`` and
+``attest_token_finish()`` are added in ``attestation_token.c``.
+
+The details are covered in following sections.
+
+Register symmetric IAK
+======================
+
+Symmetric Initial Attestation dedicated ``attest_symmetric_key.c`` implements 4
+major functions. The functions are listed in the table below.
+
+.. table:: Functions in ``attest_symmetric_key.c``
+ :widths: auto
+ :align: center
+
+ +-------------------------------------------------+----------------------------------------------------+
+ | Functions | Descriptions |
+ +=================================================+====================================================+
+ | ``attest_register_initial_attestation_key()`` | Fetches device symmetric IAK, imports it into |
+ | | Crypto service and get the handle. |
+ | | The handle will be used to compute the |
+ | | authentication tag of IAT. |
+ | | Invokes HAL API ``tfm_plat_get_symmetric_iak()`` |
+ | | to fetch symmetric IAK from device. |
+ | | |
+ | | Refer to `HAL APIs`_ for more details. |
+ +-------------------------------------------------+----------------------------------------------------+
+ | ``attest_unregister_initial_attestation_key()`` | Destroys the symmetric IAK handle after IAT |
+ | | generation completes. |
+ +-------------------------------------------------+----------------------------------------------------+
+ | ``attest_get_signing_key_handle()`` | Return the IAK handle registered in |
+ | | ``attest_register_initial_attestation_key()``. |
+ +-------------------------------------------------+----------------------------------------------------+
+ | ``attest_get_instance_id()`` | Return the Instance ID value calculated in |
+ | | ``attest_register_initial_attestation_key()``. |
+ | | |
+ | | Refer to `Instance ID claim`_ for more details. |
+ +-------------------------------------------------+----------------------------------------------------+
+
+``attest_register_initial_attestation_key()`` and
+``attest_unregister_initial_attestation_key()`` share the same API declarations
+with asymmetric Initial Attestation.
+
+``attest_get_signing_key_handle()`` and ``attest_get_instance_id()`` are defined
+by symmetric Initial Attestation but can be shared with asymmetric Initial
+Attestation later.
+
+.. note ::
+
+ Only symmetric IAK for HMAC algorithm is allowed so far.
+
+Instance ID calculation
+-----------------------
+
+In symmetric Initial Attestation, Instance ID is also calculated in
+``attest_register_initial_attestation_key()``, after IAK handle is registered.
+It can protect critical symmetric IAK from being frequently fetched, which
+increases the risk of asset disclosure.
+
+The Instance ID value is the output of hashing symmetric IAK raw data *twice*,
+as requested in PSA Attestation API [1]_. HMAC-SHA256 may be hard-coded as the
+hash algorithm of Instance ID calculation.
+
+.. note ::
+
+ According to RFC2104 [4]_, if a HMAC key is longer than the HMAC block size,
+ the key will be first hashed. The hash output is used as the key in HMAC
+ computation.
+
+ In current design, HMAC is used to calculate the authentication tag of
+ ``COSE_Mac0``. Assume that symmetric IAK is longer than HMAC block size
+ (HMAC-SHA256 by default), the Instance ID is actually the HMAC key for
+ ``COSE_Mac0`` authentication tag generation, if Instance ID value is the
+ output of hashing IAK only *once*.
+ Therefore, attackers may request an valid IAT from device and fake malicious
+ ones by using Instance ID to calculate valid authentication tags, to cheat
+ others.
+
+ As a result, symmetric IAK raw data should be hashed *twice* to generate the
+ Instance ID value.
+
+The Instance ID calculation result is stored in a static buffer.
+Token generation process can call ``attest_get_instance_id()`` to
+fetch the data from that static buffer.
+
+attest_token_start()
+====================
+
+Symmetric Initial Attestation dedicated ``attest_token_start()`` initializes the
+``COSE_Mac0`` signing context and builds up the ``COSE_Mac0`` Header.
+
+The workflow inside ``attest_token_start()`` is shown in
+:ref:`attest-token-start-figure` below.
+
+.. _attest-token-start-figure:
+
+.. figure:: media/symmetric_initial_attest/attest_token_start.png
+ :align: center
+
+ Workflow in symmetric Initial Attestation ``attest_token_start()``
+
+Descriptions of each step are listed below:
+
+#. ``t_cose_mac0_sign_init()`` is invoked to initialize ``COSE_Mac0`` signing
+ context in ``t_cose``.
+
+#. The symmetric IAK handle is returned by ``attest_get_signing_key_handle()``.
+ See the details in `Register symmetric IAK`_.
+
+#. The symmetric IAK handle is set into ``COSE_Mac0`` signing context via
+ ``t_cose_mac0_set_signing_key()``.
+
+#. Initialize ``QCBOR`` encoder.
+
+#. The header parameters are encoded into ``COSE_Mac0`` structure in
+ ``t_cose_mac0_encode_parameters()``.
+
+#. ``QCBOREncode_OpenMap()`` prepares for encoding the ``COSE_Mac0`` payload,
+ which is filled with IAT claims.
+
+All the ``COSE_Mac0`` functionalities in ``t_cose`` are covered in
+`COSE_Mac0 support in t_cose`_.
+
+Instance ID claim
+=================
+
+Symmetric Initial Attestation also implements Instance ID claims in
+``attest_add_instance_id_claim()``.
+
+The Instance ID value is fetched via ``attest_get_instance_id()``.
+The value has already been calculated during symmetric IAK registration. See
+`Instance ID calculation`_ for details.
+
+The other steps are the same as those in asymmetric Initial Attestation
+implementation. The UEID type byte is set to 0x01.
+
+attest_token_finish()
+=====================
+
+Symmetric Initial Attestation dedicated ``attest_token_finish()`` calls
+``t_cose_mac0_encode_tag()`` to calculate and encode the authentication tag of
+``COSE_Mac0`` structure.
+
+The whole COSE and CBOR encoding are completed in ``attest_token_finish()``.
+
+The simplified flow in ``attest_token_finish()`` is shown in
+:ref:`attest-token-finish-figure` below.
+
+.. _attest-token-finish-figure:
+
+.. figure:: media/symmetric_initial_attest/attest_token_finish.png
+ :align: center
+
+ Workflow in symmetric Initial Attestation ``attest_token_finish()``
+
+***************************
+COSE_Mac0 support in t_cose
+***************************
+
+``COSE_Mac0`` supports in ``t_cose`` in TF-M include the following major
+functionalities:
+
+ - Encoding ``COSE_Mac0`` structure
+ - Decoding and verifying ``COSE_Mac0`` structure
+ - HMAC computation to generate and verify authentication tag
+ - Short-circuit tagging for test mode
+
+According to RFC8152 [5]_, ``COSE_Mac0`` and ``COSE_Sign1`` have similar
+structures. Therefore, the prototype follows ``COSE_Sign1`` implementation to
+build up ``COSE_Mac0`` file structure and implement ``COSE_Mac0`` encoding and
+decoding.
+
+Although ``COSE_Mac0`` can share lots of data types, APIs and encoding/decoding
+steps with ``COSE_Sign1`` in implementation, this prototype separates
+``COSE_Mac0`` implementation from ``COSE_Sign1``. ``COSE_Mac0`` owns its
+dedicated signing/verification contexts, APIs and encoding/decoding process.
+The purposes of separating ``COSE_Mac0`` and ``COSE_Sign1`` are listed below
+
+- It can keep changes to ``COSE_Sign1`` as small as possible and avoid conflicts
+ with development in ``COSE_Sign1```. It can decrease conflicts if ``t_cose``
+ in TF-M is synchronized with original ``t_cose`` repository later.
+- ``COSE_Mac0`` and ``COSE_Sign1`` are exclusive in TF-M use cases.
+ It cannot decrease TF-M memory footprint by extracting the common components
+ shared by ``COSE_Mac0`` and ``COSE_Sign1`` but can make the design
+ over-complicated.
+
+.. note ::
+
+ Only HMAC is supported in current ``COSE_Mac0`` prototype.
+
+File structure
+==============
+
+New files are added to implement the functionalities listed above. The structure
+of files is shown in the table below.
+
+.. table:: New files in ``t_cose``
+ :widths: auto
+ :align: center
+
+ +---------------------+--------------------------------+----------------------------------------------+
+ | Directory | Files | Descriptions |
+ +=====================+================================+==============================================+
+ | ``src`` | ``t_cose_mac0_sign.c`` | Encode ``COSE_Mac0`` structure |
+ | +--------------------------------+----------------------------------------------+
+ | | ``t_cose_mac0_verify.c`` | Decode and verify ``COSE_Mac0`` structure. |
+ +---------------------+--------------------------------+----------------------------------------------+
+ | ``inc`` | ``t_cose_mac0_sign.h`` | Data type definitions and function |
+ | | | declarations of encoding and signing |
+ | | | ``COSE_Mac0`` message. |
+ | +--------------------------------+----------------------------------------------+
+ | | ``t_cose_mac0_verify.h`` | Data type definitions and function |
+ | | | declarations of verifying ``COSE_Mac0`` |
+ | | | message. |
+ +---------------------+--------------------------------+----------------------------------------------+
+
+Other ``t_cose`` files may also be changed to add ``COSE_Mac0`` associated data
+types and function declarations.
+
+HMAC operations are added in ``crypto_adapters/t_cose_psa_crypto.c``.
+Preprocessor flags are added to select corresponding crypto for COSE message
+signing and verification.
+
+ - ``T_COSE_ENABLE_SIGN1`` selects ECDSA and Hash operations for
+ ``COSE_Sign1``.
+ - ``T_COSE_ENABLE_MAC0`` selects HMAC operations for ``COSE_Mac0``.
+
+Encoding COSE_Mac0
+==================
+
+Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` encoding exports similar
+functions to Initial Attestation secure service.
+The major functions are listed below.
+
+Initialize signing context
+--------------------------
+
+``t_cose_mac0_sign_init()`` initializes ``COSE_Mac0`` signing context and
+configures option flags and algorithm used in signing.
+
+.. code-block:: c
+
+ static void
+ t_cose_mac0_sign_init(struct t_cose_mac0_sign_ctx *me,
+ int32_t option_flags,
+ int32_t cose_algorithm_id);
+
+The ``COSE_Mac0`` signing context is defined as
+
+.. code-block:: c
+
+ struct t_cose_mac0_sign_ctx {
+ /* Private data structure */
+ uint8_t protected_parameters_buffer[
+ T_COSE_MAC0_MAX_SIZE_PROTECTED_PARAMETERS];
+ struct q_useful_buf_c protected_parameters; /* The encoded protected parameters */
+ int32_t cose_algorithm_id;
+ struct t_cose_key signing_key;
+ int32_t option_flags;
+ struct q_useful_buf_c kid;
+ ...
+ };
+
+Set signing key
+---------------
+
+``t_cose_mac0_set_signing_key()`` sets the key used in ``COSE_Mac0`` signing.
+Optional ``kid``, as a key identifer, will be encoded into ``COSE_Mac0`` Header
+unprotected bucket.
+
+.. code-block:: c
+
+ static void
+ t_cose_mac0_set_signing_key(struct t_cose_mac0_sign_ctx *me,
+ struct t_cose_key signing_key,
+ struct q_useful_buf_c kid);
+
+Encode Header parameters
+------------------------
+
+``t_cose_mac0_encode_parameters()`` encodes the ``COSE_Mac0`` Header parameters
+and outputs the encoded context to ``cbor_encode_ctx``.
+
+.. code-block:: c
+
+ enum t_cose_err_t
+ t_cose_mac0_encode_parameters(struct t_cose_mac0_sign_ctx *context,
+ QCBOREncodeContext *cbor_encode_ctx);
+
+Calculate and add authentication tag
+------------------------------------
+
+``t_cose_mac0_encode_tag()`` calculates the authentication tag and finishes the
+``COSE_Mac0`` message.
+
+.. code-block:: c
+
+ enum t_cose_err_t
+ t_cose_mac0_encode_tag(struct t_cose_mac0_sign_ctx *context,
+ QCBOREncodeContext *cbor_encode_ctx);
+
+Decoding COSE_Mac0
+==================
+
+Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` decoding exports similar
+functions to test suite of Initial Attestation.
+The major functions are listed below.
+
+Initialize verification context
+-------------------------------
+
+``t_cose_mac0_verify_init()`` initializes ``COSE_Mac0`` verification context and
+configures option flags in verification.
+
+.. code-block:: c
+
+ static void
+ t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context,
+ int32_t option_flags);
+
+The ``COSE_Mac0`` verification context is defined as
+
+.. code-block:: c
+
+ struct t_cose_mac0_verify_ctx {
+ /* Private data structure */
+ struct t_cose_key verification_key;
+ int32_t option_flags;
+ };
+
+Set verification key
+--------------------
+
+``t_cose_mac0_set_verify_key()`` sets the key for verifying ``COSE_Mac0``
+authentication tag.
+
+.. code-block:: c
+
+ static void
+ t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context,
+ struct t_cose_key verify_key);
+
+Decode and verify COSE_Mac0
+---------------------------
+
+``t_cose_mac0_verify()`` decodes the ``COSE_Mac0`` structure and verifies the
+authentication tag.
+
+.. code-block:: c
+
+ enum t_cose_err_t
+ t_cose_mac0_verify(struct t_cose_mac0_verify_ctx *context,
+ struct q_useful_buf_c cose_mac0,
+ struct q_useful_buf_c *payload,
+ struct t_cose_parameters *parameters);
+
+Short-circuit tagging
+=====================
+
+If ``T_COSE_OPT_SHORT_CIRCUIT_TAG`` option is enabled, ``COSE_Mac0`` encoding
+will hash the ``COSE_Mac0`` content and add the hash output as an authentication
+tag. It is useful when critical symmetric IAK is unavailable or cannot be
+accessed, perhaps because it has not been provisioned or configured for the
+particular device. It is only for test and must not be used in actual use case.
+The ``kid`` parameter will either be skipped in ``COSE_Mac0`` Header.
+
+If ``T_COSE_OPT_ALLOW_SHORT_CIRCUIT`` option is enabled, ``COSE_Mac0`` decoding
+will only verify the hash output, without requiring symmetric key for
+authentication tag verification.
+
+***************
+TF-M Test suite
+***************
+
+Symmetric Initial Attestation adds dedicated non-secure and secure test suites.
+The test suites also follow asymmetric Initial Attestation test suites
+implementation but optimize the memory footprint.
+Symmetric Initial Attestation non-secure and secure test suites request Initial
+Attestation secure service to generate IATs. After IATs are generated
+successfully, test suites decode IATs and parse the claims.
+Secure test suite also verifies the authentication tag in ``COSE_Mac0``
+structure.
+
+Symmetric Initial Attestation implements its dedicated
+``attest_token_decode_validate_token()`` in ``attest_symmetric_iat_decoded.c``
+to perform IAT decoding required by test suites.
+If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected,
+``attest_symmetric_iat_decoded.c`` is included in build.
+Otherwise, asymmetric Initial Attestation dedicated implementations are included
+instead.
+
+The workflow of symmetric Initial Attestation dedicated
+``attest_token_decode_validate_token()`` is shown below.
+
+.. _iat-decode-figure:
+
+.. figure:: media/symmetric_initial_attest/iat_decode.png
+ :align: center
+
+ Workflow in symmetric Initial Attestation ``attest_token_decode_validate_token()``
+
+If the decoding is required from secure test suite,
+``attest_token_decode_validate_token()`` will fetch symmetric IAK to verify the
+authentication tag in ``COSE_Mac0`` structure.
+If the decoding is required from non-secure test suite,
+``attest_token_decode_validate_token()`` will decode ``COSE_Mac0`` only by
+setting ``T_COSE_OPT_DECODE_ONLY`` option flag. Non-secure must not access the
+symmetric IAK.
+
+********
+HAL APIs
+********
+
+HAL APIs are summarized below.
+
+Fetch device symmetric IAK
+==========================
+
+``tfm_plat_get_symmetric_iak()`` fetches device symmetric IAK.
+
+ .. code-block:: c
+
+ enum tfm_plat_err_t tfm_plat_get_symmetric_iak(uint8_t *key_buf,
+ size_t buf_len,
+ size_t *key_len,
+ psa_algorithm_t *key_alg);
+
+ **Parameters:**
+
+ +-------------+-----------------------------------------------------------+
+ | ``key_buf`` | Buffer to store the symmetric IAK. |
+ +-------------+-----------------------------------------------------------+
+ | ``buf_len`` | The length of ``key_buf``. |
+ +-------------+-----------------------------------------------------------+
+ | ``key_len`` | The length of the symmetric IAK. |
+ +-------------+-----------------------------------------------------------+
+ | ``key_alg`` | The key algorithm. Only HMAC SHA-256 is supported so far. |
+ +-------------+-----------------------------------------------------------+
+
+It returns error code specified in ``enum tfm_plat_err_t``.
+
+Get symmetric IAK key identifier
+================================
+
+``attest_plat_get_symmetric_iak_id()`` gets the key identifier of the symmetric
+IAK as the ``kid`` parameter in COSE Header.
+
+Optional if device doesn't install a key identifier for symmetric IAK.
+
+ .. code-block:: c
+
+ enum tfm_plat_err_t attest_plat_get_symmetric_iak_id(void *kid_buf,
+ size_t buf_len,
+ size_t *kid_len);
+
+ **Parameters:**
+
+ +-------------+-------------------------------------+
+ | ``kid_buf`` | Buffer to store the IAK identifier. |
+ +-------------+-------------------------------------+
+ | ``buf_len`` | The length of ``kid_buf``. |
+ +-------------+-------------------------------------+
+ | ``kid_len`` | The length of the IAK identifier. |
+ +-------------+-------------------------------------+
+
+It returns error code specified in ``enum tfm_plat_err_t``.
+
+*********
+Reference
+*********
+
+.. [1] `PSA Attestation API 1.0 (ARM IHI 0085) `_
+
+.. [2] :doc:`Trusted Firmware-M Profile Small Design `
+
+.. [3] :doc:`Initial Attestation Service Integration Guide `
+
+.. [4] `HMAC: Keyed-Hashing for Message Authentication `_
+
+.. [5] `CBOR Object Signing and Encryption (COSE) `_
+
+----------------
+
+*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.*
diff --git a/docs/technical_references/tfm_code_generation_with_jinja2.rst b/docs/technical_references/tfm_code_generation_with_jinja2.rst
new file mode 100644
index 0000000000..2e730238db
--- /dev/null
+++ b/docs/technical_references/tfm_code_generation_with_jinja2.rst
@@ -0,0 +1,77 @@
+###########################
+Code Generation With Jinja2
+###########################
+
+:Author: Mate Toth-Pal
+:Organization: Arm Limited
+:Contact: Mate Toth-Pal
+:Status: Accepted
+
+***************************************
+Generating files from templates in TF-M
+***************************************
+
+Some of the files in TF-M are generated from template files. The files to be
+generated are listed in ``tools/tfm_generated_file_list.yaml``. For each
+generated file ``/`` the template file is
+``/.template``. The templates are populated with
+partition information from the partition manifests. The manifests to be used for
+the generation are listed in ``tools/tfm_manifest_list.yaml``.
+
+****************************************
+Custom generator script - Current method
+****************************************
+
+``tools/tfm_parse_manifest_list.py`` Python script is used to generate files
+from the templates. This script calls the ``tools/generate_from_template.py`` to
+parse the template files, and uses ``tools/keyword_substitution.py`` to
+substitute the keychains with actual values from the manifest files.
+
+*************************************
+Use Jinja2 template engine - proposal
+*************************************
+
+The proposal is to eliminate the template parser and substituter scripts, and
+call the Jinja2 template engine library from
+``tools/tfm_parse_manifest_list.py`` to do the substitution.
+
+More information on jinja2: http://jinja.pocoo.org/
+
+Changes needed:
+===============
+
+- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2
+ library instead of the custom scripts. The data structure required by the
+ library is very similar to the one required by the current scripts.
+- template files needs to be rewritten to the Jinja syntax: The control
+ characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be
+ added to iterate over the substitutions.
+
+Improvements over the current solution
+======================================
+
+- Compatible with Python 2.7 and Python 3, while current solution only supports
+ Python 2.7
+- More advanced functionality: direct control over the list of items for a
+ keychain, meta information on that list (like length)
+- Well documented (see website)
+- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a
+ well established software in contrast with the current proprietary solution.
+
+*******
+Example
+*******
+
+Below code snippet enumerates services in Secure Partitions:
+
+.. code-block::
+
+ {% for partition in partitions %}
+ {% if partition.manifest.services %}
+ {% for service in partition.manifest.services %}
+ {do something for the service}
+ {% endfor %}
+ {% endif %}
+ {% endfor %}
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_cooperative_scheduling_rules.rst b/docs/technical_references/tfm_cooperative_scheduling_rules.rst
new file mode 100644
index 0000000000..b1c4e768b3
--- /dev/null
+++ b/docs/technical_references/tfm_cooperative_scheduling_rules.rst
@@ -0,0 +1,211 @@
+############################
+Cooperative Scheduling Rules
+############################
+
+:Author: Ashutosh Singh
+:Organization: Arm Limited
+:Contact: Ashutosh Singh
+:Status: Accepted
+
+TF-M Scheduler - Rules
+======================
+
+On ArmV8-M CPUs, NSPE and SPE share the same physical processing element(PE). A
+TF-M enabled system need to be able to handle asynchronous events (interrupts)
+regardless of current security state of the PE, and that may lead to scheduling
+decisions. This introduces significant complexity into TF-M. To keep the
+integrity of (NSPE and SPE) schedulers and call paths between NSPE and SPE,
+following set of rules are imposed on the TF-M scheduler design.
+
+Objectives and Requirements
+===========================
+
+1. Decoupling of scheduling decisions between NSPE and SPE
+2. Efficient interrupt handling by SPE as well as NSPE
+3. Reduce critical sections on the secure side to not block interrupts
+ unnecessarily
+4. Scalability to allow simplification/reduction of overheads to scale down the
+ design for constrained devices
+5. Reduce impact on NSPE software design
+
+ a. NSPE interrupt handling implementation should be independent
+ b. Impact on the NSPE scheduler should be minimal
+ c. No assumptions should be made about NSPE's scheduling capabilities
+
+Scheduler Rules for context switching between SPE and NSPE
+==========================================================
+
+To allow coherent cooperative scheduling, following set of rules are imposed on
+security state changes.
+The switching between SPE and NSPE can be triggered in multiple ways.
+
+`Involuntary security state switch`; when the software has no control over the
+switch:
+
+- A NSPE interrupt take control into NSPE from SPE
+- A SPE interrupt takes control into SPE from NSPE
+
+`Voluntary security state switch`; when software programmatically makes the
+switch:
+
+- A NSPE exception handler returns from NSPE to pre-empted SPE context
+- A SPE exception handler returns from SPE to pre-empted NSPE context
+- NSPE makes a function call into SPE
+- SPE returns a call from NSPE
+- SPE makes a function call into NSPE (not covered in current design)
+- NSPE returns a call from SPE (not covered in current design)
+
+In order to maintain the call stack integrity across NSPE and SPE, following
+rules are imposed on all security state switches.
+
+Rules for NSPE Exception handling
+---------------------------------
+
+1. **The NSPE exception handler is allowed to trigger a NSPE context switch**
+ **(regardless of security state of the preempted context.**
+
+This is expected behaviour of any (RT)OS.
+
+2. **The NSPE scheduler must eventually 'restore' the preempted (by**
+ **exception) context.**
+
+This is expected behaviour of any (RT)OS.
+
+3. **If NSPE exception results in a NSPE context switch, SPM must be informed**
+ **of the scheduling decision; this must be done BEFORE the execution of**
+ **newly scheduled-in context.**
+
+This is to ensures integrity of the call stack when SPE is ready to return a
+previous function call from NSPE.
+
+Rules for SPE Exception handling
+--------------------------------
+
+1. **All of the SPE interrupts must have higher priority than NSPE interrupts**
+
+This is rule is primarily for simplifying the SPM design.
+
+2. **The SPE interrupt handler is allowed to trigger a SPE context switch**
+ **(regardless of security state of the pre-empted context)**
+
+If the SPE context targeted by the interrupt is not same as current SPE context,
+the SPM may choose to switch the current running SPE context based on priority.
+
+3. **SPE scheduler must treat pre-empted context as one of the SPE contexts**
+
+ a. If the pre-empted SPE context is SP1, the TCB for SP1 should be used for
+ saving the context. i.e. the context of SP1 should be saved before
+ scheduling anything other secure partition.
+ b. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is
+ pre-empted by SPE exception (before NSPE scheduling decision is communicated
+ back to SPM) -- SP1 TCB must be used for saving the context
+ In this case SPM is not yet aware of the NSPE context switch, from SPM's
+ standpoint SP1 is still executing, so SPM assumes that the preempted context
+ is SP1.
+ c. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is
+ pre-empted by SPE exception `after` NSPE scheduling decision is
+ communicated back to SPM) - a TCB dedicated to NSPE should be used for
+ saving the context.
+
+ When NSPE scheduler communicates the scheduling decision to SPM, SPM must save
+ the SP1 context, if a SPE interrupt preempts the currently running NSPE context,
+ SPM should save the context to a dedicated NSPE TCB.
+
+ d. The SPE scheduler must eventually 'restore' the pre-empted context.
+ This is an expected behaviour of any scheduler.
+
+4. **All of the interrupts belonging to a partition must have same priority.**
+
+This serializes ISR execution targeted for same partition.
+
+5. **In case of nested interrupts, all of the ISRs must run to finish before**
+ **any service code is allowed to run**
+
+This is an expected behaviour of any scheduler.
+
+6. **If the previously preempted context was a NSPE ISR context, SPE ISR**
+ **handler must return to preempted NSPE context.**
+
+This is an expected behaviour of any scheduler to return to preempted context.
+
+Rules for NSPE to SPM function call (and NSPE scheduler)
+--------------------------------------------------------
+
+1. Current NSPE context must have been communicated to SPM, otherwise SPM cannot
+ guarantee NSPE function calling stack integrity.
+
+Rules for Function Return from SPE to NSPE with result
+------------------------------------------------------
+
+1. **The result available on SPE side are for currently active NSPE context.**
+
+To maintain call stack integrity, if SPE is ready to return to NSPE, it can do
+function return only if the SPE return path corresponds to currently active NSPE
+context.
+
+2. **Last entry into secure world happened programmatically (Voluntary**
+ **security state switch into SPE)**
+
+i.e. control is voluntarily given back by NSPE, either through a function call,
+or a context restore via 'return to SPE from NSPE'. As opposed to a SPE
+interrupt bringing back the execution into SPE.
+
+3. **The current NSPE call stack has not already been returned with SPM_IDLE.**
+
+This rule applies if following optional feature is enabled.
+
+Rules for Return from SPE to NSPE with SPM_IDLE
+-----------------------------------------------
+
+This is optional part of the design as it introduces significant complexity on
+both sides of the security boundary.
+It allows yielding of the CPU to NSPE when SPE has not CPU execution to do but
+it has not yet finished the previous request(s) from NSPE; i.e. SPE is waiting
+on arrival of a SPE interrupt.
+
+1. **Last entry into secure world happens programmatically (Voluntary**
+ **security context switch into SPE)**
+
+i.e. control is voluntarily given back by NSPE, either through a function call,
+or a context restore via 'return to SPE from NSPE'. As opposed to a SPE
+interrupt bringing back the execution into SPE.
+
+2. **The result for the currently active NSPE entity is not yet available,**
+ **the called service is waiting (on interrupt/event).**
+
+SPE request corresponding to currently active NSPE caller is not yet completed
+and is waiting on an ISR.
+
+3. **The current NSPE call stack has not already been returned with SPM_IDLE.**
+
+Rules for NSPE pend irq based return from SPE to NSPE
+-----------------------------------------------------
+
+This is optional part of the design as it introduces significant complexity on
+both sides. This works in conjunction with [Rules for Return from SPE to NSPE
+with SPM_IDLE](#rules-for-return-from-spe-to-nspe-with-spm_idle).
+In this scenario, when SPE is ready with result for a previous call from NSPE,
+it raises a pended IRQ to NSPE instead of returning the function call path.
+
+1. **The SPE has finished a NSPE request.**
+
+2. **The corresponding NSPE context has already been returned with SPM_IDLE.**
+
+Rules for ISR pre-emption
+-------------------------
+
+1. **A higher priority NSPE interrupt is allowed to preempt a lower priority**
+ **NSPE ISR**
+
+2. **A higher priority SPE interrupt is allowed to preempt a lower priority**
+ **SPE ISR**
+
+3. **A SPE interrupt is allowed to preempt NSPE ISR**
+
+4. **A NSPE interrupt is not allowed to preempt SPE ISR**
+
+5. **All interrupts belonging to a service must have same priority**
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_crypto_design.rst b/docs/technical_references/tfm_crypto_design.rst
new file mode 100644
index 0000000000..e2785a5dfa
--- /dev/null
+++ b/docs/technical_references/tfm_crypto_design.rst
@@ -0,0 +1,198 @@
+Crypto Service design
+=====================
+
+:Author: Antonio de Angelis
+:Organization: Arm Limited
+:Contact: Antonio de Angelis
+:Status: Accepted
+
+.. contents:: Table of Contents
+
+Abstract
+--------
+
+This document describes the design of the TF-M Cryptographic Secure Service
+(in short, TF-M Crypto service).
+
+Introduction
+------------
+
+The TF-M Crypto service provides an implementation of the PSA Crypto API
+in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which
+is a reference implementation of the PSA Crypto API. For more details on
+the PSA Crypto API or the Mbed Crypto implementation, please refer
+directly to the ``mbed-crypto`` GitHub repository [1]_ .
+
+The service can be used by other services running in the SPE, or by
+applications running in the NSPE, to provide cryptographic
+functionalities.
+
+Components
+----------
+
+The TF-M Crypto service is implemented by a number of different software
+components, which are listed below:
+
+.. table:: Components table
+ :widths: auto
+
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | **Component name** | **Description** | **Location** |
+ +=============================+===============================================================+======================================================================+
+ | SPE client API interface | This module exports the client API of PSA Crypto to the other | ``./secure_fw/partitions/crypto/tfm_crypto_secure_api.c`` |
+ | | services available in TF-M. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | NSPE client API interface | This module exports the client API of PSA Crypto to the NSPE | ``./interface/src/tfm_crypto_api.c`` |
+ | | (i.e. to the applications). | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, |
+ | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` |
+ | | during TF-M boot and provides the infrastructure to service | |
+ | | requests when TF-M is built for IPC mode. | |
+ | | Due to the fact that the functions available in the Service | |
+ | | modules use the Uniform Signature prototype [2]_ , the | |
+ | | dispatching mechanism of IPC requests is based on a look up | |
+ | | table of function pointers. | |
+ | | This design allows for better scalability and support of a | |
+ | | higher number of Secure functions with minimal overhead and | |
+ | | duplication of code. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` |
+ | | operations in the Secure world. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Service modules | These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key,| ``./secure_fw/partitions/crypto/crypto_aead.c`` |
+ | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/partitions/crypto/crypto_asymmetric.c`` |
+ | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/partitions/crypto/crypto_cipher.c`` |
+ | | They provide parameter sanitation and context retrieval for | ``./secure_fw/partitions/crypto/crypto_key_derivation.c`` |
+ | | multipart operations, and dispatching to the corresponding | ``./secure_fw/partitions/crypto/crypto_hash.c`` |
+ | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/partitions/crypto/crypto_key.c`` |
+ | | functionality. | ``./secure_fw/partitions/crypto/crypto_mac.c`` |
+ | | All the functions in the Service modules are based on the | |
+ | | Uniform Signature prototype [2]_ . | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/crypto/manifest.yaml`` |
+ | | for both library mode and IPC mode. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/partitions/crypto/CMakeLists.inc`` |
+ | | build the service as part of the Secure FW build. The service | ``./secure_fw/partitions/crypto/CMakeLists.txt`` |
+ | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` |
+ | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/partitions/crypto/tfm_crypto_api.h`` |
+ | | library as part of the Secure FW build process and archive it | ``./secure_fw/partitions/crypto/tfm_crypto_signal.h`` |
+ | | with the static library of the Crypto service. | ``./secure_fw/partitions/crypto/spe_crypto.h`` |
+ | | The headers are used to export the public prototypes of the | |
+ | | functions in the Service modules ``tfm_crypto_api.h``, and | |
+ | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | |
+ | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | |
+ | | which the service handler waits for requests when the service | |
+ | | is built for IPC mode. | |
+ | | The header available in the interface, ``tfm_crypto_defs.h`` | |
+ | | , contains types and defines for building the NSPE interface | |
+ | | as part of a Non-Secure application. | |
+ | | Finally, the ``crypto_spe.h`` header is used during the | |
+ | | build of the Mbed Crypto library, when the Mbed Crypto config | |
+ | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | |
+ | | custom prefix to the PSA API symbols so that duplication of | |
+ | | symbol names is avoided. | |
+ | | The prefix used for the PSA API symbols of the Mbed Crypto | |
+ | | library is chosen to be ``mbedcrypto__``. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Documentation | The integration guide contains the description of the TF-M | ``./docs/user_guides/services/tfm_crypto_integration_guide.rst`` |
+ | | Crypto service modules and interfaces. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+
+The interaction between the different components is described by the
+following block diagram:
+
+.. figure:: media/tfm_crypto_design.png
+
+ Block diagram of the different components of the TF-M Crypto service. A
+ dotted line is used to indicate the interaction with a library.
+
+Note: in IPC mode, the interaction between components is slightly
+different, as the Service modules are not called directly through the
+TF-M Secure Partition Manager but through the IPC handler which resides
+in the Init module.
+
+Service API description
+-----------------------
+
+Most of the APIs exported by the TF-M Crypto service (i.e. from the Service
+modules) is based on the Uniform Signature prototypes [2]_ and have a direct
+correspondence with the PSA Crypto API. The Alloc and Init modules instead
+export some APIs which are specific to the TF-M Crypto service, and are
+available only to the Service modules or the SPM. For a detailed description
+of the prototypes please refer to the ``tfm_crypto_api.h`` header.
+
+.. table:: Init and Alloc modules APIs
+ :widths: auto
+
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | **Function** | **Module** | **Caller** | **Scope** |
+ +================================+==============+=================+======================================================+
+ | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC |
+ | | | | mode, it calls the IPC service request handler. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the |
+ | | | | concurrent operation contexts storage area. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart |
+ | | | | operation. It returns an handle to the allocated |
+ | | | | context in secure memory. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context|
+ | | | | of a multipart operation, based on the handle given |
+ | | | | as input. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context |
+ | | | | of a multipart operation, based on the handle given |
+ | | | | as input. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+
+Configuration parameters
+------------------------
+
+The TF-M Crypto service exposes some configuration parameters to tailor
+the service configuration in terms of supported functionalities and
+hence FLASH/RAM size to meet the requirements of different platforms and
+use cases. These parameters can be provided via CMake parameters during
+the CMake configuration step and as a configuration header to allow the
+configuration of the Mbed Crypto library.
+
+.. table:: Configuration parameters table
+ :widths: auto
+
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | **Parameter** | **Type** | **Description** | **Scope** | **Default** |
+ +===============================+===========================+================================================================+=========================================+====================================================+
+ | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 8096 (bytes) |
+ | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 |
+ | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| use case and platform requirements. | |
+ | | | for multi-part operations, that can be allocated simultaneously| | |
+ | | | at any time. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC mode builds. In IPC mode, | To be configured based on the desired | 5120 (bytes) |
+ | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | |
+ | | | temporarily in an internal scratch buffer whose size is | | |
+ | | | determined by this parameter. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./platform/ext/common/tfm_mbedcrypto_config.h`` |
+ | | | algorithms through the usage of a a configuration header file | application and platform requirements. | |
+ | | | at build time. This allows for tailoring FLASH/RAM requirements| | |
+ | | | for different platforms and use cases. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+
+References
+----------
+
+.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/ARMmbed/mbed-crypto
+
+.. [2] Uniform Signature prototypes: \ https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/
+
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_fwu_service.rst b/docs/technical_references/tfm_fwu_service.rst
new file mode 100644
index 0000000000..6d90de4579
--- /dev/null
+++ b/docs/technical_references/tfm_fwu_service.rst
@@ -0,0 +1,313 @@
+#######################
+Firmware Update Service
+#######################
+
+:Author: Sherry Zhang
+:Organization: Arm Limited
+:Contact: Sherry Zhang
+:Status: Draft
+
+.. contents:: Table of Contents
+
+***************************************
+Introduction of Firmware Update service
+***************************************
+The Firmware Update(FWU) service provides the functionality of updating firmware
+images. It provides a standard interface for updating firmware and it is
+platform independent. TF-M defines a shim layer to support cooperation between
+bootloader and FWU service.
+
+This partition supports the following features:
+
+- Query image information
+ Fetch information about the firmware images on the device. This covers the
+ images in the running area and also the staging area.
+- Store image
+ Write a candidate image to its staging area.
+- Validate image
+ Starts the validation of the image.
+- Trigger reboot
+ Trigger a reboot to restart the platform.
+
+**********
+Components
+**********
+The structure of the TF-M Firmware Update service is listed below:
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | **Component name** | **Description** | **Location** |
+ +=============================+===============================================================+==================================================================================+
+ | SPE client API interface | This module exports the client API of PSA Firmware Update to | ``./secure_fw/partitions/firmware_update/tfm_fwu_secure_api.c`` |
+ | | the other services available in TF-M. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | NSPE client API interface | This module exports the client API of PSA Firmware Update to | ``./interface/src/tfm_firmware_update_func_api.c`` |
+ | | the NSPE(i.e. to the applications). | ``./interface/src/tfm_firmware_update_ipc_api.c`` |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/firmware_update/tfm_firmware_update.yaml`` |
+ | | for both library mode and IPC mode. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | Secure functions and IPC | This module handles all the secure function requests in | ``./secure_fw/partitions/firmware_update/tfm_fwu_req_mngr.c`` |
+ | request handlers | library model and all the service requests in IPC model. | |
+ | | It maitains the image state context and calls the image ID | |
+ | | converter to achieve the firmware update functionalities. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | Image ID Converter | This module converts the image ID between psa_image_id_t, | ``./secure_fw/partitions/firmware_update/tfm_fwu_internal.c`` |
+ | | which is the image ID structure in user interfaces, and | |
+ | | bl_image_id_t which is the image ID structure in bootloader. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | Shim layer between FWU and | This module provides the APIs with the functionality of | ``./secure_fw/partitions/firmware_update/tfm_bootloader_fwu_abstraction.h`` |
+ | bootloader | operating the bootloader to cooperate with the Firmware Update| |
+ | | service | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+ | Shim layer example based on | This module is the implementation of the shim layer between | ``./secure_fw/partitions/firmware_update/bootloader/mcuboot/tfm_mcuboot_fwu.c`` |
+ | MCUboot | FWU and bootloader based on MCUboot. | |
+ | | | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+
+
+***********************
+Service API description
+***********************
+This service follows the `Firmware Update API `_ spec of version 0.7.
+It implements the mandatory interface functions listed in section 5.1 and the
+optional interface ``psa_fwu_accept()``. Please refer to Firmware Update spec
+for the detailed description.
+
+*************************************
+Shim Layer between FWU and bootloader
+*************************************
+The firmware update operations are achieved by calling the shim layer APIs
+between bootloader and FWU.
+
+Shim layer introduction
+=======================
+This shim layer provides the APIs with the functionality of operating the
+bootloader to cooperate with the Firmware Update service. This shim layer
+is decoupled from bootloader implementation. Users can specify a specific
+bootloader by setting ``TFM_FWU_BOOTLOADER_LIB`` build configuration and
+adding the specific build scripts into that file. By default, the MCUboot
+is chosen as the bootloader.
+
+Interfaces of the shim Layer
+============================
+
+fwu_bootloader_init(function)
+-----------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_init(void);
+
+Description
+^^^^^^^^^^^
+Bootloader related initialization for the firmware update, such as reading
+some necessary shared data from the memory if needed.
+
+Parameters
+^^^^^^^^^^
+ N/A
+
+fwu_bootloader_staging_area_init(function)
+------------------------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_staging_area_init(bl_image_id_t bootloader_image_id);
+
+Description
+^^^^^^^^^^^
+Prepare the staging area of the image with the given ID for image download.
+For example, initialize the staging area, open the flash area, and so on.
+The image will be written into the staging area later.
+
+Parameters
+^^^^^^^^^^
+- ``bootloader_image_id``: The identifier of the target image in bootloader.
+
+fwu_bootloader_load_image(function)
+-----------------------------------
+Prototype
+^^^^^^^^^
+
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_load_image(bl_image_id_t bootloader_image_id,
+ size_t image_offset,
+ const void *block,
+ size_t block_size);
+
+Description
+^^^^^^^^^^^
+Load the image to its staging area.
+
+Parameters
+^^^^^^^^^^
+- ``bootloader_image_id``: The identifier of the target image in bootloader.
+- ``image_offset``: The offset of the image being passed into block, in bytes.
+- ``block``: A buffer containing a block of image data. This might be a complete image or a subset.
+- ``block_size``: Size of block.
+
+fwu_bootloader_install_image(function)
+---------------------------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_install_image(bl_image_id_t bootloader_image_id,
+ bl_image_id_t *dependency,
+ psa_image_version_t *dependency_version);
+
+Description
+^^^^^^^^^^^
+Check the authenticity and integrity of the image. If a reboot is required to
+complete the check, then mark this image as a candidate so that the next time
+bootloader runs it will take this image as a candidate one to bootup. Return
+the error code PSA_SUCCESS_REBOOT.
+
+Parameters
+^^^^^^^^^^
+- ``bootloader_image_id``: The identifier of the target image in bootloader.
+- ``dependency``: Bootloader image ID of dependency if needed.
+- ``dependency_version``: Bootloader image version of dependency if needed.
+
+fwu_bootloader_mark_image_accepted(function)
+--------------------------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_mark_image_accepted(void);
+
+Description
+^^^^^^^^^^^
+Call this API to mark the running images as permanent/accepted to avoid
+revert when next time bootup. Usually, this API is called after the running
+images have been verified as valid.
+
+Parameters
+^^^^^^^^^^
+ N/A
+
+fwu_bootloader_abort(function)
+------------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_abort(void);
+
+Description
+^^^^^^^^^^^
+Abort the current image download process.
+
+Parameters
+^^^^^^^^^^
+ N/A
+
+fwu_bootloader_get_image_info(function)
+---------------------------------------
+Prototype
+^^^^^^^^^
+.. code-block:: c
+
+ psa_status_t fwu_bootloader_get_image_info(bl_image_id_t bootloader_image_id,
+ bool staging_area,
+ tfm_image_info_t *info);
+
+Description
+^^^^^^^^^^^
+Get the image information of the given bootloader_image_id in the staging area
+or the running area.
+
+Parameters
+^^^^^^^^^^
+ - ``bootloader_image_id``: The identifier of the target image in bootloader.
+ - ``active_image``: Indicates image location.
+
+ - ``True``: the running image.
+ - ``False``: the image in the passive(or staging) slot.
+
+ - ``info``: Buffer containing the image information.
+
+******************************************
+Additional shared data between BL2 and SPE
+******************************************
+An additional TLV area "image version" is added into the shared memory between
+BL2 and TF-M. So that the firmware update partition can get the image version.
+Even though the image version information is also included in the ``BOOT RECORD``
+TLV area which is encoded by CBOR, adding a dedicated ``image version`` TLV area
+is preferred to avoid involving the CBOR encoder which can increase the code
+size. The FWU partition will read the shared data at the partition
+initialization.
+
+******************
+Image ID structure
+******************
+The structure of image ID is:
+ image_id[7:0]: slot.
+ image_id[15:8]: image type.
+ image_id[31:16]: specific image ID.
+
+Three image types are defined in this partition.
+- FWU_IMAGE_TYPE_NONSECURE: the non_secure image
+- FWU_IMAGE_TYPE_SECURE: the secure image
+- FWU_IMAGE_TYPE_FULL: the secure + non_secure image
+
+.. Note::
+
+ Currently, images update with dependency is not supported by FWU in multiple image boot.
+
+Macros **FWU_CALCULATE_IMAGE_ID**, **FWU_IMAGE_ID_GET_TYPE** and
+**FWU_IMAGE_ID_GET_SLOT** are dedicated to converting the image id, type, and
+slot. The service users can call these macros to get the image ID.
+
+.. Note::
+
+ The image ID structure, as well as the macros listed here, is TF-M specific implementation.
+
+***********************************
+Benefits Analysis on this Partition
+***********************************
+
+Implement the FWU functionality in the non-secure side
+======================================================
+The Firmware Update APIs listed in `User interfaces`_ can also be implemented
+in the non-secure side. The library model implementation can be referred to for
+the non-secure side implementation.
+
+Pros and Cons for Implementing FWU APIs in Secure Side
+======================================================
+
+Pros
+----
+- It protects the image in the passive or staging area from being tampered with
+ by the NSPE. Otherwise, a malicious actor from NSPE can tamper the image
+ stored in the non-secure area to break image update.
+
+- It protects secure image information from disclosure. In some cases, the
+ non-secure side shall not be permitted to get secure image information.
+
+- It protects the active image from being manipulated by NSPE. Some bootloader
+ supports testing the image. After the image is successfully installed and
+ starts to run, the user should set the image as permanent image if the image
+ passes the test. To achieve this, the area of the active image needs to be
+ accessed. In this case, implementing FWU service in SPE can prevent NSPE
+ from manipulating the active image area.
+
+- On some devices, such as the Arm Musca-B1 board, the passive or staging area
+ is restricted as secure access only. In this case, the FWU partition should
+ be implemented in the secure side.
+
+Cons
+----
+- It increases the image size of the secure image.
+- It increases the execution latency and footprint. Compared to implementing
+ FWU in NSPE directly, calling the Firmware Update APIs which are implemented
+ in the secure side increases the execution latency and footprint.
+- It can increase the attack surface of the secure runtime.
+
+Users can decide whether to call the FWU service in TF-M directly or implement
+the Firmware Update APIs in the non-secure side based on the pros and cons
+analysis above.
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_its_512_flash.rst b/docs/technical_references/tfm_its_512_flash.rst
new file mode 100644
index 0000000000..aa58c2b036
--- /dev/null
+++ b/docs/technical_references/tfm_its_512_flash.rst
@@ -0,0 +1,104 @@
+###############################################################
+Add support for block-aligned flash in Internal Trusted Storage
+###############################################################
+
+:Author: Minos Galanakis
+:Organization: Arm Limited
+:Contact: Minos Galanakis
+:Status: Accepted
+
+Abstract
+========
+
+The proposal is describing a mechanism to enable the use of larger flash
+devices, imposing a requirement for word-aligned full-block program operations,
+in Trusted Firmware-M.
+
+
+Requirements
+============
+
+- Allow page-aligned writes for up to 512 Bytes per page.
+- Guarantee data integrity and power-failure reliability.
+- Do not alter existing supported platform behaviour.
+
+Current implementation
+======================
+
+In the current ITS filesystem design, each filesystem create or write operation
+requires two flash blocks to be updated: first the data block and then the
+metadata block. Buffering is avoided as much as possible to reduce
+RAM requirements.
+
+However, if the ITS_FLASH_PROGRAM_UNIT is 512 Bytes then the data will have to
+stored in a temporary memory location in order to be able to write
+that much data in one-shot.
+
+Proposed implementation overview
+================================
+
+1. A new block-sized static buffer should be added to its_flash.c when
+ ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported.
+2. Methods calling the flash API such as ``its_flash_write()`` or
+ ``its_flash_block_to_block_move()`` will populate the buffer instead of
+ directly programming the flash.
+3. A new method ``its_flash_flush()``, should be provided in order to flush
+ the block buffer to the device.
+4. ``its_flash_flush()`` should be called twice: Once after a data block
+ update and once more after the metadata block update is completed.
+5. The proposed design should require that the data block update is always
+ completed before the metadata block update starts
+6. Writes to the block buffer should be atomic, and guarded against corruption
+ by data from different blocks.
+
+Considerations
+==============
+
+- The proposed implementation will increase the RAM usage of ITS by the size
+ of a block, only for platforms which require block-aligned writes.
+- Currently power-failure is detected by software by incrementing an 8-bit
+ metadata header field (``swap_count``), as the last written byte. When the
+ proposed block-buffer is used, the block is programmed in one-shot and the
+ order the bytes are written on the physical device, is hardware dependent.
+- A set of guarantees are required by the supported flash ECC devices.
+ The device's flash APIs should provide a mechanism to capture and raise
+ incomplete program operations, as well as write bytes in a sequential order.
+
+For example, if a board powers down through a 512 page program operation, the
+next read operation should return an error rather than read invalid data.
+
+Functional flow diagram
+=======================
+
+The logic of the proposal is described in the following diagram
+
+.. code-block::
+
+ |----------------------|
+ | data write() |
+ |----------------------|
+ | | |------------------------------|
+ |-> | its_flash_write | ---> | data[] -> its_block_buffer[] |
+ | | | |------------------------------|
+ | |----------------------|
+ | | | |------------------------------------|
+ | | its_flash_flush | ---> | its_block_buffer[] -> flash dev IO |
+ | | | |------------------------------------|
+ | |----------------------|
+ | |
+ | ------------------------------------
+ | |
+ | V
+ | |----------------------| |--------------------------|
+ | | data write() complete| | metadata write() complete|
+ | |----------------------| |--------------------------|
+ | <-| Metadata write() | |
+ |----------------------| |
+ V
+ |--------------------------|
+ | Operation Complete |
+ |--------------------------|
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_its_service.rst b/docs/technical_references/tfm_its_service.rst
new file mode 100644
index 0000000000..a9c71b7ac6
--- /dev/null
+++ b/docs/technical_references/tfm_its_service.rst
@@ -0,0 +1,281 @@
+======================================
+Internal Trusted Storage (ITS) Service
+======================================
+
+:Author: Jamie Fox
+:Organization: Arm Limited
+:Contact: Jamie Fox
+:Status: Accepted
+
+PSA Internal Trusted Storage
+============================
+PSA Internal Trusted Storage (ITS) is a PSA RoT Service for storing the most
+security-critical device data (e.g. cryptographic keys) in internal storage,
+which is trusted to provide data confidentiality and authenticity. This
+contrasts with PSA Protected Storage, which is an Application RoT service that
+allows larger data sets to be stored securely in external flash, with the option
+for encryption, authentication and rollback protection to protect the
+data-at-rest.
+
+Current TF-M Secure Storage
+===========================
+Currently, the TF-M Secure Storage service implements PSA Protected Storage
+version 1.0-beta2. There is not yet an implementation of PSA Internal Trusted
+Storage in TF-M.
+
+New TF-M service
+================
+The proposal is to implement the *PSA Internal Trusted Storage API* with the
+*TF-M Internal Trusted Storage service*. It can be abbreviated to *TF-M ITS
+service* in general and to ``its`` in code. This name has the advantage of
+making clear the correspondence between the service and the API it implements.
+
+If this name is adopted, then it may make sense to rename the *Secure Storage
+service* to the *Protected Storage service* in the future to match. Then "secure
+storage" could refer to the two services as a collective.
+
+The TF-M ITS service will implement PSA ITS version 1.0. It will be provided by
+a separate partition to Protected Storage, for a couple of reasons:
+
+- To permit isolation between the services.
+
+ - ITS is a PSA RoT Service, while Protected Storage is an Application RoT
+ Service.
+
+- To avoid circular dependencies.
+
+ - The PSA Firmware Framework does not permit circular dependencies between
+ partitions, which would occur if Protected Storage and ITS were provided by
+ the same partition. Protected Storage depends on Crypto, which in turn
+ depends on ITS.
+
+The existing SST filesystem will be reused to provide the backend of the
+service, with the flash layer modified to direct storage to internal flash,
+rather than external.
+
+Compared to Protected Storage, encryption, authentication and rollback
+protection are not required, so the SST encrypted object layer and the crypto
+and NV counter interfaces are not required. The rollback protection feature of
+the object table is also not required.
+
+Code structure
+==============
+The code structure of the service will be as follows:
+
+TF-M repo:
+
+``interface/``
+
+- ``include/psa/internal_trusted_storage.h`` - PSA ITS API
+- ``src/tfm_its_api.c`` - PSA ITS API implementation for NSPE
+
+``secure_fw/ns_callable/tfm_veneers.c`` - ITS veneers (auto-generated from
+manifest)
+
+``secure_fw/partitions/internal_trusted_storage/``
+
+- ``tfm_internal_trusted_storage.yaml`` - Partition manifest
+- ``tfm_its_secure_api.c`` - PSA ITS API implementation for SPE
+- ``tfm_its_req_mngr.c`` - Uniform secure functions and IPC request handlers
+- ``tfm_internal_trusted_storage.h`` - TF-M ITS API (with client_id parameter)
+- ``tfm_internal_trusted_storage.c`` - TF-M ITS implementation, using the
+ flash_fs as a backend
+- ``flash_fs/`` - Filesystem
+- ``flash/`` - Flash interface
+
+tf-m-tests repo:
+
+``test/suites/its/``
+
+- ``non_secure/psa_its_ns_interface_testsuite.c`` - Non-secure interface tests
+- ``secure/psa_its_s_interface_testsuite.c`` - Secure interface tests
+
+TF-M ITS implementation
+-----------------------
+The following APIs will be exposed by ``tfm_internal_trusted_storage.h``::
+
+ psa_status_t tfm_its_init(void);
+
+ psa_status_t tfm_its_set(int32_t client_id,
+ psa_storage_uid_t uid,
+ size_t data_length,
+ const void *p_data,
+ psa_storage_create_flags_t create_flags);
+
+ psa_status_t tfm_its_get(int32_t client_id,
+ psa_storage_uid_t uid,
+ size_t data_offset,
+ size_t data_size,
+ void *p_data,
+ size_t *p_data_length);
+
+ psa_status_t tfm_its_get_info(int32_t client_id,
+ psa_storage_uid_t uid,
+ struct psa_storage_info_t *p_info);
+
+ psa_status_t tfm_its_remove(int32_t client_id,
+ psa_storage_uid_t uid);
+
+That is, the TF-M ITS APIs will have the same prototypes as the PSA ITS APIs,
+but with the addition of a ``client_id`` parameter, which will be passed from
+the ITS request manager. A ``tfm_its_init`` function will also be present, which
+will be called at initialisation time and not exposed through a veneer or SID.
+
+The implementation in ``tfm_internal_trusted_storage.c`` must validate the
+parameters (excepting memory references, which are validated by the SPM),
+translate the UID and client ID into a file ID and then make appropriate calls
+to the filesystem layer. It must also take care ensure that any PSA Storage
+flags associated with the UID are honoured.
+
+Filesystem
+----------
+The ITS filesystem will be copied and modified from the SST filesystem. The
+modifications required will be to rename symbols from ``sst`` to ``its`` and to
+update the implementation to be aligned with the latest version of the PSA
+Storage spec (which consists mainly of moving to the ``psa_status_t`` error type
+and using common error codes from ``psa/error.h``).
+
+The filesystem will also be modified to align the size of each file stored to
+the alignment requirement exposed by the flash interface, by adding appropriate
+padding.
+
+The filesystem code will be de-duplicated again once the ITS service is
+implemented (see below).
+
+Flash layer
+-----------
+The flash layer will be copied from SST, and modified to direct writes to the
+internal flash device. It too needs to be updated to use ``psa_status_t`` error
+types.
+
+Platform layer
+--------------
+The TF-M platform layer must be be updated to distinguish between the external
+flash device used for Protected Storage and internal flash device used for ITS.
+A flash region for the relevant storage service needs to be allocated in each.
+
+On test platforms these may just be two distinct regions of the same flash
+device, but in general they will separate devices with their own drivers.
+
+Detailed design considerations
+==============================
+
+Mapping UID onto file ID
+------------------------
+The ITS APIs identify assets with 64-bit UIDs, to which the ITS service must
+append the 32-bit client ID of the calling partition for access control. The
+existing filesystem uses 32-bit file IDs to identify files, so some mapping
+would be required to convert between the identifiers.
+
+SST uses the object table to do the mapping from client ID, UID pairs to file
+IDs, which means making an extra filesystem read/write for each get/set
+operation. This mapping has minimal overhead for SST though, because object
+table lookups are already required for rollback protection.
+
+For ITS, no rollback protection feature is required, so there are two options:
+
+- Keep a simplified version of the SST object table that just maps from
+ (client ID, UID) to file ID
+
+- Modify the filesystem to take (at least) 96-bit file IDs, in the form of a
+ fixed-length char buffer.
+
+The advantage of the former is that it would require no extra modification to
+the existing filesystem code, and the existing SST object table could be cut
+down for ITS. However, it would mean that every ITS request would invoke twice
+the number of filesystem operations, increasing latency and flash wear. The code
+size of the ITS partition would be increased, as would RAM usage as the table
+would need to be read into RAM.
+
+The latter option would make the filesystem slightly more complex: the size of a
+metadata entry would be increased by 64-bits and the 96-bit fids would need to
+be copied and compared with ``memcpy`` and ``memcmp`` calls. On the other hand,
+mapping onto file IDs would incur only the cost of copying the UID and client ID
+values into the file ID buffer.
+
+A third, even more general, solution would be to use arbitrary-length
+null-terminated strings as the file IDs. This is the standard solution in
+full-featured filesystems, but we do not currently require this level of
+complexity in secure storage.
+
+With this in mind, the proposed option is the second.
+
+Storing create flags
+--------------------
+The ITS APIs provide a 32-bit ``create_flags`` parameter, which contains bit
+flags that determine the properties of the stored data. Only one flag is
+currently defined for ITS: ``PSA_STORAGE_FLAG_WRITE_ONCE``, which prevents a UID
+from being modified or deleted after it is set for the first time.
+
+There are two places that these flags could be stored: in the file data or as
+part of the file metadata.
+
+For the first option, the ITS implementation would need to copy to the flags
+into the buffer containing the data, and adjust the size accordingly, for each
+set operation, and the reverse for each get. Every get_info operation would need
+to read some of the file data, rather than just the metadata, implying a second
+flash read. A potential downside is that many of the cryptographic assets stored
+in ITS will be aligned to power-of-two sizes; adding an extra 32-bits would
+misalign the size, which may reduce flash performance or necessitate adding
+padding to align to the flash page size.
+
+To implement the second option, a 32-bit ``flag`` field would be added to the
+filesystem's metadata structure, whose interpretation is defined by the user.
+This field would clearly be catered towards the PSA Storage APIs, even if
+nominally generic, and alternative filesystems may not have any such field.
+However, it is a more intuitive solution and would simplify both flash alignment
+and get_info operations.
+
+Overall, it seems more beneficial to store the flags in the metadata, so this is
+the proposed solution.
+
+Code sharing between Protected Storage and ITS
+----------------------------------------------
+To de-duplicate the filesystem code used by both Protected Storage and ITS, it
+is proposed that Protected Storage calls ITS APIs as its backend filesystem.
+
+Protected Storage essentially becomes an encryption, authentication and rollback
+protection layer on top of ITS. It makes IPC requests or secure function calls
+to the ITS service to do filesystem operations on its behalf.
+
+This has a couple of advantages:
+
+- It shrinks Protected Storage's stack size, because the filesystem and flash
+ layer stack is only in ITS.
+
+- It automatically solves the problem of ensuring mutual exclusion in the
+ filesystem and flash layers when Protected Storage and ITS are called
+ concurrently. The second request to ITS will just be made to wait by the SPM.
+
+The disadvantage of this approach is that it will increase the latency of
+Protected Storage requests, due to the extra overhead associated with making a
+second IPC request or secure function call. It also limits Protected Storage to
+using only the ITS APIs, unless extra veneers are added solely for Protected
+Storage to use. This, for example, prevents Protected Storage from doing partial
+writes to file without reading and re-writing the whole file.
+
+ITS will need to be modified to direct calls from Protected Storage to a
+different flash device. It can use the client ID to detect when the caller is
+Protected Storage, and pass down the identity of the flash device to use to the
+flash layer, which then calls the appropriate driver.
+
+An open question is what to do if Protected Storage itself wants to store
+something in internal storage in the future (e.g. rollback counters, hash
+tree/table or top hash). A couple of possible solutions would be:
+
+- Divide up the UIDs, so certain UIDs from Protected Storage refer to assets in
+ internal storage, and others to ones in external storage.
+
+- Use the ``type`` field of ``psa_call`` in IPC model and extra veneers in
+ library model to distinguish between internal and external storage requests.
+
+The other option for code sharing would be for Protected Storage and ITS to
+directly share filesystem code, which would be placed in a shared code region.
+With this approach, mutual exclusion to the flash device would need to be
+implemented separately, as would some way of isolating static memory belonging
+to each partition but not the code. Because of these complications, this option
+has not been considered further at this time.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_log_system_design_document.rst b/docs/technical_references/tfm_log_system_design_document.rst
new file mode 100644
index 0000000000..269bcfc69d
--- /dev/null
+++ b/docs/technical_references/tfm_log_system_design_document.rst
@@ -0,0 +1,209 @@
+##########################
+Log system design document
+##########################
+
+:Authors: Shawn Shan
+:Organization: Arm Limited
+:Contact: shawn.shan@arm.com
+
+**********
+Background
+**********
+
+In current TF-M log system, the SPM and Secure partitions share the same log
+APIs and implementations. While TF-M is keep evolving, the requirements for the
+log system has changed:
+
+ - Log level is required for both SPM and SP sides to output message in
+ different scenarios.
+ - SPM only needs simple log format such as hex and string, while SP needs rich
+ formatting.
+ - Distinctions on log output between SPM and SP are required.
+
+A new log system is needed to separate the SPM and Secure partitions and to
+meet their different requirements.
+
+******
+Design
+******
+
+To allow customizable configurations, the log interfaces are defined as macros.
+The macros are easy to be forwarded or even empty. When SPM trying to output
+message and a value, it relies on a wrapper function, and finally output the
+formatted message by the HAL API.
+
+The design principles of TF-M log system:
+
+ - Configurable log levels.
+ - Separated SPM and SP log implementations.
+ - Platforms provide log HAL implementations.
+
+SPM Log System
+==============
+
+Level Control
+-------------
+Three log levels for SPM log system are defined:
+
+ - TFM_SPM_LOG_LEVEL_DEBUG
+ - TFM_SPM_LOG_LEVEL_INFO
+ - TFM_SPM_LOG_LEVEL_ERROR
+ - TFM_SPM_LOG_LEVEL_SILENCE
+
+Then a macro ``TFM_SPM_LOG_LEVEL`` is defined as an indicator, it should
+be equal to one of the four log levels.
+
+API Definition
+--------------
+The following three APIs LOG APIs output the given 'msg' with hexadecimal
+formatted 'val' together. These APIs provide constrained ability to output
+numbers inside SPM. The 'msg' can be skipped with giving an empty string like
+"". And these APIs supports constant 'msg' string only, giving a runtime string
+as parameter 'msg' would potentially cause a runtime error.
+
+ SPMLOG_DBGMSGVAL(msg, val);
+
+ SPMLOG_INFMSGVAL(msg, val);
+
+ SPMLOG_ERRMSGVAL(msg, val);
+
+A C-function needs to work as an underlayer for these APIs as string formatting
+is required. Check 'spm_log_msgval' for details.
+
+.. code-block:: c
+
+ /**
+ * brief Output the given message plus one value as hexadecimal. The message
+ * can be skipped if the 'msg' is 'NULL' or 'len' equals 0. The
+ * formatted hexadecimal string for 'value' has a '0x' prefix and
+ * leading zeros are not stripped. This function rely on HAL API
+ * 'tfm_hal_output_spm_log' to output the formatted string.
+ *
+ * \param[in] msg A string message
+ * \param[in] len The length of the message
+ * \param[in] value A value need to be output
+ *
+ * \retval >=0 Number of chars output.
+ * \retval <0 TFM HAL error code.
+ */
+ int32_t spm_log_msgval(const char *msg, size_t len, uint32_t value)
+
+The following three APIs output a message in string.
+
+ SPMLOG_DBGMSG(msg);
+
+ SPMLOG_INFMSG(msg);
+
+ SPMLOG_ERRMSG(msg);
+
+Here is a table about the effective APIs with different SPM log level.
+
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| | TFM_SPM_LOG_LEVEL_DEBUG | TFM_SPM_LOG_LEVEL_INFO | TFM_SPM_LOG_LEVEL_ERROR | TFM_SPM_LOG_LEVEL_SILENCE |
++==================+=========================+===========================+===========================+=============================+
+| SPMLOG_DBGMSGVAL | Yes | No | No | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| SPMLOG_INFMSGVAL | Yes | Yes | No | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| SPMLOG_ERRMSGVAL | Yes | Yes | Yes | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| SPMLOG_DBGMSG | Yes | No | No | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| SPMLOG_INFMSG | Yes | Yes | No | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+| SPMLOG_ERRMSG | Yes | Yes | Yes | No |
++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+
+
+HAL API
+-------
+Define HAL API for SPM log system:
+
+.. code-block:: c
+
+ /* SPM log HAL API */
+ int32_t tfm_hal_output_spm_log(const char *str, uint32_t len);
+
+Take debug message as an example:
+
+.. code-block:: c
+
+ /* For debug message */
+ #define SPMLOG_DBGMSG(msg) tfm_hal_output_spm_log(msg, sizeof(msg))
+ /* For debug message with a value */
+ #define SPMLOG_DBGMSGVAL(msg, val) spm_log_msgval(msg, sizeof(msg), val)
+
+Partition Log System
+====================
+Partition log outputting required rich formatting in particular cases. There is
+a customized print inside TF-M(``tfm_log_printf``), and it is wrapped as macro.
+
+Level Control
+-------------
+Three log levels for partition log system are defined:
+
+ - TFM_PARTITION_LOG_LEVEL_DEBUG
+ - TFM_PARTITION_LOG_LEVEL_INFO
+ - TFM_PARTITION_LOG_LEVEL_ERROR
+ - TFM_PARTITION_LOG_LEVEL_SILENCE
+
+Then a macro ``TFM_PARTITION_LOG_LEVEL`` is defined as an indicator. It should
+be equal to one of the four log levels and it is an overall setting for all
+partitions.
+
+Log Format
+----------
+Compared to SPM, SP log API supports formatting. Similar to ``printf``, these
+log APIs use a format outputting to output various type of data:
+
+.. code-block:: c
+
+ %d - decimal signed integer
+ %u - decimal unsigned integer
+ %x - hex(hexadecimal)
+ %c - char(character)
+ %s - string
+
+API Definition
+--------------
+Define partition log APIs:
+
+ LOG_DBGFMT(...);
+
+ LOG_INFFMT(...);
+
+ LOG_ERRFMT(...);
+
+Here is a table about the effective APIs with different partition log level.
+
++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
+| | TFM_PARTITION_LOG_LEVEL_DEBUG | TFM_PARTITION_LOG_LEVEL_INFO | TFM_PARTITION_LOG_LEVEL_ERROR | TFM_PARTITION_LOG_LEVEL_SILENCE |
++============+===============================+=================================+=================================+=================================+
+| LOG_DBGFMT | Yes | No | No | No |
++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
+| LOG_INFFMT | Yes | Yes | No | No |
++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
+| LOG_ERRFMT | Yes | Yes | Yes | No |
++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+
+
+HAL API
+-------
+Please refers to the HAL design document.
+
+***********
+Log Devices
+***********
+In most of the cases, a serial device could be used as a log device. And in
+other particular cases, a memory-based log device could be applied as well.
+These log device interfaces are abstracted into HAL APIs.
+
+.. note::
+
+ It is not recommended to re-use the same HAL for both SPM and SP log
+ outputting especially when SPM and SP run under different privileged level,
+ which makes them have a different information confidential level. Unless:
+
+ - The SPM log outputting would be disabled as silence in the release version.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_non-secure_interrupt_handling.rst b/docs/technical_references/tfm_non-secure_interrupt_handling.rst
new file mode 100644
index 0000000000..6560a0cf85
--- /dev/null
+++ b/docs/technical_references/tfm_non-secure_interrupt_handling.rst
@@ -0,0 +1,318 @@
+#############################
+Non-Secure Interrupt Handling
+#############################
+
+:Author: Mate Toth-Pal
+:Organization: Arm Limited
+:Contact: Mate Toth-Pal
+:Status: Accepted
+
+
+*****
+Terms
+*****
+
+========== ================================================
+Term Meaning
+========== ================================================
+AIRCR Application Interrupt and Reset Control Register
+AIRCR.PRIS PRIoritize Secure exceptions
+ISR Interrupt Service Routine
+NS Non-Secure
+NSPM Non-Secure Partition Manager
+SAU Security Attribution Unit
+SPM Secure Partition Manager
+TF-M Trusted Firmware-M
+========== ================================================
+
+************
+Introduction
+************
+
+In the current design it is possible to use Non-secure interrupts, however the
+Non-secure interrupts cannot pre-empt Secure service execution. TF-M core
+achieves this by making the following configurations:
+
+1. ``AIRCR.PRIS`` is set to 1 during TF-M core initialisation. This
+ de-prioritizes Non-secure exceptions compared to Secure exceptions, so that
+ they cannot interrupt Secure Handler mode. the ``AIRCR.PRIS`` bit remains set
+ during TF-M run. The bit is set in the function
+
+.. code-block:: c
+
+ static void tfm_arch_set_secure_exception_priorities(void);
+
+.. Note::
+
+ Setting ``AIRCR.PRIS`` in itself doesn't prevent NS interrupts to pre-empt
+ Secure Thread mode when it runs on normal priority i.e., 256.
+
+2. On Secure service entry ``PRIMASK_NS`` is set, to boost the Non-secure
+ execution priority so that all NS interrupts are masked. This is done in the
+ ``TFM_NS_EXC_DISABLE()`` macro called from
+
+.. code-block:: c
+
+ static int32_t tfm_start_partition(struct tfm_sfn_req_s *desc_ptr, uint32_t excReturn)
+
+.. Note::
+
+ '2.' is only in Library model.
+
+In the below chapters a design is proposed to enable Non-secure interrupts to
+pre-empt Secure Thread mode.
+
+**********************************
+Limitations of the proposed design
+**********************************
+
+Library model
+=============
+
+The proposed design keeps the Secure lock in place, which means Non-secure code
+can do a single Secure service call, all further calls to Secure services will
+be rejected until the first Secure service call returns.
+
+IPC model
+=========
+
+The PSA client API can only be entered once. All the functions in the client API
+(``psa_framework_version``, ``psa_version``, ``psa_connect``, ``psa_call``,
+``psa_close``) are part of the same critical section.
+
+Non-secure software
+===================
+
+The Non-secure API functions that wraps the Secure service veneers (either
+Library or IPC model) should continue to use the NS locking mechanism currently
+implemented by calling ``tfm_ns_lock_dispatch(...)``.
+
+If any of the Non-secure software decides to bypass the locking mechanism, then
+concurrent access of veneer functions is detected by TF-M, and NS software
+execution is halted.
+
+.. Note::
+
+ This makes denial of service attack possible by a malicious NS application
+
+***************************************************
+Enabling NS interrupts to pre-empt Secure execution
+***************************************************
+
+To enable NS interrupts, 2) described in chapter 'Current design' must be turned
+off. (For details see implementation notes)
+
+When a Non-secure interrupt is triggered during Secure code execution, and the
+ISR have to be executed based on the priority settings, the hardware saves the
+current execution context on the current Secure stack, and clears the general
+purpose registers, to prevents data leakage. After that the NS ISR starts
+execution.
+
+When the Non-secure ISR returns with the EXC_RETURN value provided to it in the
+link register, the context is fetched from the Secure stack, and the Secure code
+continues execution.
+
+If TF-M is used with a single threaded NS software, the mechanisms provided by
+the HW is enough to maintain the consistency of the system, and keep the
+secrets.
+
+However if the NS software is allowed to change execution context during an
+interrupt (e.g an NS operating system schedules another thread during a SysTick
+interrupt), then the Secure code can return execution to an NS thread, with the
+context of a different thread. So extra measures needs to be introduced in TF-M
+to prevent this.
+
+For IPC model
+=============
+
+In the current implementation there is no locking mechanism on the Secure side
+that would prevent the Non-secure code to enter psa_client functions multiple
+times. (For the Library model the ``tfm_secure_lock global`` variable is used
+for this purpose). Note, that the ``tfm_ns_lock_dispatch(...)`` function that
+is used by the NS service API implementations to prevent Secure services to be
+called simultaneously can be bypassed by a malicious Non-secure application, so
+a Secure side locking mechanism have to be implemented.
+
+When an NS client calls a PSA client API function, the client ID of the calling
+NS context have to be saved, and execution can only return to NS if the current
+scheduled NS thread is the one that did the call.
+
+For Library model
+=================
+
+As currently there is no scheduling in the Library model, the calls follow each
+other just like in an ordinary function call scheme. Then when the original
+Secure service that was called from the NS code is about to return, it has to
+check for the current NS client ID, and only return if it is the same as the one
+saved on Secure service entry from NS. If the ID's don't match, the Secure side
+waits so that NS OS can do context switch.
+
+Common measures
+===============
+
+Exception priorities
+--------------------
+
+The priority of the Secure SVC and the Secure faults must be higher than any
+Secure exception in the system.
+
+.. note::
+
+ The priority of PendSV Is set to be the lowest priority Secure interrupt,
+ but still higher than the maximum possible NS execution priority when
+ ``AIRCR.PRIS`` is set.
+
+NSPM
+----
+
+If the Non-secure software allows the use of multiple threads, it needs to use
+the NSPM feature of TF-M. It is expected, that all the NS context that use
+Secure services have a unique client ID, and the other contexts, that don't use
+Secure service need to have a client ID that doesn't match with any of the
+client IDs of the Secure service calling contexts.
+
+In other words, for all the *cs(0)*, *cs(1)*, ..., *cs(n)* NS contexts that use
+Secure services and for all *cn(0)*, *cn(1)*, ..., *cn(m)* NS contexts that
+don't use Secure service (where *n* > 0, *m* >= 0):
+
+- *cs(i).client_id* != *cs(j).client_id* (where 0 <= *i* < *j* <= *n*)
+- *cs(i).client_id* != *cn(j).client_id* (where 0 <= *i* <= *n* and 0 <= *j*
+ <= *m*)
+
+Entering from Non-secure to Secure
+----------------------------------
+
+The Secure code can be entered through the following gateways:
+
+1. NSPM related functions (``TZ_(...)``,
+ ``tfm_register_client_id(...)``)
+
+ These functions are expected to be called from Handler mode. The execution
+ priority, after the execution crosses the security boundary will be the same
+ as it was during NS execution. This means a malicious Non-secure application,
+ can set up Non-secure interrupt priorities in a way that it can enter one or
+ more of the NSPM APIs simultaneously.
+
+ This might leave the NSPM database in an inconsistent state, however if the
+ attacker has influence over the interrupt priorities, they can gain no
+ additional privilege by this.
+
+ .. Note::
+ The NS software is able to consume the main stack of the Secure software.
+ The Main Secure stack have to be protected by MSPLIM, to prevent stack
+ overflow. However a denial of service attack is still possible.
+
+2. PSA Client API, Library model service veneers
+
+ When a veneer is called from Non-secure, the Secure code have to check
+ whether the veneer is only entered by a single NS thread. This can be done by
+ checking the veneer stack usage. It can only contain the locals of the veneer
+ implementation. If the veneer has been entered from multiple NS threads,
+ there is at least one extra context stack frame that was created by the
+ hardware when the veneer execution had been interrupted by the NS systick.
+
+********************
+Implementation notes
+********************
+
+IPC model
+=========
+
+Save NS client ID on Secure service veneer entry
+------------------------------------------------
+
+As long as the Secure lock is in place, a single client ID have to be stored, so
+it can be done in a global variable.
+
+The caller client ID can be saved in the function
+``void tfm_psa_ipc_request_handler(uint32_t svc_ctx[])`` depending on the return
+value of the PSA API function. (Doesn't execute any Secure service code, only
+sets signals, and triggers scheduling. If the return value is success, that
+means a scheduling is to happen, and a secure service is about to be entered.)
+
+Check client ID on Secure service return
+----------------------------------------
+
+The saved client ID can be compared with the current client ID in the function
+``tfm_core_ns_ipc_request``, after the SVC return. Before doing the comparison,
+``BASEPRI_NS`` must be set to 1.
+
+The original ``BASEPRI_NS`` value can be stored in a global variable (because of
+the single context).
+
+If the client ID's don't match, ``BASEPRI_NS`` must be reset, WFI to be issued,
+and start the checking sequence from the beginning.
+
+Library model
+=============
+
+Save NS client ID on Secure veneer entry
+----------------------------------------
+
+As long as the Secure lock is in place, only a single client ID have to be
+stored, so it can be done in a global variable.
+
+The caller client ID can be saved in the function
+``uint32_t tfm_core_partition_request_svc_handler(uint32_t *svc_args, uint32_t excReturn)``.
+
+Check client ID on SP return
+----------------------------
+
+The saved client ID can be compared with the current client ID in the function
+``tfm_core_partition_request``, after the ``tfm_core_sfn_request return``.
+
+If the client ID's don't match, WFI to be issued, and the checking sequence have
+to be started from the beginning.
+
+Common
+======
+
+Enforce single NS entry to Secure
+---------------------------------
+
+On Secure service entry (from the SVC implementation) check that (pseudocode)
+
+.. code-block:: c
+
+ svc_handler()
+ {
+ /* If there are multiple context stacked in veneer stack, hang NSPE */
+ expected_sp_top = veneer_stack_addr -
+ sizeof(svc_state_context) + sizeof(locals);
+ if (__get_PSP() != expected_sp_top) {
+ /* Multiple frames are existing, panic */
+ panic();
+ }
+ }
+
+*******
+Testing
+*******
+
+Basic scenario
+==============
+
+Basic testing of the feature is possible, by adding a new scenario to the
+existing IRQ test. The flow of the test would be something like this:
+
+============ ===================== ===========================================
+IRQ_TEST_1 prepare test scenario Do nothing
+CORE_TEST_2 prepare test scenario Do nothing
+NS prepare test scenario Initialise and start timer
+IRQ_TEST_1 execute test scenario Do nothing
+CORE_TEST_2 execute test scenario Busy wait until NS interrupt is
+ acknowledged (a flag in non Secure data is
+ set) set flag CORE_TEST_2 waits on
+NS execute test scenario Do nothing
+============ ===================== ===========================================
+
+The test is successful if NS execute test scenario returns.
+
+Advanced scenarios
+==================
+
+Testing advanced scenarios (that involves NS scheduling during secure execution,
+NS interrupting Secure interrupt, Secure interrupting NS interrupt) would
+require more advanced test framework and are not covered in this proposal.
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_non_secure_client_management.rst b/docs/technical_references/tfm_non_secure_client_management.rst
new file mode 100644
index 0000000000..970550aa49
--- /dev/null
+++ b/docs/technical_references/tfm_non_secure_client_management.rst
@@ -0,0 +1,388 @@
+############################
+Non-secure Client Management
+############################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint
+:Status: Accepted
+
+***********
+Terminology
+***********
+
+**Secure service call**: request to a secure partition by a secure or non-secure
+client thread
+
+**Secure function call**: any function call from NSPE to SPE
+
+**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure
+context management
+
+**Client ID**: the identifier defining a single entity within the system,
+determining its access policies for any given secure assets
+
+*************************
+Assumptions, restrictions
+*************************
+
+This design considers as its baseline the current operation of TF-M: an
+operating mode where at any given time only a single non-secure access is
+permitted to call a secure service.
+
+If a non-secure RTOS/bare-metal application does not use the API calls defined
+in this design, that non-secure application is still able to use secure services
+using a single, default non-secure client context. That remains a supported use
+case and use of this API is optional and is only needed if multiple access
+policies and/or concurrent secure contexts initiated by non-secure threads are
+required.
+
+Investigation is ongoing to address the option of enabling multiple concurrent
+calls by non-secure threads without the use of the context management API below.
+
+******
+Issues
+******
+
+The topics being discussed in this document:
+
+- NS client/thread awareness in TF-M Core
+- "Known client" list
+
+Improvements, alternatives, investigations
+
+- Concurrent secure service requests
+- NS to S priority inheritance
+- NS privilege to be derived from CONTROL_NS register
+
+**************
+Design details
+**************
+
+NS thread awareness in TF-M Core
+================================
+
+Description
+-----------
+
+TrustZone context management API defines a set of secure function calls from NS
+RTOS handler mode to TF-M Core to get notification of context switch.
+
+While CMSIS context management can be used to directly expose secure context
+management to the non-secure OS, TF-M has a proprietary implementation: the
+context management API is used to get notification of NS context switches and
+to track various non-secure clients.
+
+.. _`API definition`:
+
+API definition
+--------------
+
+TZ_MemoryId_t data type
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TZ Memory ID identifies an allocated memory slot.
+
+TF-M usage
+""""""""""
+
+``TZ_MemoryId_t`` is used for an index into an array containing active NS client
+IDs. The memory ID is required by CMSIS to be a positive integer, so it is
+mapped to the array index by being decremented by 1.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ typedef uint32_t TZ_MemoryId_t;
+
+Context management initialization: TZ_InitContextSystem_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Initialize secure context memory system.
+
+Return value
+""""""""""""
+
+This function returns execution status: 1 for success, 0 for error.
+
+TF-M usage
+""""""""""
+
+This function call is used to identify a non-secure RTOS that has TZ context
+management capabilities, as this function is expected to be called before any
+other TZ API function is used.
+
+Signature
+""""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_InitContextSystem_S (void);
+
+Context allocation: TZ_AllocModuleContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allocate context memory for calling secure software modules in TrustZone.
+
+Parameters
+""""""""""
+
+``module`` [input]: identifies software modules called from non-secure mode
+
+Return value
+""""""""""""
+
+``value != 0`` TrustZone memory slot identifier
+``value == 0`` no memory available or internal error
+
+TF-M usage
+""""""""""
+
+This function is used to identify a new non-secure thread that may be identified
+as a client in the non-secure domain. The ``module`` parameter is unused. The
+returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array
+where the client ID for the newly allocated context is stored.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
+
+Context freeing: TZ_FreeModuleContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Free context memory that was previously allocated with TZ_AllocModuleContext_S
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+This function indicates that a non-secure client is inactive, meaning that any
+subsequent references to the client ID are considered erroneous. In effect, the
+client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as
+free.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
+
+Context activation: TZ_LoadContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Load secure context (called on RTOS thread context switch)
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+The client ID indexed by ``(id – 1)`` becomes the active NS client. Any
+subsequent secure service requests coming from non-secure domain will be
+associated with this client ID.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
+
+Context deactivation: TZ_StoreContext_S
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Store secure context (called on RTOS thread context switch)
+
+Parameters
+""""""""""
+
+``id`` [input]: TrustZone memory slot identifier
+
+Return value
+""""""""""""
+
+Execution status (1: success, 0: error)
+
+TF-M usage
+""""""""""
+
+The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure
+service requests coming from non-secure domain will be invalid until a new NS
+context is loaded.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
+
+Security implications (to be assessed separately if needed)
+-----------------------------------------------------------
+
+If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed
+to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee
+non-secure client isolation. Support for this API is only an enabler for a
+non-secure RTOS feature.
+
+Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of
+assets owned by secure entities to non-secure actors after the introduction of
+this feature as a malicious NS handler can only ever assume the identity of
+another non-secure client and cannot elevate its access privileges to those of
+secure clients.
+
+Known client list
+=================
+
+Description
+-----------
+
+A different – but related – API to that defined by CMSIS is proposed in this
+design to register a specific client ID to the active non-secure thread.
+
+The purpose of this API is to provide non-secure privileged code with the
+ability to associate the active non-secure context with a pre-defined identity.
+This enables the application of a pre-set access policy on the secure side to be
+applied to the non-secure thread.
+
+Use cases
+---------
+
+It is valid for non-secure privileged code to only support the TF-M-specific API
+defined below and not the CMSIS TZ API defined previously. In this case the
+single non-secure client is still able to access resources based on a
+pre-defined access policy in secure services without relying on the default
+non-secure identity configured in TF-M.
+
+If used in conjunction with the TZ API, this function can provide a means to
+assign and identify multiple non-secure client IDs based on the active context,
+overriding TF-M’s default non-secure client identity assignment policy.
+
+API definition
+--------------
+
+NS RTOS client registration API – secure function calls from NS handler mode to
+TF-M Core to associate a “known” Client ID to the active non-secure thread.
+
+Register specific client ID: ``tfm_register_client_id``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assign client ID to the current TZ context.
+
+**Note**: This function must be called from handler mode so that TF-M can verify
+that it was sent by a privileged entity.
+
+This function call must follow all TZ_AllocModuleContext_S function calls to
+override the default NS client IDs allocated by TF-M.
+
+Secure and non-secure client IDs are allocated from different ranges (negative
+IDs for non-secure clients, positive for secure clients). The function call is
+rejected if called with a secure ID.
+
+Parameters
+""""""""""
+
+``ns_client_id`` [input]: The client ID to be assigned to the current context
+
+Return value
+""""""""""""
+
+``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error
+code in case of error.
+
+Signature
+"""""""""
+
+.. code-block:: c
+
+ enum tfm_status_e tfm_register_client_id (int32_t ns_client_id);
+
+********************
+Implementation notes
+********************
+
+Option to reduce required context switch notifications
+======================================================
+
+According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called
+"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at
+thread context switch before running a thread". The API definition does not
+define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are
+made without an interleaving StoreContext.
+
+The proposal for TF-M is to accept this as a valid scenario where the second
+``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with
+the previous active Memory_Id.
+
+This assumption does not alter the intended use of ``TZ_StoreContext_S()``,
+which remains a valid call with the behaviour as defined in the
+`API definition`_ section above.
+
+******************************************
+Investigations, improvements, alternatives
+******************************************
+
+Concurrent secure service requests
+==================================
+
+If there are concurrent services requests, TF-M needs to identify the client for
+each request and should make their corresponding context available in the secure
+domain. Client ID needs to be associated with the secure service request so that
+a NS context switch does not break client identification.
+
+If a non-secure client is blocked on an asynchronous secure service completion,
+the NS TFM library must provide a semaphore the NS thread can wait on, whereby
+NS RTOS can schedule a different context.
+
+Should a secure service completion happen for an inactive NS context, a
+notification mechanism needs to be created to activate the given NS context.
+
+The proposal is for the NS TFM library to include a NS IRQ handler for a
+reserved interrupt signal. The ISR would identify the context to be activated
+and release the corresponding semaphore.
+
+NS to S priority inheritance
+============================
+
+Whether or not NS thread priorities should be influencing secure service
+prioritization needs to be analysed. It is raised as a topic of discussion and
+is not detailed in this document further at this stage.
+
+NS privilege check for secure function calls
+============================================
+
+Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to
+call context management veneers in handler mode. This can be a more generic
+approach, but implications are to be investigated.
+
+**********
+References
+**********
+
+Description of the TZ API:
+https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/technical_references/tfm_ns_client_identification.rst b/docs/technical_references/tfm_ns_client_identification.rst
new file mode 100644
index 0000000000..44fd3435ad
--- /dev/null
+++ b/docs/technical_references/tfm_ns_client_identification.rst
@@ -0,0 +1,43 @@
+###########################
+Non-Secure Identity Manager
+###########################
+The ID of the current application/thread is known by TF-M, and the PS service
+queries the ID of the currently running client via a dedicated API.
+
+The identity of secure clients can be tracked by TF-M core, because it also
+manages the contexts of the partitions. However to differentiate NS clients, it
+relies on the services provided by the NS OS.
+
+Tracking of context changes are possible by relying on the NS OS calling the
+Thread Context Management for Armv8-M TrustZone APIs, as described
+`here `__
+
+However TF-M needs an extra API, to assign a client ID to the TZ context created
+as a result of the
+``TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module)`` call.
+
+To do this, the
+``enum tfm_status_e tfm_register_client_id (int32_t ns_client_id)`` have to be
+called from an SVC handler, with the client ID of the currently running client.
+
+In the current implementation of TF-M, an SVC call is provided for the NS
+clients to be called at the beginning of their main function.
+
+``SVC(SVC_TFM_NSPM_REGISTER_CLIENT_ID);``
+
+The SVC call handler of the above SVC maps the name of the current thread to a
+hardcoded client id, and sends it to the TF-M core via the earlier discussed
+API.
+
+The mapping is implemented in ``interface/src/tfm_nspm_svc_handler.c``.
+
+The system integrators **may** implement the non-secure ID mapping based on
+their application/threat model.
+
+In case the NS OS doesn't use the Thread Context Management for Armv8-M
+TrustZone APIs, then TF-M considers the NS SW as a single client, and assigns a
+client ID to it automatically.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_partition_and_service_design_document.rst b/docs/technical_references/tfm_partition_and_service_design_document.rst
new file mode 100644
index 0000000000..500e7a11dd
--- /dev/null
+++ b/docs/technical_references/tfm_partition_and_service_design_document.rst
@@ -0,0 +1,150 @@
+#####################################
+Partition and Service Design Document
+#####################################
+
+:Authors: Summer Qin
+:Organization: Arm Limited
+:Contact: summer.qin@arm.com
+:Status: Accepted
+
+***********
+Terminology
+***********
+Secure Partition - A thread of execution with protected runtime state within the
+Secure Processing Environment. Container for the implementation of one or more
+RoT Services. Multiple Secure Partitions are allowed in a platform.
+SPM - Secure Partition Manager.
+
+***************
+Design Overview
+***************
+As the PSA Firmware Framework described: "A Secure Partition is one execution
+environment. Partition provides access to resources, protection of its own code
+and data and mechanisms to interact with other components in the system. Each
+Secure Partition is a single thread of execution and is the smallest unit of
+isolation: if the strongest isolation level is implemented, every Secure
+Partition is isolated from every other Secure Partition.
+Security functionality is exposed by PSA as a collection of Root of Trust
+Services. Each RoT Service is a set of related security functionality. RoT
+Service are typically implemented within a Secure Partition."
+
+******************
+Partition Database
+******************
+Partition Database collects partition information of all existing partitions.
+These partitions are built together as built-in partitions at the current stage.
+Partition's code and private date are put into dedicated regions, while
+Partition Database are put in TF-M SPM region. There is a defined structure for
+partition information:
+
+.. code-block:: c
+
+ struct spm_partition_desc_t {
+ struct spm_partition_runtime_data_t runtime_data;
+ const struct spm_partition_static_data_t *static_data;
+ const struct platform_data_t *platform_data;
+ };
+
+The structure describes the partition information from four aspects and every
+structure member has its own detailed members. These members can be recorded in
+partition information:
+
+- Runtime data contains runtime change-able members like context, stack and so
+ on.
+- Static data contains partition id, flags, priority and init function entry.
+- Platform data contains a single peripheral's information this partition owns.
+ This is a little different from the PSA Firmware Framework defines.
+- Memory data contains partition memory region address and size.
+
+These data types with different names also have different accessing attribute
+requirements and can be put in memory with different attributes. The listed four
+types of data can be defined with a different qualifier to indicate the
+accessing attribute and finally, these data are linked into a global structure
+type 'spm_partition_desc_t' for usage. Define the global partition_list array to
+store all the partitions information and all members are set to zero so that
+partition_list will be stored in bss segment. For static information, like
+static member, platform member, and some memory data, assign this information
+with 'const' qualifier. This would avoid involving unnecessary read-only data
+into the read-write area and cause storage waste. The partition's database is
+managed by the following steps:
+
+#. The four types of data are defined with different qualifier in
+ 'tfm_spm_db.inc'. For example, static data is qualified with 'const' to
+ indicate it is a read-only data.
+#. Include partition predefined static information in spm_api.c by adding the
+ tfm_spm_db.inc file.
+#. Initialize the partition runtime information
+#. Assign the static data, platform data and memory data to corresponding
+ partition.
+
+Partition Database Generating
+=============================
+Partition Database is represented as a global array that contains objects of
+type spm_partition_desc_t. The include file named tfm_spm_db.inc contains this
+array which is auto-generated from tfm_spm_db.inc.template by a tool script
+named as 'tfm_parse_manifest_list.py'. This tool parses partition manifests and
+converts members in manifest into the array member.
+
+Partition Database Initialization
+=================================
+The dedicated partition information file will be added into spm initialization
+file to initialize the global spm data array g_spm_partition_db.
+
+.. code-block:: c
+
+ #include "secure_fw/partitions/tfm_spm_db.inc"
+
+Built-in Partitions
+===================
+Currently, there are two built-in internal partitions which have no manifest,
+and all the information is statically defined. These two partitions are:
+non-secure partition and core partition. They are added to the first and second
+position of the array.
+
+****************
+Service Database
+****************
+Each Secure Partition can host one or more RoT Services. Typically, related
+services that share underlying functionality or data would be implemented within
+the same Secure Partition.
+All the services are registered in every partition's manifest. There is a
+defined structure for service information:
+
+.. code-block:: c
+
+ struct tfm_spm_service_t {
+ const struct tfm_spm_service_db_t *service_db;
+ struct spm_partition_desc_t *partition;
+ struct bi_list_node_t handle_list;
+ struct tfm_msg_queue_t msg_queue;
+ struct bi_list_node_t list;
+ };
+
+These members are necessary for a service and the following bullets explain the
+members:
+
+- Service database contains service name, partition id, service signal, service
+ identifier, non-secure client(if it can be called by non-secure client),
+ version and version_policy.
+- Partition points to the secure partition data.
+- Handle list contains the handle connected to the service.
+- Message queue contains the message for the service.
+- List is the service list indicator. It is a double-chain list node.
+
+The member tfm_spm_service_db_t contains statically defined service information.
+This variable can be defined statically with a qualifier 'const' to put it into
+the read-only data.
+The service information is managed by the following steps:
+
+#. Define five types of data with different qualifiers in
+ 'tfm_service_list.inc'. For example, service db is qualified with 'const' to
+ indicate it is a read-only data.
+#. Include service predefined static information in spm_api_ipc.c by adding the
+ tfm_service_list.inc file.
+#. Assign the service db to the corresponding service.
+#. Get the corresponding partition information and link with the service.
+#. Initialize the handle_list of every service.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_physical_attack_mitigation.rst b/docs/technical_references/tfm_physical_attack_mitigation.rst
new file mode 100644
index 0000000000..a167d12530
--- /dev/null
+++ b/docs/technical_references/tfm_physical_attack_mitigation.rst
@@ -0,0 +1,626 @@
+#################################################
+Physical attack mitigation in Trusted Firmware-M
+#################################################
+
+:Authors: Tamas Ban; David Hu
+:Organization: Arm Limited
+:Contact: tamas.ban@arm.com; david.hu@arm.com
+:Status: Draft
+
+************
+Requirements
+************
+PSA Certified Level 3 Lightweight Protection Profile [1]_ requires protection
+against physical attacks. This includes protection against manipulation of the
+hardware and any data, undetected manipulation of memory contents, physical
+probing on the chip's surface. The RoT detects or prevents its operation outside
+the normal operating conditions (such as voltage, clock frequency, temperature,
+or external energy fields) where reliability and secure operation has not been
+proven or tested.
+
+.. note::
+
+ Mitigation against certain level of physical attacks is a mandatory
+ requirement for PSA Level 3 certification.
+ The :ref:`tf-m-against-physical-attacks` discussed below
+ doesn't provide mitigation against all the physical attacks considered in
+ scope for PSA L3 certification. Please check the Protection Profile document
+ for an exhaustive list of requirements.
+
+****************
+Physical attacks
+****************
+The goal of physical attacks is to alter the expected behavior of a circuit.
+This can be achieved by changing the device's normal operating conditions to
+untested operating conditions. As a result a hazard might be triggered on the
+circuit level, whose impact is unpredictable in advance but its effect can be
+observed. With frequent attempts, a weak point of the system could be identified
+and the attacker could gain access to the entire device. There is a wide variety
+of physical attacks, the following is not a comprehensive list rather just give
+a taste of the possibilities:
+
+ - Inject a glitch into the device power supply or clock line.
+ - Operate the device outside its temperature range: cool down or warm it up.
+ - Shoot the chip with an electromagnetic field. This can be done by passing
+ current through a small coil close to the chip surface, no physical contact
+ or modification of the PCB (soldering) is necessary.
+ - Point a laser beam on the chip surface. It could flip bits in memory or a
+ register, but precise knowledge of chip layout and design is necessary.
+
+The required equipment and cost of these attacks varies. There are commercial
+products to perform such attacks. Furthermore, they are shipped with a scripting
+environment, good documentation, and a lot of examples. In general, there is a
+ton of videos, research paper and blogs about fault injection attacks. As a
+result the threshold, that even non-proficient can successfully perform such
+attack, gets lower over time.
+
+*****************************************************************
+Effects of physical attacks in hardware and in software execution
+*****************************************************************
+The change in the behavior of the hardware and software cannot be seen in
+advance when performing a physical attack. On circuit-level they manifest
+in bit faults. These bit faults can cause varied effects in the behavior of
+the device micro-architecture:
+
+ - Instruction decoding pipeline is flushed.
+ - Altering instructions when decoding.
+ - Altering data when fetching or storing.
+ - Altering register content, and the program counter.
+ - Flip bits in register or memory.
+
+These phenomenons happen at random and cannot be observed directly but the
+effect can be traced in software execution. On the software level the following
+can happen:
+
+ - A few instructions are skipped. This can lead to taking different branch
+ than normal.
+ - Corrupted CPU register or data fetch could alter the result of a comparison
+ instruction. Or change the value returned from a function.
+ - Corrupted data store could alter the config of peripherals.
+ - Very precise attacks with laser can flip bits in any register or in memory.
+
+This is a complex domain. Faults are not well-understood. Different fault models
+exist but all of them target a specific aspect of fault injection. One of the
+most common and probably the easily applicable fault model is the instruction
+skip.
+
+***********************************
+Mitigation against physical attacks
+***********************************
+The applicability of these attacks highly depends on the device. Some
+devices are more sensitive than others. Protection is possible at hardware and
+software levels as well.
+
+On the hardware level, there are chip design principles and system IPs that are
+resistant to fault injection attacks. These can make it harder to perform a
+successful attack and as a result the chip might reset or erase sensitive
+content. The device maker needs to consider what level of physical attack is in
+scope and choose a SoC accordingly.
+
+On top of hardware-level protection, a secondary protection layer can be
+implemented in software. This approach is known as "defence in depth".
+
+Neither hardware nor software level protection is perfect because both can be
+bypassed. The combination of them provides the maximum level of protection.
+However, even when both are in place, it is not certain that they provide 100%
+protection against physical attacks. The best of what is to achievable to harden
+the system to increase the cost of a successful attack (in terms of time and
+equipment), thereby making it non profitable to perform them.
+
+.. _phy-att-countermeasures:
+
+Software countermeasures against physical attacks
+=================================================
+There are practical coding techniques which can be applied to harden software
+against fault injection attacks. They significantly decrease the probability of
+a successful attack:
+
+ - Control flow monitor
+
+ To catch malicious modification of the expected control flow. When an
+ important portion of a program is executed, a flow monitor counter is
+ incremented. The program moves to the next stage only if the accumulated
+ flow monitor counter is equal to an expected value.
+
+ - Default failure
+
+ The return value variable should always contain a value indicating
+ failure. Changing its value to success is done only under one protected
+ flow (preferably protected by double checks).
+
+ - Complex constant
+
+ It is hard to change a memory region or register to a pre-defined value, but
+ usual boolean values (0 or 1) are easier to manipulate.
+
+ - Redundant variables and condition checks
+
+ To make branch condition attack harder it is recommended to check the
+ relevant condition twice (it is better to have a random delay between the
+ two comparisons).
+
+ - Random delay
+
+ Successful fault injection attacks require very precise timing. Adding
+ random delay to the code execution makes the timing of an attack much
+ harder.
+
+ - Loop integrity check
+
+ To avoid to skip critical loop iterations. It can weaken the cryptographic
+ algorithms. After a loop has executed, check the loop counter whether it
+ indeed has the expected value.
+
+ - Duplicated execution
+
+ Execute a critical step multiple times to prevent fault injection from
+ skipping the step. To mitigate multiple consecutive fault injections, random
+ delay can be inserted between duplicated executions.
+
+These techniques should be applied in a thoughtful way. If it is applied
+everywhere then it can result in messy code that makes the maintenance harder.
+Code must be analysed and sensitive parts and critical call path must be
+identified. Furthermore, these techniques increase the overall code size which
+might be an issue on the constrained devices.
+
+Currently, compilers are not providing any support to implement these
+countermeasures automatically. On the contrary, they can eliminate the
+protection code during optimization. As a result, the C level protection does
+not add any guarantee about the final behavior of the system. The effectiveness
+of these protections highly depends on the actual compiler and the optimization
+level. The compiled assembly code must be visually inspected and tested to make
+sure that proper countermeasures are in-place and perform as expected.
+
+.. _phy-att-threat-model:
+
+******************************************
+TF-M Threat Model against physical attacks
+******************************************
+
+Physical attack target
+======================
+A malicious actor performs physical attack against TF-M to retrieve assets from
+device. These assets can be sensitive data, credentials, crypto keys. These
+assets are protected in TF-M by proper isolation.
+
+For example, a malicious actor can perform the following attacks:
+
+ - Reopen the debug port or hinder the closure of it then connect to the device
+ with a debugger and dump memory.
+ - Bypass secure boot to replace authentic firmware with a malicious image.
+ Then arbitrary memory can be read.
+ - Assuming that secure boot cannot be bypassed then an attacker can try to
+ hinder the setup of the memory isolation hardware by TF-M
+ :term:`Secure Partition Manager` (SPM) and manage to execute the non-secure
+ image in secure state. If this is achieved then still an exploitable
+ vulnerability is needed in the non-secure code which can be used to inject
+ and execute arbitrary code to read the assets.
+ - Device might contain unsigned binary blob next to the official firmware.
+ This can be any data, not necessarily code. If an attacker manages to
+ replace this data with arbitrary content (e.g. a NOP slide leading to a
+ malicious code) then they can try to manipulate the program counter to jump
+ to this area before setting up the memory isolation.
+
+.. _attacker-capability:
+
+Assumptions on attacker capability
+==================================
+It is assumed that the attacker owns the following capabilities to perform
+physical attack against devices protected by TF-M.
+
+ - Has physical access to the device.
+ - Able to access external memory, read and possibly tamper it.
+ - Able to load arbitrary candidate images for firmware upgrade.
+ - Able to manage that bootloader tries to upgrade the arbitrary image from
+ staging area.
+ - Able to inject faults on hardware level (voltage or power glitch, EM pulse,
+ etc.) to the system.
+ - Precise timing of fault injection is possible once or a few times, but in
+ general the more intervention is required for a successful attack the harder
+ will be to succeed.
+
+It is out of the scope of TF-M mitigation if an attacker is able to directly
+tamper or disclose the assets. It is assumed that an attacker has the following
+technical limitations.
+
+ - No knowledge of the image signing key. Not able to sign an arbitrary image.
+ - Not able to directly access to the chip through debug port.
+ - Not able to directly access internal memory.
+ - No knowledge of the layout of the die or the memory arrangement of the
+ secure code, so precise attack against specific registers or memory
+ addresses are out of scope.
+
+Physical attack scenarios against TF-M
+======================================
+Based on the analysis above, a malicious actor may perform physical attacks
+against critical operations in :term:`SPE` workflow and critical modules in
+TF-M, to indirectly gain unauthenticated accesses to assets.
+
+Those critical operations and modules either directly access the assets or
+protect the assets from disclosure. Those operations and modules can include:
+
+ - Image validation in bootloader
+ - Isolation management in TF-M, including platform specific configuration
+ - Cryptographic operations
+ - TF-M Secure Storage operations
+ - PSA client permission check in TF-M
+
+The detailed scenarios are discussed in following sections.
+
+Physical attacks against bootloader
+-----------------------------------
+Physical attacks may bypass secure image validation in bootloader and a
+malicious image can be installed.
+
+The countermeasures is bootloader specific implementation and out of the scope
+of this document. TF-M relies on MCUboot by default. MCUboot has already
+implemented countermeasures against fault injection attacks [3]_.
+
+.. _physical-attacks-spm:
+
+Physical attacks against TF-M SPM
+---------------------------------
+TF-M SPM initializes and manages the isolation configuration. It also performs
+permission check against secure service requests from PSA clients.
+
+Static isolation configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+It is TF-M SPM's responsibility to build up isolation during the initialization
+phase. If this is missed or not done correctly then it might be possible for
+non-secure code to access some secure memory area or an external device can
+access assets in the device through a debug port.
+
+Therefore, hindering the setup of memory or peripheral isolation hardware is an
+obvious candidate for physical attacks. The initialization phase has a constant
+time execution (like the previous boot-up state), therefore the timing of the
+attack is simpler, compared to cases when secure and non-secure runtime firmware
+is up-and-running for a while and IRQs make timing unpredictable.
+
+Some examples of attacking isolation configuration are shown in the list below.
+
+ - Hinder the setting of security regions. Try to execute non-secure code as
+ secure.
+ - Manipulate the setting of secure regions, try to extend the non-secure
+ regions to cover a memory area which otherwise is intended to be secure
+ area.
+ - Hinder the setting of isolation boundary. In this case vulnerable ARoT code
+ has access to all memory.
+ - Manipulate peripheral configuration to give access to non-secure code to a
+ peripheral which is intended to be secure.
+
+PSA client permission checks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+TF-M SPM performs several permission checks against secure service requests from
+a PSA client, such as:
+
+- Check whether the PSA client is a non-secure client or a secure client
+
+ NS client's PSA client ID is negative. NS client is not allowed to directly
+ access secure areas. A malicious actor can inject faults when TF-M SPM
+ authenticates a NS client. It may manipulate TF-M to accept it as a secure
+ client and allow the NS client to access assets.
+
+- Memory access checks
+
+ TF-M SPM checks whether the request has correct permission to access a secure
+ memory area. A malicious actor can inject faults when TF-M SPM checks memory
+ access permission. It may skip critical check steps or corrupt the check
+ result. Thereby a malicious service request may pass TF-M memory access check
+ and accesses assets which it is not allowed to.
+
+The physical attacks mentioned above relies on the a malicious NS application or
+a vulnerable RoT service to start a malicious secure service request to access
+the assets. The malicious actor has to be aware of the accurate timing of
+dealing with the malicious request in TF-M SPM. The timing can be affected by
+other clients and interrupts.
+It should be more difficult than pure fault injection.
+
+Dynamic isolation boundary configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Physical attack may affect the isolation boundary setting during TF-M context
+switch, especially in Isolation Level 3. For example:
+
+ - A fault injection may cause TF-M SPM to skip clear privileged state before
+ switching in an ARoT service.
+ - A fault injection may cause TF-M SPM to skip updating MPU regions and
+ therefore the next RoT service may access assets belonging to a previous
+ one.
+
+However, it is much more difficult to find out the accurate timing of TF-M
+context switch, compared to other scenarios in TF-M SPM. It also requires a
+vulnerable RoT service to access assets after fault injection.
+
+Physical attacks against TF-M Crypto service
+--------------------------------------------
+Since crypto operations are done by mbedTLS library or by a custom crypto
+accelerator engine and its related software driver stack, the analysis of
+physical attacks against crypto operations is out-of-scope for this document.
+However, in general the same requirements are applicable for the crypto, to be
+compliant with PSA Level 3 certification. That is, it must be resistant against
+physical attacks. So crypto software and hardware must be hardened against
+side-channel and physical attacks.
+
+Physical attacks against Secure Storage
+---------------------------------------
+Physical attacks against Internal Trusted Storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Based on the assumption in :ref:`attacker-capability`, a malicious actor is
+unable to directly retrieve assets via physical attacks against
+:term:`Internal Trusted Storage` (ITS).
+
+Instead, a malicious actor can inject faults into isolation configuration of ITS
+area in TF-M SPM to gain the access to assets stored in ITS. Refer to
+:ref:`physical-attacks-spm` for details.
+
+Physical attacks against Protected Storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Based on the assumption in :ref:`attacker-capability`, a malicious actor can be
+able to directly access external storage device.
+Therefore :term:`Protected Storage` (PS) shall enable encryption and
+authentication by default to detect tampering with the content in external
+storage device.
+
+A malicious actor can also inject faults into isolation configuration of PS and
+external storage device peripherals in TF-M SPM to gain the access to assets
+stored in PS. Refer to :ref:`physical-attacks-spm` for details.
+
+It is out of the scope of TF-M to fully prevent malicious actors from directly
+tampering with or retrieving content stored in external storage devices.
+
+Physical attacks against platform specific implementation
+---------------------------------------------------------
+Platform specific implementation includes critical TF-M HAL implementations.
+A malicious actor can perform physical attack against those platform specific
+implementations to bypass the countermeasures in TF-M common code.
+
+Debug access setting
+^^^^^^^^^^^^^^^^^^^^
+TF-M configures debug access according to device lifecycle and accessible debug
+certificates. In general, TF-M locks down the debug port if the device is in
+secure production state. TF-M exposed a HAL API for this purpose.
+The system integrator is responsible to implement this API on a particular SoC
+and harden it against physical attacks:
+
+.. code-block:: c
+
+ enum tfm_plat_err_t tfm_spm_hal_init_debug(void);
+
+Platform specific isolation configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+TFM SPM exposes a HAL API for static and dynamic isolation configuration. The
+system integrator is responsible to implement these API on a particular SoC and
+harden it against physical attacks.
+
+.. code-block:: c
+
+ enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(void);
+ enum tfm_plat_err_t tfm_spm_hal_configure_default_isolation(
+ uint32_t partition_idx,
+ const struct platform_data_t *platform_data);
+ enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start,
+ uintptr_t end);
+
+Memory access check
+^^^^^^^^^^^^^^^^^^^
+TFM SPM exposes a HAL API for platform specific memory access check. The
+system integrator is responsible to implement these API on a particular SoC and
+harden it against physical attacks.
+
+.. code-block:: c
+
+ tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base,
+ size_t size,
+ uint32_t attr);
+
+.. _tf-m-against-physical-attacks:
+
+*********************************************
+TF-M countermeasures against physical attacks
+*********************************************
+This section propose a design of software countermeasures against physical
+attacks.
+
+Fault injection hardening library
+=================================
+There is no open-source library which implements generic mitigation techniques
+listed in :ref:`phy-att-countermeasures`.
+TF-M project implements a portion of these techniques. TF-M software
+countermeasures are implemented as a small library Fault Injection Hardening
+(FIH) in TF-M code base. A similar library was first introduced and tested in
+the MCUboot project (version 1.7.0) [2]_ which TF-M relies on.
+
+The FIH library is put under TF-M ``lib/fih/``.
+
+The implementation of the different techniques was assigned to fault injection
+protection profiles. Four profile (OFF, LOW, MEDIUM, HIGH) was introduced to fit
+better to the device capability (memory size, TRNG availability) and to
+protection requirements mandated by the device threat model. Fault injection
+protection profile is configurable at compile-time, default value: OFF.
+
+Countermeasure profiles and corresponding techniques are listed in the table
+below.
+
++--------------------------------+-------------+----------------+--------------+------------------+
+| Countermeasure | Profile LOW | Profile MEDIUM | Profile HIGH | Comments |
++================================+=============+================+==============+==================+
+| Control flow monitor | Y | Y | Y | |
++--------------------------------+-------------+----------------+--------------+------------------+
+| Failure loop hardening | Y | Y | Y | |
++--------------------------------+-------------+----------------+--------------+------------------+
+| Complex constant | | Y | Y | |
++--------------------------------+-------------+----------------+--------------+------------------+
+| Redundant variables and checks | | Y | Y | |
++--------------------------------+-------------+----------------+--------------+------------------+
+| Random delay | | | Y | Implemented, but |
+| | | | | depends on HW |
+| | | | | capability |
++--------------------------------+-------------+----------------+--------------+------------------+
+
+Similar to MCUboot four profiles are supported, it can be configured at build
+time by setting(default is OFF):
+
+ ``-DTFM_FIH_PROFILE=``
+
+How to use FIH library
+======================
+As analyzed in :ref:`phy-att-threat-model`, this section focuses on integrating
+FIH library in TF-M SPM to mitigate physical attacks.
+
+ - Identify critical function call path which is mandatory for configuring
+ isolation or debug access. Transfer them to ``fih_int`` functions with the
+ usage of ``FIH_CALL`` and ``FIH_RET`` macros. These are providing the extra
+ checking functionality (control flow monitor, redundant checks and
+ variables, random delay, complex constant) according to the profile
+ settings. More details about usage can be found here:
+ ``tf-m/lib/fih/inc/fault_injection_hardening.h``
+
+ Take simplified TF-M SPM initialization flow as an example:
+
+ .. code-block:: c
+
+ main()
+ |
+ |--> tfm_core_init()
+ | |
+ | |--> tfm_spm_hal_init_debug()
+ | | |
+ | | |--> platform specific debug init
+ | |
+ | |--> tfm_hal_set_up_static_boundaries()
+ | |
+ | |--> platform specific isolation impl.
+ |
+ |--> During each partition initialization
+ |
+ |--> tfm_spm_hal_configure_default_isolation()
+ |
+ |--> platform specific peripheral
+ isolation impl.
+
+ - Might make the important setting of peripheral config register redundant
+ and verify them to match expectations before continue.
+
+ - Implements an extra verification function which checks the critical hardware
+ config before secure code switches to non-secure. Proposed API for this
+ purpose:
+
+ .. code-block:: c
+
+ fih_int tfm_spm_hal_verify_isolation_hw(void);
+
+ This function is intended to be called just before the security state
+ transition and is responsible for checking all critical hardware
+ configuration. The goal is to catch if something is missed and act according
+ to system policy. The introduction of one more checking point requires one
+ more intervention with precise timing. The system integrator is responsible
+ to implement this API on a particular SoC and harden it against physical
+ attacks. Make sure that all platform dependent security feature is properly
+ configured.
+
+ - The most powerful mitigation technique is to add random delay to the code
+ execution. This makes the timing of the attack much harder. However it
+ requires an entropy source. It is recommended to use the ``HIGH`` profile
+ when hardware support is available. There is a porting API layer to fetch
+ random numbers in FIH library:
+
+ .. code-block:: c
+
+ int fih_delay_init(void);
+ unsigned char fih_delay_random_uchar(void);
+
+ - Similar countermeasures can be implemented in critical steps in platform
+ specific implementation.
+
+ Take memory isolation settings on AN521 and Musca-B1 platforms as an
+ example.
+ The following hardware components are responsible for memory isolation in a
+ SoC, which is based on SSE-200 subsystem.
+ System integrators must examine the chip specific memory isolation solution,
+ identify the key components and harden the configuration of those.
+ This list just serves as an example here for easier understanding:
+
+ - Implementation Defined Attribution Unit (IDAU): Implementation defined,
+ it can be a static config or dynamic.
+ Contains the default security access permissions of the memory map.
+ - SAU: The main module in the CPU to determine the security settings of
+ the memory.
+ - :term:`MPC`: External module from the CPU point of view. It protects the
+ non security aware memories from unauthenticated access. Having a
+ properly configured MPC significantly increases the security of the
+ system.
+ - :term:`PPC`: External module from the CPU
+ point of view. Protects the non security aware peripherals from
+ unauthenticated access.
+ - MPU: Protects memory from unprivileged access. ARoT code has only a
+ restricted access in secure domain. It mitigates that a vulnerable or
+ malicious ARoT partition can access to device assets.
+
+ The following AN521/Musca-B1 specific isolation configuration functions
+ shall be hardened against physical attacks.
+
+ .. code-block:: c
+
+ sau_and_idau_cfg()
+ mpc_init_cfg()
+ ppc_init_cfg()
+
+ Some platform specific implementation rely on platform standard device
+ driver libraries. It can become much more difficult to maintain drivers if
+ the standard libraries are modified with FIH library. Platform specific
+ implementation can implement duplicated execution and redundant variables/
+ condition check when calling platform standard device driver libraries
+ according to usage scenarios.
+
+Impact on code size
+===================
+The addition of protection code against physical attacks increases the code
+size. The actual increase depends on the selected profile and where the
+mitigation code is added.
+
+Attack experiment with SPM
+==========================
+The goal is to bypass the setting of memory isolation hardware with simulated
+instruction skips in fast model execution (FVP_MPS2_AEMv8M) in order to execute
+the regular non-secure test code in secure state. This is done by identifying
+the configuration steps which must be bypassed to make this happen. The
+instruction skip simulation is achieved by breakpoints and manual manipulation
+of the program counter. The following steps are done on AN521 target, but this
+can be different on another target:
+
+ - Bypass the configuration of isolation HW: SAU, MPC.
+ - Bypass tfm_spm_hal_nvic_interrupt_enable: The state of the MPC is checked
+ here whether is it initialized or not.
+ - Bypass the setting of the PSP limit register. Otherwise, a stack overflow
+ exception will happen. Because the secure PSP will be overwritten by the
+ address of the non-secure stack and on this particular target the non-secure
+ stack is on lower address than the value in the secure PSP_LIMIT register.
+ - Avoid the clearing of the least significant bit in the non-secure entry
+ point, where BLXNS/BXNS is jumping to non-secure code. Having the least
+ significant bit cleared indicates to the hardware to switch security state.
+
+The previous steps are enough to execute the non-secure Reset_Handler() in
+secure state. Usually, RTOS is executing on the non-secure side. In order to
+properly boot it up further steps are needed:
+
+ - Set the S_VTOR system register to point the address of the NS Vector table.
+ Code is executed in secure state therefore when an IRQ hit then the handler
+ address is fetched from the table pointed by S_VTOR register. RTOS usually
+ do an SVC call at start-up. If S_VTOR is not modified then SPM's SVC handler
+ will be executed.
+ - TBC: RTX osKernelStart still failing.
+
+The bottom line is that in order to execute the regular non-secure code in
+secure state the attacker need to interfere with the execution flow at many
+places. Successful attack can be made even harder by adding the described
+mitigation techniques and some random delays.
+
+
+*********
+Reference
+*********
+
+.. [1] `PSA Certified Level 3 Lightweight Protection Profile `_
+
+.. [2] `MCUboot project `_
+
+.. [3] `MCUboot fault injection mitigation `_
diff --git a/docs/technical_references/tfm_psa_inter_process_communication.rst b/docs/technical_references/tfm_psa_inter_process_communication.rst
new file mode 100644
index 0000000000..19691711bc
--- /dev/null
+++ b/docs/technical_references/tfm_psa_inter_process_communication.rst
@@ -0,0 +1,234 @@
+################################
+TF-M Inter-Process Communication
+################################
+
+:Authors: Ken Liu, Mingyang Sun
+:Organization: Arm Limited
+:Contact: ken.liu@arm.com, mingyang.sun@arm.com
+:Status: Accepted
+
+***********
+Terminology
+***********
+
+IPC - Inter-Process Communication
+
+For more terminology please check Reference_ document.
+
+***************
+Design Overview
+***************
+IPC re-uses existed components in library model:
+
+- SPM – for partition information and isolation actions
+- Core – for exception handling
+
+Extra components for implementing IPC:
+
+- Memory pool
+- Message manager
+- Thread
+- Synchronization objects
+- PSA API
+
+**********************
+Implementation Details
+**********************
+Listed modules are all internal modules except PSA API. Prototypes and
+definitions are not listed for internal modules in this document. For PSA
+API definitions, check them in PSA Firmware Framework specification in the
+reference chapter.
+
+SPM and Core
+============
+SPM manages Secure Partition information. Enhancements need to be done in SPM
+data structure for Secure Partition for IPC due to:
+
+- IPC model requires each Secure Partition has its own stack area while
+ isolation level 1 of library model makes all partition shares same stack
+ pointer. This needs to be changed while implementing IPC.
+- Multiple services are holding in same Secure Partition and each service
+ has its own information like message queue, SID and priority.
+- Changed information related manifest items need to be changed, too.
+
+Modifications in Core:
+
+- More SVC calls need to be added into list since PSA API are implemented as
+ SVC calls in TF-M.
+- New PendSV handler for thread scheduling.
+- Arch-related context stacking and switching.
+
+Memory Pool
+===========
+Handles of connection and messages for Secure Partition needs to be allocated
+dynamically. A memory pool is provided in the system to handle dynamic
+allocation. Each memory pool item contains below information:
+
+- A list iterator to chain all of memory pool items.
+- An information member to record information like size and types.
+- The memory item body for caller usage.
+
+A memory area needs to be provided in SPM for the memory pool. It could be an
+array of memory areas defined in the linker script. Two chains are available to
+manage the items: free chain and used chain. And an LRU (Last recent used)
+mechanism is applied for fast seeking while item allocating and destroying.
+
+Message Manager
+===============
+Message Manager handles message creating, pushing, retrieving and destroy. A
+message contains below information:
+
+- Message sender and destination
+- Message status
+- IO vectors for service
+- 'psa_msg_t' for service
+
+A checking needs to be performed in SPM before creating a message to detect if
+a message with the same sender and destination is ongoing. This avoids repeat
+messages are available in the queue.
+
+Thread
+======
+Each Secure Partition has a thread as execution environment. Secure Partition
+is defined statically in TF-M manifest, which indicates that a number of
+threads are statically defined. Threads are chained in SPM and sorted with
+its priority, and there is an extra indicator point to first running thread
+with the highest priority. This helps fast seeking of running threads while
+the scheduler is switching threads.
+
+Thread context contains below information:
+
+- Priority
+- Status
+- Stack pointer
+- Stack pointer limitation
+- Entry
+- Parameter
+- Entry return value
+- Context
+- List iterator
+
+Thread API provides below functions:
+
+- Thread creating and destroying
+- Thread status retrieving and changing
+- Current thread retrieving
+- Thread context switching
+
+PendSV exception in TF-M core is the place thread context APIs been called.
+Before thread switching taking place, isolation status needs to be changed
+based on Secure Partition change and current isolation level – a thread is a
+member of partition which means thread switching caused a partition switching.
+
+Synchronization API
+===================
+A first synchronization object is an event. This could be applied into event
+waiting in the partition, and message response handling in IPC. The event
+object contains below members:
+
+- Owner thread who is waiting for this event
+- Event status (Ready or Not-Ready)
+- List iterator for synchronization objects management
+
+Event API Limitation: could be waited by one thread only.
+
+PSA API
+=======
+This chapter describes the PSA API in an implementation manner.
+
+- API type: could be Client API and Service Partition API
+- Block-able: Block-able API may block caller thread; Non-Block API does not
+ block caller thread.
+- Description: The functionality description and important comments.
+
+.. code-block:: c
+
+ uint32_t psa_framework_version(void);
+ uint32_t psa_version(uint32_t sid);
+
+- Client API
+- Non-Block API
+- These 2 functions are finally handled in SPM and return the framework version
+ or version to the caller.
+
+.. code-block:: c
+
+ psa_handle_t psa_connect(uint32_t sid, uint32_t version);
+ psa_status_t psa_call(psa_handle_t handle, int32_t type,
+ const psa_invec *in_vec, size_t in_len,
+ psa_outvec *out_vec, size_t out_len);
+ void psa_close(psa_handle_t handle);
+
+- Client API
+- Block-able API
+- These 3 APIs are implemented in the same manner and just different
+ parameters. SPM converts each call into a corresponding message with a
+ parameter in the message body and pushes the message into service queue to
+ wait for the response. Scheduler switches to a specified thread (partition)
+ and makes Secure Partition to have chance retrieving and process message.
+ After a message response is returned to the caller, the waiting caller gets
+ to go and get the result.
+
+.. code-block:: c
+
+ psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
+
+- Secure Partition API
+- Block-able API
+- This API blocks caller partition if there is no expected event for it. This
+ function is implemented based on event API.
+
+.. code-block:: c
+
+ void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
+ psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);
+ size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
+ void *buffer, size_t num_bytes);
+ size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx,
+ size_t num_bytes);
+ void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
+ const void *buffer, size_t num_bytes);
+ void psa_reply(psa_handle_t msg_handle, psa_status_t status);
+ void psa_clear(void);
+ void psa_eoi(psa_signal_t irq_signal);
+
+- Secure Partition API
+- Non-Block
+- These APIs do not take the initiative to change caller status. They process
+ data and return the processed data back to the caller.
+
+.. code-block:: c
+
+ void psa_notify(int32_t partition_id);
+
+- Secure Partition API
+- Non-Block
+- This API sets DOORBELL bit in destination partition's event. This API does
+ not take the initiative to change caller status.
+
+.. code-block:: c
+
+ void psa_panic(void);
+
+- Secure Partition API
+- Block-able API
+- This function will terminate execution within the calling Secure Partition
+ and will not return.
+
+*********
+Reference
+*********
+
+| `PSA Firmware Framework specification URL`_
+| `Slides includes IPC basic introduction URL`_
+| `IPC model implementation URL`_
+
+.. _PSA Firmware Framework specification URL: https://pages.arm.com/psa-
+ resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333
+.. _Slides includes IPC basic introduction URL: https://connect.linaro.org/
+ resources/yvr18/sessions/yvr18-108/
+.. _IPC model implementation URL: https://www.youtube.com/watch?v=6wEFoq49qUw
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_boot.rst b/docs/technical_references/tfm_secure_boot.rst
new file mode 100644
index 0000000000..95d3f68ed5
--- /dev/null
+++ b/docs/technical_references/tfm_secure_boot.rst
@@ -0,0 +1,808 @@
+###########
+Secure boot
+###########
+For secure devices it is security critical to enforce firmware authenticity to
+protect against execution of malicious software. This is implemented by building
+a trust chain where each step in the execution chain authenticates the next
+step before execution. The chain of trust in based on a "Root of Trust" which
+is implemented using asymmetric cryptography. The Root of Trust is a combination
+of an immutable bootloader and a public key (ROTPK).
+
+.. Warning::
+ In order to implement a proper chain of trust functionality, it is
+ mandatory that the first stage bootloader and ROTPK is stored in an
+ **immutable** way. To achieve this the bootloader code must be stored and
+ executed from ROM or such part of flash memory which supports write
+ protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If
+ the SoC has a built-in BL1 (immutable) bootloader and the immutability of
+ TF-M secure boot code is not guaranteed then TF-M secure boot code must be
+ authenticated by BL1 bootloader before execution. If immutability of root
+ of trust (first stage bootloader + ROTPK) is not ensured then there is a
+ risk that the secure boot process could be bypassed, which could lead to
+ arbitrary code execution on the device. Current TF-M secure boot code is
+ intended to be a second stage bootloader, therefore it requires
+ authentication before execution. If TF-M secure boot code is used as a first
+ stage bootloader then it must be stored according to the above requirements.
+
+*******************************
+Second stage bootloader in TF-M
+*******************************
+By default, the MCUboot project from
+`GitHub `__ is used as the secure
+bootloader in TF-M. The repository is going to be automatically downloaded by
+CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION``
+CMake variable. If you wish to use a locally downloaded copy, the CMake variable
+``MCUBOOT_PATH`` can be set to its location. This document contains information
+about how MCUboot has been integrated to TF-M. For further information about
+MCUboot design please refer to the `MCUBoot homepage `__.
+
+Bootloader is started when CPU is released from reset. It runs in secure mode.
+It authenticates the firmware image by hash (SHA-256) and digital signature
+(RSA-3072) validation. Public key, that the checks happens against, can be built
+into the bootloader image or can be provisioned to the SoC during manufacturing.
+Metadata of the image is delivered together with the image itself in a header
+and trailer section. In case of successful authentication, bootloader passes
+execution to the secure image. Execution never returns to bootloader until
+next reset.
+
+A default RSA key pair is stored in the repository, public key is in ``keys.c``
+and private key is in ``root-RSA-3072.pem``.
+
+.. Warning::
+ DO NOT use them in production code, they are exclusively for testing!
+
+The private key must be stored in a safe place outside of the repository.
+``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository,
+or installed through the pip package manager) can be used to generate new key
+pairs.
+
+The bootloader can handle the secure and non-secure images independently
+(multiple image boot) or together (single image boot). In case of multiple image
+boot they are signed independently with different keys and they can be updated
+separately. In case of single image boot the secure and non-secure image is
+handled as a single blob, therefore they must be contiguous in the device
+memory. In this case they are signed together and also they can be updated only
+together. In order to have the same artefacts at the end of the build regardless
+of how the images are handled (independently or together) the images are always
+concatenated. In case of single image boot they are concatenated first and then
+signed. In case of multiple image boot they are separately signed first and then
+concatenated. Preparation of payload is done by Python scripts:
+``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M
+payload can be found in: ``/bin/tfm_s_ns_signed.bin``
+
+*********************
+Integration with TF-M
+*********************
+MCUBoot assumes a predefined memory layout which is described below (applicable
+for AN521). It is mandatory to define the primary slot and the secondary slot
+partitions, but their size and location can be changed::
+
+ - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
+ - 0x0008_0000 - 0x000F_FFFF: Primary slot : Single binary blob:
+ Secure + Non-Secure image;
+ Primary memory partition
+ - 0x0008_0000 - 0x0008_03FF: Common image header
+ - 0x0008_0400 - 0x0008_xxxx: Secure image
+ - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF)
+ - 0x0010_0400 - 0x0010_xxxx: Non-secure image
+ - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of combined image
+
+ - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image;
+ Secondary memory partition, structured
+ identically to the primary slot
+ - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image
+ swapping
+
+Multiple image boot requires a slightly different layout::
+
+ - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot
+ - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image
+ - 0x0008_0000 - 0x0008_03FF: Secure image header
+ - 0x0008_0400 - 0x000x_xxxx: Secure image
+ - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of secure image
+
+ - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image
+ - 0x0010_0000 - 0x0010_03FF: Non-secure image header
+ - 0x0010_0400 - 0x001x_xxxx: Non-secure image
+ - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other
+ metadata of non-secure image
+
+ - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image
+ - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image
+
+ - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image
+ swapping, used for secure and non-secure
+ image as well
+
+**************************
+Firmware upgrade operation
+**************************
+MCUBoot handles only the firmware authenticity check after start-up and the
+firmware switch part of the firmware update process. Downloading the new version
+of the firmware is out-of-scope for MCUBoot. MCUBoot supports three different
+ways to switch to the new firmware and it is assumed that firmware images are
+executed-in-place (XIP). The default behaviour is the overwrite-based image
+upgrade. In this case the active firmware is always executed from the primary
+slot and the secondary slot is a staging area for new images. Before executing
+the new firmware image, the content of the primary slot must be overwritten with
+the content of the secondary slot (the new firmware image). The second option is
+the image swapping strategy when the content of the two memory slots must be
+physically swapped. This needs the scratch area to be defined in the memory
+layout. The third option is the direct execute-in-place version, which
+eliminates the complexity of image swapping and its administration. Active image
+can be executed from either memory slot, but new firmware must be linked to the
+address space of the proper (currently inactive) memory slot.
+
+Overwrite operation
+===================
+Active image is stored in the primary slot, and this image is started always by
+the bootloader. Therefore images must be linked to the primary slot. If the
+bootloader finds a valid image in the secondary slot, which is marked for
+upgrade, then the content of the primary slot will be simply overwritten with
+the content of the secondary slot, before starting the new image from the
+primary slot. After the content of the primary slot has been successfully
+overwritten, the header and trailer of the new image in the secondary slot is
+erased to prevent the triggering of another unnecessary image upgrade after a
+restart. The overwrite operation is fail-safe and resistant to power-cut
+failures. For more details please refer to the MCUBoot
+`documentation `__.
+
+Swapping operation
+==================
+This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
+switch (see `Build time configuration`_). With swapping image upgrade strategy
+the active image is also stored in the primary slot and it will always be
+started by the bootloader. If the bootloader finds a valid image in the
+secondary slot, which is marked for upgrade, then contents of the primary slot
+and the secondary slot will be swapped, before starting the new image from the
+primary slot. Scratch area is used as a temporary storage place during image
+swapping. Update mark from the secondary slot is removed when the swapping is
+successful. The boot loader can revert the swapping as a fall-back mechanism to
+recover the previous working firmware version after a faulty update. The swap
+operation is fail-safe and resistant to power-cut failures. For more details
+please refer to the MCUBoot
+`documentation `__.
+
+.. Note::
+
+ After a successful image upgrade the firmware can mark itself as "OK" at
+ runtime by setting the image_ok flag in the flash. When this happens, the
+ swap is made "permanent" and MCUBoot will then still choose to run it
+ during the next boot. Currently TF-M does not set the image_ok flag,
+ therefore the bootloader will always perform a "revert" (swap the images
+ back) during the next boot.
+
+Direct execute-in-place operation
+=================================
+This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time
+switch (see `Build time configuration`_). When enabling direct-xip operation
+then the active image flag is moved between slots during firmware upgrade. If
+firmware is executed-in-place (XIP), then two firmware images must be generated.
+One of them is linked to be executed from the primary slot memory region and the
+other from the secondary slot. The firmware upgrade client, which downloads the
+new image, must be aware, which slot hosts the active firmware and which acts as
+a staging area and it is responsible for downloading the proper firmware image.
+At boot time MCUBoot inspects the version number in the image header and passes
+execution to the newer firmware version. New image must be marked for upgrade
+which is automatically done by Python scripts at compile time. Image
+verification is done the same way in all operational modes. If new image fails
+during authentication then MCUBoot erases the memory slot and starts the other
+image, after successful authentication.
+
+To select which slot the image is to be executed from, set
+``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create
+two build directories when building images using this mode, as intermediate
+dependencies cannot be reused due to changes in the flash layout.
+
+.. Note::
+
+ Only single image boot is supported with direct-xip upgrade mode.
+
+RAM Loading firmware upgrade
+============================
+Musca-S supports an image upgrade mode that is separate to the other (overwrite,
+swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer
+to the table below). Like the direct-xip mode, this selects the newest image
+by reading the image version numbers in the image headers, but instead of
+executing it in place, the newest image is copied to RAM for execution. The load
+address, the location in RAM where the image is copied to, is stored in the
+image header.
+
+.. Note::
+
+ Only single image boot is supported with ``RAM load`` upgrade mode.
+
+Summary of different modes for image upgrade
+============================================
+Different implementations of the image upgrade operation (whether through
+overwriting, swapping, direct-xip or loading into RAM and executing from
+there) are supported by the platforms. The table below shows which of these
+modes are supported by which platforms:
+
++---------------------+-----------------+----------------------------------------------------------+
+| | Without BL2 [1]_| With BL2 [2]_ |
++=====================+=================+===============+==========+================+==============+
+| | XIP | XIP | XIP | XIP | Not XIP |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| | | Overwrite [3]_| Swap [4]_| direct-xip [5]_| RAM load [6]_|
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| AN521 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| AN519 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| FVP_SSE300_MPS2 | No | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| LPC55S69 | Yes | Yes | No | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| Musca-B1 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| Musca-S1 | Yes | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| AN524 | Yes | No | No | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| AN547 | No | Yes | Yes | Yes | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| PSoC64 | Yes | No | No | No | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| STM_DISCO_L562QE | No | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| nRF9160 DK | Yes | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+| nRF5340 PDK/DK | Yes | Yes | No | No | No |
++---------------------+-----------------+---------------+----------+----------------+--------------+
+
+.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF``
+
+.. [2] BL2 is enabled by default
+
+.. [3] The image executes in-place (XIP) and is in Overwrite mode for image
+ update by default
+
+.. [4] To enable XIP Swap mode, assign the "SWAP" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+.. [5] To enable direct-xip, assign the "DIRECT_XIP" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+.. [6] To enable RAM load, assign the "RAM_LOAD" string to the
+ ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build
+ configuration file, or include this macro definition in the command line
+
+*******************
+Multiple image boot
+*******************
+It is possible to update the firmware images independently to support the
+scenario when secure and non-secure images are provided by different vendors.
+Multiple image boot is supported only together with the overwrite and swap
+firmware upgrade modes.
+
+It is possible to describe the dependencies of the images on each other in
+order to avoid a faulty upgrade when incompatible versions would be installed.
+These dependencies are part of the image manifest area.
+The dependencies are composed from two parts:
+
+ - **Image identifier:** The number of the image which the current image (whose
+ manifest area contains the dependency entry) depends on. The image identifier
+ starts from 0.
+
+ - **Minimum version:** The minimum version of other image must be present on
+ the device by the end of the upgrade (both images might be updated at the
+ same time).
+
+Dependencies can be added to the images at compile time with the following
+compile time switches:
+
+ - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the
+ minimum required version of the secure image.
+ - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the
+ minimum required version of the non-secure image.
+
+Example of how to provide the secure image minimum version::
+
+ cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 ..
+
+********************
+Signature algorithms
+********************
+MbedTLS library is used to sign the images. The list of supported signing
+algorithms:
+
+ - `RSA-2048`
+ - `RSA-3072`: default
+
+Example keys stored in:
+
+ - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image
+ in case of multiple image boot
+ - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple
+ image boot
+ - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image
+ in case of multiple image boot
+ - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple
+ image boot
+
+************************
+Build time configuration
+************************
+MCUBoot related compile time switches can be set by cmake variables.
+
+- BL2 (default: True):
+ - **True:** TF-M built together with bootloader. MCUBoot is executed after
+ reset and it authenticates TF-M and starts secure code.
+ - **False:** TF-M built without bootloader. Secure image linked to the
+ beginning of the device memory and executed after reset. If it is false
+ then using any of the further compile time switches is invalid.
+- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"):
+ - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite.
+ - **"SWAP":** Activate swapping firmware upgrade operation.
+ - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade
+ operation.
+ - **"RAM_LOAD":** Activate RAM loading firmware upgrade operation, where
+ the latest image is copied to RAM and runs from there instead of being
+ executed in-place.
+- MCUBOOT_SIGNATURE_TYPE (default: RSA):
+ - **RSA:** Image is signed with RSA algorithm
+- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072):
+ - **2048:** Image is signed with 2048 bit key.
+ - **3072:** Image is signed with 3072 bit key.
+- MCUBOOT_IMAGE_NUMBER (default: 2):
+ - **1:** Single image boot, secure and non-secure images are signed and
+ updated together.
+ - **2:** Multiple image boot, secure and non-secure images are signed and
+ updatable independently.
+- MCUBOOT_HW_KEY (default: True):
+ - **True:** The hash of public key is provisioned to the SoC and the image
+ manifest contains the whole public key (imgtool uses
+ ``--public_key_format=full``). MCUBoot validates the key before using it
+ for firmware authentication, it calculates the hash of public key from the
+ manifest and compare against the retrieved key-hash from the hardware.
+ This way MCUBoot is independent from the public key(s). Key(s) can be
+ provisioned any time and by different parties.
+ - **False:** The whole public key is embedded to the bootloader code and the
+ image manifest contains only the hash of the public key (imgtool uses
+ ``--public_key_format=hash``). MCUBoot validates the key before using it
+ for firmware authentication, it calculates the hash of built-in public key
+ and compare against the retrieved key-hash from the image manifest. After
+ this the bootloader can verify that the image was signed with a private
+ key that corresponds to the retrieved key-hash (it can have more public
+ keys embedded in and it may have to look for the matching one). All the
+ public key(s) must be known at MCUBoot build time.
+- MCUBOOT_LOG_LEVEL:
+ Can be used to configure the level of logging in MCUBoot. The possible
+ values are the following:
+
+ - **OFF**
+ - **ERROR**
+ - **WARNING**
+ - **INFO**
+ - **DEBUG**
+
+ The logging in MCUBoot can be disabled and thus the code size can be reduced
+ by setting it to ``OFF``. Its value depends on the build type. If the build
+ type is ``Debug`` then default value is ``INFO``. In case of different kinds
+ of ``Release`` builds the default value is ``OFF``. The default value can
+ be overridden through the command line or in the CMake GUI regardless of the
+ build type.
+- MCUBOOT_ENC_IMAGES (default: False):
+ - **True:** Adds encrypted image support in the source and encrypts the
+ resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot
+ repository.
+ - **False:** Doesn't add encrypted image support and doesn't encrypt the
+ image.
+
+ .. Note::
+ The decryption takes place during the upgrade process, when the images
+ are being moved between the slots. This means that boards that don't
+ already have an image on them with MCUBoot that has been compiled with
+ ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load
+ an encrypted image to such boards, an upgrade needs to be executed. This
+ can be done by using MCUBoot, putting an image in the secondary image
+ area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the
+ ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using
+ ``SWAP``, an image is needed in the primary image area as well, to
+ trigger the update.
+
+ .. Warning::
+ DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is
+ exclusively for testing!
+
+Image versioning
+================
+An image version number is written to its header by one of the Python scripts,
+and this number is used by the bootloader when the direct execute-in-place or
+the RAM loading mode is enabled. It is also used in case of multiple image boot
+when the bootloader checks the image dependencies if any have been added to the
+images.
+
+The version number of the image (single image boot) can manually be passed in
+through the command line in the cmake configuration step::
+
+ cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=1.2.3+4 ..
+
+Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3),
+where the missing numbers are automatically set to zero. The image version
+number argument is optional, and if it is left out, then the version numbers of
+the image(s) being built in the same directory will automatically change. In
+this case, the last component (the build number) automatically increments from
+the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran,
+**until a number is explicitly provided**. If automatic versioning is in place
+and then an image version number is provided for the first time, the new number
+will take precedence and be used instead. All subsequent image versions are
+then set to the last number that has been specified, and the build number would
+stop incrementing. Any new version numbers that are provided will overwrite
+the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image
+versioning, please start a clean build without specifying the image version
+number at all. In case of multiple image boot there are separate compile time
+switches for both images to provide their version: ``IMAGE_VERSION_S`` and
+``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``.
+
+Security counter
+================
+Each signed image contains a security counter in its manifest. It is used by the
+bootloader and its aim is to have an independent (from the image version)
+counter to ensure rollback protection by comparing the new image's security
+counter against the original (currently active) image's security counter during
+the image upgrade process. It is added to the manifest (to the TLV area that is
+appended to the end of the image) by one of the Python scripts when signing the
+image. The value of the security counter is security critical data and it is in
+the integrity protected part of the image. The last valid security counter
+should always be stored in a non-volatile and trusted component of the device
+and its value should always be increased if a security flaw was fixed in the
+current image version. The value of the security counter (single image boot) can
+be specified at build time in the cmake configuration step::
+
+ cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=42 ../
+
+The security counter can be independent from the image version, but not
+necessarily. Alternatively, if it is not specified at build time with the
+``SECURITY_COUNTER`` option the Python script will automatically generate it
+from the image version number (not including the build number) and this value
+will be added to the signed image. In case of multiple image boot there are
+separate compile time switches for both images to provide their security counter
+value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used
+instead of ``SECURITY_COUNTER_S``. If these are not defined then the security
+counter values will be derived from the corresponding image version similar to
+the single image boot.
+
+***************************
+Signing the images manually
+***************************
+Normally the build system handles the signing (computing hash over the image
+and security critical manifest data and then signing the hash) of the firmware
+images. However, the images also can be signed manually by using the ``imgtool``
+Python program which is located in the MCUboot repository in the ``scripts``
+folder or can be installed with the pip package manager.
+Issue the ``python3 imgtool.py sign --help`` command in the directory for more
+information about the mandatory and optional arguments. The tool takes an image
+in binary or Intel Hex format and adds a header and trailer that MCUBoot is
+expecting. In case of single image boot after a successful build the
+``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure
+images) must be passed to the script and in case of multiple image boot the
+``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed
+images.
+
+Signing the secure image manually in case of multiple image boot
+================================================================
+
+::
+
+ python3 bl2/ext/mcuboot/scripts/imgtool.py sign \
+ --layout /bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \
+ -k /bl2/ext/mcuboot/root-RSA-3072.pem \
+ --public-key-format full \
+ --align 1 \
+ -v 1.2.3+4 \
+ -d "(1,1.2.3+0)" \
+ -s 42 \
+ -H 0x400 \
+ /bin/tfm_s.bin \
+ /bin/tfm_s_signed.bin
+
+************************
+Testing firmware upgrade
+************************
+As downloading the new firmware image is out of scope for MCUBoot, the update
+process is started from a state where the original and the new image are already
+programmed to the appropriate memory slots. To generate the original and a new
+firmware package, TF-M is built twice with different build configurations.
+
+Overwriting firmware upgrade
+============================
+Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases
+(single image boot), but with two different build configurations: default and
+regression. Save the artifacts between builds, because second run can overwrite
+original binaries. Download default build to the primary slot and regression
+build to the secondary slot.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+.. code-block:: bash
+
+ /sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=/bin/bl2.axf \
+ --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=/bin/tfm_s_ns_signed.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob
+
+The following message will be shown in case of successful firmware upgrade:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Swap type: test
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x100000 bytes
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ ...
+
+To update the secure and non-secure images separately (multiple image boot),
+set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default
+configuration value) and follow the same instructions as in case of single image
+boot.
+
+Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board
+------------------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 4 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image
+ IMAGE3ADDRESS: 0x10200000
+ IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image
+
+Note that both the concatenated binary blob (the images are signed separately
+and then concatenated) and the separate signed images can be downloaded to the
+device because on this platform (AN521) both the primary slots and the secondary
+slots are contiguous areas in the Flash (see `Integration with TF-M`_). The
+following message will be shown in case of successful firmware upgrades:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Swap type: test
+ [INF] Swap type: test
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
+ [INF] Image upgrade secondary slot -> primary slot
+ [INF] Erasing the primary slot
+ [INF] Copying the secondary slot to the primary slot: 0x80000 bytes
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+ TFM level is: 1
+ [Sec Thread] Jumping to non-secure code...
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ ...
+
+Swapping firmware upgrade
+=============================
+Follow the same instructions and platform related configurations as in case of
+overwriting build including these changes:
+
+- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP"
+ before build.
+- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image
+ boot) or "2" (multiple image boot) before build.
+
+During single image boot the following message will be shown in case of
+successful firmware upgrade, ``Swap type: test`` indicates that images were
+swapped:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3
+ [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2
+ [INF] Boot source: primary slot
+ [INF] Swap type: test
+ [INF] Bootloader chainload address offset: 0x80000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ ...
+
+Direct execute-in-place firmware upgrade
+========================================
+Follow the same instructions and platform related configurations as in case of
+overwriting build including these changes:
+
+- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "DIRECT_XIP"
+ before build.
+- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir.
+- Make sure the image version number was increased between the two build runs
+ either by specifying it manually or by checking in the build log that it was
+ incremented automatically.
+
+Executing firmware upgrade on FVP_MPS2_AEMv8M
+---------------------------------------------
+
+.. code-block:: bash
+
+ /sw/models/bin/FVP_MPS2_AEMv8M \
+ --parameter fvp_mps2.platform_type=2 \
+ --parameter cpu0.baseline=0 \
+ --parameter cpu0.INITVTOR_S=0x10000000 \
+ --parameter cpu0.semihosting-enable=0 \
+ --parameter fvp_mps2.DISABLE_GATING=0 \
+ --parameter fvp_mps2.telnetterminal0.start_telnet=1 \
+ --parameter fvp_mps2.telnetterminal1.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal2.start_telnet=0 \
+ --parameter fvp_mps2.telnetterminal0.quiet=0 \
+ --parameter fvp_mps2.telnetterminal1.quiet=1 \
+ --parameter fvp_mps2.telnetterminal2.quiet=1 \
+ --application cpu0=/bin/bl2.axf \
+ --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \
+ --data cpu0=/bin/tfm_s_ns_signed.bin@0x10180000
+
+Executing firmware upgrade on SSE 200 FPGA on MPS2 board
+--------------------------------------------------------
+
+::
+
+ TITLE: Versatile Express Images Configuration File
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader
+ IMAGE1ADDRESS: 0x10080000
+ IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob
+ IMAGE2ADDRESS: 0x10180000
+ IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob
+
+Executing firmware upgrade on Musca-B1 and Musca-S1 boards
+----------------------------------------------------------
+After the two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux::
+
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+- Windows::
+
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade,
+notice that image with higher version number (``version=1.2.3.5``) is executed:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: version=1.2.3.4, magic= good, image_ok=0x3
+ [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3
+ [INF] Booting image from the secondary slot
+ [INF] Bootloader chainload address offset: 0xa0000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+ #### Execute test suites for the Secure area ####
+ Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)...
+ ...
+
+Executing firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524)
+-------------------------------------------------------------------------
+
+::
+
+ TITLE: Arm MPS3 FPGA prototyping board Images Configuration File
+
+ [IMAGES]
+ TOTALIMAGES: 3 ;Number of Images (Max: 32)
+
+ IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ IMAGE0ADDRESS: 0x00000000
+ IMAGE0FILE: \SOFTWARE\bl2.bin ;BL2 bootloader
+ IMAGE1UPDATE: AUTO
+ IMAGE1ADDRESS: 0x00040000
+ IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob
+ IMAGE2UPDATE: AUTO
+ IMAGE2ADDRESS: 0x000C0000
+ IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob
+
+RAM loading firmware upgrade
+============================
+To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOAD"
+(either in the configuration file or through the command line), and then specify
+a destination load address in RAM where the image can be copied to and executed
+from. The ``IMAGE_LOAD_ADDRESS`` macro must be specified in the target dependent
+files, for example with Musca-S, its ``flash_layout.h`` file in the ``platform``
+folder should include ``#define IMAGE_LOAD_ADDRESS #0xA0020000``
+
+Executing firmware upgrade on Musca-S board
+--------------------------------------------
+After two images have been built, they can be concatenated to create the
+combined image using ``srec_cat``:
+
+- Linux::
+
+ srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+- Windows::
+
+ srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel
+
+The following message will be shown in case of successful firmware upgrade when,
+RAM loading is enabled, notice that image with higher version number
+(``version=0.0.0.2``) is executed:
+
+::
+
+ [INF] Starting bootloader
+ [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3
+ [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3
+ [INF] Image has been copied from the secondary slot in flash to SRAM address 0xA0020000
+ [INF] Booting image from SRAM at address 0xA0020000
+ [INF] Bootloader chainload address offset: 0x20000
+ [INF] Jumping to the first image slot
+ [Sec Thread] Secure image initializing!
+
+--------------
+
+****************************************
+Integration with Firmware Update service
+****************************************
+The shim layer of the Firmware Update partition calls the APIs in
+bootutil_misc.c to control the image status.
+
+- Call ``boot_write_magic()`` to make the image as a candidate image for booting.
+- Call ``boot_set_confirmed()`` to make the image as a permanent image.
+
+.. Note::
+ Currently, in direct-xip mode and ram-load mode, TF-M cannot get the
+ information of which slot contains the running image from the bootloader.
+ So the Firmware Update partition cannot decide where to write the new
+ image. As a result, the firmware update service is not supported in
+ direct-xip mode and ram-load mode.
+
+*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_irq_handling.rst b/docs/technical_references/tfm_secure_irq_handling.rst
new file mode 100644
index 0000000000..8cd664e260
--- /dev/null
+++ b/docs/technical_references/tfm_secure_irq_handling.rst
@@ -0,0 +1,182 @@
+###################
+Secure IRQ handling
+###################
+
+The Armv8-M Architecture makes it possible to configure interrupts to target
+secure state.
+
+TF-M makes it possible for secure partitions to get notified of secure
+interrupts.
+
+By default TF-M sets up interrupts to target NS state. To configure an interrupt
+to target secure state and assign a handler to it, the manifest of the partition
+must be edited.
+
+See the following example:
+
+
+.. code-block:: yaml
+
+ {
+ "name": "...",
+ "type": "...",
+ "priority": "...",
+
+ ...
+
+ "irqs": [
+ {
+ "source": "5",
+ "signal": "DUAL_TIMER"
+ },
+ {
+ "source": "TFM_IRQ_LINE_TIMER_1",
+ "signal": "TIMER_1"
+ "tfm_irq_priority": 64,
+ }
+ ],
+
+ ...
+
+ }
+
+To set up a handler in a partition, the ``irqs`` node must be added. A single
+secure partition can have handlers registered for multiple IRQs, in this case
+the list ``irqs`` has multiple elements in it.
+
+An IRQ handler is defined by the following nodes:
+
+- ``source``: The IRQ number or the name of the IRQ line. With the name of the
+ IRQ line, there must be defined a macro in ``tfm_peripherals_def.h`` which is
+ substituted to the IRQ line num. The IRQ line nums and sources are defined by
+ each platform: for example, they are defined in ``platform_irq.h`` for the
+ Musca-S1 platform. When defining new macros in ``tfm_peripherals_def.h``, it
+ is important the macro name matches the platform's handler function for that
+ IRQ source.
+- ``signal``: The name of the signal for this IRQ.
+- ``tfm_irq_priority``: The priority of the IRQ. This number must be in the
+ range [0-255] inclusive. Please note that some of the less significant bits of
+ this value might be dropped based on the number of priority bits implemented
+ in the platform.
+
+.. important::
+
+ The name of the privileged interrupt handler is derived from the node
+ specifying the IRQ line number.
+
+ - In case ``source`` is IRQ number, the name of the handler becomes
+ ``void irq__Handler(void)``.
+ - In case ``source`` is defined IRQ macro, the name of the handler becomes
+ ``void _Handler(void)``.
+
+ This is important, because the derived name has to be present in the vector
+ table as the handler of the IRQ. The platform startup functions are specified
+ in the vector table defined in the platform secure startup file. The user
+ should verify the names of the generated handlers match for a given platform
+ IRQ.
+
+.. Note::
+
+ ``signal`` and ``source`` are mandatory.
+
+ ``tfm_irq_priority`` is optional. If ``tfm_irq_priority`` is not set for an
+ IRQ, the default is value is ``TFM_DEFAULT_SECURE_IRQ_PRIOTITY``.
+
+If an IRQ handler is registered, TF-M will:
+
+- Set the IRQ with number or macro to target secure state
+- Set the priority of IRQ with number or macro to ``tfm_irq_priority`` or to
+ the default.
+
+TF-M configures the interrupt lines to be disabled by default. Interrupts for a
+service can be enabled by the secure service by calling
+``void tfm_enable_irq(psa_signal_t irq_signal)``. The function can be called in
+the service init function.
+
+Library model
+=============
+
+In Library model a function with the name derived from the value of the
+``source`` property is generated. This function will be put in the vector table
+by the linker (as the handlers in the startup assembly are defined as weak
+symbols). The code generated for this function will forward the call to the
+function with the name of the value of the ``signal`` property post-fixed with
+``_isr``.
+
+.. hint::
+
+ for a signal ``"signal": "DUAL_TIMER"`` the name of the handler function is
+ ``DUAL_TIMER_isr``
+
+The signature of the IRQ handler in the partition must be the following:
+
+.. code-block:: c
+
+ void partition_irq_handler(void);
+
+The detailed description on how secure interrupt handling works in the Library
+model see
+`Secure Partition Interrupt Handling design document `_.
+
+IPC model
+=========
+
+The detailed description on how secure interrupt handling works in the IPC
+model, see the
+`PSA Firmware Framework and RoT Services specification `_.
+
+**********************
+Implementation details
+**********************
+
+Library model implementation
+============================
+
+As a result of the function call like behaviour of secure services in library
+model, some information that is critical for the SPM to keep track of partition
+states, is stored on the stack of the active partitions. When an interrupt
+happens, and a handler partition is set to running state, it has access to its
+whole stack, and could corrupt the data stacked by the SPM. To prevent this, a
+separate Context stack is introduced for each secure partition, that is used by
+the SPM to save this information before starting to execute secure partition
+code.
+
+A stack frame to this context stack is pushed when the execution in the
+partition is interrupted, and when a handler in the partition interrupts another
+service. So the maximal stack usage can happen in the following situation:
+
+Consider secure partition 'A'. 'A' is running, and then it is interrupted by
+an other partition. Then the lowest priority interrupt of 'A' is triggered.
+Then before the handler returns, the partition is interrupted by another
+partition's handler. Then before the running handler returns, the second
+lowest interrupt of 'A' is triggered. This can go until the highest priority
+interrupt of 'A' is triggered, and then this last handler is interrupted. At
+this point the context stack looks like this:
+
+.. code-block::
+
+ +------------+
+ | [intr_ctx] |
+ | [hndl_ctx] |
+ | . |
+ | . |
+ | . |
+ | [intr_ctx] |
+ | [hndl_ctx] |
+ | [intr_ctx] |
+ +------------+
+
+ Legend:
+ [intr_ctx]: Frame pushed when the partition is interrupted
+ [hndl_ctx]: Frame pushed when the partition is handling an interrupt
+
+So the max stack size can be calculated as a function of the IRQ count of 'A':
+
+.. code-block::
+
+
+ max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size))
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
new file mode 100644
index 0000000000..6d9a5e1d04
--- /dev/null
+++ b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
@@ -0,0 +1,234 @@
+###################################
+Secure Partition Interrupt Handling
+###################################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint
+:Status: Accepted
+
+Secure Partitions that implement peripheral drivers may need to use interrupts
+to efficiently manage PE utilization.
+
+************************
+Partition implementation
+************************
+
+IRQ lines declared in manifest files for Secure Partitions are assigned IRQ
+signals as described in PSA Firmware Framework.
+
+Interrupt handling is implemented as interrupt service routines (Partition ISR)
+that are executed in the partition context.
+
+Partitions that are owners of IRQ must define interrupt service routines for
+them.
+
+manifest file IRQ declaration example
+=====================================
+
+.. code-block:: json
+
+ {"irqs": [
+ {
+ "line_num": 17,
+ "signal": "RTC"
+ },
+ {
+ "line_name": "UART1_IRQ",
+ "signal": "UART1"
+ }
+ ]}
+
+See
+:doc:`secure IRQ handling `
+for further information on IRQ source and signal.
+
+Partition ISR function
+======================
+
+The symbol name of the ISR implemented for a given interrupt must be
+``manifest[‘irqs’][idx].signal`` attribute post-fixed with "_isr".
+
+Partition ISR has the signature of a regular interrupt service routine, e.g.:
+
+.. code-block:: c
+
+ void UART1_isr(void);
+
+*************
+SPM behaviour
+*************
+
+In the vector table, each interrupt that has an associated partition ISR is
+assigned to an SPM interrupt handler (SPM ISR) that delegates handling to a
+Partition ISR.
+
+Each partition is allocated an asserted signal mask. Every IRQ associated with
+the partition is assigned a position in the signal mask.
+
+When a secure hardware interrupt is asserted, the SPM:
+
+- Acknowledges the interrupt and masks the hardware interrupt line.
+
+- Identifies the Secure Partition which has registered the interrupt (in the
+ manifest). This identification can happen either
+
+ - using a runtime lookup or
+
+ - by registering different instances of the SPM ISR for each interrupt, so the
+ runtime lookup is avoided both for the partition Id and the ISR function
+ location.
+
+- Sets up execution environment for the secure partition that has registered the
+ interrupt.
+
+- Asserts the IRQ signal for the interrupt in the partition's signal mask.
+
+- Execute Partition ISR. If the partition’s stack is active at the time of
+ pre-emption by the interrupt (i.e. the Secure Partition is not in idle state),
+ the Partition ISR stack frame will be amended to that. If the Secure Partition
+ had been idle, a stack frame will be reserved for the duration of the
+ Partition ISR execution. The Secure Partition state is changed to running for
+ the duration of the Partition ISR.
+
+When the Secure Partition ISR returns, execution is returned to the context
+pre-empted by the IRQ.
+
+Implementation notes
+====================
+
+Interrupts can pre-empt NSPE or secure service execution. Pre-emption of an
+interrupt is only possible by an interrupt of a higher priority, ensuring
+deterministic nesting/un-nesting of stack frames.
+
+*************
+API functions
+*************
+
+psa_wait()
+==========
+
+A call to ``psa_wait()`` from a secure service yields execution to the framework
+and becomes blocked waiting for the assertion of a signal. In the meantime, SPM
+will schedule other contexts that are ready to run. The client remains blocked
+until the service function returns.
+
+If an IRQ signal matching one in ``signal_mask`` to ``psa_wait()`` is asserted,
+the Secure Partition becomes ready to run. When the scheduler activates the
+Secure Partition, the IRQ signal(s) that had been asserted are returned by
+``psa_wait()``. When the service function completes its execution and returns,
+control is taken back to client.
+
+.. Note::
+
+ The only signals implemented in the current TF-M implementation are
+ interrupt signals.
+
+Signature
+---------
+
+.. code-block:: c
+
+ psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
+
+Parameters
+----------
+
+``psa_signal_t signal_mask`` defines the set of interrupt signals that can
+resume execution of the secure service.
+
+``uint32_t timeout`` defines timeout for the function, as defined in PSA
+Firmware Framework 1.0-beta-0 (Chapter 4.3.3).
+
+Return
+------
+
+The return value indicates the signal(s) that triggered the resumption of the
+service; i.e. If multiple interrupt events have been handled, it will be
+indicated by the mask value in the return code.
+
+tfm_enable_irq()
+================
+
+A call to ``tfm_enable_irq()`` from a secure service enables an irq.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void tfm_enable_irq(psa_signal_t irq_signal);
+
+Parameters
+----------
+
+``psa_signal_t irq_signal`` defines the interrupt signal to be enabled.
+
+Return
+------
+
+``void`` Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- irq_signal is not an interrupt signal.
+- irq_signal indicates more than one signal.
+
+tfm_disable_irq()
+=================
+
+A call to ``tfm_disable_irq()`` from a secure service disables an irq.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void tfm_disable_irq(psa_signal_t irq_signal);
+
+Parameters
+----------
+``psa_signal_t irq_signal`` defines the interrupt signal to be disabled.
+
+Return
+------
+
+``void``: Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- irq_signal is not an interrupt signal.
+- irq_signal indicates more than one signal.
+
+psa_eoi()
+=========
+
+A call ``to psa_eoi()`` from a secure service function or a Partition ISR
+informs SPM that an interrupt has been processed. This clears the IRQ signal in
+the asserted signal mask associated with the partition.
+
+Signature
+---------
+
+.. code-block:: c
+
+ void psa_eoi(psa_signal_t irq_signal);
+
+Parameters
+----------
+
+``psa_signal_t irq_signal`` defines the interrupt signal that has been
+processed.
+
+Return
+------
+
+``void``: Success.
+
+Does not return: The call is invalid, one or more of the following are true:
+
+- ``irq_signal`` is not an interrupt signal.
+- ``irq_signal`` indicates more than one signal.
+- ``irq_signal`` is not currently asserted.
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_partition_runtime_library.rst b/docs/technical_references/tfm_secure_partition_runtime_library.rst
new file mode 100644
index 0000000000..97e8444174
--- /dev/null
+++ b/docs/technical_references/tfm_secure_partition_runtime_library.rst
@@ -0,0 +1,361 @@
+################################
+Secure Partition Runtime Library
+################################
+
+:Organization: Arm Limited
+:Contact: tf-m@lists.trustedfirmware.org
+
+**********
+Background
+**********
+Trusted Firmware - M (TF-M) uses a toolchain provided runtime library and
+supervisor calls to easily implement the PSA Firmware Framework (PSA FF) API.
+This working model works well under isolation level 1 since there are no data
+isolation requirements. While TF-M is evolving, this model is not suitable
+because:
+
+ - The high-level isolation requires isolating data but some toolchain library
+ interfaces have their own global data which cannot be shared between the
+ Secure Partitions.
+ - The toolchain libraries are designed without taking security as a core
+ design principle.
+
+A TF-M specific runtime library is needed for the following reasons:
+
+ - Easier evaluation or certification by security standards.
+ - Source code transparency.
+ - Sharing code to save ROM and RAM space for TF-M.
+
+PSA FF specification also describes the requirements of C runtime API for Secure
+Partitions.
+
+This runtime library is named the ``Secure Partition Runtime Library``, and the
+abbreviation is ``SPRTL``.
+
+****************
+Design Principal
+****************
+The following requirements are mandatory for SPRTL implementation:
+
+.. important::
+ - **CODE ONLY** - No read-write data should be introduced into runtime library
+ implementation.
+ - **Thread safe** - All functions are designed with thread-safe consideration.
+ These APIs access caller stack and caller provided memory only.
+ - **Isolation** - Runtime API code is set as executable and read-only in
+ higher isolation levels.
+ - **Security first** - SPRTL is designed for security and it may come with
+ some performance loss.
+
+API Categories
+==============
+Several known types of functions are included in SPRTL:
+
+ - C runtime API.
+ - RoT Service API.
+ - PSA Client and Service API.
+ - [Future expansion, to be detailed later] other secure API.
+
+Security Implementation Requirements
+------------------------------------
+If ``malloc/realloc/free`` are provided, they must obey additional requirements
+compared to the C standard: newly allocated memory must be initialized to
+ZERO, and freed memory must be wiped immediately in case the block contains
+sensitive data.
+
+The comparison API ('memcmp' e.g.), they should not return immediately when the
+fault case is detected. The implementation should execute in linear time based
+on input to avoid execution timing side channel attack.
+
+The pointer validation needs to be considered. In general, at least the
+'non-NULL' checking is mandatory. A detection for invalid pointer leads to a
+``psa_panic()``.
+
+The following section describes the first 3 API types and the implementation
+requirements.
+
+C Runtime API
+-------------
+PSA FF describes a small set of the C standard library. Part of toolchain
+library API can be used as default if these APIs meet the `Design Principal`_
+and `Security Implementation Requirements`_. The toolchain 'header' and 'types'
+can be reused to simplify the implementation.
+
+These APIs can take the toolchain provided version, or separately implemented
+in case there are extra requirements:
+
+.. note::
+ - 'memcpy()/memmove()/memset()'
+ - String API
+
+These APIs are proposed to be implemented with the security consideration
+mentioned in `Security Implementation Requirements`_:
+
+.. note::
+ - 'memcmp()'
+ - Other comparison API if referenced ('strcmp' e.g.).
+
+The following functions are optional, but if present, they must conform to
+additional `Security Implementation Requirements`_:
+
+.. note::
+ - 'malloc()/free()/realloc()'
+ - 'assert()/printf()'
+
+The following APIs are coupled with toolchain library much so applying toolchain
+library implementation is recommended:
+
+.. note::
+ - Division and modulo - arithmetic operations.
+ - Other low level or compiler specific functions (such as 'va_list').
+
+Besides the APIs mentioned above, the following runtime APIs are required for
+runtime APIs with private runtime context ('malloc' e.g.):
+
+.. note::
+ - '__sprtmain()' - partition entry runtime wrapper.
+
+RoT Service API
+---------------
+The description of RoT Service API in PSA FF:
+
+.. note::
+ Arm recommends that the RoT Service developer also defines an RoT Service API
+ and implementation to encapsulate the use of the IPC protocol, and improve the
+ usability of the service for client firmware.
+
+Part of the RoT Service API have proposed specifications, such as the PSA
+Cryptography API, PSA Storage API, and PSA Attestation API. It is suggested that
+the service developer create documents of their RoT Service API and make them
+publicly available.
+
+The RoT Service API has a large amount and it is the main part of SPRTL. This
+chapter describes the general implementation of the RoT Service API and the
+reason for putting them into SPRTL.
+
+In general, a client uses the PSA Client API to access a secure service.
+For example:
+
+.. code-block:: c
+
+ /* Example, not a real implementation */
+ caller_status_t psa_example_service(void)
+ {
+ ...
+ handle = psa_connect(SERVICE_SID, SERVICE_VERSION);
+ if (INVALID_HANDLE(handle)) {
+ return INVALID_RETURN;
+ }
+
+ status = psa_call(handle, type, invecs, inlen, outvecs, outlen);
+
+ psa_close(handle);
+
+ return TO_CALLER_STATUS(status);
+ }
+
+This example encapsulates the PSA Client API, and can be provided as a simpler
+and more generic API for clients to call. It is not possible to statically link
+this API to each Secure Partition because of the limited storage space. The
+ideal solution is to put it inside SPRTL and share it to all Secure Partitions.
+This would simplify the caller logic into this:
+
+.. code-block:: c
+
+ if (psa_example_service() != STATUS_SUCCESS) {
+ /* do something */
+ }
+
+This is the simplest case of encapsulating PSA Client API. If a RoT Service API
+is connect heavy, then, the encapsulation can be changed to include a connection
+handle inside a context data structure. This context data structure type is
+defined in RoT Service headers and the instance is allocated by API caller since
+API implementation does not have private data.
+
+.. note::
+ - Even the RoT Service APIs are provided in SPRTL for all clients, the SPM
+ performs the access check eventually and decides if the access to service
+ can be processed.
+ - For those RoT Service APIs only get called by a specific client, they can be
+ implemented inside the caller client, instead of putting it into SPRTL.
+
+PSA Client and Service API
+--------------------------
+Most of the PSA APIs can be called directly with supervisor calls. The only
+special function is ``psa_call``, because it has **6** parameters. This makes
+the supervisor call handler complex because it has to extract the parameters
+from the stack. The definition of psa_call is the following:
+
+.. code-block:: c
+
+ psa_status_t psa_call(psa_handle_t handle, int32_t type,
+ const psa_invec *in_vec, size_t in_len,
+ psa_outvec *out_vec, size_t out_len);
+
+The parameters need to be packed to avoid passing parameters on the stack, and
+the supervisor call needs to unpack the parameters back to **6** for subsequent
+processing.
+
+Privileged Access Supporting
+============================
+Due to specified API (printf, e.g.) need to access privileged resources, TF-M
+Core needs to provide interface for the resources accessing. The permission
+checking must happen in Core while caller is calling these interface.
+
+Secure Partition Scratch Area
+=============================
+For the API needs partition specific private data, there needs to be a way to
+pass the partition specific data for the API. Use C language preprocessor to
+forward the existing prototype declaration can work, but it has the risks of
+breaking the build since this method needs compilers support ('-include' e.g.).
+Furthermore, no valid runtime tricks can work due to these limitations on
+M-profile architecture:
+
+.. note::
+ - We cannot apply the aligned mask on a stack address to get stack bottom
+ where the private data pointer stands. This is because aligned stack bottom
+ is not supported.
+ - We cannot read special registers such as 'PSPLIMIT' for retrieving the
+ private data pointer while executing in unprivileged mode.
+ - Furthermore, some earlier versions of the ARM architecture do not have
+ certain special-purpose registers ('PSPLIMIT' etc.).
+
+A system-provided scratch area is a precondition for implementing APIs that need
+to access private data (such as 'malloc'). The requirements for implementing
+such an area are:
+
+.. important::
+ - The area must be ``READ-ONLY`` for the running Secure Partition.
+ - The SPM must put the running Secure Partition's metadata into this area
+ while scheduling.
+
+With these requirements, the passed parameters can be retrieved by SPRTL easily
+with a read operation on the fixed memory address.
+
+Tooling Support on Partition Entry
+==================================
+PSA FF requires each Secure Partition to have an entry point. For example:
+
+.. code-block:: c
+
+ /* The entry point function must not return. */
+ void entry_point(void);
+
+Each partition has its own dedicated metadata for heap tracking and other
+runtime state. The metadata is designed to be saved at the read-write data area
+of a partition with a specific name. A generic entry point needs to be available
+to get partition metadata and do initialization before calling into the actual
+partition entry. This generic entry point is defined as '__sprtmain':
+
+.. code-block:: c
+
+ void __sprtmain(void)
+ {
+ /* Get current SP private data from scratch area */
+ struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data;
+
+ /* Potential heap init - check later chapter */
+ if (m->heap_size) {
+ m->heap_instance = tfm_sprt_heap_init(m->heap_sa, m->heap_sz);
+ }
+
+ /* Call thread entry 'entry_point' */
+ m->thread_entry();
+
+ /* SVC back to tell Core end this thread */
+ SVC(THREAD_EXIT);
+ }
+
+Since SPM is not aware of the '__sprtmain' in SPRTL, it just calls into the
+entry point listed in partition runtime data structure. And the partition writer
+may be not aware of running of '__sprtmain' as the generic wrapper entry,
+tooling support needs to happen to support this magic. Here is an example of
+partition manifest:
+
+.. code-block:: sh
+
+ {
+ "name": "TFM_SP_SERVICE",
+ "type": "PSA-ROT",
+ "priority": "NORMAL",
+ "entry_point": "tfm_service_entry",
+ "stack_size": "0x1800",
+ "heap_size": "0x1000",
+ ...
+ }
+
+Tooling would do manipulation to tell SPM the partition entry as '__sprtmain',
+and TF-M SPM would switch the activated metadata into the scratch area. Finally,
+the partition entry point gets called and run, tooling helps on the decoupling
+of SPM and SPRTL implementation. The pseudo code of a tooling result:
+
+.. code-block:: c
+
+ struct partition_t sp1 {
+ .name = "TFM_SP_SERVICE",
+ .type = PSA_ROT,
+ .priority = NORMAL,
+ .id = 0x00000100,
+ .entry_point = __sprtmain, /* Tell SPM entry is '__sprtmain' */
+ .metadata = { /* struct sprt_meta_t */
+ .heap_sa = sp1_heap_buf,
+ .heap_sz = sizeof(sp1_heap_buf),
+ .thread_entry = sp1_entry, /* Actual Partition Entry */
+ .heap_instance = NULL,
+ },
+ }
+
+Implementation
+==============
+The SPRTL C Runtime sources are put under:
+'$TFM_ROOT/secure_fw/partitions/lib/sprt/'
+
+The output of this folder is a static library named as 'libtfm_sprt.a'. The code
+of 'libtfm_sprt.a' is put into a dedicated section so that a hardware protected
+region can be applied to contain it.
+
+The RoT Service API are put under service interface folder. These APIs are
+marked with the same section attribute where 'libtfm_sprt.a' is put.
+
+The Formatting API - 'printf' and variants
+------------------------------------------
+The 'printf' and its variants need special parameters passing mechanism. To
+implement these APIs, the toolchain provided builtin macro 'va_list', 'va_start'
+and 'va_end' cannot be avoided. This is because of some scenarios such as when
+'stack canaries' are enabled, only the compiler knows the format of the 'canary'
+in order to extract the parameters correctly.
+
+To provide a simple implementation, the following requirements are defined for
+'printf':
+
+- Format keyword 'xXduscp' needs to be supported.
+- Take '%' as escape flag, '%%' shows a '%' in the formatted string.
+- To save heap usage, 32 bytes buffer in the stack for collecting formatted
+ string.
+- Flush string outputting due to: a) buffer full b) function ends.
+
+The interface for flushing can be a logging device.
+
+Function with Implied Parameters
+--------------------------------
+Take 'malloc' as an example. There is only one parameter for 'malloc' in
+the prototype. Heap management code is put in the SPRTL for sharing with caller
+partitions. The heap instance belongs to each partition, which means this
+instance needs to be passed into the heap management code as a parameter. For
+allocation API in heap management, it needs two parameters - 'size' and
+'instance', while for 'malloc' caller it needs a 'malloc' with one parameter
+'size' only. As mentioned in the upper chapter, this instance can be retrieved
+from the Secure Partition scratch area. The implementation can be:
+
+.. code-block:: c
+
+ void *malloc(size_t sz)
+ {
+ struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data;
+
+ return tfm_sprt_alloc(m->heap_instance, sz);
+ }
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_uniform_secure_service_signature.rst b/docs/technical_references/tfm_uniform_secure_service_signature.rst
new file mode 100644
index 0000000000..70c6c6031a
--- /dev/null
+++ b/docs/technical_references/tfm_uniform_secure_service_signature.rst
@@ -0,0 +1,114 @@
+################################
+Uniform Secure Service Signature
+################################
+
+:Author: Miklos Balint
+:Organization: Arm Limited
+:Contact: Miklos Balint
+:Status: Accepted
+
+**********************************
+Declaring secure service interface
+**********************************
+
+The following alternative secure service signature is proposed as an
+amendment to existing implementation.
+
+Individual signatures - current method
+======================================
+
+A ``_veneers.c`` file is created in the ``secure_fw/ns_callable``
+directory, that specifies the signature for each veneer function, and calls the
+secure function from the veneers. The respective
+``interface/include/_veneers.h`` file with the veneer declarations
+have to be created and maintained manually.
+Note that at present TF-M framework limits the range of valid return values a
+secure service can provide, reserving a range for framework error codes.
+
+Uniform signatures - proposal
+=============================
+
+The proposal is to use a uniform signature for all the secure functions of the
+secure service. There are multiple advantages of this method:
+
+- TF-M Core can do a sanity check on the access rights of the veneer
+ parameters, and there is no need for the secure services to make these checks
+ individually. Please note that in the present implementation sanity check is
+ only fully supported for level 1 isolation.
+
+- The veneer declarations and implementations for the secure functions can be
+ generated automatically from a template (using the secure function list in the
+ secure service's manifest)
+
+The signature for such secure services would look like this:
+
+.. code-block:: c
+
+ psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len,
+ struct psa_outvec *out_vec, size_t out_len);
+
+where
+
+Return value:
+-------------
+
+``psa_status_t`` is a status code whose values are described in PSA Firmware
+Framework (as in version 1.0-beta-0 chapter 4.3.3).
+
+Note:
+-----
+The return value limitations imposed by TF-M framework for proprietary
+secure service veneers would not apply to secure services using the uniform
+signature. This is analogous to how PSA Firmware Framework handles values
+returned by ``psa_reply()`` function.
+
+Arguments:
+----------
+
+.. code-block:: c
+
+ /**
+ * A read-only input memory region provided to a RoT Service.
+ */
+ typedef struct psa_invec {
+ const void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+ } psa_invec;
+
+ /**
+ * A writable output memory region provided to a RoT Service.
+ */
+ typedef struct psa_outvec {
+ void *base; /*!< the start address of the memory buffer */
+ size_t len; /*!< the size in bytes */
+ } psa_outvec;
+
+ /**
+ * in_len: the number of input parameters, i.e. psa_invecs
+ * out_len: the number of output parameters, i.e. psa_outvecs
+ */
+
+The number of vectors that can be passed to a secure service is constrained:
+
+.. code-block:: c
+
+ in_len + out_len <= PSA_MAX_IOVEC
+
+The veneer function declarations and implementations are generated in the
+``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c``
+files respectively. The veneer functions are created with the name
+``tfm__veneer``
+
+Services that implement the uniform signature do not need to manually fill
+the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro.
+
+*************
+Compatibility
+*************
+
+Note that the proposal is for the two types of services (those with proprietary
+signatures and those with uniform signatures) to co-exist, with the intention of
+eventually phasing out proprietary signatures in favour of the more robust,
+uniform signature.
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/threat_models/TF-M-block-diagram.png b/docs/threat_models/TF-M-block-diagram.png
deleted file mode 100644
index e5d0371e26..0000000000
Binary files a/docs/threat_models/TF-M-block-diagram.png and /dev/null differ
diff --git a/docs/threat_models/generic_threat_model.rst b/docs/threat_models/generic_threat_model.rst
deleted file mode 100644
index 7aa048ad3e..0000000000
--- a/docs/threat_models/generic_threat_model.rst
+++ /dev/null
@@ -1,1130 +0,0 @@
-#######################################
-Trusted Firmware-M Generic Threat Model
-#######################################
-
-************
-Introduction
-************
-
-This document introduces a generic thread model of Trusted Firmware-M (TF-M).
-This generic thread model provides an overall analysis of TF-M implementation
-and identifies general threats and mitigation.
-
-.. note::
-
- If you think a security vulnerability is found, please follow
- Trustedfirmware.org [Security-Incident-Process]_ to contact TF-M security
- team.
-
-Scope
-=====
-
-TF-M supports diverse models and topologies. It also implements multiple
-isolation levels. Each case may focus on different target of evaluation (TOE)
-and identify different assets and threats.
-TF-M implementation consists of several secure services, defined as
-Root of Trust (RoT) service. Those RoT services belong to diverse RoT
-(Application RoT or PSA RoT) and access different assets and hardware. Therefore
-each RoT service may require a dedicated threat model.
-
-The analysis on specific models, topologies or RoT services may be covered in
-dedicated thread model documents. Those threat models are out of the scope of
-this document.
-
-Methodology
-===========
-
-The threat modeling in this document follows the process listed below to
-build up the threat model.
-
-- Target of Evaluation (TOE)
-- Assets identification
-- Data Flow Diagram (DFD)
-- Threats Prioritization
-- Threats identification
-
-TOE is the entity on which threat modeling is performed. The logic behind this
-process is to firstly investigate the TOE which could be a system, solution or
-use case. This first step helps to identify the assets to be protected in TOE.
-
-According to TOE and assets, Trust Boundaries can be determined. The Data Flow
-Diagram (DFD) across Trust Boundaries is then defined to help identify the
-threats.
-
-Those threats should be prioritized based on a specific group of principals and
-metrics. The principals and metrics should also be specified.
-
-********************
-Target of Evaluation
-********************
-
-A typical TF-M system diagram from a high-level overview is shown below. TF-M is
-running in the Secure Processing Environment (SPE) and NS software is running in
-Non-secure Processing Environment (NSPE). For more details, please refer to
-Platform Security Architecture Firmware Framework for M (FF-M) [FF-M]_.
-
-.. figure:: TF-M-block-diagram.png
-
-The TOE in this general model is the SPE, including TF-M and other components
-running in SPE.
-
-The TOE can vary in different TF-M models, RoT services and usage scenarios.
-Refer to dedicated thread models for the specific TOE definitions.
-
-********************
-Asset identification
-********************
-
-In this threat model, assets include the general items listed below:
-
-- Hardware Root of Trust data, e.g.
-
- - Hardware Unique Key (HUK)
- - Root authentication key
- - Other embedded root keys
-
-- Software RoT data, e.g.
-
- - Secure Partition Manager (SPM) code and data
- - Secure partition code and data
- - NSPE data stored in SPE
- - Data generated in SPE as requested by NSPE
-
-- Availability of entire RoT service
-
-- Secure logs, including event logs
-
-Assets may vary in different use cases and implementations. Additional assets
-can be defined in an actual usage scenario and a dedicated threat model.
-
-For example, in a network camera use case, the following data can be defined as
-assets too:
-
-- Certificate for connecting to cloud
-- Session keys for encryption/decryption in the communication with cloud
-- Keys to encrypt/decrypt the videos and photos
-
-*****************
-Data Flow Diagram
-*****************
-
-The Trust Boundary isolates SPE from NSPE, according to the TOE definition in
-`Target of Evaluation`_. The Trust Boundary mapped to block diagram is shown
-in the figure below. Other modules inside SPE stay in the same TOE as TF-M does.
-
-Valid Data flows across the Trust Boundary are also shown in the figure below.
-This thread model only focuses on the data flows related to TF-M.
-
-.. figure:: overall-DFD.png
-
-More details of data flows are listed below.
-
-.. _data-flow-table:
-
-.. table:: TF-M Data Flows between NSPE and SPE
-
- +-----------+----------------------------------------------------------------+
- | Data flow | Description |
- +===========+================================================================+
- | ``DF1`` | TF-M initializes NS entry and activates NSPE. |
- | | |
- | | - On single Armv8-M core platforms, TF-M will hand over the |
- | | control to Non-secure state. |
- | | - On dual-cpu platforms, Secure core starts NS core booting. |
- +-----------+----------------------------------------------------------------+
- | ``DF2`` | NSPE requests TF-M RoT services. |
- | | |
- | | - In TF-M Library model, NS invokes Secure Function calls |
- | | - In TF-M IPC model, NS invokes PSA Client calls based on IPC |
- | | protocol defined in [FF-M]_. |
- | | |
- | | In single Armv8-M core scenarios, SG instruction is executed |
- | | in Non-secure Callable region to trigger a transition from |
- | | Non-secure state to Secure state. |
- | | |
- | | On dual-cpu platforms, non-secure core sends PSA Client calls |
- | | to secure core via mailbox. |
- +-----------+----------------------------------------------------------------+
- | ``DF3`` | Secure Partitions fetch input data from NS and write back |
- | | output data to NS. |
- | | |
- | | In TF-M IPC model, as required in [FF-M]_, Secure Partitions |
- | | should not directly access NSPE memory. Instead, RoT services |
- | | relies on TF-M SPM to access NSPE memory. |
- +-----------+----------------------------------------------------------------+
- | ``DF4`` | TF-M returns RoT service results to NSPE after NS request to |
- | | RoT service is completed. |
- | | |
- | | In single Armv8-M core scenarios, it also trigger a transition |
- | | from Secure state back to Non-secure state. |
- | | |
- | | On dual-cpu platforms, secure core returns the result to |
- | | non-secure core via mailbox. |
- +-----------+----------------------------------------------------------------+
- | ``DF5`` | Non-secure interrupts preempt SPE execution in single Armv8-M |
- | | core scenarios. |
- +-----------+----------------------------------------------------------------+
- | ``DF6`` | Secure interrupts preempt NSPE execution in single Armv8-M |
- | | core scenarios. |
- +-----------+----------------------------------------------------------------+
-
-.. note::
-
- All the other data flows across the Trusted Boundary besides the valid ones
- mentioned above should be prohibited by default.
- Proper isolation must be configured to prevent NSPE directly accessing SPE.
-
- Threats irrelevant to data flows in
- :ref:`TF-M Data Flows between NSPE and SPE ` may be specified
- in `Miscellaneous threats`_.
-
-Data flows inside SPE (informative)
-===================================
-
-Since all the SPE components stay in the TOE within the same Trust Boundary in
-this threat model, the data flows between SPE components are not covered in this
-threat model. Instead, those data flows and corresponding threats will be
-identified in the dedicated threat model documents of TF-M RoT services and
-usage scenarios.
-
-Those data flows inside SPE include following examples:
-
-- Data flows between TF-M and BL2
-- Data flows between RoT services and SPM
-- Data flows between RoT services and corresponding secure hardware and assets,
- such as secure storage device, crypto hardware accelerator and Hardware Unique
- Key (HUK).
-
-*********************
-Threat identification
-*********************
-
-Threat priority
-===============
-
-Threat priority is indicated by the score calculated via Common Vulnerability
-Scoring System (CVSS) Version 3.1 [CVSS]_. The higher the threat scores, the
-greater severity the threat is with and the higher the priority is.
-
-CVSS scores can be mapped to qualitative severity ratings defined in CVSS 3.1
-specification [CVSS_SPEC]_. This threat model follows the same mapping between
-CVSS scores and threat priority rating.
-
-As a generic threat model, this document focuses on *Base Score* which reflects
-the constant and general severity of a threat according to its intrinsic
-characteristics.
-
-The *Impacted Component* defined in [CVSS_SPEC]_ refers to the assets listed in
-`Asset identification`_.
-
-Threats and mitigation list
-===========================
-
-This section lists generic threats and corresponding mitigation, based on the
-the analysis of data flows in `Data Flow Diagram`_.
-
-Threats are identified following ``STRIDE`` model. Please refer to [STRIDE]_ for
-more details.
-
-The field ``CVSS Score`` reflects the threat priority defined in
-`Threat priority`_. The field ``CVSS Vector String`` contains the textual
-representation of the CVSS metric values used to score the threat. Refer to
-[CVSS_SPEC]_ for more details of CVSS vector string.
-
-.. note::
-
- A generic threat may have different behaviors and therefore require different
- mitigation, in diverse TF-M models and usage scenarios.
-
- This threat model document focuses on general analysis of the following
- threats. For the details in a specific configuration and usage scenario,
- please refer to the dedicated threat model document.
-
-NS entry initialization
------------------------
-
-This section identifies threats on ``DF1`` defined in `Data Flow Diagram`_.
-
-.. table:: TFM-GENERIC-NS-INIT-T-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-T-1** |
- +---------------+------------------------------------------------------------+
- | Description | The NS image can be tampered by an attacker |
- +---------------+------------------------------------------------------------+
- | Justification | An attack may tamper the NS image to inject malicious code |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | By default TF-M relies on MCUBoot to validate NS image. |
- | | The validation of NS image integrity and authenticity is |
- | | completed in secure boot before jumping to NS entry or |
- | | booting up NS core. |
- | | Refer to [SECURE-BOOT]_ for more details. |
- | | |
- | | The validation may vary in diverse vendor platforms |
- | | specific Chain of Trust (CoT) implementation. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 3.5 (Low) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INIT-T-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-T-2** |
- +---------------+------------------------------------------------------------+
- | Description | An attacker may replace the current NS image with an older |
- | | version. |
- +---------------+------------------------------------------------------------+
- | Justification | The attacker downgrades the NS image with an older version |
- | | which has been deprecated due to known security issues. |
- | | |
- | | The older version image can pass the image signature |
- | | validation and its vulnerabilities can be exploited by |
- | | attackers. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M relies on MCUBoot to perform anti-rollback |
- | | protection. |
- | | |
- | | TF-M defines a non-volatile counter API to support |
- | | anti-rollback. Each platform must implement it using |
- | | specific trusted hardware non-volatile counters. |
- | | For more details, refer to [ROLLBACK-PROTECT]_. |
- | | |
- | | The anti-rollback protection implementation can vary on |
- | | diverse platforms. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 3.5 (Low) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INIT-T-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-T-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | If SPE doesn't complete isolation configuration before |
- | | NSPE starts, NSPE can access secure regions which it is |
- | | disallowed to. |
- +---------------+------------------------------------------------------------+
- | Justification | Secure data can be tampered or disclosed if NSPE is |
- | | activated and accesses secure regions before isolation |
- | | configuration is completed by SPE. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering/Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | SPE must complete and enable proper isolation to protect |
- | | secure regions from being accessed by NSPE, before jumping |
- | | to NS entry or booting up NS core. |
- | | |
- | | TF-M executes isolation configuration at early stage of |
- | | secure initialization before NS initialization starts. |
- | | |
- | | On dual-cpu platform, platform specific initialization |
- | | must halt NS core until isolation is completed, as defined |
- | | in [DUAL-CPU-BOOT]_. |
- | | |
- | | TF-M defines isolation configuration HALs for platform |
- | | implementation. The specific isolation configuration |
- | | depends on platform specific implementation. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 9.0 (Critical) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INIT-T-I-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-T-I-2** |
- +---------------+------------------------------------------------------------+
- | Description | If SPE doesn't complete isolation configuration before |
- | | NSPE starts, NSPE can control devices or peripherals which |
- | | it is disallowed to. |
- +---------------+------------------------------------------------------------+
- | Justification | On some platforms, devices and peripherals can be |
- | | configured as Secure state in runtime. If security status |
- | | configuration of those device and peripherals are not |
- | | properly completed before NSPE starts, NSPE can control |
- | | those device and peripherals and may be able to tamper |
- | | data or access secure data. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering/Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | SPE must complete and enable proper configuration and |
- | | isolation to protect critical devices and peripherals from |
- | | being accessed by NSPE, before jumping to NS entry or |
- | | booting up NS core. |
- | | |
- | | TF-M executes isolation configuration of devices and |
- | | peripherals at early stage of secure initialization before |
- | | NS initialization starts. |
- | | |
- | | The specific isolation configuration depends on platform |
- | | specific implementation. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 9.0 (Critical) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INIT-I-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-I-2** |
- +---------------+------------------------------------------------------------+
- | Description | If SPE leaves some SPE information in non-secure memory |
- | | or shared registers when NSPE starts, NSPE may access |
- | | those SPE information. |
- +---------------+------------------------------------------------------------+
- | Justification | If NSPE can access those SPE information from shared |
- | | registers or non-secure memory, secure information may be |
- | | disclosed. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | SPE must clean up the secure information from shared |
- | | registers before NS starts. |
- | | |
- | | TF-M invalidates registers not banked before handing over |
- | | the system to NSPE on single Armv8-M platform. |
- | | |
- | | On dual-cpu platforms, shared registers are implementation |
- | | defined, such as Inter-Processor Communication registers. |
- | | Dual-cpu platforms must not store any data which may |
- | | disclose secure information in the shared registers. |
- | | |
- | | SPE must avoid storing SPE information in non-secure |
- | | memory. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.3 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INIT-D-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INIT-D-1** |
- +---------------+------------------------------------------------------------+
- | Description | An attacker may block NS to boot up |
- +---------------+------------------------------------------------------------+
- | Justification | An attacker may block NS to boot up, such as by corrupting |
- | | NS image, to stop the whole system from performing normal |
- | | functionalities. |
- +---------------+------------------------------------------------------------+
- | Category | Denial of service |
- +---------------+------------------------------------------------------------+
- | Mitigation | No SPE information will be disclosed and TF-M won't be |
- | | directly impacted. |
- | | |
- | | It relies on NSPE and platform specific implementation to |
- | | mitigate this threat. It is out of scope of this threat |
- | | model. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.0 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-NSPE requests TF-M secure service
----------------------------------
-
-This section identifies threats on ``DF2`` defined in `Data Flow Diagram`_.
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-S-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-S-1** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may pretend as a secure client |
- | | to access secure data which NSPE must not directly access. |
- +---------------+------------------------------------------------------------+
- | Justification | [FF-M]_ defines ``Client ID`` to distinguish clients which |
- | | request RoT services. Secure clients are assigned with |
- | | positive IDs and non-secure clients are assigned with |
- | | negative ones. |
- | | |
- | | A malicious NS application may provide a positive |
- | | ``Client ID`` to pretend as a secure client to access |
- | | secure data. |
- +---------------+------------------------------------------------------------+
- | Category | Spoofing |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M checks the ``Client ID`` from NSPE. If the NS |
- | | ``Client ID`` is not a valid one, TF-M will report this as |
- | | a security error. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 8.4 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-T-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-T-1** |
- +---------------+------------------------------------------------------------+
- | Description | An attacker in NSPE may tamper the service request input |
- | | or output vectors between check and use |
- | | (Time-Of-Check-to-Time-Of-Use (TOCTOU)). |
- +---------------+------------------------------------------------------------+
- | Justification | If SPE validates the content in input/output vectors |
- | | locally in NSPE memory, an attacker in NSPE can have a |
- | | chance to tamper the content after the validation |
- | | successfully passes. Then SPE will provide RoT service |
- | | according to the corrupted parameters and it may cause |
- | | further security issues. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | In TF-M implementation, the validation of NS input/output |
- | | vectors are only executed after those vectors are copied |
- | | from NSPE into SPE. It prevents an attack from NSPE to |
- | | tamper those parameters after validation in TF-M. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 7.8 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:H/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-T-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-T-2** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may request to tamper data |
- | | belonging to SPE. |
- +---------------+------------------------------------------------------------+
- | Justification | A malicious NS application may request SPE RoT services to |
- | | write malicious value to SPE data. The malicious NS |
- | | application may try to tamper SPE assets, such as keys, or |
- | | modify configurations in SPE. The SPE data belongs to |
- | | components in SPE and must not be accessed by NSPE. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M executes memory access check to all the RoT service |
- | | requests. If a request doesn't have enough permission to |
- | | access the target memory region, TF-M will refuse this |
- | | request and assert a security error. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 7.1 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-R-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-R-1** |
- +---------------+------------------------------------------------------------+
- | Description | A NS application may repudiate that it has requested |
- | | services from a RoT service. |
- +---------------+------------------------------------------------------------+
- | Justification | A malicious NS application may call a RoT service to |
- | | access critical data in SPE, which it is disallowed to, |
- | | via a non-public vulnerability. It may refuse to admit |
- | | that it has accessed that data. |
- +---------------+------------------------------------------------------------+
- | Category | Repudiation |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M implements an event logging secure service to record |
- | | the critical events, such as the access to critical data. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 0.0 (None) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may request to read data |
- | | belonging to SPE. |
- +---------------+------------------------------------------------------------+
- | Justification | A malicious NS application may request SPE RoT services to |
- | | copy SPE data to NS memory. The SPE data belongs to |
- | | components in SPE and must not be disclosed to NSPE, such |
- | | as root keys. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M executes memory access check to all the RoT service |
- | | requests. If a request doesn't have enough permission to |
- | | access the target memory region, TF-M will refuse this |
- | | request and assert a security error. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 7.1 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-T-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-T-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may request to control secure |
- | | device and peripherals, on which it doesn't have the |
- | | permission. |
- +---------------+------------------------------------------------------------+
- | Justification | A malicious NS application may request RoT services to |
- | | control secure device and peripherals, on which it doesn't |
- | | have the permission. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering/Information disclose |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M performs client check to validate whether the client |
- | | has the permission to access the secure device and |
- | | peripherals. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 9.0 (Critical) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-D-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-D-1** |
- +---------------+------------------------------------------------------------+
- | Description | A Malicious NS applications may frequently call secure |
- | | services to block secure service requests from other NS |
- | | applications. |
- +---------------+------------------------------------------------------------+
- | Justification | TF-M runs on IoT devices with constrained resource. Even |
- | | though multiple outstanding NS PSA Client calls can be |
- | | supported in system, the number of NS PSA client calls |
- | | served by TF-M simultaneously are still limited. |
- | | |
- | | Therefore, if a malicious NS application or multiple |
- | | malicious NS applications continue calling TF-M secure |
- | | services frequently, it may block other NS applications to |
- | | request secure service from TF-M. |
- +---------------+------------------------------------------------------------+
- | Category | Denial of service |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M is unable to manage behavior of NS applications. |
- | | Assets are not disclosed and TF-M is neither directly |
- | | impacted in this threat. |
- | | |
- | | It relies on NS OS to enhance scheduling policy and |
- | | prevent a single NS application to occupy entire CPU time. |
- | | It is beyond the scope of this threat model. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.0 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-REQUEST-SERVICE-D-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-REQUEST-SERVICE-D-2** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may provide invalid NS memory |
- | | addresses as the addresses of input and output data in RoT |
- | | service requests. |
- +---------------+------------------------------------------------------------+
- | Justification | SPE may be unable to achieve full knowledge of NS memory |
- | | mapping. SPE may fail to capture those invalid NS memory |
- | | addresses during memory access check since those invalid |
- | | addresses may not be included in isolation configuration. |
- | | |
- | | In that case, SPE will access those invalid NS memory |
- | | addresses later to read or write data. It may trigger a |
- | | system error to crash the whole system immediately. |
- | | |
- | | The malicious NS application may be blocked by NS MPU from |
- | | directly accessing that invalid NS memory address. But it |
- | | may manipulate SPE to access that address instead. |
- +---------------+------------------------------------------------------------+
- | Category | Denial of service |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M executes memory access check to the memory addresses |
- | | in all the NS requests. |
- | | |
- | | On single Armv8-M core platforms, TF-M invokes ``TT`` |
- | | instructions to execute memory address check. If a NS |
- | | memory area is not matched in any valid SAU or MPU region, |
- | | it will be marked as invalid and any access permission is |
- | | disallowed. Therefore, SPM will reject any NS request |
- | | containing invalid NS memory addresses and reports it as |
- | | as a security error. |
- | | |
- | | On dual-core platforms, TF-M implements a default memory |
- | | access check. If a NS memory area is not found in any |
- | | memory region configured for isolation, it will be marked |
- | | as invalid and therefore SPM will reject the corresponding |
- | | NS request. It will be reported as a security error. |
- | | |
- | | Dual-core platforms may implement platform specific memory |
- | | check to replace the default one. It relies on platform |
- | | specific implementation to capture invalid memory address. |
- | | It is out of the scope of this document. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 3.2 (Low) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:N/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-RoT services read and write NS data
------------------------------------
-
-This section identifies threats on ``DF3`` defined in `Data Flow Diagram`_.
-
-According to [FF-M]_, in TF-M IPC model, RoT services should rely on TF-M SPM to
-obtain NS input data and send response data back to NS memory.
-
-In Library model, RoT services directly read and write NS memory to simplify the
-implementation and decrease latency.
-
-.. _TFM-GENERIC-SECURE-SERVICE-RW-T-1:
-
-.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-1** |
- +---------------+------------------------------------------------------------+
- | Description | An attacker may tamper NS input data while the RoT service |
- | | is processing those data. |
- +---------------+------------------------------------------------------------+
- | Justification | A RoT service may access NS input data multiple times |
- | | during its data processing. For example, it may validate |
- | | or authenticate the NS input data before it performs |
- | | further processing. |
- | | |
- | | If the NS input data remains in NSPE memory during the RoT |
- | | service execution, an attacker may tamper the NS input |
- | | data in NSPE memory after the validation passes. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | In TF-M IPC model, RoT services request SPM to read and |
- | | write NS data. TF-M SPM follows [FF-M]_ to copy the NS |
- | | input data into SPE memory region owned by the RoT |
- | | service, before the RoT service processes the data. |
- | | Therefore, the NS input data is protected during the RoT |
- | | service execution from being tampered. |
- | | |
- | | In TF-M Library model, RoT services can directly access NS |
- | | memory. If a RoT service accesses NS input data multiple |
- | | times during data processing, it is required to review and |
- | | confirm Library model implementation of the RoT service |
- | | copies NS input data into SPE memory area before it |
- | | processes the data. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 3.2 (Low) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. _TFM-GENERIC-SECURE-SERVICE-RW-T-2:
-
-.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-2
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-2** |
- +---------------+------------------------------------------------------------+
- | Description | A malicious NS application may embed secure memory |
- | | addresses into a structure in RoT service request input |
- | | vectors, to tamper secure memory which the NS application |
- | | must not access. |
- +---------------+------------------------------------------------------------+
- | Justification | [FF-M]_ limits the total number of input/output vectors to |
- | | 4. If a RoT service requires more input/output vectors, it |
- | | may define a parameter structure which embeds multiple |
- | | input/output buffers addresses. |
- | | |
- | | However, as a potential security risk, a malicious NS |
- | | application can put secure memory addresses into a valid |
- | | parameter structure to bypass TF-M validation on those |
- | | memory addresses. |
- | | |
- | | The parameter structure can pass TF-M memory access check |
- | | since itself is valid. However, if the RoT service parses |
- | | the structure and directly write malicious data from NSPE |
- | | to the secure memory addresses in parameter structure, the |
- | | secure data will be tampered. |
- +---------------+------------------------------------------------------------+
- | Category | Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | It should be avoided to embed memory addresses into a |
- | | single input/output vector. If more than 4 memory |
- | | addresses are required in a RoT service request, it is |
- | | recommended to split this request into two or multiple |
- | | service calls and therefore each service call requires no |
- | | more than 4 input/output vectors. |
- | | |
- | | In TF-M IPC model, RoT services request SPM to read and |
- | | write NS data. SPM will validate the target addresses and |
- | | can detect the invalid addresses to mitigate this threat. |
- | | |
- | | In TF-M Library model, RoT services can directly access NS |
- | | memory. It is required to review and confirm Library model |
- | | implementation of RoT service request doesn't embed memory |
- | | addresses. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 7.1 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-SECURE-SERVICE-RW-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-SECURE-SERVICE-RW-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | Similar to TFM-GENERIC-SECURE-SERVICE-RW-T-2_, a malicious |
- | | NS application can embed secure memory addresses in a |
- | | parameter structure in RoT service request input vectors, |
- | | to read secure data which the NS application must not |
- | | access. |
- +---------------+------------------------------------------------------------+
- | Justification | Similar to the description in |
- | | TFM-GENERIC-SECURE-SERVICE-RW-T-2_, the secure memory |
- | | addresses hidden in the RoT service input/output vector |
- | | structure may bypass TF-M validation. Without a proper |
- | | check, the RoT service may copy secure data to NSPE |
- | | according to the secure memory addresses in structure, |
- | | secure information can be disclosed. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | It should be avoided to embed memory addresses into a |
- | | single input/output vector. If more than 4 memory |
- | | addresses are required in a RoT service request, it is |
- | | recommended to split this request into two or multiple |
- | | service calls and therefore each service call requires no |
- | | more than 4 input/output vectors. |
- | | |
- | | In TF-M IPC model, RoT services request SPM to read and |
- | | write NS data. SPM will validate the target addresses and |
- | | can detect the invalid addresses to mitigate this threat. |
- | | |
- | | In TF-M Library model, RoT services can directly access NS |
- | | memory. It is required to review and confirm Library model |
- | | implementation of RoT service request doesn't embed memory |
- | | addresses. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 7.1 (High) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-TF-M returns secure service result
-----------------------------------
-
-This section identifies threats on ``DF4`` defined in `Data Flow Diagram`_.
-
-When RoT service completes the request from NSPE, TF-M returns the success or
-failure error code to NS application.
-
-In single Armv8-M core scenario, TF-M writes the return code value in the
-general purpose register and returns to Non-secure state.
-
-On dual-cpu platforms, TF-M writes the return code to NSPE mailbox message queue
-via mailbox.
-
-.. table:: TFM-GENERIC-RETURN-CODE-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-RETURN-CODE-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | SPE may leave secure data in the registers not banked |
- | | after the SPE completes PSA Client calls and executes |
- | | ``BXNS`` to switch Armv8-M back to Non-secure state. |
- +---------------+------------------------------------------------------------+
- | Justification | If SPE doesn't clean up the secure data in registers not |
- | | banked before switching into NSPE in Armv8-M core, NSPE |
- | | can read the SPE context from those registers. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | In single Armv8-M core scenario, TF-M cleans general |
- | | purpose registers not banked before switching into NSPE to |
- | | prevent NSPE probing secure context from the registers. |
- | | |
- | | Current TF-M implementation doesn't support FPU in SPE. |
- | | TF-M build will stop if FPU is enabled on platform. |
- | | Therefore, FPU registers doesn't contain data that needs |
- | | to be protected from NSPE. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.3 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-NS interrupts preempts SPE execution
-------------------------------------
-
-This section identifies threats on ``DF5`` defined in `Data Flow Diagram`_.
-
-.. table:: TFM-GENERIC-NS-INTERRUPT-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INTERRUPT-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | Shared registers may contain secure data when NS |
- | | interrupts occur. |
- +---------------+------------------------------------------------------------+
- | Justification | The secure data in shared registers should be cleaned up |
- | | before NSPE can access shared registers. Otherwise, secure |
- | | data leakage may occur. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | In single Armv8-M core scenario, Armv8-M architecture |
- | | automatically cleans up the registers not banked before |
- | | switching to Non-secure state while taking NS interrupts. |
- | | |
- | | Current TF-M implementation doesn't support FPU in SPE. |
- | | TF-M build will stop if FPU is enabled on platform. |
- | | Therefore, FPU registers doesn't contain data that needs |
- | | to be protected from NSPE. |
- | | |
- | | On dual-cpu platforms, shared registers are implementation |
- | | defined, such as Inter-Processor Communication registers. |
- | | Dual-cpu platforms must not store any data which may |
- | | disclose secure information in the shared registers. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.3 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-NS-INTERRUPT-D-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-NS-INTERRUPT-D-1** |
- +---------------+------------------------------------------------------------+
- | Description | An attacker may trigger spurious NS interrupts frequently |
- | | to block SPE execution. |
- +---------------+------------------------------------------------------------+
- | Justification | In single Armv8-M core scenario, an attacker may inject a |
- | | malicious NS application or hijack a NS hardware to |
- | | frequently trigger spurious NS interrupts to keep |
- | | preempting SPE and block SPE to perform normal secure |
- | | execution. |
- +---------------+------------------------------------------------------------+
- | Category | Denial of service |
- +---------------+------------------------------------------------------------+
- | Mitigation | It is out of scope of TF-M. |
- | | |
- | | Assets protected by TF-M won't be leaked. TF-M won't be |
- | | directly impacted. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.0 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-Secure interrupts preempts NSPE execution
------------------------------------------
-
-This section identifies threats on ``DF6`` defined in `Data Flow Diagram`_.
-
-.. table:: TFM-GENERIC-S-INTERRUPT-I-1
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-S-INTERRUPT-I-1** |
- +---------------+------------------------------------------------------------+
- | Description | Shared registers may contain secure data when Armv8-M core |
- | | switches back to Non-secure state on Secure interrupt |
- | | return. |
- +---------------+------------------------------------------------------------+
- | Justification | Armv8-M architecture doesn't automatically clean up shared |
- | | registers while returning to Non-secure state during |
- | | Secure interrupt return. |
- | | |
- | | If SPE leaves critical data in the Armv8-M registers not |
- | | banked, NSPE can read secure context from those registers |
- | | and secure data leakage may occur. |
- +---------------+------------------------------------------------------------+
- | Category | Information disclosure |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M saves NPSE context in general purpose register R4~R11 |
- | | into secure stack during secure interrupt entry. |
- | | After secure interrupt handling completes, TF-M unstacks |
- | | NSPE context from secure stack to overwrite secure context |
- | | in R4~R11 before secure interrupt return. |
- | | |
- | | Armv8-M architecture will automatically unstack NSPE |
- | | context from non-secure stack to overwrite other registers |
- | | not banked, such as R0~R3 and R12, during secure interrupt |
- | | return, before NSPE software can access those registers. |
- | | |
- | | Current TF-M implementation doesn't support FPU in SPE. |
- | | TF-M build will stop if FPU is enabled on platform. |
- | | Therefore, FPU registers doesn't contain data that needs |
- | | to be protected from NSPE. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.3 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N |
- | String | |
- +---------------+------------------------------------------------------------+
-
-Miscellaneous threats
----------------------
-
-This section collects threats irrelevant to the valid TF-M data flows shown
-above.
-
-.. table:: TFM-GENERIC-STACK-SEAL
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-STACK_SEAL** |
- +---------------+------------------------------------------------------------+
- | Description | Armv8-M processor Secure software Stack Sealing |
- | | vulnerability. |
- +---------------+------------------------------------------------------------+
- | Justification | On Armv8-M based processors with TrustZone, if Secure |
- | | software does not properly manage the Secure stacks when |
- | | the stacks are created, or when performing non-standard |
- | | transitioning between states or modes, for example, |
- | | creating a fake exception return stack frame to |
- | | de-privilege an interrupt, it is possible for Non-secure |
- | | world software to manipulate the Secure Stacks, and |
- | | potentially influence Secure control flow. |
- | | |
- | | Refer to [STACK-SEAL]_ for details. |
- +---------------+------------------------------------------------------------+
- | Category | Elevation of privilege |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M has implemented common mitigation against stack seal |
- | | vulnerability. |
- | | |
- | | Refer to [ADVISORY-TFMV-1]_ for details on analysis and |
- | | mitigation in TF-M. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 5.3 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:L/I:L/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-.. table:: TFM-GENERIC-SVC-CALL-SP-FETCH
- :widths: 10 50
-
- +---------------+------------------------------------------------------------+
- | Index | **TFM-GENERIC-SVC-CALL-SP-FETCH** |
- +---------------+------------------------------------------------------------+
- | Description | Invoking Secure functions from handler mode may cause TF-M |
- | | IPC model to behave unexpectedly. |
- +---------------+------------------------------------------------------------+
- | Justification | On Armv8-M based processors with TrustZone, if NSPE calls |
- | | a secure function via Secure Gateway (SG) from non-secure |
- | | Handler mode , TF-M selects secure process stack by |
- | | mistake for SVC handling. |
- | | It will most likely trigger a crash in secure world or |
- | | reset the whole system, with a very low likelihood of |
- | | overwriting some memory contents. |
- +---------------+------------------------------------------------------------+
- | Category | Denial of service/Tampering |
- +---------------+------------------------------------------------------------+
- | Mitigation | TF-M has enhanced implementation to mitigate this |
- | | vulnerability. |
- | | |
- | | Refer to [ADVISORY-TFMV-2]_ for details on analysis and |
- | | mitigation in TF-M. |
- +---------------+------------------------------------------------------------+
- | CVSS Score | 4.5 (Medium) |
- +---------------+------------------------------------------------------------+
- | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:L |
- | String | |
- +---------------+------------------------------------------------------------+
-
-***************
-Version control
-***************
-
-.. table:: Version control
-
- +---------+--------------------------------------------------+---------------+
- | Version | Description | TF-M version |
- +=========+==================================================+===============+
- | v0.1 | Initial draft | TF-M v1.1 |
- +---------+--------------------------------------------------+---------------+
- | v1.0 | First version | TF-M v1.2.0 |
- +---------+--------------------------------------------------+---------------+
-
-*********
-Reference
-*********
-
-.. [Security-Incident-Process] `Security Incident Process `_
-
-.. [FF-M] `Arm® Platform Security Architecture Firmware Framework 1.0 `_
-
-.. [DUAL-CPU-BOOT] :doc:`Booting a dual core system `
-
-.. [CVSS] `Common Vulnerability Scoring System Version 3.1 Calculator `_
-
-.. [CVSS_SPEC] `CVSS v3.1 Specification Document `_
-
-.. [STRIDE] `The STRIDE Threat Model `_
-
-.. [SECURE-BOOT] :doc:`Secure boot `
-
-.. [ROLLBACK-PROTECT] :doc:`Rollback protection in TF-M secure boot `
-
-.. [STACK-SEAL] `Armv8-M processor Secure software Stack Sealing vulnerability `_
-
-.. [ADVISORY-TFMV-1] :doc:`Advisory TFMV-1 `
-
-.. [ADVISORY-TFMV-2] :doc:`Advisory TFMV-2 `
-
---------------------
-
-*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.*
diff --git a/docs/threat_models/index.rst b/docs/threat_models/index.rst
deleted file mode 100644
index 227d4d41e1..0000000000
--- a/docs/threat_models/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Threat Models
-=============
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/threat_models/overall-DFD.png b/docs/threat_models/overall-DFD.png
deleted file mode 100644
index 39cf4c8549..0000000000
Binary files a/docs/threat_models/overall-DFD.png and /dev/null differ
diff --git a/platform/ext/index.rst b/platform/ext/index.rst
index d763c7c735..1d12b9a7c0 100644
--- a/platform/ext/index.rst
+++ b/platform/ext/index.rst
@@ -1,13 +1,13 @@
-Platforms
-=========
+Supported Platforms
+===================
.. toctree::
:maxdepth: 1
:caption: Information
- readme
/platform/readme
- /docs/contributing/platform_deprecation.rst
+ readme
+ /platform/ext/platform_deprecation.rst
.. toctree::
:maxdepth: 4
@@ -55,4 +55,4 @@ Platforms
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/platform/ext/platform_deprecation.rst b/platform/ext/platform_deprecation.rst
new file mode 100644
index 0000000000..5d7a3de987
--- /dev/null
+++ b/platform/ext/platform_deprecation.rst
@@ -0,0 +1,68 @@
+################################
+Platform deprecation and removal
+################################
+
+********************************************
+Process for Platform deprecation and removal
+********************************************
+
+A platform may need to be removed from upstream code due to lack of community
+interest or it may have reached end of life. The below section calls out the
+process for removing platform support from TF-M.
+
+ 1. An email to the TF-M mailing list proposing the removal of the platform.
+
+ 2. The merit of the proposal will be considered by the maintainers for a
+ period of 4 weeks and community can express their opinion on the same
+ during this time window. The platform owner can veto the proposal and
+ incase of multiple platform owners with differing opinion or community
+ having interest in the platform, then the project maintainer can work
+ with the platform owner and use their discretion to decide on the
+ proposal.
+
+ 3. Once a decision is made to remove the platform, the platform is
+ considered to be in `deprecated` state as per platform support lifecyle
+ defined here: "https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/".
+ The platform will be marked as deprecated and the TF-M version after
+ which it will be removed will also be mentioned. Suitable build time
+ or runtime messages needs to be incorporated to the platform to warn
+ about the `deprecation`.
+
+ 4. The project should strive to keep the `deprecated` platforms
+ building/running till the removal. This relies on platform owners being
+ still actively involved with the project and maintaining the platform.
+
+ 5. Although this will be the usual process for platform deprecation and
+ eventual removal, the process still leaves room for the platform
+ deprecation to be cancelled after it has been marked as `deprecated`
+ due to evolving project and market requirements. This is left to
+ consensus between project maintainers and platform owner/s.
+
+ 6. Once a platform has been removed, it can be added back in future and
+ this would follow the same guidelines as for a new platform contribution.
+
+****************************
+List of Deprecated Platforms
+****************************
+
+The below list calls out platforms marked for deprecation according to the
+above process and the platform will be removed soon after the mentioned
+release.
+
++--------------------------------------+-----------+---------------------------+
+| Deprecated Platform | Removed | Comments |
+| | after | |
+| | release | |
++======================================+===========+===========================+
+| mps2/an539 | v1.2.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| mps2/sse-200_aws | v1.3.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| musca_a | v1.3.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+| nordic_nrf/nrf5340pdk_nrf5340_cpuapp | v1.3.0 | N.A |
++--------------------------------------+-----------+---------------------------+
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/platform/ext/target/musca_b1/secure_enclave/readme.rst b/platform/ext/target/musca_b1/secure_enclave/readme.rst
index 8b301aa37e..a9af495776 100644
--- a/platform/ext/target/musca_b1/secure_enclave/readme.rst
+++ b/platform/ext/target/musca_b1/secure_enclave/readme.rst
@@ -17,7 +17,7 @@ SSE-200 subsystem used. But if the ``FORWARD_PROT_MSG`` cmake flag is turned
on, the TF-M instance running on SSE-200 will communicate with the SE.
For more information you can check the
-:doc:`Secure Enclave design document `.
+:doc:`Secure Enclave design document `.
***********
System boot
@@ -102,4 +102,4 @@ Known limitations
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/readme.rst b/readme.rst
index abace9fad9..4f21e380eb 100644
--- a/readme.rst
+++ b/readme.rst
@@ -45,6 +45,6 @@ Feedback can be submitted via email to
.. _Trusted Firmware-M documentation: `Documentation home`_
.. _Documentation home: https://ci.trustedfirmware.org/job/tf-m-build-docs-nightly/lastStableBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/index.html
.. _trustedfirmware.org: http://www.trustedfirmware.org
-.. _Release notes: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/reference/changelog.html
+.. _Release notes: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/reference/releases/index.html
*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
--
cgit v1.2.3