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 <[email protected]> Change-Id: I0352bebabe09d4f7b5e8848ee620c0cea6881c94
Tide00 · Apr 23, 2022 · 91281f0 · 91281f0
1 parent 8e44834
commit 91281f0
Show file tree

Hide file tree

Showing 25 changed files with 285 additions and 272 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -107,9 +107,11 @@
 # documentation.
 #
 html_theme_options = {
-    'collapse_navigation': False,
-    'prev_next_buttons_location' : None   # Hide Prev and Next buttons
+    'collapse_navigation' : False,
+    'prev_next_buttons_location' : None,   # Hide Prev and Next buttons
 #    'display_version': True,    # Show version under logo
+    'sticky_navigation': True,
+    'navigation_depth': 2,
 }
 
 # Remove the "View page source" link from the top of docs pages

diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst
@@ -20,7 +20,7 @@ The following short-list provides a quick summary of the rules.
 
 - If the patch modifies a present file, the file's style should be followed
 - If creating a new file,
-  :doc:`integration guide </integration_guide/tfm_integration_guide>` can be used as a reference.
+  :doc:`integration guide </integration_guide/index>` can be used as a reference.
 - When a new style is to be expressed, consult the `Python Documentation Guidelines`_
 
 *************

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -3,10 +3,14 @@ Contribution Guidelines
 
 .. toctree::
     :maxdepth: 1
-    :glob:
-
-    *
+    :titlesonly:
 
+    The process <contributing_process>
+    Code review <code_review_guide>
+    Maintainers and Owners <maintainers>
+    coding_guide
+    Documentation <doc_guidelines>
+    Design proposal <tfm_design_proposal_guideline>
 
 --------------
 

diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
@@ -2,10 +2,6 @@ Getting Started Guides
 ======================
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    tfm_getting_started
+.. include:: tfm_getting_started.rst
 
---------------
-
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/tfm_getting_started.rst b/docs/getting_started/tfm_getting_started.rst
@@ -1,6 +1,44 @@
-####################################
-Select and set up build environments
-####################################
+##################
+First Things First
+##################
+
+************
+Prerequisite
+************
+Trusted Firmware M provides a reference implementation of platform security
+architecture  reference implementation aligning with PSA Certified guidelines.
+It is assumed that the reader is familiar with specifications can be found at
+`Platform Security Architecture Resources <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>`__.
+
+The current TF-M implementation specifically targets TrustZone for ARMv8-M so a
+good understanding of the v8-M architecture is also necessary. A good place to
+get started with ARMv8-M is
+`developer.arm.com <https://developer.arm.com/architectures/cpu-architecture/m-profile>`__.
+
+**************************
+Build and run instructions
+**************************
+Trusted Firmware M source code is available on
+`git.trustedfirmware.org <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/>`__.
+
+To build & run TF-M:
+
+    - Follow the this guide to set up and check your environment.
+    - Follow the
+      :doc:`Build instructions </technical_references/instructions/tfm_build_instruction>`
+      to compile and build the TF-M source.
+    - Follow the :doc:`Run TF-M examples on Arm platforms </technical_references/instructions/run_tfm_examples_on_arm_platforms>`
+      for information on running the example.
+
+To port TF-M to a another system or OS, follow the
+:doc:`OS Integration Guide </integration_guide/index>`
+
+:doc:`Contributing Guidelines </contributing/contributing_process>` contains guidance on how to
+contribute to this project.
+
+#########################
+Set up build environments
+#########################
 
 TF-M officially supports a limited set of build environments and setups. In
 this context, official support means that the environments listed below
@@ -369,8 +407,9 @@ To build the TF-M firmware the following tools are needed:
    - Python v3.x
    - a set of python modules listed in ``tools/requiremtns.txt``
 
+****************
 Dependency chain
-----------------
+****************
 
 .. uml::
 
@@ -409,9 +448,7 @@ Dependency chain
     imgtool --> python
    @enduml
 
-##########
-Next steps
-##########
+.. rubric:: Next steps
 
 Here are some next steps for exploring TF-M:
 

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -49,15 +49,15 @@ Glossary of terms and abbreviations
         permitted.
 
     SP
-        Secure Partition:
+    Secure Partition
         A logical container for secure services.
 
     SPE
         Secure Processing Environment:
         `PSA term`_. In TF-M this means the secure domain protected by TF-M.
 
     SPM
-        Secure Partition Manager
+    Secure Partition Manager
         The TF-M component responsible for enumeration, management and isolation
         of multiple Secure Partitions within the TEE.
 
@@ -76,10 +76,12 @@ Glossary of terms and abbreviations
         view, i.e. which is viewed as a single entity from a TF-M point of view.
 
     PS
-        Protected Storage service provided by TF-M.
+    Protected Storage
+       One of PSA services provided by TF-M.
 
     ITS
-        Internal Trusted Storage service provided by TF-M.
+    Internal Trusted Storage
+       One of PSA services provided by TF-M.
 
     TFM
     TF-M

diff --git a/docs/index.rst b/docs/index.rst
@@ -67,32 +67,44 @@ Trusted Firmware-M Documentation
     </ul>
 
 .. toctree::
-    :caption: Table of Contents
-    :name: mastertoc
-    :titlesonly:
+    :caption: Overview
     :maxdepth: 1
     :hidden:
 
-    Home<self>
     introduction/index
-    getting_started/index
-    platform/ext/index
-    contributing/index
-    integration_guide/index
-    technical_references/index
+    Getting Started <getting_started/index>
     security/index
     releases/index
+    Glossary <glossary>
+
+.. toctree::
+    :caption: Development
+    :maxdepth: 1
+    :hidden:
 
+    Platform Selection<platform/ext/index>
+    Building <technical_references/instructions/tfm_build_instruction>
+    integration_guide/index
+    technical_references/design_docs/index
+    Tools <tools/index>
+
+.. toctree::
+    :caption: Contribution
+    :titlesonly:
+    :hidden:
+
+    Guidelines <contributing/index>
+    contributing/lic
+    DCO <contributing/dco>
 
 .. toctree::
     :maxdepth: 2
     :hidden:
-    :caption: Quick Links
+    :caption: Links
 
     API Reference <https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/reference_manual/html/index.html>
     Security Center <https://developer.trustedfirmware.org/w/collaboration/security_center>
-    Platform Security Architecture <https://developer.arm.com/architectures/security-architectures/platform-security-architecture>
-    Glossary <glossary>
+    PSA <https://www.arm.com/architecture/security-features/platform-security>
 
 --------------
 

diff --git 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
@@ -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/...n_guide/porting_TFM_to_a_new_hardware.rst → ...latform/porting_TFM_to_a_new_hardware.rst b/...n_guide/porting_TFM_to_a_new_hardware.rst → ...latform/porting_TFM_to_a_new_hardware.rst
diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst
@@ -12,7 +12,6 @@ Services
     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
@@ -298,7 +298,7 @@ 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 </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