docs: Documentation restructure
- Change main index structure
- Sort out integration and porting guidelines
- Resort table with releases
- Add Tools section. To be adjusted further for tf-m-tools
Intention to minimise files movement to simplify review process.
Affected files shall be moved later after the new structure agreement.
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I0352bebabe09d4f7b5e8848ee620c0cea6881c94
diff --git a/docs/integration_guide/SQUAD_Dashboard.rst b/docs/integration_guide/SQUAD_Dashboard.rst
deleted file mode 100644
index 0bf6fad..0000000
--- a/docs/integration_guide/SQUAD_Dashboard.rst
+++ /dev/null
@@ -1,113 +0,0 @@
-#######################
-SQUAD metrics dashboard
-#######################
-
-:Author: Hugo L'Hostis
-:Organization: Arm Limited
-:Contact: hugo.lhostis@arm.com
-
-******************
-SQUAD Presentation
-******************
-
-Software Quality Dashboard (SQUAD) is a tool used by Trusted Firmware-M (TF-M)
-to keep track of some metrics for the project. It is a Linaro project (see here
-a link to the `SQUAD Documentation`_).
-
-For TF-M the purpose of having such a tool available is to have a history on
-some metrics of the project for different configurations of TF-M.
-
-The TF-M SQUAD is available here : `TFM's SQUAD`_. There are several
-configurations and metrics that can be selected, here is a link with some of
-them already selected :
-`SQUAD parametered for Default, profileS and MinsizeProfileS`_.
-
-**************************
-Metrics and configurations
-**************************
-
-The metrics sent to the dashboard are currently the memory footprint
-measurements from the TFM project calculated by the arm-none-eabi-size
-function for the 2 files bl2.axf and tfm_s.axf :
-
- - Text section size.
- - bss section size.
- - data total size.
- - Total file size.
-
-Each metric sent to the dashboard can be compared for different configurations
-used. The configurations available currently are the following :
-
- - Default
- - CoreIPC
- - CoreIPCTfmLevel2
- - DefaultProfileS
- - DefaultProfileM
- - DefaultProfileL
- - MinSizeProfileS (DefaultProfileS with MinsizeRel Cmake type)
-
-For all of the configurations, tests are disabled and the release build type is
-used. For more details about the configurations and how the rest of the options
-are set for each of them, see
-:ref:`Migration from legacy buildsystem`.
-More configurations and metrics could be added to the dashboard in the future.
-
-For each metric sent to the SQUAD dashboard, the metric must be linked with the
-state of the TF-M repository at the time of the build. On the dashboard this is
-visible from a string of numbers in the abscissa of the graphs displayed in
-SQUAD. This is the change ID of the latest commit used for the build. This
-means that in the case of 2 consecutive days with no new commit for TF-M, no
-new data points will be created.
-
-**************
-CI integration
-**************
-
-The data is currently sent by the `TFM CI's nightly build`_.
-
-The parameter "SQUAD_CONFIGURATIONS" of the CI build is what will trigger the
-configurations sent to the SQUAD dashboard. It should be set to the
-configurations's names separated by a comma, example :
-
-``SQUAD_CONFIGURATIONS = Default,DefaultProfileS``
-
-In this case, the 2 configurations Default and DefaultProfileS will be enabled
-and the data for those (and only those 2) will be sent to the dashboard.
-This is case insensitive and will ignore any space between the configurations.
-All the files manipulating the data and sending the data is available in the
-`tf-m-ci-scripts repo`_.
-
-The script `memory_footprint.py`_ is launched by the CI nightly build, it
-gathers and sends the data.
-
-*********************
-Adding a new platform
-*********************
-
-Currently, all the data sent is from AN521 builds. To add a new platform to the
-dashboard :
-
-1. If the new platform is not already tested by the CI nightly build, it needs
-to be added.
-
-2. The ``memory_footprint.py`` file in the `tf-m-ci-scripts repo`_ has to be
-modified to recognise the new platform.
-
-3. If ``memory_footprint.py`` detects the new platform with a reference
-configuration, it should send a new metric with a different name to the
-existing ones containing the platform's name.
-
-The data will then be accessible by selecting the correct metrics on the
-dashboard.
-
-
-.. _SQUAD Documentation: https://squad.readthedocs.io/en/latest/index.html
-.. _TFM's SQUAD: https://qa-reports.linaro.org/tf/tf-m/metrics/
-.. _SQUAD parametered for Default, profileS and MinsizeProfileS: https://qa-reports.linaro.org/tf/tf-m/metrics/?environment=Default&environment=DefaultProfileS&environment=MinSizeProfileS&metric=tfms_size&metric=tfms_data&metric=tfms_bss&metric=bl2_size&metric=bl2_data&metric=bl2_bss&range_tfms_size=0,100&range_tfms_data=0,100&range_tfms_bss=0,100&range_bl2_size=0,100&range_bl2_data=0,100&range_bl2_bss=0,100
-.. _TFM CI's nightly build: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-nightly/
-.. _tf-m-ci-scripts repo: https://review.trustedfirmware.org/admin/repos/ci/tf-m-ci-scripts
-.. _memory_footprint.py: https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/memory_footprint.py?h=refs/heads/master
-
---------------
-
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst
index 41bc4d2..0f6e276 100644
--- a/docs/integration_guide/index.rst
+++ b/docs/integration_guide/index.rst
@@ -1,12 +1,140 @@
+#################
Integration Guide
-=================
+#################
+The purpose of this document is to provide a guide on how to integrate TF-M
+with other hardware platforms and operating systems.
+
+
.. toctree::
:maxdepth: 1
- :glob:
- */index
- *
+ NS client integration <non-secure_client_extension_integration_guide.rst>
+ OS migration to Armv8-M <os_migration_guide_armv8m.rst>
+ tfm_fpu_support.rst
+ tfm_secure_irq_integration_guide.rst
+ Adding a Test Suite <tfm_test_suites_addition.rst>
+ How to add a partition <services/tfm_secure_partition_addition>
+
+.. toctree::
+ :maxdepth: 2
+
+ platform/index
+ services/index
+
+
+*****************
+How to build TF-M
+*****************
+Follow the :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
+
+********************************************************
+How to export files for building non-secure applications
+********************************************************
+Explained in the :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
+
+*************************
+How to add a new platform
+*************************
+
+:doc:`Porting TF-M to a New Hardware </integration_guide/platform/porting_TFM_to_a_new_hardware>`
+contains guidance on how to add a new platform.
+
+***************************
+How to integrate another OS
+***************************
+
+OS migration to Armv8-M platforms
+=================================
+To work with TF-M on Armv8-M platforms, the OS needs to support the Armv8-M
+architecture and, in particular, it needs to be able to run in the non-secure
+world. More information about OS migration to the Armv8-M architecture can be
+found in the :doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon
+the system configuration this may require configuring drivers to use appropriate
+address ranges.
+
+Interface with TF-M
+===================
+The files needed for the interface with TF-M are exported at the
+``<install_dir>/interface`` path. The NS side is only allowed to call
+TF-M secure functions (veneers) from the NS Thread mode.
+
+TF-M interface header files are exported in ``<install_dir>/interface/include``
+directory. For example, the Protected Storage (PS) service PSA API is declared
+in the file ``<install_dir>/interface/include/psa/protected_storage.h``.
+
+TF-M also exports a reference implementation of PSA APIs for NS clients in the
+``<install_dir>/interface/src``.
+
+On Armv8-M TrustZone based platforms, NS OS shall implement interface API
+``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
+APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
+of ``tfm_ns_interface_dispatch()``.
+TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
+Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
+``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
+See ``interface/src/tfm_ns_interface.c.example`` for more details.
+
+TF-M provides a reference implementation of NS mailbox on multi-core platforms,
+under folder ``interface/src/multi_core``.
+See :doc:`Mailbox design </technical_references/design_docs/dual-cpu/mailbox_design_on_dual_core_system>`
+for TF-M multi-core mailbox design.
+
+Interface with non-secure world regression tests
+================================================
+A non-secure application that wants to run the non-secure regression tests
+needs to call the ``tfm_non_secure_client_run_tests()``. This function is
+exported into the header file ``test_framework_integ_test.h`` inside the
+``<build_dir>/install`` folder structure in the test specific files,
+i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
+tests are precompiled and delivered as a static library which is available in
+``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
+needs to link against the library to be able to invoke the
+``tfm_non_secure_client_run_tests()`` function. The PS non-secure side
+regression tests rely on some OS functionality e.g. threads, mutexes etc. These
+functions comply with CMSIS RTOS2 standard and have been exported as thin
+wrappers defined in ``os_wrapper.h`` contained in
+``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
+implementation of these wrappers to be able to run the tests.
+
+NS client Identification
+========================
+
+The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
+If SPM manages the NSID (default option), then the same NSID (-1) will be used
+for all connections from NS clients.
+For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
+used for different NS clients. See
+:doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`.
+
+*********************
+Non-secure interrupts
+*********************
+Non-secure interrupts are allowed to preempt Secure thread mode.
+With the current implementation, a NSPE task can spoof the identity of another
+NSPE task. This is an issue only when NSPE has provisions for task isolation.
+Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
+to NS interrupts to the lower half of available priorities so that it wouldn't
+be possible for any non-secure interrupt to preempt a higher-priority secure
+interrupt.
+
+**********************************
+Integration with non-Cmake systems
+**********************************
+
+Generated Files
+===============
+
+Files that are derived from PSA manifests are generated at build-time by cmake.
+For integration with systems that do no use cmake, the files must be generated
+manually.
+
+The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
+arguments will be needed to be provided. Please refer to
+``tfm_parse_manifest_list.py --help`` for more details.
+
+Some variables are used in the template files, these will need to be set in the
+environment before the script will succeed when the script is not run via cmake.
--------------
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/index.rst b/docs/integration_guide/platform/index.rst
new file mode 100644
index 0000000..9fd2f2c
--- /dev/null
+++ b/docs/integration_guide/platform/index.rst
@@ -0,0 +1,13 @@
+Porting to a new platform
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ porting_TFM_to_a_new_hardware
+ /platform/readme
+ /platform/ext/readme
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/porting_TFM_to_a_new_hardware.rst b/docs/integration_guide/platform/porting_TFM_to_a_new_hardware.rst
similarity index 100%
rename from docs/integration_guide/porting_TFM_to_a_new_hardware.rst
rename to docs/integration_guide/platform/porting_TFM_to_a_new_hardware.rst
diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst
index f8892ab..7567e78 100644
--- a/docs/integration_guide/services/index.rst
+++ b/docs/integration_guide/services/index.rst
@@ -12,7 +12,6 @@
Platform <tfm_platform_integration_guide>
Protected Storage <tfm_ps_integration_guide>
PSA Proxy <tfm_psa_proxy_integration_guide>
- How to add a partition <tfm_secure_partition_addition>
--------------
diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst
index 66f8d21..f64fe3b 100644
--- a/docs/integration_guide/services/tfm_ps_integration_guide.rst
+++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst
@@ -298,7 +298,7 @@
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 </integration_guide/tfm_integration_guide>`
+The :doc:`integration guide </integration_guide/index>`
provides further details of non-secure implementation requirements for TF-M.
Cryptographic Interface
diff --git a/docs/integration_guide/tfm_integration_guide.rst b/docs/integration_guide/tfm_integration_guide.rst
deleted file mode 100644
index 6b3ae7a..0000000
--- a/docs/integration_guide/tfm_integration_guide.rst
+++ /dev/null
@@ -1,122 +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 </technical_references/instructions/tfm_build_instruction>`.
-
-********************************************************
-How to export files for building non-secure applications
-********************************************************
-Explained in the :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`.
-
-*************************
-How to add a new platform
-*************************
-
-:doc:`Porting TF-M to a New Hardware </integration_guide/porting_TFM_to_a_new_hardware>`
-contains guidance on how to add a new platform.
-
-***************************
-How to integrate another OS
-***************************
-
-OS migration to Armv8-M platforms
-=================================
-To work with TF-M on Armv8-M platforms, the OS needs to support the Armv8-M
-architecture and, in particular, it needs to be able to run in the non-secure
-world. More information about OS migration to the Armv8-M architecture can be
-found in the :doc:`OS requirements <os_migration_guide_armv8m>`. Depending upon
-the system configuration this may require configuring drivers to use appropriate
-address ranges.
-
-Interface with TF-M
-===================
-The files needed for the interface with TF-M are exported at the
-``<install_dir>/interface`` path. The NS side is only allowed to call
-TF-M secure functions (veneers) from the NS Thread mode.
-
-TF-M interface header files are exported in ``<install_dir>/interface/include``
-directory. For example, the Protected Storage (PS) service PSA API is declared
-in the file ``<install_dir>/interface/include/psa/protected_storage.h``.
-
-TF-M also exports a reference implementation of PSA APIs for NS clients in the
-``<install_dir>/interface/src``.
-
-On Armv8-M TrustZone based platforms, NS OS shall implement interface API
-``tfm_ns_interface_dispatch()`` to integrate with TF-M implementation of PSA
-APIs. See ``interface/include/tfm_ns_interface.h`` for the detailed declaration
-of ``tfm_ns_interface_dispatch()``.
-TF-M provides an example of ``tfm_ns_interface_dispatch()`` implementation on
-Armv8-M TrustZone based platforms. In this example, NS OS calls mutex in
-``tfm_ns_interface_dispatch()`` to synchronize multiple NS client calls to TF-M.
-See ``interface/src/tfm_ns_interface.c.example`` for more details.
-
-TF-M provides a reference implementation of NS mailbox on multi-core platforms,
-under folder ``interface/src/multi_core``.
-See :doc:`Mailbox design </technical_references/design_docs/dual-cpu/mailbox_design_on_dual_core_system>`
-for TF-M multi-core mailbox design.
-
-Interface with non-secure world regression tests
-================================================
-A non-secure application that wants to run the non-secure regression tests
-needs to call the ``tfm_non_secure_client_run_tests()``. This function is
-exported into the header file ``test_framework_integ_test.h`` inside the
-``<build_dir>/install`` folder structure in the test specific files,
-i.e. ``<build_dir>/install/export/tfm/test/inc``. The non-secure regression
-tests are precompiled and delivered as a static library which is available in
-``<build_dir>/install/export/tfm/test/lib``, so that the non-secure application
-needs to link against the library to be able to invoke the
-``tfm_non_secure_client_run_tests()`` function. The PS non-secure side
-regression tests rely on some OS functionality e.g. threads, mutexes etc. These
-functions comply with CMSIS RTOS2 standard and have been exported as thin
-wrappers defined in ``os_wrapper.h`` contained in
-``<build_dir>/install/export/tfm/test/inc``. OS needs to provide the
-implementation of these wrappers to be able to run the tests.
-
-NS client Identification
-========================
-
-The NS client identification (NSID) is specified by either SPM or NSPE RTOS.
-If SPM manages the NSID (default option), then the same NSID (-1) will be used
-for all connections from NS clients.
-For the case that NSPE RTOS manages the NSID and/or different NSIDs should be
-used for different NS clients. See
-:doc:`Non-secure Client Extension Integration Guide </integration_guide/non-secure_client_extension_integration_guide>`.
-
-*********************
-Non-secure interrupts
-*********************
-Non-secure interrupts are allowed to preempt Secure thread mode.
-With the current implementation, a NSPE task can spoof the identity of another
-NSPE task. This is an issue only when NSPE has provisions for task isolation.
-Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available
-to NS interrupts to the lower half of available priorities so that it wouldn't
-be possible for any non-secure interrupt to preempt a higher-priority secure
-interrupt.
-
-**********************************
-Integration with non-Cmake systems
-**********************************
-
-Generated Files
-===============
-
-Files that are derived from PSA manifests are generated at build-time by cmake.
-For integration with systems that do no use cmake, the files must be generated
-manually.
-
-The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some
-arguments will be needed to be provided. Please refer to
-``tfm_parse_manifest_list.py --help`` for more details.
-
-Some variables are used in the template files, these will need to be set in the
-environment before the script will succeed when the script is not run via cmake.
-
---------------
-
-*Copyright (c) 2017-2022, Arm Limited. All rights reserved.*