Docs: Update code structure doc
- fix the number of CPU to 8 to avoid Sphinx crash in OpenCI
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I4f05857a639ec2609f5b21cb739a6e91e5372fc0
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
index 36a4930..821d894 100644
--- a/docs/integration_guide/index.rst
+++ b/docs/integration_guide/index.rst
@@ -4,15 +4,16 @@
The purpose of this document is to provide a guide on how to integrate TF-M
with other hardware platforms and operating systems.
-
.. toctree::
:maxdepth: 1
- SPM Backends <spm_backends.rst>
- NS client integration <non-secure_client_extension_integration_guide.rst>
+ Source Structure <source_structure/index>
+ SPM Backends <spm_backends.rst>
+ NS client integration <non-secure_client_extension_integration_guide.rst>
OS migration to Armv8-M <os_migration_guide_armv8m.rst>
- tfm_fpu_support
- Secure Interrupt <tfm_secure_irq_integration_guide.rst>
+ Floating-Point Support <tfm_fpu_support.rst>
+ Secure Interrupt <tfm_secure_irq_integration_guide.rst>
+ Platform Provisioning <platform_provisioning.rst>
.. toctree::
:maxdepth: 2
@@ -20,7 +21,6 @@
platform/index
services/index
-
*****************
How to build TF-M
*****************
diff --git a/docs/integration_guide/platform/index.rst b/docs/integration_guide/platform/index.rst
index a02134e..ff3ed0b 100644
--- a/docs/integration_guide/platform/index.rst
+++ b/docs/integration_guide/platform/index.rst
@@ -1,3 +1,5 @@
+.. _adding_platform:
+
#####################
Adding a new platform
#####################
@@ -5,13 +7,10 @@
.. toctree::
:maxdepth: 1
- platform_folder.rst
- platform_ext_folder.rst
porting_TFM_to_a_new_hardware
documenting_platform.rst
- platform_provisioning.rst
platform_deprecation.rst
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_provisioning.rst b/docs/integration_guide/platform_provisioning.rst
similarity index 100%
rename from docs/integration_guide/platform/platform_provisioning.rst
rename to docs/integration_guide/platform_provisioning.rst
diff --git a/docs/integration_guide/services/tfm_its_integration_guide.rst b/docs/integration_guide/services/tfm_its_integration_guide.rst
index b8a1bd8..d8c1f31 100644
--- a/docs/integration_guide/services/tfm_its_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_its_integration_guide.rst
@@ -254,7 +254,7 @@
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/platform_ext_folder` along with other
+available in :ref:`platform_ext_folder` along with other
platform information.
ITS Service Build Definitions
diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst
index 11ea68a..bbc0636 100644
--- a/docs/integration_guide/services/tfm_ps_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst
@@ -261,7 +261,7 @@
logical filesystem block.
More information about the ``flash_layout.h`` content, not ITS related, is
-available in :doc:`../platform/platform_ext_folder` along with other
+available in :ref:`platform_ext_folder` along with other
platform information.
TF-M NV Counter Interface
diff --git a/docs/integration_guide/source_structure/index.rst b/docs/integration_guide/source_structure/index.rst
new file mode 100644
index 0000000..426e2a9
--- /dev/null
+++ b/docs/integration_guide/source_structure/index.rst
@@ -0,0 +1,8 @@
+.. toctree::
+ :maxdepth: 1
+
+ source_structure.rst
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_ext_folder.rst b/docs/integration_guide/source_structure/platform_ext_folder.rst
similarity index 99%
rename from docs/integration_guide/platform/platform_ext_folder.rst
rename to docs/integration_guide/source_structure/platform_ext_folder.rst
index 949f2c6..ec52d26 100644
--- a/docs/integration_guide/platform/platform_ext_folder.rst
+++ b/docs/integration_guide/source_structure/platform_ext_folder.rst
@@ -1,3 +1,5 @@
+.. _platform_ext_folder:
+
###################################
Details for the platform/ext folder
###################################
@@ -302,6 +304,6 @@
--------------
-*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2023, Arm Limited. All rights reserved.*
*Copyright (c) 2020-2022 Cypress Semiconductor Corporation (an Infineon company)
or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
diff --git a/docs/integration_guide/platform/platform_folder.rst b/docs/integration_guide/source_structure/platform_folder.rst
similarity index 97%
rename from docs/integration_guide/platform/platform_folder.rst
rename to docs/integration_guide/source_structure/platform_folder.rst
index d165ce9..8b36222 100644
--- a/docs/integration_guide/platform/platform_folder.rst
+++ b/docs/integration_guide/source_structure/platform_folder.rst
@@ -1,3 +1,5 @@
+.. _platform_folder:
+
###############################
Details for the platform folder
###############################
@@ -94,4 +96,4 @@
--------------
-*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/source_structure/source_structure.rst b/docs/integration_guide/source_structure/source_structure.rst
new file mode 100644
index 0000000..126bd9c
--- /dev/null
+++ b/docs/integration_guide/source_structure/source_structure.rst
@@ -0,0 +1,126 @@
+.. _source_structure:
+
+################
+Source Structure
+################
+
+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. Additionally, the folders below are
+important for TF-M integration and descibed in a separate documents:
+
+.. toctree::
+ :maxdepth: 1
+
+ Details for the /platform folder <platform_folder.rst>
+ Details for the /platform/ext folder <platform_ext_folder.rst>
+
+/ (TF-M root)
+=============
+This table describes the structure under the root folder with part of
+possible folders.
+
+========================= ====================================
+Folder name Description
+========================= ====================================
+bl1 The 1st stage immutable bootloader
+bl2 MCUBoot based 2nd stage bootloader
+cmake Cmake files of the build system
+config Configuration system files
+docs The documentation
+interface RoT service API for client calls
+lib The 3rd party libraries
+`platform`_ Platform intermedia files
+`secure_fw`_ The secure firmware
+tools Tools in scripts for building
+========================= ====================================
+
+platform
+========
+The `platform` folder contains SW ports of all :ref:`supported platforms
+<supported_platforms>` and the files necessary for :ref:`adding a new platform
+<adding_platform>`. Please refer to :ref:`platform folder document
+<platform_folder>` for more information.
+
+========================= =============================================
+Folder name Description
+========================= =============================================
+include HAL and platform public headers
+ext Platform ports and related files
+========================= =============================================
+
+platform/ext
+------------
+This folder can include imported files licensed differently from TF-M's
+BSD-3 license. More details are in the dedicated document :ref:`platform_ext_folder`.
+
+========================= =============================================
+Folder name Description
+========================= =============================================
+accelerator Supported Crypto HW accelerators
+cmsis A copy of essential CMSIS headers
+common Common HAL implementation
+driver Driver headers for porting
+target/<vendor> Vendor specific folders with ported platforms
+========================= =============================================
+
+Each `vendor` is assigned one folder for usage under `target/`.
+A `vendor` contributes platform's ports and 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 Description
+========================= =============================================
+include Public headers of `secure_fw`
+partitions Default services and SPRTL
+spm PSA FF-M SPM implementation
+shared Sources shared out of SPRTL
+========================= =============================================
+
+The shared sources can be referenced by the building system out of SPRTL.
+Generally, they are runtime and PSA APIs.
+
+secure_fw/include
+-----------------
+This folder holds public headers for external references by clients,
+services and platforms. Avoid putting private headers, not referenced by
+other modules in this `include` folder.
+
+secure_fw/partitions
+--------------------
+This folder contains default services implemented as partitions and runtime
+utilities used and provided by TF-M.
+
+============================== =============================================
+Folder name Description
+============================== =============================================
+lib/runtime The SPRTL sources and intermedia files
+<partition_x> Sources of `partition_x`
+<partition_x>/include RoT Service API headers of `partition_x`
+<partition_y> Sources of `partition_y`
+<partition_y>/include RoT Service API headers of `partition_y`
+============================== =============================================
+
+Here `partition_x` and `partition_y` are examples of RoT services without
+detailed structure of them.
+
+secure_fw/spm
+-------------
+The SPM is the core component to provide a mechanism for providing secure
+services complied with PSA FF-M.
+
+============================== =============================================
+Folder name Description
+============================== =============================================
+include SPM public headers.
+ffm SPM logic complies with PSA FF-M specification
+cmsis_psa CMSIS implementation for PSA FF-M SPM
+============================== =============================================
+
+--------------
+
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*