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/CMakeLists.txt b/docs/CMakeLists.txt
index cf3e364..eb17631 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -34,14 +34,14 @@
file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst ${SPHINXCFG_SOURCE_PATH}/*.md)
add_custom_target(tfm_docs_userguide_html ALL
- COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
+ COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j 8 -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
DEPENDS ${SPHINXCFG_DOC_FILES}
)
add_dependencies(docs tfm_docs_userguide_html)
add_custom_target(tfm_docs_userguide_pdf ALL
- COMMAND "${SPHINX_EXECUTABLE}" -W -b latex -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/latex"
+ COMMAND "${SPHINX_EXECUTABLE}" -W -b latex -j 8 -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/latex"
COMMAND ${PDFLATEX_COMPILER} -output-directory "${SPHINXCFG_OUTPUT_PATH}/latex" TF-M.tex
COMMAND ${CMAKE_COMMAND} -E copy "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf" "${SPHINXCFG_OUTPUT_PATH}/tf-m_user_guide.pdf"
WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
diff --git a/docs/contributing/code_review_guide.rst b/docs/contributing/code_review_guide.rst
index 343fb17..622bf75 100644
--- a/docs/contributing/code_review_guide.rst
+++ b/docs/contributing/code_review_guide.rst
@@ -15,7 +15,7 @@
- Read the :doc:`Contributing Process </contributing/contributing_process>`
to know basic concepts.
-- Read the :doc:`Source Structure </design_docs/source_structure>`
+- Read the :ref:`source_structure`
for structure related reference.
The review guidelines consist of these items:
diff --git a/docs/design_docs/hardware_abstraction_layer.rst b/docs/design_docs/hardware_abstraction_layer.rst
index 89b7092..2a06297 100644
--- a/docs/design_docs/hardware_abstraction_layer.rst
+++ b/docs/design_docs/hardware_abstraction_layer.rst
@@ -71,8 +71,8 @@
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 </integration_guide/platform/platform_folder>` for more
- details.
+ settings section </integration_guide/source_structure/platform_folder>`
+ for more details.
*****************
Design Principles
diff --git a/docs/design_docs/source_structure.rst b/docs/design_docs/source_structure.rst
deleted file mode 100644
index 89d7205..0000000
--- a/docs/design_docs/source_structure.rst
+++ /dev/null
@@ -1,164 +0,0 @@
-###################################
-Trusted Firmware-M Source Structure
-###################################
-
-:Organization: Arm Limited
-:Contact: tf-m@lists.trustedfirmware.org
-
-.. note::
- Reference the document :doc:`Glossary </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> 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/runtime/\* The SPRTL sources and intermedia files. [1]
-lib/runtime/shared\* Sources can be shared by out of SPRTL. [2]
-<partition_x>/\* Files for 'partition_x'.
-<partition_x>/include/\* RoT Service API headers of 'partition_x'. [3]
-<partition_y>/\* Files for 'partition_y'.
-<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 `<interface>` 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]
-\* 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-2022, Arm Limited. All rights reserved.*
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.*
diff --git a/docs/platform/index.rst b/docs/platform/index.rst
index 871395b..3bce6f1 100644
--- a/docs/platform/index.rst
+++ b/docs/platform/index.rst
@@ -1,3 +1,5 @@
+.. _supported_platforms:
+
##############
TF-M Platforms
##############