TF-M Manifest Tool User Guide
This document describes the TF-M manifest tool and its usage. The target audiences are mainly platform integrators and Secure Partition developers.
This document assumes that audiences have knowledge about the terminologies defined in PSA Firmware Framework (FF-M) v1.0 1 and the FF-M v1.1 extensions 2, such as Secure Partition and manifests.
Introduction
The TF-M manifest tool is a python script which is used to parse Secure
Partition manifests and generate source header files defined by FF-M 1 such
as psa_manifest/pid.h and psa_manifest/sid.h.
It also generates TF-M specific files for building.
In the TF-M build system, the manifest tool is invoked during building automatically. Arguments are passed through CMake variables and they are customizable. See Usage in TF-M Build System for more details.
It can be also used as a standalone tool.
Arguments
The tool takes 5 arguments at most.
tfm_parse_manifest_list.py [-h] -o out_dir
-m manifest list [manifest list ...]
-f file-list [file-list ...]
-c config-files [config-files ...]
[-q]
-o/–outdir
Required.
The directory to hold the output files.
-m/–manifest-lists
Required. At least one item must be provided.
A list of TF-M Secure Partition manifest lists which contain one or more Secure Partition manifests in each. See Manifest List for details.
-f/–file-list
Required. At least one item must be provided.
A list of files that describe what files the tool should generate. See Generated File List for details.
-c/–config-files
Required. At least one item must be provided.
A list of header files which contain build configurations such as isolation level and Secure Partition enabled status. See Configuration Header File for details.
-q/–quiet
Optional.
Reduces log messages, only warnings and errors will be printed.
Manifest List
A manifest list is a YAML 3 file that describes a list of Secure Partition manifests. Refer to the TF-M default manifest list 4 as an example.
Each manifest list must contain a manifest_list attribute which collects the
descriptions of Secure Partition manifests.
Following are the supported attributes of in the manifest lists.
descriptionRequired.
Descriptive information for the tool to refer to the Secure Partition, for example in logs.
manifestRequired.
The manifest file of the Secure Partition. Both absolute path and relative path to the manifest list are supported. Environment variables are supported.
output_pathOptional.
The directory to hold the Secure Partition specific output files. See Generated File List for more details.
Both absolute path and relative path to the directory specified by
-o/--outdirare supported. Environment variables are supported.It is set to the directory specified by
-o/--outdirif omitted.conditionalOptional.
The configuration to enable or disable this Secure Partition. The value must be defined in one of the Configuration Header File. If it is omitted, the Secure Partition is always enabled.
pidOptional.
The Secure Partition ID (PID).
For non-test purpose Secure Partitions, it is required. See Adding Secure Partition for the PID allocations.
For test purpose Secure Partitions, this attribute is optional. The manifest tool assigns one for the Secure Partition. The value is not guaranteed to the same for different builds.
linker_patternOptional.
The information for linker to place the symbols of the Secure Partition. It is only required if you are using the linker scripts provided by TF-M. Each Secure Partition is expected to be built as a library. The name of the library must follow the format of
tfm_<type>_partition_<name>. The valid value for<type>is[psa_rot, app_rot]corresponding to the type of the Secure Partitions. The<name>is any string to distinguish the Secure Partition from others.Supported patterns are:
library_list, must be*tfm_*partition_<name>.*.object_listAny object files containing symbols belonging to the Secure Partition that are not included in the Secure Partitions library.
non_ffm_attributesOptional.
TF-M defines some special manifest attributes for TF-M dedicated Secure Partitions. Those special attributes are not compliant to FF-M. Using the specific attributes requires explicit registration by adding them to this
non_ffm_attributes. The purpose is to ensure that developers are aware of the compliance issue. The manifest tool will report errors if unregistered Non-FFM attributes are detected. This attribute is for TF-M specific Secure Partitions and using TF-M-specific attributes is not encouraged.
Generated File List
A generated file list is a YAML file that describes the files to be generated by the manifest tool. Refer to TF-M default generated file list 5 as an example.
Each one must contain a file_list attribute which collects the files to
generate.
Each item in the file_list must contain the following attributes.
templateThis attribute is the file path of a Jinja2 6 template. The TF-M manifest tool uses Jinja2 template engine for file generations. It can be a relative path to TF-M root directory or an absolute path. Environment variables are supported.
outputThe output file of the
template. Both absolute path and relative path to the directory specified by-o/--outdirare supported. Environment variables are supported.
The tfm_generated_file_list.yaml is essential to build TF-M.
There are several files that are required for each Secure Partition, so they are not in any generated file lists since one template generates multiple files.
psa_manifest/<manifestfilename>.hmanifestfilenameis the file name of the manifest. This file contains internal definitions for the Secure Partition implementation, such as RoT Service signals and Secure Functions. Refer to FF-M 1 for more details. The corresponding template ismanifestfilename.templateintermedia_<manifestfilename>.cTF-M specific, which holds the stacks of Secure Partitions. This file must be built with the Secure Partition libraries. The corresponding template is
partition_intermedia.template.load_info_<manifestfilename>.cTF-M specific, which contains the load information of Secure Partitions. This file must be built with the TF-M SPM library. The corresponding template is
partition_load_info.template.
These files are generated to output_path specified by each Secure Partition
in the manifest lists.
Configuration Header File
The format of each configuration item must be
#define CONFIG_NAME VALUE
The following format is also supported for boolean type configurations.
#define CONFIG_NAME
The configurations can be divided into two categories.
Generic configurations:
PSA_FRAMEWORK_ISOLATION_LEVELThe isolation level, required. Valid values are
[1, 2, 3].CONFIG_TFM_SPM_BACKENDThe backend of SPM, required. Valid values are
[SFN, IPC]. See SPM backends for details of backends.
Secure Partition enablement configurations
Configurations used to enable or disable Secure Partitions. The configuration names must match the values of
conditionalattributes in Manifest List. Valid values are[0, 1]. It’s optional for a Secure Partition which does not have theconditionalattribute.
The configurations can be split to multiple files corresponding to the multiple manifest lists.
Usage in TF-M Build System
In the TF-M build system, the manifest tool is invoked during building automatically. The arguments can be customized by altering the CMake configurations.
The manifest lists are passed to the manifest tool via the TFM_MANIFEST_LIST
CMake configuration.
The default value is the tfm_manifest_list.yaml.
It can be overridden or appended with other manifest lists.
Corresponding manifest lists of test Secure Partitions are appended if either TF-M regression or PSA compliance tests are enabled.
The generated file lists are passed via GENERATED_FILE_LISTS.
It can be also overridden or appended with other file lists.
The -q argument is appended if PARSE_MANIFEST_QUIET_FLAG is enabled.
Paths in manifest lists and generated file lists can have CMake variables as
long as the are absolute paths.
The lists then must be processed by the CMake command configure_file() 7
before passing to the manifest tool.
The configuration header file is generated by the build system automatically.