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 158- ``non_ffm_attributes`` 159 160 Optional. 161 162 TF-M defines some special manifest attributes for TF-M dedicated Secure Partitions. 163 Those special attributes are not compliant to FF-M. 164 Using the specific attributes requires explicit registration by adding them to 165 this ``non_ffm_attributes``. 166 The purpose is to ensure that developers are aware of the compliance issue. 167 The manifest tool will report errors if unregistered Non-FFM attributes are detected. 168 This attribute is for TF-M specific Secure Partitions and using TF-M-specific attributes 169 is not encouraged. 170 171Generated File List 172=================== 173A generated file list is a YAML file that describes the files to be generated 174by the manifest tool. 175Refer to TF-M default generated file list [5]_ as an example. 176 177Each one must contain a ``file_list`` attribute which collects the files to 178generate. 179Each item in the ``file_list`` must contain the following attributes. 180 181- ``template`` 182 183 This attribute is the file path of a Jinja2 [6]_ template. 184 The TF-M manifest tool uses Jinja2 template engine for file generations. 185 It can be a relative path to TF-M root directory or an absolute path. 186 Environment variables are supported. 187 188- ``output`` 189 190 The output file of the ``template``. 191 Both absolute path and relative path to the directory specified by 192 ``-o/--outdir`` are supported. 193 Environment variables are supported. 194 195**The tfm_generated_file_list.yaml is essential to build TF-M.** 196 197There are several files that are required for each Secure Partition, 198so they are not in any generated file lists since one template generates 199multiple files. 200 201- ``psa_manifest/<manifestfilename>.h`` 202 203 ``manifestfilename`` is the file name of the manifest. 204 This file contains internal definitions for the Secure Partition 205 implementation, such as RoT Service signals and Secure Functions. 206 Refer to FF-M [1]_ for more details. 207 The corresponding template is ``manifestfilename.template`` 208 209- ``intermedia_<manifestfilename>.c`` 210 211 TF-M specific, which holds the stacks of Secure Partitions. 212 This file must be built with the Secure Partition libraries. 213 The corresponding template is ``partition_intermedia.template``. 214 215- ``load_info_<manifestfilename>.c`` 216 217 TF-M specific, which contains the load information of Secure Partitions. 218 This file must be built with the TF-M SPM library. 219 The corresponding template is ``partition_load_info.template``. 220 221These files are generated to ``output_path`` specified by each Secure Partition 222in the manifest lists. 223 224Configuration Header File 225========================= 226The format of each configuration item must be 227 228.. code-block:: 229 230 #define CONFIG_NAME VALUE 231 232The following format is also supported for boolean type configurations. 233 234.. code-block:: 235 236 #define CONFIG_NAME 237 238The configurations can be divided into two categories. 239 240- Generic configurations: 241 242 - ``PSA_FRAMEWORK_ISOLATION_LEVEL`` 243 244 The isolation level, required. Valid values are ``[1, 2, 3]``. 245 246 - ``CONFIG_TFM_SPM_BACKEND`` 247 248 The backend of SPM, required. Valid values are ``[SFN, IPC]``. 249 See :doc:`SPM backends </integration_guide/spm_backends>` 250 for details of backends. 251 252- Secure Partition enablement configurations 253 254 Configurations used to enable or disable Secure Partitions. 255 The configuration names must match the values of ``conditional`` attributes in 256 `Manifest List`_. Valid values are ``[0, 1]``. 257 It's optional for a Secure Partition which does not have the ``conditional`` 258 attribute. 259 260The configurations can be split to multiple files corresponding to the multiple 261manifest lists. 262 263************************** 264Usage in TF-M Build System 265************************** 266In the TF-M build system, the manifest tool is invoked during building 267automatically. 268The arguments can be customized by altering the CMake configurations. 269 270The manifest lists are passed to the manifest tool via the ``TFM_MANIFEST_LIST`` 271CMake configuration. 272The default value is the ``tfm_manifest_list.yaml``. 273It can be overridden or appended with other manifest lists. 274 275Corresponding manifest lists of test Secure Partitions are appended if either 276TF-M regression or PSA compliance tests are enabled. 277 278The generated file lists are passed via ``GENERATED_FILE_LISTS``. 279It can be also overridden or appended with other file lists. 280 281The ``-q`` argument is appended if ``PARSE_MANIFEST_QUIET_FLAG`` is enabled. 282 283Paths in manifest lists and generated file lists can have CMake variables as 284long as the are absolute paths. 285The lists then must be processed by the CMake command ``configure_file()`` [7]_ 286before passing to the manifest tool. 287 288The configuration header file is generated by the build system automatically. 289 290********** 291References 292********** 293 294.. [1] `FF-M v1.0 Specification <https://developer.arm.com/documentation/den0063/latest/>`__ 295 296.. [2] `FF-M v1.1 Extension <https://documentation-service.arm.com/static/600067c09b9c2d1bb22cd1c5?token=>`__ 297 298.. [3] `YAML <https://yaml.org/>`__ 299 300.. [4] `TF-M manifest list <https://git.trustedfirmware.org/plugins/gitiles/TF-M/trusted-firmware-m.git/+/HEAD/tools/tfm_manifest_list.yaml>`__ 301 302.. [5] `TF-M generated file list <https://git.trustedfirmware.org/plugins/gitiles/TF-M/trusted-firmware-m.git/+/HEAD/tools/tfm_generated_file_list.yaml>`__ 303 304.. [6] `Jinja2 <https://jinja.palletsprojects.com/en/3.1.x/>`__ 305 306.. [7] `CMake configure_file() <https://cmake.org/cmake/help/latest/command/configure_file.html>`__ 307 308-------------- 309 310*Copyright (c) 2022, Arm Limited. All rights reserved.* 311*Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company) 312or an affiliate of Cypress Semiconductor Corporation. All rights reserved.* 313