Docs: Structure - 'include' folder renaming etc
Added SPM support layer implemented by CMSIS to hold the support
layer between SPM and actual platform since CMSIS is the first
implementation base for SPM. Also, collect library model
implementation into 'secure_fw/spm/func_cmsis'.
Change-Id: I8dff1cc60f7431e0f0434d044f4efb2a2e1ee9d3
Signed-off-by: Ken Liu <ken.liu@arm.com>
diff --git a/docs/design_documents/source_structure.rst b/docs/design_documents/source_structure.rst
index b22be0b..1b71215 100644
--- a/docs/design_documents/source_structure.rst
+++ b/docs/design_documents/source_structure.rst
@@ -12,18 +12,16 @@
************
Introduction
************
-TF-M is designed to provide a user-friendly source structure to easy
+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. Staging
- changes must reference this document since it is the goal of structure
- design.
- - Related non-source content like libraries, scripts and binaries are also
- introduced but briefly since this document focuses more on the source
- code.
+ 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
@@ -33,29 +31,24 @@
Root Direcotry
==============
-This table describes the structure under the root directory. The item with a
-`No` in the `Detailed` field is briefly introduced but not detailed into
-subsections.
+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. [1]
-cmake Cmake files. No. [2]
-configs Configuration system files. No. [2]
-docs The documentations. No. [2]
-lib The 3rd party library. No. [1]
+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'`_.
-**test** Tests. See `'test'`_.
-tools Tools in scripts for building. No. [2]
+test Tests. No.
+tools Tools in scripts for building. No.
============= ==================================== ====================
-.. note::
- 1. 3rd party project structure is not introduced.
- 2. Non-source content maybe not listed here, or introduction is skipped even
- they are listed.
-
'platform'
==========
The platform sources contain necessary platform sources or intermedia files
@@ -65,7 +58,8 @@
Folder name Purpose
========================= =============================================
common/\* Common HAL implementation.
-<vendor> Vendor specific folder.
+include/\* Platform public headers.
+<vendor> Vendor specific folders.
========================= =============================================
.. note::
@@ -83,64 +77,38 @@
This folder contains components needed by secure firmware, and the exported
interfaces for application, service development and HAL integration:
-============== =========================================== ====================
-Folder name Purpose Detailed
-============== =========================================== ====================
-**spm** Generic SPM sources. See `'spm'`_
-**include** Interfaces for PSA FF and TF-M generic. See `'include'`_
-**partitions** Default services and supportings. See `'partitions'`_
-**shared** Sources not only for secure firmware usage. See `'shared'`_
-============== =========================================== ====================
-
-'spm'
------
-The SPM is the core component to provide a mechanism for providing secure
-services.
-
-=================================== ===========================================
-Folder name Purpose
-=================================== ===========================================
-arch/\* Architecture sources. [1]
-include/\* SPM public headers.
-include/hal\* SPM public headers for HAL.
-init/* SPM initializing entry. [2]
-model_ipc/\* PSA-FF-M SPM implementation. [3]
-model_func/\* The library model SPM implementation. [4]
-runtime/\* SPM runtime utilities. [5]
-services/\* PRoT Services not in partitions. [6]
-=================================== ===========================================
+================= ===================================== ======================
+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. The Architecture source focus on context-related operations.
- 2. SPM startup code.
- 3. A PSA-FF-M-complied SPM implementation.
- 4. A customized library model SPM implementation.
- 5. The SPM runtime utilities such as memory managing and scheduling.
- 6. The services can be implemented as Secure Partitions or partition-less PSA
- RoT Services. Here puts the partition-less services.
+ 1. A PSA-FF-M complied SPM implementation.
- The private headers for each component in this folder are
- development-defined. Do not mix private headers with public headers into the
- same folder.
+ 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/\*.h PSA FF headers.
-tfm/\*.h TF-M specific feature headers.
-=========================== =============================================
+=========================== ===================================================
+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 '\*/include', this folder needs
- to be added into the project's searching path if this project needs to
- include headers in this folder. The 'include' in a path indicates the end of
- including-path. If there are subfolders under folder 'include', apply a
- relative hierarchy including.
+ 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'
------------
@@ -151,57 +119,44 @@
Folder name Purpose
================================= =============================================
lib/sprt/\* The SPRTL sources and intermedia files. [1]
+lib/sprt/shared\* Sources can be shared by out of SPRTL. [2]
<partition_x>/\* Files for 'partition_x'.
-<partition_x>/export/include/\*.h RoT Service API headers of 'partition_x'. [2]
-<partition_x>/export/src/\*.c RoT Service API sources of 'partition_x'. [2]
+<partition_x>/include/\* RoT Service API headers of 'partition_x'. [3]
<partition_y>/\* Files for 'partition_y'.
-<partition_y>/export/include/\*.h RoT Service API headers of 'partition_y'. [2]
-<partition_y>/export/src/\*.c RoT Service API sources of 'partition_y'. [2]
+<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. Here takes 'partition_x' and 'partition_y' as an example, and showcases
- a detailed structure of them.
+ 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.
-'shared'
---------
-Here place the sources which are needed by SPE components and shared between
-multiple components (includes NSPE components).
+'spm'
+-----
+The SPM is the core component to provide a mechanism for providing secure
+services.
-========================= =============================================
-Folder name Purpose
-========================= =============================================
-shared/psa/\*.c Shared PSA FF sources.
-shared/tfm/\*.c Shared TF-M feature sources.
-========================= =============================================
+=================================== ===========================================
+Folder name Purpose
+=================================== ===========================================
+include/\* SPM public headers.
+common/\* SPM common logic complies PSA-FF-M.
+psa_cmsis/\* CMSIS implementation for PSA-FF-M SPM. [1]
+func_cmsis/\* The library model implementation. [2]
+\* Implementation sources.
+=================================== ===========================================
.. note::
- Examples for the shared sources:
- The parameter packing for ``psa_call()`` is same between NSPE clients and
- the secure clients, the only difference is the final call. In a TrustZone
- implementation it is an 'SG' for NSPE while for secure clients it can be a
- 'SVC'. So this ``psa_call`` implementation under 'psa/' can be shared
- between NSPE clients and the secure clients. So does the TF-M customized
- feature sources under the 'tfm/' direcotry.
-
-'test'
-======
-The NSPE examples are for test-purpose-specific.
-
-============================== ===========================================
-Folder name Purpose
-============================== ===========================================
-test/nspe/rtx/\* RTX - the example NSPE instance. [1]
-test/* Other test related sources. [2]
-============================== ===========================================
-
-.. note::
- 1. This is the example NSPE instance.
- 2. Other sources are managed by the 'test' design. The test purpose secure
- services are also put under this foler (NOT the `'partitions'`_ folder).
+ 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.
--------------