1###################################
2Trusted Firmware-M Source Structure
3###################################
4
5:Organization: Arm Limited
6:Contact: tf-m@lists.trustedfirmware.org
7
8.. note::
9  Reference the document :doc:`Glossary </glossary>` for terms
10  and abbreviations.
11
12************
13Introduction
14************
15TF-M is designed to provide a user-friendly source structure to ease
16integration and service development. This document introduces the source
17structure and its design intention of TF-M.
18
19.. note::
20  - This document goes ahead of the implementation so the existing source
21    structure may be different from the description listed here. It is
22    recommended to refer to this document for ongoing code structure changes.
23  - By getting feedback from the practical implementation, this document is
24    updated continuously before it is detailed enough to be a user guide.
25
26****************
27Source Structure
28****************
29The description of the source structure is broken down into subsections, each
30subsection introduces one detailed folder.
31
32Root Directory
33==============
34This table describes the structure under the root directory with part of
35possible folders. Note that the ``Detailed`` field indicates if the folder is
36described in details here in this document:
37
38============= ==================================== ====================
39Folder name   Purpose                              Detailed
40============= ==================================== ====================
41bl2           The 2nd stage bootloader.            No.
42cmake         Cmake files.                         No.
43configs       Configuration system files.          No.
44docs          The documentations.                  No.
45lib           The 3rd party library.               No.
46**platform**  Platform intermedia files.           See `'platform'`_.
47**secure_fw** The secure firmware.                 See `'secure_fw'`_.
48tools         Tools in scripts for building.       No.
49============= ==================================== ====================
50
51'platform'
52==========
53The platform sources contain necessary platform sources or intermedia files
54pointing to the sources out of TF-M folder.
55
56========================= =============================================
57Folder name               Purpose
58========================= =============================================
59common/\*                 Common HAL implementation.
60include/\*                Platform public headers.
61<vendor>                  Vendor specific folders.
62========================= =============================================
63
64.. note::
65  The ``common`` folder contains the example implementation of the ``HAL`` API
66  bases on common ``system`` (CMSIS e.g.). The platform could reference to
67  sources in the ``common`` folder directly if applicable or apply a
68  customized HAL implementation.
69  A ``system`` can have a standalone folder under ``common``, depends on how
70  'common' this system is. Each ``platform vendor`` is assigned with one
71  folder for usage. As the content of the ``vendor`` folder comes by the
72  contribution of vendors, the ``vendor`` manages the structure inside it.
73
74'secure_fw'
75===========
76This folder contains components needed by secure firmware, and the exported
77interfaces for application, service development and HAL integration:
78
79================= ===================================== ======================
80Folder name       Purpose                               Detailed
81================= ===================================== ======================
82**include**       Public headers of 'secure_fw'.        See `'include'`_
83**partitions**    Default services and supportings.     See `'partitions'`_
84**spm**           PSA-FF-M SPM implementation. [1]      See `'spm'`_
85================= ===================================== ======================
86
87.. note::
88  1. A PSA-FF-M complied SPM implementation.
89
90  The headers referenced by other modules are public headers and put under the
91  'include' folder of the current module. Do not put headers not referenced by
92  other modules in this 'include' folder.
93
94'include'
95---------
96This folder holds headers for client, services and platform integration usage.
97
98=========================== ===================================================
99Folder name                 Purpose
100=========================== ===================================================
101psa/\*                      PSA FF Client API.
102=========================== ===================================================
103
104.. note::
105  TFM applies an explicit including policy. Each module's headers are put into
106  a specific folder which follows the pattern '\*/inc', this folder needs to be
107  added into the project's searching path if this project needs to include
108  headers in this folder. The 'inc' in a path indicates the end of
109  including-path. If there are subfolders under folder 'inc', apply a
110  hierarchy including.
111
112'partitions'
113------------
114This folder contains default services implemented as partitions and necessary
115partition runtime utilities provided by TF-M.
116
117================================= =============================================
118Folder name                       Purpose
119================================= =============================================
120lib/runtime/\*                    The SPRTL sources and intermedia files. [1]
121lib/runtime/shared\*              Sources can be shared by out of SPRTL. [2]
122<partition_x>/\*                  Files for 'partition_x'.
123<partition_x>/include/\*          RoT Service API headers of 'partition_x'. [3]
124<partition_y>/\*                  Files for 'partition_y'.
125<partition_y>/include/\*          RoT Service API headers of 'partition_y'. [3]
126================================= =============================================
127
128.. note::
129  1. The SPRTL sources and intermediate files. SPRTL contains sources from
130     other folders, such as necessary RoT Service API implementation from
131     'partitions' folder.
132  2. The sources here can be referenced by the building system out of SPRTL.
133     Generally, they are runtime and PSA APIs.
134  3. Here takes 'partition_x' and 'partition_y' as an example, and showcases
135     a detailed structure of them. The `<interface>` contains the RoT Service
136     API for client calls.  The folder name of this client-orient folder is
137     decided by the service developer.
138
139'spm'
140-----
141The SPM is the core component to provide a mechanism for providing secure
142services.
143
144=================================== ===========================================
145Folder name                         Purpose
146=================================== ===========================================
147include/\*                          SPM public headers.
148ffm/\*                              SPM logic complies with PSA-FF-M and
149                                    its necessary supporting functionalities,
150                                    such as the runtime API and the thread
151                                    operation, etc.
152cmsis_psa/\*                        CMSIS implementation for PSA-FF-M SPM. [1]
153\*                                  Implementation sources.
154=================================== ===========================================
155
156.. note::
157  1. CMSIS is the first implementation system.
158  2. This folder contains a function call based secure firmware implementation.
159     This model is the prototype model which would be updated after the PSA
160     model. Create a standalone folder to hold it.
161
162--------------
163
164*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
165