Docs: Structure the Design documents
- gather documents in folders:
"booting" for secure boot related designs
"services" for Secure services and SPM
"software" for general TF-M framework design and rules
- add short document names in indexes
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I4efd309c186e431cf24c3259a35bfef53e2eb24c
diff --git a/docs/design_docs/bl1.rst b/docs/design_docs/booting/bl1.rst
similarity index 100%
rename from docs/design_docs/bl1.rst
rename to docs/design_docs/booting/bl1.rst
diff --git a/docs/design_docs/booting/index.rst b/docs/design_docs/booting/index.rst
new file mode 100644
index 0000000..7326868
--- /dev/null
+++ b/docs/design_docs/booting/index.rst
@@ -0,0 +1,8 @@
+.. toctree::
+ :maxdepth: 1
+
+ Secure Boot <tfm_secure_boot.rst>
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/design_docs/secure_boot_hw_key_integration.rst b/docs/design_docs/booting/secure_boot_hw_key_integration.rst
similarity index 100%
rename from docs/design_docs/secure_boot_hw_key_integration.rst
rename to docs/design_docs/booting/secure_boot_hw_key_integration.rst
diff --git a/docs/design_docs/secure_boot_rollback_protection.rst b/docs/design_docs/booting/secure_boot_rollback_protection.rst
similarity index 100%
rename from docs/design_docs/secure_boot_rollback_protection.rst
rename to docs/design_docs/booting/secure_boot_rollback_protection.rst
diff --git a/docs/design_docs/tfm_secure_boot.rst b/docs/design_docs/booting/tfm_secure_boot.rst
similarity index 99%
rename from docs/design_docs/tfm_secure_boot.rst
rename to docs/design_docs/booting/tfm_secure_boot.rst
index 043af16..df3bbaf 100644
--- a/docs/design_docs/tfm_secure_boot.rst
+++ b/docs/design_docs/booting/tfm_secure_boot.rst
@@ -1,6 +1,14 @@
###########
Secure boot
###########
+
+.. toctree::
+ :maxdepth: 1
+
+ BL1 Immutable bootloader <bl1.rst>
+ Rollback Protection <secure_boot_rollback_protection.rst>
+ HW Key integration <secure_boot_hw_key_integration.rst>
+
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
diff --git a/docs/design_docs/dual-cpu/index.rst b/docs/design_docs/dual-cpu/index.rst
index f302748..008a244 100644
--- a/docs/design_docs/dual-cpu/index.rst
+++ b/docs/design_docs/dual-cpu/index.rst
@@ -3,9 +3,12 @@
.. toctree::
:maxdepth: 1
- :glob:
- *
+ Booting <booting_a_dual_core_system.rst>
+ SPE - NSPE communication <communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst>
+ Mailbox <mailbox_design_on_dual_core_system.rst>
+ Mailbox update <mailbox_ns_agent_update.rst>
+ Memory Access Check <tfm_multi_core_access_check.rst>
--------------
diff --git a/docs/design_docs/mailbox_ns_agent_update.rst b/docs/design_docs/dual-cpu/mailbox_ns_agent_update.rst
similarity index 99%
rename from docs/design_docs/mailbox_ns_agent_update.rst
rename to docs/design_docs/dual-cpu/mailbox_ns_agent_update.rst
index 116b2a6..40ee9d6 100644
--- a/docs/design_docs/mailbox_ns_agent_update.rst
+++ b/docs/design_docs/dual-cpu/mailbox_ns_agent_update.rst
@@ -62,7 +62,7 @@
Agent needs customization in SPM since it has extra requirements compared to
a generic secure partition.
-.. figure:: media/mailbox_ns_agent1.*
+.. figure:: /design_docs/media/mailbox_ns_agent1.*
:align: center
:name: fig-mailbox1
:width: 70%
diff --git a/docs/design_docs/ff_isolation.rst b/docs/design_docs/ff_isolation.rst
index e637c65..ad0000e 100644
--- a/docs/design_docs/ff_isolation.rst
+++ b/docs/design_docs/ff_isolation.rst
@@ -175,7 +175,7 @@
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 <tfm_secure_partition_runtime_library>`
+:doc:`Secure Partition Runtime Library </design_docs/services/tfm_secure_partition_runtime_library>`
for more detail.
.. note::
@@ -390,7 +390,7 @@
The design document
-:doc:`TF-M Hardware Abstraction Layer <hardware_abstraction_layer>`
+:doc:`TF-M Hardware Abstraction Layer </design_docs/software/hardware_abstraction_layer>`
gives a detail design, include the platform initialization, isolation
interfaces. Please refer to it for more detail.
diff --git a/docs/design_docs/index.rst b/docs/design_docs/index.rst
index e091bbb..1c9fcdb 100644
--- a/docs/design_docs/index.rst
+++ b/docs/design_docs/index.rst
@@ -2,11 +2,20 @@
================
.. toctree::
- :maxdepth: 1
- :glob:
+ :maxdepth: 2
- */index
- *
+ Secure Boot <booting/index>
+ Dual CPU <dual-cpu/index>
+ Secure Services <services/index>
+ Software Design <software/index>
+
+.. toctree::
+ :maxdepth: 1
+
+ Isolation Rules <ff_isolation.rst>
+ Builtin Keys <tfm_builtin_keys.rst>
+ Logging system <tfm_log_system_design_document.rst>
+ Physical Attack Mitigation <tfm_physical_attack_mitigation.rst>
--------------
diff --git a/docs/design_docs/services/index.rst b/docs/design_docs/services/index.rst
new file mode 100644
index 0000000..5024f88
--- /dev/null
+++ b/docs/design_docs/services/index.rst
@@ -0,0 +1,21 @@
+###############
+Secure Services
+###############
+
+.. toctree::
+ :maxdepth: 1
+
+ Secure Partition Manager <secure_partition_manager.rst>
+ Secure RTL <tfm_secure_partition_runtime_library.rst>
+ Inter-Process Communication <tfm_psa_inter_process_communication.rst>
+ Stateless Services <stateless_rot_service.rst>
+ Service Signing <tfm_uniform_secure_service_signature.rst>
+ Crypto <tfm_crypto_design.rst>
+ Initial Attestation <symmetric_initial_attest.rst>
+ Internal Storage <tfm_its_service.rst>
+ Firmware Update <tfm_fwu_service.rst>
+ PS Key Management <ps_key_management.rst>
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/design_docs/ps_key_management.rst b/docs/design_docs/services/ps_key_management.rst
similarity index 100%
rename from docs/design_docs/ps_key_management.rst
rename to docs/design_docs/services/ps_key_management.rst
diff --git a/docs/design_docs/secure_partition_manager.rst b/docs/design_docs/services/secure_partition_manager.rst
similarity index 98%
rename from docs/design_docs/secure_partition_manager.rst
rename to docs/design_docs/services/secure_partition_manager.rst
index eddec2e..366619a 100644
--- a/docs/design_docs/secure_partition_manager.rst
+++ b/docs/design_docs/services/secure_partition_manager.rst
@@ -18,7 +18,7 @@
************
The service access process of FF-M:
-.. figure:: media/tfmdev.*
+.. figure:: /design_docs/media/tfmdev.*
:align: center
:name: fig-tfmdev
:width: 80%
@@ -106,7 +106,7 @@
fulfil different security requirements by defining different isolation
boundaries.
-.. figure:: media/modelisolation.*
+.. figure:: /design_docs/media/modelisolation.*
:align: center
:name: fig-modelisolation
:width: 80%
@@ -173,7 +173,7 @@
The state transition diagram:
-.. figure:: media/spestate.*
+.. figure:: /design_docs/media/spestate.*
:align: center
:name: fig-spestate
:width: 70%
@@ -341,7 +341,7 @@
scheduling, the isolation boundaries NEED to be switched if there are
boundaries between components.
-.. figure:: media/hybridruntime.*
+.. figure:: /design_docs/media/hybridruntime.*
:align: center
:name: fig-hybridruntime
:width: 60%
@@ -363,7 +363,7 @@
directly, while a cross-boundary call needs a mechanism (Supervisor call e.g.)
to cross the boundary first before reaching the API entrance.
-.. figure:: media/twocalltypes.*
+.. figure:: /design_docs/media/twocalltypes.*
:align: center
:name: fig-twocalltypes
:width: 60%
@@ -374,7 +374,7 @@
---------------------------
SPM internal execution flow as shown in diagram:
-.. figure:: media/abi_scheduler.*
+.. figure:: /design_docs/media/abi_scheduler.*
:align: center
:name: fig-abi_scheduler
:width: 60%
@@ -483,7 +483,7 @@
shows up: The IPC partition, hence `schedule` is the mechanism when accessing
services inside an IPC partition.
-.. figure:: media/spmabitypes.*
+.. figure:: /design_docs/media/spmabitypes.*
:align: center
:name: fig-spmabi
:width: 60%
@@ -662,7 +662,7 @@
identify them, special mechanisms can be proposed to provide the identification.
Check specific NS ID client ID or context related documents for details.
-.. figure:: media/tzcontext.*
+.. figure:: /design_docs/media/tzcontext.*
:align: center
:name: fig-tzcontext
:width: 40%
diff --git a/docs/design_docs/stateless_rot_service.rst b/docs/design_docs/services/stateless_rot_service.rst
similarity index 100%
rename from docs/design_docs/stateless_rot_service.rst
rename to docs/design_docs/services/stateless_rot_service.rst
diff --git a/docs/design_docs/symmetric_initial_attest.rst b/docs/design_docs/services/symmetric_initial_attest.rst
similarity index 97%
rename from docs/design_docs/symmetric_initial_attest.rst
rename to docs/design_docs/services/symmetric_initial_attest.rst
index 02b23cd..bc20284 100644
--- a/docs/design_docs/symmetric_initial_attest.rst
+++ b/docs/design_docs/services/symmetric_initial_attest.rst
@@ -46,7 +46,7 @@
.. _overall-diagram-figure:
-.. figure:: media/symmetric_initial_attest/overall_diagram.png
+.. figure:: /design_docs/media/symmetric_initial_attest/overall_diagram.png
:align: center
Overall design diagram
@@ -96,7 +96,7 @@
.. _ia-service-figure:
-.. figure:: media/symmetric_initial_attest/ia_service_flow.png
+.. figure:: /design_docs/media/symmetric_initial_attest/ia_service_flow.png
:align: center
Symmetric IAT generation flow in Initial Attestation secure service
@@ -177,7 +177,7 @@
.. _attest-token-start-figure:
-.. figure:: media/symmetric_initial_attest/attest_token_start.png
+.. figure:: /design_docs/media/symmetric_initial_attest/attest_token_start.png
:align: center
Workflow in symmetric Initial Attestation ``attest_token_start()``
@@ -228,7 +228,7 @@
.. _attest-token-finish-figure:
-.. figure:: media/symmetric_initial_attest/attest_token_finish.png
+.. figure:: /design_docs/media/symmetric_initial_attest/attest_token_finish.png
:align: center
Workflow in symmetric Initial Attestation ``attest_token_finish()``
@@ -474,7 +474,7 @@
.. _iat-decode-figure:
-.. figure:: media/symmetric_initial_attest/iat_decode.png
+.. figure:: /design_docs/media/symmetric_initial_attest/iat_decode.png
:align: center
Workflow in symmetric Initial Attestation ``attest_token_decode_validate_token()``
diff --git a/docs/design_docs/tfm_crypto_design.rst b/docs/design_docs/services/tfm_crypto_design.rst
similarity index 99%
rename from docs/design_docs/tfm_crypto_design.rst
rename to docs/design_docs/services/tfm_crypto_design.rst
index cf2cbe0..7106849 100644
--- a/docs/design_docs/tfm_crypto_design.rst
+++ b/docs/design_docs/services/tfm_crypto_design.rst
@@ -96,7 +96,7 @@
The interaction between the different components is described by the
following block diagram:
-.. figure:: media/tfm_crypto_design.png
+.. figure:: /design_docs/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.
diff --git a/docs/design_docs/tfm_fwu_service.rst b/docs/design_docs/services/tfm_fwu_service.rst
similarity index 99%
rename from docs/design_docs/tfm_fwu_service.rst
rename to docs/design_docs/services/tfm_fwu_service.rst
index ab3c294..f97dfd4 100644
--- a/docs/design_docs/tfm_fwu_service.rst
+++ b/docs/design_docs/services/tfm_fwu_service.rst
@@ -26,7 +26,7 @@
A typical flow through the component states is shown below [1]_.
-.. figure:: media/fwu-states.svg
+.. figure:: /design_docs/media/fwu-states.svg
:scale: 65 %
:align: center
:name: The component state model transitions.
diff --git a/docs/design_docs/tfm_its_512_flash.rst b/docs/design_docs/services/tfm_its_512_flash.rst
similarity index 100%
rename from docs/design_docs/tfm_its_512_flash.rst
rename to docs/design_docs/services/tfm_its_512_flash.rst
diff --git a/docs/design_docs/tfm_its_service.rst b/docs/design_docs/services/tfm_its_service.rst
similarity index 99%
rename from docs/design_docs/tfm_its_service.rst
rename to docs/design_docs/services/tfm_its_service.rst
index 06c2ceb..e170504 100644
--- a/docs/design_docs/tfm_its_service.rst
+++ b/docs/design_docs/services/tfm_its_service.rst
@@ -6,6 +6,11 @@
:Organization: Arm Limited
:Contact: Jamie Fox <jamie.fox@arm.com>
+.. toctree::
+ :maxdepth: 1
+
+ Block-aligned flash <tfm_its_512_flash.rst>
+
PSA Internal Trusted Storage
============================
PSA Internal Trusted Storage (ITS) is a PSA RoT Service for storing the most
diff --git a/docs/design_docs/tfm_psa_inter_process_communication.rst b/docs/design_docs/services/tfm_psa_inter_process_communication.rst
similarity index 100%
rename from docs/design_docs/tfm_psa_inter_process_communication.rst
rename to docs/design_docs/services/tfm_psa_inter_process_communication.rst
diff --git a/docs/design_docs/tfm_secure_partition_runtime_library.rst b/docs/design_docs/services/tfm_secure_partition_runtime_library.rst
similarity index 100%
rename from docs/design_docs/tfm_secure_partition_runtime_library.rst
rename to docs/design_docs/services/tfm_secure_partition_runtime_library.rst
diff --git a/docs/design_docs/tfm_uniform_secure_service_signature.rst b/docs/design_docs/services/tfm_uniform_secure_service_signature.rst
similarity index 100%
rename from docs/design_docs/tfm_uniform_secure_service_signature.rst
rename to docs/design_docs/services/tfm_uniform_secure_service_signature.rst
diff --git a/docs/design_docs/code_sharing.rst b/docs/design_docs/software/code_sharing.rst
similarity index 100%
rename from docs/design_docs/code_sharing.rst
rename to docs/design_docs/software/code_sharing.rst
diff --git a/docs/design_docs/enum_implicit_casting.rst b/docs/design_docs/software/enum_implicit_casting.rst
similarity index 100%
rename from docs/design_docs/enum_implicit_casting.rst
rename to docs/design_docs/software/enum_implicit_casting.rst
diff --git a/docs/design_docs/hardware_abstraction_layer.rst b/docs/design_docs/software/hardware_abstraction_layer.rst
similarity index 98%
rename from docs/design_docs/hardware_abstraction_layer.rst
rename to docs/design_docs/software/hardware_abstraction_layer.rst
index 2a06297..bf70d6c 100644
--- a/docs/design_docs/hardware_abstraction_layer.rst
+++ b/docs/design_docs/software/hardware_abstraction_layer.rst
@@ -45,7 +45,7 @@
********
This section provides an overview of the abstraction layer structure.
-.. figure:: media/hal_structure.png
+.. figure:: /design_docs/media/hal_structure.png
Here lists a minimal set of necessary functionalities:
@@ -524,7 +524,7 @@
Log API
=======
-The log API is used by the :term:`TF-M` :doc:`log system <tfm_log_system_design_document>`.
+The log API is used by the :term:`TF-M` :doc:`log system </design_docs/tfm_log_system_design_document>`.
The log device could be uart, memory, usb, etc.
APIs
@@ -583,8 +583,8 @@
**Note**
-Please check :doc:`TF-M log system <tfm_log_system_design_document>` for more
-information.
+Please check :doc:`TF-M log system </design_docs/tfm_log_system_design_document>`
+for more information.
Interrupt APIs
==============
diff --git a/docs/design_docs/software/index.rst b/docs/design_docs/software/index.rst
new file mode 100644
index 0000000..45240ed
--- /dev/null
+++ b/docs/design_docs/software/index.rst
@@ -0,0 +1,16 @@
+#####################
+Software Design Notes
+#####################
+
+.. toctree::
+ :maxdepth: 1
+
+ Code Sharing <code_sharing.rst>
+ Hardware Abstraction Layer <hardware_abstraction_layer.rst>
+ Cooperative Scheduling <tfm_cooperative_scheduling_rules.rst>
+ Code Templates <tfm_code_generation_with_jinja2.rst>
+ Implicit Typecasintg <enum_implicit_casting.rst>
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/design_docs/tfm_code_generation_with_jinja2.rst b/docs/design_docs/software/tfm_code_generation_with_jinja2.rst
similarity index 100%
rename from docs/design_docs/tfm_code_generation_with_jinja2.rst
rename to docs/design_docs/software/tfm_code_generation_with_jinja2.rst
diff --git a/docs/design_docs/tfm_cooperative_scheduling_rules.rst b/docs/design_docs/software/tfm_cooperative_scheduling_rules.rst
similarity index 100%
rename from docs/design_docs/tfm_cooperative_scheduling_rules.rst
rename to docs/design_docs/software/tfm_cooperative_scheduling_rules.rst