diff options
Diffstat (limited to 'docs/technical_references/source_structure.rst')
-rw-r--r-- | docs/technical_references/source_structure.rst | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/docs/technical_references/source_structure.rst b/docs/technical_references/source_structure.rst new file mode 100644 index 0000000000..b2de0dda20 --- /dev/null +++ b/docs/technical_references/source_structure.rst @@ -0,0 +1,165 @@ +################################### +Trusted Firmware-M Source Structure +################################### + +:Organization: Arm Limited +:Contact: tf-m@lists.trustedfirmware.org + +.. note:: + Reference the document :doc:`Glossary </docs/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/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>/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] +cmsis_func/\* The library model implementation. [2] +\* 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-2021, Arm Limited. All rights reserved.* |