1.. _source_structure:
2
3################
4Source Structure
5################
6
7TF-M is designed to provide a user-friendly source structure to ease
8integration and service development. This document introduces the source
9structure and its design intention of TF-M. Additionally, the folders below are
10important for TF-M integration and descibed in a separate documents:
11
12.. toctree::
13    :maxdepth: 1
14
15    Details for the /platform folder     <platform_folder.rst>
16    Details for the /platform/ext folder <platform_ext_folder.rst>
17
18/ (TF-M root)
19=============
20This table describes the structure under the root folder with part of
21possible folders.
22
23========================= ====================================
24Folder name               Description
25========================= ====================================
26bl1                       The 1st stage immutable bootloader
27bl2                       MCUBoot based 2nd stage bootloader
28cmake                     Cmake files of the build system
29config                    Configuration system files
30docs                      The documentation
31interface                 RoT service API for client calls
32lib                       The 3rd party libraries
33`platform`_               Platform intermedia files
34`secure_fw`_              The secure firmware
35tools                     Tools in scripts for building
36========================= ====================================
37
38platform
39========
40The `platform` folder contains SW ports of all :ref:`supported platforms
41<supported_platforms>` and the files necessary for :ref:`adding a new platform
42<adding_platform>`. Please refer to :ref:`platform folder document
43<platform_folder>` for more information.
44
45========================= =============================================
46Folder name               Description
47========================= =============================================
48include                   HAL and platform public headers
49ext                       Platform ports and related files
50========================= =============================================
51
52platform/ext
53------------
54This folder can include imported files licensed differently from TF-M's
55BSD-3 license. More details are in the dedicated document :ref:`platform_ext_folder`.
56
57========================= =============================================
58Folder name               Description
59========================= =============================================
60accelerator               Supported Crypto HW accelerators
61cmsis                     A copy of essential CMSIS headers
62common                    Common HAL implementation
63driver                    Driver headers for porting
64target/<vendor>           Vendor specific folders with ported platforms
65========================= =============================================
66
67Each `vendor` is assigned one folder for usage under `target/`.
68A `vendor` contributes platform's ports and manages the structure inside it.
69
70secure_fw
71=========
72This folder contains components needed by secure firmware and the exported
73interfaces for application, service development and HAL integration.
74
75========================= =============================================
76Folder name               Description
77========================= =============================================
78include                   Public headers of `secure_fw`
79partitions                Default services and SPRTL
80spm                       PSA FF-M SPM implementation
81shared                    Sources shared out of SPRTL
82========================= =============================================
83
84The shared sources can be referenced by the building system out of SPRTL.
85Generally, they are runtime and PSA APIs.
86
87secure_fw/include
88-----------------
89This folder holds public headers for external references by clients,
90services and platforms. Avoid putting private headers, not referenced by
91other modules in this `include` folder.
92
93secure_fw/partitions
94--------------------
95This folder contains default services implemented as partitions and runtime
96utilities used and provided by TF-M.
97
98============================== =============================================
99Folder name                    Description
100============================== =============================================
101lib/runtime                    The SPRTL sources and intermedia files
102<partition_x>                  Sources of `partition_x`
103<partition_x>/include          RoT Service API headers of `partition_x`
104<partition_y>                  Sources of `partition_y`
105<partition_y>/include          RoT Service API headers of `partition_y`
106============================== =============================================
107
108Here `partition_x` and `partition_y` are examples of RoT services without
109detailed structure of them.
110
111secure_fw/spm
112-------------
113The SPM is the core component to provide a mechanism for providing secure
114services complied with PSA FF-M.
115
116============================== =============================================
117Folder name                    Description
118============================== =============================================
119include                        SPM public headers.
120core                           SPM base functionalities
121\*ext                          Extended SPM functionalities
122============================== =============================================
123
124--------------
125
126*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
127