How trustedfirmware-a/tf-a-tests works
1. This repository is a bare-metal test suite for Trusted Firmware-A, not a firmware product itself. The core architecture is a Normal World test harness that boots on AArch32/AArch64 and exercises TF-A through SMC/HVC calls, plus a few adjacent boot flows such as EL3 payloads, firmware update, secure payloads, and Realm/FF-A scenarios.
2. The top-level execution boundary is: test code runs in the non-secure test environment, TF-A runs externally as the firmware under test, and secure components are reached only through defined interfaces. Most interactions are synchronous monitor calls, but some subsystems also validate interrupts, power-state transitions, memory sharing, and message passing.
3. tftf/framework is the main test runtime. It provides startup/entrypoints, exception handling, reporting, timer support, and the common test API used by all suites. It is the central “test OS” layer that orchestrates test lifecycle and abstracts CPU state, traps, and result reporting.
4. tftf/tests is the primary test catalog. It is organized by TF-A feature area: PSCI, SDEI, PMF, runtime services, secure services, firmware handoff/update, Realm/FF-A, extensions, negative scenarios, performance, and platform-specific checks. The .mk and .xml files define which suites are built and how they are grouped for automation.
5. The most important functional boundary is runtime-service testing. Under tftf/tests/runtime_services, the suite drives TF-A services such as standard SMCs, PSCI, SDEI, TRNG, RAS-related flows, Trusted OS/TSP interactions, FF-A secure services, and Realm Management Interface scenarios. These tests are usually paired with helper code in include/runtime_services and lib/* that encode the service-specific call patterns.
6. Secure payload testing is a separate companion-image architecture. The repo contains spm/cactus, spm/cactus_mm, and spm/ivy for secure partition manager scenarios, realm/* for Realm payload execution, and el3_payload/* for EL3 alternative boot flow testing. These are not just libraries; they build into separate images with their own entrypoints, linker scripts, and platform ports.
7. Firmware-update and recovery paths are represented by fwu/ns_bl1u and fwu/ns_bl2u, which are standalone non-secure bootloader/update images used to validate TF-A update flows. This subsystem interacts with platform NVM/IO abstractions rather than the normal test framework directly.
8. plat/* holds platform ports and is a major architectural axis. Each platform directory supplies setup, power-state handling, topology description, timers, memory-protection hooks, and sometimes platform-specific tests-to-skip lists. Common platform logic lives in plat/common, while vendor trees such as Arm, AMD, Xilinx, NVIDIA, Hisilicon, QEMU, and others adapt the suite to different boards and emulators.
9. lib/* and include/* are the shared support layer. They provide minimal C library support, exception and interrupt helpers, context management, MMU/page-table setup, spinlocks, power management, SMC wrappers, PCIe helpers, event logging, HOB structures, UUID utilities, and architecture-specific assembly helpers for both AArch32 and AArch64. This layer is what lets the tests run bare-metal without a full OS.
10. drivers/* contains device access and transport abstractions used by the tests and payloads. The main categories are console UARTs, GIC interrupt controller drivers, timers, and storage/IO drivers for FIP, memory-mapped devices, and NOR flash. These drivers form the hardware-facing edge of the suite.
11. The repository also includes fuzzing infrastructure in smc_fuzz. That subtree generates and runs SMC-call corpora for PSCI, SDEI, FF-A, vendor calls, and generic SMC coverage. It is a separate test-generation path that feeds the same TF-A interface boundary but focuses on robustness and call-space exploration.
12. Build and generation tooling is part of the architecture, not just convenience. The root Makefile, make_helpers, and per-subsystem *.mk files assemble the correct image set for a chosen platform. tools/generate_test_list, tools/generate_dtb, and tools/generate_json generate metadata consumed by the test harness and automation.
13. Documentation under docs/ mirrors the architecture and defines the supported platform matrix, build/run process, porting rules, and design notes. Skip lists, platform descriptors, and test manifests are used to keep the same logical suite portable across many boards and emulators.
14. In diagram terms, the key flows are: build system selects platform + suite → framework boots and initializes drivers/lib support → tests invoke TF-A services via SMC/HVC, FF-A, PSCI, SDEI, or update interfaces → TF-A may dispatch into secure payloads or update images → results return to the framework for reporting. The major boundaries are Normal World vs Secure World, test harness vs platform port, and shared libraries vs standalone payload images.
Main entry points: Makefile Makefile · runtime_services Runtime svcs · plat Platforms · framework Framework
Components 22
Core test runtime
Normal-world harness, shared support, and test suites that drive TF-A interfaces.
- Framework · Main bare-metal harness: entry, exceptions, reporting, timers, and test API.
tftf/framework - Tests · Primary TF-A test suites organized by feature area and automation manifests.
tftf/tests - Runtime svcs · Central interface tests for SMC/HVC services such as PSCI, SDEI, FF-A, TRNG, and RMI.
tftf/tests/runtime_services - Std services · Standard-service tests covering PSCI, SDEI, PMF, TRNG, errata, and unknown SMCs.
tftf/tests/runtime_services/standard_service - FF-A services · FF-A and secure-partition messaging, discovery, interrupts, memory sharing, and setup.
tftf/tests/runtime_services/secure_service - Realm payload · Host-side Realm Management Interface and Realm payload scenario tests.
tftf/tests/runtime_services/realm_payload - Host realm · Helper code for realm creation, delegation, shared data, and RMI call patterns.
tftf/tests/runtime_services/host_realm_managment - Shared support · Common C/assembly helpers, context management, MMU/xlat, SMC wrappers, and utility code.
lib - APIs · Common interfaces consumed by tests, platform ports, and payload images.
include - Drivers · Console, GIC, timer, and storage/IO drivers forming the hardware edge.
drivers - SMC fuzz · Corpus and generators for exploring PSCI, SDEI, FF-A, vendor, and generic SMC space.
smc_fuzz
Companion images
Standalone secure or boot-flow images built alongside the main harness.
- Cactus SP · Secure partition payload image and its platform-specific descriptors/tests.
spm/cactus - Ivy SPM · Secure-partition manager image with shim and payload app components.
spm/ivy - Realm img · Standalone Realm payload image and its exception/entry support.
realm - EL3 payload · Alternative EL3 boot-flow payload built as a separate image.
el3_payload - FWU images · Standalone non-secure BL1U/BL2U images used to validate firmware update flows.
fwu
Platform layer
Platform ports, board-specific setup, and skip matrices.
- Platforms · Board/emulator ports with setup, timers, power-state logic, topology, and skip lists.
plat - Common plat · Shared platform code for topology, state IDs, image loading, and NVM access.
plat/common
Build and tooling
Image assembly, metadata generation, and documentation.
- Makefile · Top-level build entry that selects images, platforms, and suites.
Makefile - Make helpers · Shared make logic and defaults used by subsystem build files.
make_helpers - Generators · Scripts that generate test lists, DTBs, and JSON metadata.
tools - Docs · Architecture, porting, fuzzing, and usage guidance for the suite.
docs
Connections 30
- Makefile → Make helpers: includes · Top-level build uses shared make macros and defaults.
- Makefile → Framework: builds · Assembles the main harness image.
- Makefile → Tests: selects · Chooses which suites are built for the target platform.
- Makefile → Platforms: targets · Build is parameterized by platform port.
- Makefile → Cactus SP: builds · May include secure payload companion images.
- Makefile → Realm img: builds · May include Realm payload images.
- Makefile → EL3 payload: builds · May include EL3 alternate boot-flow payloads.
- Makefile → FWU images: builds · May include firmware update bootloader images.
- Makefile → SMC fuzz: builds · May include fuzzing targets and corpora.
- Generators → Tests: generates metadata · Produces manifests and lists consumed by automation.
- Docs → Platforms: describes · Documents supported ports and porting requirements.
- Framework → APIs: uses API · Harness exposes common test and platform interfaces through headers.
- Framework → Shared support: depends on · Harness relies on shared runtime support code.
- Framework → Drivers: uses · Framework initializes and exercises hardware-facing drivers.
- Tests → Runtime svcs: contains · Primary test family for TF-A interface validation.
- Tests → Platforms: filtered by · Per-platform manifests and skip lists shape what runs.
- Runtime svcs → Std services: includes · Standard SMC service validation suite.
- Runtime svcs → FF-A services: includes · FF-A / secure-partition interaction suite.
- Runtime svcs → Realm payload: includes · Realm payload and RMI host-side scenarios.
- Runtime svcs → Host realm: uses · Realm tests share host-side delegation and memory helpers.
- Std services → Shared support: calls into · Service tests use shared SMC, PSCI, SDEI, and utility helpers.
- FF-A services → Cactus SP: exercises · Tests validate secure partition manager and FF-A message paths.
- FF-A services → Ivy SPM: exercises · Tests cover SPM shim and secure-partition image behavior.
- Realm payload → Realm img: exercises · Host tests drive the Realm payload boundary.
- Shared support → Drivers: uses · Shared code depends on console, timer, GIC, and storage access.
- Shared support → Common plat: interfaces with · Common runtime support relies on shared platform primitives.
- Common plat → Platforms: shared by · Platform ports build on common board logic.
- Platforms → Drivers: binds to · Each platform supplies hardware-specific driver wiring.
- FWU images → Common plat: uses · Update images use platform NVM/IO accessors and boot plumbing.
- SMC fuzz → Runtime svcs: targets · Fuzzing generates call corpora for the same TF-A service boundary.