Getting Started Guides

First Things First

Prerequisite

Trusted Firmware M provides a reference implementation of platform security architecture reference implementation aligning with PSA Certified guidelines. It is assumed that the reader is familiar with specifications can be found at Platform Security Architecture Resources.

The current TF-M implementation specifically targets TrustZone for ARMv8-M so a good understanding of the v8-M architecture is also necessary. A good place to get started with ARMv8-M is developer.arm.com.

Build and run instructions

Trusted Firmware M source code is available on git.trustedfirmware.org.

To build & run TF-M:

To port TF-M to a another system or OS, follow the OS Integration Guide

Contributing Guidelines contains guidance on how to contribute to this project.

Set up build environments

TF-M officially supports a limited set of build environments and setups. In this context, official support means that the environments listed below are actively used by team members and active developers, hence users should be able to recreate the same configurations by following the instructions described below. In case of problems, the TF-M team provides support only for these environments, but building in other environments can still be possible.

The following environments are supported:

  1. version supported:

    Ubuntu 18.04 x64+

  2. install dependencies:

sudo apt-get install -y git curl wget build-essential libssl-dev python3 \
python3-pip cmake make

  1. verify cmake version:

cmake --version

Note

Please download cmake 3.15 or later version from https://cmake.org/download/.

  1. add CMake path into environment:

export PATH=<CMake path>/bin:$PATH

Install python dependencies

Clone the TF-M source code, and then install the TF-M’s additional Python dependencies.

  1. get the TF-M source code:

cd <base folder>
git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git

  1. TF-M’s tools/requirements.txt file declares additional Python dependencies. Install them with pip3:

pip3 install --upgrade pip
cd trusted-firmware-m
pip3 install -r tools/requirements.txt

Install a toolchain

To compile TF-M code, at least one of the supported compiler toolchains have to be available in the build environment. The currently supported compiler versions are:

  • Arm Compiler v6.10.1 ~ v6.14.1

    • Download the standalone packages from here.

    • Add Arm Compiler into environment:

      export PATH=<ARM_CLANG_PATH>/bin:$PATH
export ARM_PRODUCT_PATH=<ARM_CLANG_PATH>/sw/mappings

    • Configure proper tool variant and license.

    Note

    Arm compiler starting from v6.15 may cause MemManage fault in TF-M higher isolation levels. The issue is under investigation and recommended to using versions prior to v6.15.

  • GNU Arm compiler v7.3.1+

    • Download the GNU Arm compiler from here.

    • Add GNU Arm into environment:

      export PATH=<GNU_ARM_PATH>/bin:$PATH

    Note

    GNU Arm compiler version 10-2020-q4-major has an issue in CMSE support. The bug is reported in here. Select other GNU Arm compiler versions instead.

  • IAR Arm compiler v8.42.x, v8.50.x

    • Download IAR build tools from here.

    • Add IAR Arm compiler into environment:

      export PATH=<IAR_COMPILER_PATH>/bin:$PATH

Build AN521 regression sample

Here, we take building TF-M for AN521 platform with regression tests using GCC as an example:

cd trusted-firmware-m
cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake -DCMAKE_BUILD_TYPE=Debug -DTEST_S=ON -DTEST_NS=ON
cmake --build cmake_build -- install

Alternately using traditional cmake syntax

cd trusted-firmware-m
mkdir cmake_build
cd cmake_build
cmake .. -DTFM_PLATFORM=arm/mps2/an521 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DTEST_S=ON -DTEST_NS=ON
make install

Run AN521 regression sample

Run the sample code on SSE-200 Fast-Model, using FVP_MPS2_AEMv8M provided by Arm Development Studio.

Note

Arm Development Studio is not essential to develop TF-M, you can skip this section if don’t want to try on Arm develop boards.

  1. install Arm Development Studio to get the fast-model.

    Download Arm Development Studio from here.

  2. Add bl2.axf and tfm_s_ns_signed.bin to symbol files in Debug Configuration menu.

<DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M  \
--parameter fvp_mps2.platform_type=2 \
--parameter cpu0.baseline=0 \
--parameter cpu0.INITVTOR_S=0x10000000 \
--parameter cpu0.semihosting-enable=0 \
--parameter fvp_mps2.DISABLE_GATING=0 \
--parameter fvp_mps2.telnetterminal0.start_telnet=1 \
--parameter fvp_mps2.telnetterminal1.start_telnet=0 \
--parameter fvp_mps2.telnetterminal2.start_telnet=0 \
--parameter fvp_mps2.telnetterminal0.quiet=0 \
--parameter fvp_mps2.telnetterminal1.quiet=1 \
--parameter fvp_mps2.telnetterminal2.quiet=1 \
--application cpu0=<build_dir>/bin/bl2.axf \
--data cpu0=<build_dir>/bin/tfm_s_ns_signed.bin@0x10080000

After completing the procedure you should see the following messages on the DAPLink UART (baud 115200 8n1):

[INF] Starting bootloader
[INF] Image 0: magic=good, copy_done=0xff, image_ok=0xff
[INF] Scratch: magic=bad, copy_done=0x5, image_ok=0x9
[INF] Boot source: primary slot
[INF] Swap type: none
[INF] Bootloader chainload address offset: 0x20000
[INF] Jumping to the first image slot
[Sec Thread] Secure image initializing!

#### Execute test suites for the protected storage service ####
Running Test Suite PS secure interface tests (TFM_PS_TEST_2XXX)...
> Executing 'TFM_PS_TEST_2001'
  Description: 'Create interface'
  TEST PASSED!
> Executing 'TFM_PS_TEST_2002'
  Description: 'Get handle interface (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
  TEST PASSED!
> Executing 'TFM_PS_TEST_2003'
  Description: 'Get handle with null handle pointer (DEPRECATED)'
This test is DEPRECATED and the test execution was SKIPPED
  TEST PASSED!
> Executing 'TFM_PS_TEST_2004'
  Description: 'Get attributes interface'
  TEST PASSED!
> Executing 'TFM_PS_TEST_2005'
  Description: 'Get attributes with null attributes struct pointer'
....

Tool & Dependency overview

To build the TF-M firmware the following tools are needed:

  • C compiler of supported toolchains

  • CMake version 3.15 or later

  • Git

  • gmake, aka GNU Make

  • Python v3.x

  • a set of python modules listed in tools/requiremtns.txt

Dependency chain

@startuml skinparam state { BackgroundColor #92AEE0 FontColor black FontSize 16 AttributeFontColor black AttributeFontSize 16 } state fw as "Firmware" : TF-M binary state c_comp as "C Compiler" : C99 state python as "Python" : v3.x fw --> c_comp fw --> CMake CMake --> gmake CMake --> Ninja fw --> cryptography fw --> pyasn1 fw --> yaml fw --> jinja2 fw --> cbor2 fw --> click fw --> imgtool c_comp --> GCC c_comp --> CLANG c_comp --> IAR cryptography --> python pyasn1 --> python yaml --> python jinja2 --> python cbor2 --> python click --> python imgtool --> python @enduml

Next steps

Here are some next steps for exploring TF-M:

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