Trusted Firmware-M Source Structure

Organization

Arm Limited

Contact

tf-m@lists.trustedfirmware.org

Note

Reference the document Glossary for terms and abbreviations.

Introduction

TF-M is designed to provide a user-friendly source structure to ease integration and service development. This document introduces the source structure and its design intention of TF-M.

Note

  • This document goes ahead of the implementation so the existing source structure may be different from the description listed here. It is recommended to refer to this document for ongoing code structure changes.

  • By getting feedback from the practical implementation, this document is updated continuously before it is detailed enough to be a user guide.

Source Structure

The description of the source structure is broken down into subsections, each subsection introduces one detailed folder.

Root Directory

This table describes the structure under the root directory with part of possible folders. Note that the Detailed field indicates if the folder is described in details here in this document:

Folder name

Purpose

Detailed

bl2

The 2nd stage bootloader.

No.

cmake

Cmake files.

No.

configs

Configuration system files.

No.

docs

The documentations.

No.

lib

The 3rd party library.

No.

platform

Platform intermedia files.

See ‘platform’.

secure_fw

The secure firmware.

See ‘secure_fw’.

tools

Tools in scripts for building.

No.

‘platform’

The platform sources contain necessary platform sources or intermedia files pointing to the sources out of TF-M folder.

Folder name

Purpose

common/*

Common HAL implementation.

include/*

Platform public headers.

<vendor>

Vendor specific folders.

Note

The common folder contains the example implementation of the HAL API bases on common system (CMSIS e.g.). The platform could reference to sources in the common folder directly if applicable or apply a customized HAL implementation. A system can have a standalone folder under common, depends on how ‘common’ this system is. Each platform vendor is assigned with one folder for usage. As the content of the vendor folder comes by the contribution of vendors, the vendor manages the structure inside it.

‘secure_fw’

This folder contains components needed by secure firmware, and the exported interfaces for application, service development and HAL integration:

Folder name

Purpose

Detailed

include

Public headers of ‘secure_fw’.

See ‘include’

partitions

Default services and supportings.

See ‘partitions’

spm

PSA-FF-M SPM implementation. [1]

See ‘spm’

Note

  1. A PSA-FF-M complied SPM implementation.

The headers referenced by other modules are public headers and put under the ‘include’ folder of the current module. Do not put headers not referenced by other modules in this ‘include’ folder.

‘include’

This folder holds headers for client, services and platform integration usage.

Folder name

Purpose

psa/*

PSA FF Client API.

Note

TFM applies an explicit including policy. Each module’s headers are put into a specific folder which follows the pattern ‘*/inc’, this folder needs to be added into the project’s searching path if this project needs to include headers in this folder. The ‘inc’ in a path indicates the end of including-path. If there are subfolders under folder ‘inc’, apply a hierarchy including.

‘partitions’

This folder contains default services implemented as partitions and necessary partition runtime utilities provided by TF-M.

Folder name

Purpose

lib/runtime/*

The SPRTL sources and intermedia files. [1]

lib/runtime/shared*

Sources can be shared by out of SPRTL. [2]

<partition_x>/*

Files for ‘partition_x’.

<partition_x>/include/*

RoT Service API headers of ‘partition_x’. [3]

<partition_y>/*

Files for ‘partition_y’.

<partition_y>/include/*

RoT Service API headers of ‘partition_y’. [3]

Note

  1. The SPRTL sources and intermediate files. SPRTL contains sources from other folders, such as necessary RoT Service API implementation from ‘partitions’ folder.

  2. The sources here can be referenced by the building system out of SPRTL. Generally, they are runtime and PSA APIs.

  3. Here takes ‘partition_x’ and ‘partition_y’ as an example, and showcases a detailed structure of them. The <interface> contains the RoT Service API for client calls. The folder name of this client-orient folder is decided by the service developer.

‘spm’

The SPM is the core component to provide a mechanism for providing secure services.

Folder name

Purpose

include/*

SPM public headers.

ffm/*

SPM logic complies with PSA-FF-M and its necessary supporting functionalities, such as the runtime API and the thread operation, etc.

cmsis_psa/*

CMSIS implementation for PSA-FF-M SPM. [1]

*

Implementation sources.

Note

  1. CMSIS is the first implementation system.

  2. This folder contains a function call based secure firmware implementation. This model is the prototype model which would be updated after the PSA model. Create a standalone folder to hold it.


Copyright (c) 2020-2022, Arm Limited. All rights reserved.