1#############################
2TF-M Manifest Tool User Guide
3#############################
4This document describes the TF-M manifest tool and its usage.
5The target audiences are mainly platform integrators and Secure Partition
6developers.
7
8This document assumes that audiences have knowledge about the terminologies
9defined in PSA Firmware Framework (FF-M) v1.0 [1]_ and the FF-M v1.1 extensions
10[2]_, such as Secure Partition and manifests.
11
12************
13Introduction
14************
15The TF-M manifest tool is a python script which is used to parse Secure
16Partition manifests and generate source header files defined by FF-M [1]_ such
17as ``psa_manifest/pid.h`` and ``psa_manifest/sid.h``.
18It also generates TF-M specific files for building.
19
20In the TF-M build system, the manifest tool is invoked during building
21automatically. Arguments are passed through CMake variables and they are
22customizable.
23See `Usage in TF-M Build System`_ for more details.
24
25It can be also used as a standalone tool.
26
27*********
28Arguments
29*********
30The tool takes 5 arguments at most.
31
32.. code-block:: bash
33
34    tfm_parse_manifest_list.py [-h] -o out_dir
35                               -m manifest list [manifest list ...]
36                               -f file-list [file-list ...]
37                               -c config-files [config-files ...]
38                               [-q]
39
40**-o/--outdir**
41
42Required.
43
44The directory to hold the output files.
45
46**-m/--manifest-lists**
47
48Required. At least one item must be provided.
49
50A list of TF-M Secure Partition manifest lists which contain one or more
51Secure Partition manifests in each.
52See `Manifest List`_ for details.
53
54**-f/--file-list**
55
56Required. At least one item must be provided.
57
58A list of files that describe what files the tool should generate.
59See `Generated File List`_ for details.
60
61**-c/--config-files**
62
63Required. At least one item must be provided.
64
65A list of header files which contain build configurations such as isolation
66level and Secure Partition enabled status.
67See `Configuration Header File`_ for details.
68
69**-q/--quiet**
70
71Optional.
72
73Reduces log messages, only warnings and errors will be printed.
74
75.. _tfm_manifest_list:
76
77Manifest List
78=============
79A manifest list is a YAML [3]_ file that describes a list of Secure Partition
80manifests.
81Refer to the TF-M default manifest list [4]_ as an example.
82
83Each manifest list must contain a ``manifest_list`` attribute which collects the
84descriptions of Secure Partition manifests.
85Following are the supported attributes of in the manifest lists.
86
87- ``description``
88
89  Required.
90
91  Descriptive information for the tool to refer to the Secure Partition, for
92  example in logs.
93
94- ``manifest``
95
96  Required.
97
98  The manifest file of the Secure Partition.
99  Both absolute path and relative path to the manifest list are supported.
100  Environment variables are supported.
101
102- ``output_path``
103
104  Optional.
105
106  The directory to hold the Secure Partition specific output files.
107  See `Generated File List`_ for more details.
108
109  Both absolute path and relative path to the directory specified by
110  ``-o/--outdir`` are supported.
111  Environment variables are supported.
112
113  It is set to the directory specified by ``-o/--outdir`` if omitted.
114
115- ``conditional``
116
117  Optional.
118
119  The configuration to enable or disable this Secure Partition.
120  The value must be defined in one of the `Configuration Header File`_.
121  If it is omitted, the Secure Partition is always enabled.
122
123- ``pid``
124
125  Optional.
126
127  The Secure Partition ID (PID).
128
129  **For non-test purpose Secure Partitions, it is required.**
130  See :doc:`Adding Secure Partition <tfm_secure_partition_addition>`
131  for the PID allocations.
132
133  For test purpose Secure Partitions, this attribute is optional.
134  The manifest tool assigns one for the Secure Partition.
135  The value is not guaranteed to the same for different builds.
136
137- ``linker_pattern``
138
139  Optional.
140
141  The information for linker to place the symbols of the Secure Partition.
142  It is only required if you are using the linker scripts provided by TF-M.
143  Each Secure Partition is expected to be built as a library.
144  The name of the library must follow the format of
145  ``tfm_<type>_partition_<name>``.
146  The valid value for ``<type>`` is ``[psa_rot, app_rot]`` corresponding to the
147  type of the Secure Partitions.
148  The ``<name>`` is any string to distinguish the Secure Partition from others.
149
150  Supported patterns are:
151
152  - ``library_list``, must be ``*tfm_*partition_<name>.*``.
153  - ``object_list``
154
155    Any object files containing symbols belonging to the Secure Partition that
156    are not included in the Secure Partitions library.
157
158Generated File List
159===================
160A generated file list is a YAML file that describes the files to be generated
161by the manifest tool.
162Refer to TF-M default generated file list [5]_ as an example.
163
164Each one must contain a ``file_list`` attribute which collects the files to
165generate.
166Each item in the ``file_list`` must contain the following attributes.
167
168- ``template``
169
170  This attribute is the file path of a Jinja2 [6]_ template.
171  The TF-M manifest tool uses Jinja2 template engine for file generations.
172  It can be a relative path to TF-M root directory or an absolute path.
173  Environment variables are supported.
174
175- ``output``
176
177  The output file of the ``template``.
178  Both absolute path and relative path to the directory specified by
179  ``-o/--outdir`` are supported.
180  Environment variables are supported.
181
182**The tfm_generated_file_list.yaml is essential to build TF-M.**
183
184There are several files that are required for each Secure Partition,
185so they are not in any generated file lists since one template generates
186multiple files.
187
188- ``psa_manifest/<manifestfilename>.h``
189
190  ``manifestfilename`` is the file name of the manifest.
191  This file contains internal definitions for the Secure Partition
192  implementation, such as RoT Service signals and Secure Functions.
193  Refer to FF-M [1]_ for more details.
194  The corresponding template is ``manifestfilename.template``
195
196- ``intermedia_<manifestfilename>.c``
197
198  TF-M specific, which holds the stacks of Secure Partitions.
199  This file must be built with the Secure Partition libraries.
200  The corresponding template is ``partition_intermedia.template``.
201
202- ``load_info_<manifestfilename>.c``
203
204  TF-M specific, which contains the load information of Secure Partitions.
205  This file must be built with the TF-M SPM library.
206  The corresponding template is ``partition_load_info.template``.
207
208These files are generated to ``output_path`` specified by each Secure Partition
209in the manifest lists.
210
211Configuration Header File
212=========================
213The format of each configuration item must be
214
215.. code-block::
216
217    #define CONFIG_NAME   VALUE
218
219The following format is also supported for boolean type configurations.
220
221.. code-block::
222
223    #define CONFIG_NAME
224
225The configurations can be divided into two categories.
226
227- Generic configurations:
228
229  - ``PSA_FRAMEWORK_ISOLATION_LEVEL``
230
231    The isolation level, required. Valid values are ``[1, 2, 3]``.
232
233  - ``CONFIG_TFM_SPM_BACKEND``
234
235    The backend of SPM, required. Valid values are ``[SFN, IPC]``.
236    See :doc:`SPM backends </integration_guide/spm_backends>`
237    for details of backends.
238
239- Secure Partition enablement configurations
240
241  Configurations used to enable or disable Secure Partitions.
242  The configuration names must match the values of ``conditional`` attributes in
243  `Manifest List`_. Valid values are ``[0, 1]``.
244  It's optional for a Secure Partition which does not have the ``conditional``
245  attribute.
246
247The configurations can be split to multiple files corresponding to the multiple
248manifest lists.
249
250**************************
251Usage in TF-M Build System
252**************************
253In the TF-M build system, the manifest tool is invoked during building
254automatically.
255The arguments can be customized by altering the CMake configurations.
256
257The manifest lists are passed to the manifest tool via the ``TFM_MANIFEST_LIST``
258CMake configuration.
259The default value is the ``tfm_manifest_list.yaml``.
260It can be overridden or appended with other manifest lists.
261
262Corresponding manifest lists of test Secure Partitions are appended if either
263TF-M regression or PSA compliance tests are enabled.
264
265The generated file lists are passed via ``GENERATED_FILE_LISTS``.
266It can be also overridden or appended with other file lists.
267
268The ``-q`` argument is appended if ``PARSE_MANIFEST_QUIET_FLAG`` is enabled.
269
270Paths in manifest lists and generated file lists can have CMake variables as
271long as the are absolute paths.
272The lists then must be processed by the CMake command ``configure_file()`` [7]_
273before passing to the manifest tool.
274
275The configuration header file is generated by the build system automatically.
276
277**********
278References
279**********
280
281.. [1] `FF-M v1.0 Specification <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4>`__
282
283.. [2] `FF-M v1.1 Extension <https://documentation-service.arm.com/static/600067c09b9c2d1bb22cd1c5?token=>`__
284
285.. [3] `YAML <https://yaml.org/>`__
286
287.. [4] `TF-M manifest list <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/tools/tfm_manifest_list.yaml>`__
288
289.. [5] `TF-M generated file list <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/tools/tfm_generated_file_list.yaml>`__
290
291.. [6] `Jinja2 <https://jinja.palletsprojects.com/en/3.1.x/>`__
292
293.. [7] `CMake configure_file() <https://cmake.org/cmake/help/latest/command/configure_file.html>`__
294
295--------------
296
297*Copyright (c) 2022, Arm Limited. All rights reserved.*
298*Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company)
299or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
300