# trustedfirmware-a/tf-a-tests architecture

> Architecture diagram of the GitHub repository trustedfirmware-a/tf-a-tests, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trustedfirmware-a/tf-a-tests
- Repository: https://github.com/trustedfirmware-a/tf-a-tests

## Overview

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`](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/Makefile) (Makefile), [`tftf/tests/runtime_services`](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services) (Runtime svcs), [`plat`](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/plat) (Platforms), [`tftf/framework`](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/framework) (Framework)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_core["Core test runtime"]
  node_framework["Framework<br/>test runtime"]
  node_tests_catalog["Tests<br/>suite catalog"]
  node_runtime_services["Runtime svcs<br/>service tests"]
  node_standard_service["Std services<br/>SMC service tests"]
  node_secure_service["FF-A services<br/>FFA/SPM tests"]
  node_realm_payload_tests["Realm payload<br/>RMM tests"]
  node_host_realm_mgmt["Host realm<br/>RMI helpers"]
  node_framework_support["Shared support<br/>lib/include"]
  node_headers["APIs<br/>public headers"]
  node_drivers["Drivers<br/>hw access"]
  node_smc_fuzz["SMC fuzz<br/>fuzzing"]
end

subgraph group_g_payloads["Companion images"]
  node_spm_cactus["Cactus SP<br/>secure payload"]
  node_spm_ivy["Ivy SPM<br/>secure payload"]
  node_realm_image["Realm img<br/>realm payload"]
  node_el3_payload["EL3 payload<br/>boot flow image"]
  node_fwu_images["FWU images<br/>update bootloaders"]
end

subgraph group_g_platforms["Platform layer"]
  node_platforms["Platforms<br/>ports"]
  node_plat_common["Common plat<br/>shared port code"]
end

subgraph group_g_build["Build and tooling"]
  node_root_makefile["Makefile<br/>build root"]
  node_build_helpers["Make helpers<br/>build macros"]
  node_tools_gen["Generators<br/>metadata tools"]
  node_docs["Docs<br/>documentation"]
end

node_root_makefile -->|"includes"| node_build_helpers
node_root_makefile -->|"builds"| node_framework
node_root_makefile -->|"selects"| node_tests_catalog
node_root_makefile -->|"targets"| node_platforms
node_root_makefile -->|"builds"| node_spm_cactus
node_root_makefile -->|"builds"| node_realm_image
node_root_makefile -->|"builds"| node_el3_payload
node_root_makefile -->|"builds"| node_fwu_images
node_root_makefile -->|"builds"| node_smc_fuzz
node_tools_gen -->|"generates metadata"| node_tests_catalog
node_docs -->|"describes"| node_platforms
node_framework -->|"uses API"| node_headers
node_framework -->|"depends on"| node_framework_support
node_framework -->|"uses"| node_drivers
node_tests_catalog -->|"contains"| node_runtime_services
node_tests_catalog -->|"filtered by"| node_platforms
node_runtime_services -->|"includes"| node_standard_service
node_runtime_services -->|"includes"| node_secure_service
node_runtime_services -->|"includes"| node_realm_payload_tests
node_runtime_services -->|"uses"| node_host_realm_mgmt
node_standard_service -->|"calls into"| node_framework_support
node_secure_service -->|"exercises"| node_spm_cactus
node_secure_service -->|"exercises"| node_spm_ivy
node_realm_payload_tests -->|"exercises"| node_realm_image
node_framework_support -->|"uses"| node_drivers
node_framework_support -->|"interfaces with"| node_plat_common
node_plat_common -->|"shared by"| node_platforms
node_platforms -->|"binds to"| node_drivers
node_fwu_images -->|"uses"| node_plat_common
node_smc_fuzz -->|"targets"| node_runtime_services

click node_root_makefile "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/Makefile"
click node_build_helpers "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/make_helpers"
click node_tools_gen "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tools"
click node_docs "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/docs"
click node_framework "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/framework"
click node_tests_catalog "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests"
click node_runtime_services "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services"
click node_standard_service "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/standard_service"
click node_secure_service "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/secure_service"
click node_realm_payload_tests "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/realm_payload"
click node_host_realm_mgmt "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/host_realm_managment"
click node_framework_support "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/lib"
click node_headers "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/include"
click node_drivers "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/drivers"
click node_platforms "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/plat"
click node_plat_common "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/plat/common"
click node_spm_cactus "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/spm/cactus"
click node_spm_ivy "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/spm/ivy"
click node_realm_image "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/realm"
click node_el3_payload "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/el3_payload"
click node_fwu_images "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/fwu"
click node_smc_fuzz "https://github.com/trustedfirmware-a/tf-a-tests/tree/main/smc_fuzz"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_framework,node_tests_catalog,node_runtime_services,node_standard_service,node_secure_service,node_realm_payload_tests,node_host_realm_mgmt,node_framework_support,node_headers,node_drivers,node_smc_fuzz toneBlue
class node_spm_cactus,node_spm_ivy,node_realm_image,node_el3_payload,node_fwu_images toneAmber
class node_platforms,node_plat_common toneMint
class node_root_makefile,node_build_helpers,node_tools_gen,node_docs toneRose
```

## Components

### Core test runtime

Normal-world harness, shared support, and test suites that drive TF-A interfaces.

- [Framework](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/framework): test runtime · Main bare-metal harness: entry, exceptions, reporting, timers, and test API. · `tftf/framework`
- [Tests](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests): suite catalog · Primary TF-A test suites organized by feature area and automation manifests. · `tftf/tests`
- [Runtime svcs](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services): service tests · Central interface tests for SMC/HVC services such as PSCI, SDEI, FF-A, TRNG, and RMI. · `tftf/tests/runtime_services`
- [Std services](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/standard_service): SMC service tests · Standard-service tests covering PSCI, SDEI, PMF, TRNG, errata, and unknown SMCs. · `tftf/tests/runtime_services/standard_service`
- [FF-A services](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/secure_service): FFA/SPM tests · FF-A and secure-partition messaging, discovery, interrupts, memory sharing, and setup. · `tftf/tests/runtime_services/secure_service`
- [Realm payload](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/realm_payload): RMM tests · Host-side Realm Management Interface and Realm payload scenario tests. · `tftf/tests/runtime_services/realm_payload`
- [Host realm](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tftf/tests/runtime_services/host_realm_managment): RMI helpers · Helper code for realm creation, delegation, shared data, and RMI call patterns. · `tftf/tests/runtime_services/host_realm_managment`
- [Shared support](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/lib): lib/include · Common C/assembly helpers, context management, MMU/xlat, SMC wrappers, and utility code. · `lib`
- [APIs](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/include): public headers · Common interfaces consumed by tests, platform ports, and payload images. · `include`
- [Drivers](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/drivers): hw access · Console, GIC, timer, and storage/IO drivers forming the hardware edge. · `drivers`
- [SMC fuzz](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/smc_fuzz): fuzzing · 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](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/spm/cactus): secure payload · Secure partition payload image and its platform-specific descriptors/tests. · `spm/cactus`
- [Ivy SPM](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/spm/ivy): secure payload · Secure-partition manager image with shim and payload app components. · `spm/ivy`
- [Realm img](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/realm): realm payload · Standalone Realm payload image and its exception/entry support. · `realm`
- [EL3 payload](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/el3_payload): boot flow image · Alternative EL3 boot-flow payload built as a separate image. · `el3_payload`
- [FWU images](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/fwu): update bootloaders · Standalone non-secure BL1U/BL2U images used to validate firmware update flows. · `fwu`

### Platform layer

Platform ports, board-specific setup, and skip matrices.

- [Platforms](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/plat): ports · Board/emulator ports with setup, timers, power-state logic, topology, and skip lists. · `plat`
- [Common plat](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/plat/common): shared port code · Shared platform code for topology, state IDs, image loading, and NVM access. · `plat/common`

### Build and tooling

Image assembly, metadata generation, and documentation.

- [Makefile](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/Makefile): build root · Top-level build entry that selects images, platforms, and suites. · `Makefile`
- [Make helpers](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/make_helpers): build macros · Shared make logic and defaults used by subsystem build files. · `make_helpers`
- [Generators](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/tools): metadata tools · Scripts that generate test lists, DTBs, and JSON metadata. · `tools`
- [Docs](https://github.com/trustedfirmware-a/tf-a-tests/tree/main/docs): documentation · Architecture, porting, fuzzing, and usage guidance for the suite. · `docs`

## Connections

- 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.
