# arm-software/arm-trusted-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/arm-software/arm-trusted-firmware
- Repository: https://github.com/arm-software/arm-trusted-firmware

## Overview

Trusted Firmware-A is secure-world boot and runtime firmware for Arm A-profile systems. Its main workflow starts at reset, loads and authenticates firmware images, initializes EL3 runtime, and transfers control to the next stage or a secure payload. Runtime EL3 also handles monitor calls and exceptions. The graph combines documented product scope with the supplied tree and excerpts; several platform storage implementations are sampled, but PSCI and SDEI implementation paths are not present in the supplied tree, so their wiring is not asserted.

Main entry points: [`bl31/bl31_main.c`](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/bl31_main.c) (BL31 EL3), [`bl2/bl2_main.c`](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_main.c) (BL2), [`bl2/bl2_image_load_v2.c`](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_image_load_v2.c) (Image loader), [`common/runtime_svc.c`](https://github.com/arm-software/arm-trusted-firmware/blob/master/common/runtime_svc.c) (Runtime services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot stages"]
  node_bl1["BL1<br/>[bl1_main.c]"]
  node_bl2["BL2<br/>[bl2_main.c]"]
  node_bl2u["BL2U update<br/>[bl2u_main.c]"]
  node_bl31["BL31 EL3<br/>[bl31_main.c]"]
  node_sp_min["SP_MIN<br/>[sp_min_main.c]"]
end

subgraph group_loading["Image loading"]
  node_image_loader["Image loader"]
  node_image_descriptors["Image descriptors<br/>[desc_image_load.c]"]
end

subgraph group_trust["Boot trust"]
  node_auth["Image authentication<br/>[auth_mod.c]"]
  node_crypto["Crypto backend<br/>[crypto_mod.c]"]
end

subgraph group_runtime["Secure runtime"]
  node_tsp["TSP<br/>[tsp_main.c]"]
  node_runtime_svc["Runtime services<br/>[runtime_svc.c]"]
  node_interrupts["Interrupt management<br/>[interrupt_mgmt.c]"]
  node_traps["EL3 traps<br/>[bl31_traps.c]"]
  node_scmi["SCMI messaging<br/>[entry.c]"]
  node_sdei["SDEI exception interface<br/>[ehf.c]"]
end

subgraph group_platform["Platform I/O"]
  node_io_api["I/O storage API<br/>[io_storage.c]"]
  node_platform_io["Platform image policy<br/>[arm_io_storage.c]"]
  node_fip["Firmware package<br/>[io_fip.c]"]
  node_block_io["Block storage<br/>[io_block.c]"]
  node_scmi_platform["Platform SCMI<br/>[scmi_common.c]"]
end

node_reset(("Platform reset"))
node_secure_monitor(("Secure monitor caller"))

node_reset -->|"enters"| node_bl1
node_bl1 -->|"requests images"| node_image_descriptors
node_bl1 -->|"hands off"| node_bl2
node_bl2 -->|"loads firmware"| node_image_loader
node_image_loader -->|"uses metadata"| node_image_descriptors
node_image_loader -->|"requests source"| node_platform_io
node_platform_io -->|"opens device"| node_io_api
node_io_api -->|"dispatches reads"| node_fip
node_io_api -->|"dispatches reads"| node_block_io
node_image_loader -->|"authenticates images"| node_auth
node_auth -->|"uses crypto"| node_crypto
node_bl2 -->|"hands off"| node_bl31
node_bl31 -->|"registers services"| node_runtime_svc
node_secure_monitor -->|"issues SMC"| node_runtime_svc
node_runtime_svc -->|"returns result"| node_secure_monitor
node_bl31 -->|"manages interrupts"| node_interrupts
node_bl31 -->|"handles traps"| node_traps
node_bl31 -.->|"dispatches payload"| node_tsp
node_bl31 -.->|"dispatches payload"| node_sp_min
node_scmi -->|"uses protocols"| node_scmi_platform
node_runtime_svc -.->|"dispatches requests"| node_scmi
node_bl31 -.->|"supports exceptions"| node_sdei
node_bl2 -.->|"optional update stage"| node_bl2u

click node_bl1 "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl1/bl1_main.c"
click node_bl2 "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_main.c"
click node_bl2u "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2u/bl2u_main.c"
click node_bl31 "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/bl31_main.c"
click node_sp_min "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl32/sp_min/sp_min_main.c"
click node_tsp "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl32/tsp/tsp_main.c"
click node_image_loader "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_image_load_v2.c"
click node_image_descriptors "https://github.com/arm-software/arm-trusted-firmware/blob/master/common/desc_image_load.c"
click node_io_api "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_storage.c"
click node_platform_io "https://github.com/arm-software/arm-trusted-firmware/blob/master/plat/arm/common/arm_io_storage.c"
click node_fip "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_fip.c"
click node_block_io "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_block.c"
click node_auth "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/auth/auth_mod.c"
click node_crypto "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/auth/crypto_mod.c"
click node_runtime_svc "https://github.com/arm-software/arm-trusted-firmware/blob/master/common/runtime_svc.c"
click node_interrupts "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/interrupt_mgmt.c"
click node_traps "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/bl31_traps.c"
click node_scmi "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/scmi-msg/entry.c"
click node_scmi_platform "https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/arm/css/scmi/scmi_common.c"
click node_sdei "https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/ehf.c"

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_bl1,node_bl2,node_bl2u,node_bl31,node_sp_min toneBlue
class node_image_loader,node_image_descriptors toneAmber
class node_auth,node_crypto toneMint
class node_tsp,node_runtime_svc,node_interrupts,node_traps,node_scmi,node_sdei toneRose
class node_io_api,node_platform_io,node_fip,node_block_io,node_scmi_platform,node_reset,node_secure_monitor toneIndigo
```

## Components

### Boot stages

- [BL1](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl1/bl1_main.c): `bl1/bl1_main.c`
- [BL2](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_main.c): `bl2/bl2_main.c`
- [BL2U update](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2u/bl2u_main.c): `bl2u/bl2u_main.c`
- [BL31 EL3](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/bl31_main.c): `bl31/bl31_main.c`
- [SP_MIN](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl32/sp_min/sp_min_main.c): `bl32/sp_min/sp_min_main.c`

### Image loading

- [Image loader](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl2/bl2_image_load_v2.c): `bl2/bl2_image_load_v2.c`
- [Image descriptors](https://github.com/arm-software/arm-trusted-firmware/blob/master/common/desc_image_load.c): `common/desc_image_load.c`

### Boot trust

- [Image authentication](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/auth/auth_mod.c): `drivers/auth/auth_mod.c`
- [Crypto backend](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/auth/crypto_mod.c): `drivers/auth/crypto_mod.c`

### Secure runtime

- [TSP](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl32/tsp/tsp_main.c): `bl32/tsp/tsp_main.c`
- [Runtime services](https://github.com/arm-software/arm-trusted-firmware/blob/master/common/runtime_svc.c): `common/runtime_svc.c`
- [Interrupt management](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/interrupt_mgmt.c): `bl31/interrupt_mgmt.c`
- [EL3 traps](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/bl31_traps.c): `bl31/bl31_traps.c`
- [SCMI messaging](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/scmi-msg/entry.c): `drivers/scmi-msg/entry.c`
- [SDEI exception interface](https://github.com/arm-software/arm-trusted-firmware/blob/master/bl31/ehf.c): `bl31/ehf.c`

### Platform I/O

- [I/O storage API](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_storage.c): `drivers/io/io_storage.c`
- [Platform image policy](https://github.com/arm-software/arm-trusted-firmware/blob/master/plat/arm/common/arm_io_storage.c): `plat/arm/common/arm_io_storage.c`
- [Firmware package](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_fip.c): `drivers/io/io_fip.c`
- [Block storage](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/io/io_block.c): `drivers/io/io_block.c`
- [Platform SCMI](https://github.com/arm-software/arm-trusted-firmware/blob/master/drivers/arm/css/scmi/scmi_common.c): `drivers/arm/css/scmi/scmi_common.c`

### Other components

- **Platform reset**
- **Secure monitor caller**

## Connections

- Platform reset → BL1: enters
- BL1 → Image descriptors: requests images
- BL1 → BL2: hands off
- BL2 → Image loader: loads firmware
- Image loader → Image descriptors: uses metadata
- Image loader → Platform image policy: requests source
- Platform image policy → I/O storage API: opens device
- I/O storage API → Firmware package: dispatches reads
- I/O storage API → Block storage: dispatches reads
- Image loader → Image authentication: authenticates images
- Image authentication → Crypto backend: uses crypto
- BL2 → BL31 EL3: hands off
- BL31 EL3 → Runtime services: registers services
- Secure monitor caller → Runtime services: issues SMC
- Runtime services → Secure monitor caller: returns result
- BL31 EL3 → Interrupt management: manages interrupts
- BL31 EL3 → EL3 traps: handles traps
- BL31 EL3 → TSP: dispatches payload
- BL31 EL3 → SP_MIN: dispatches payload
- SCMI messaging → Platform SCMI: uses protocols
- Runtime services → SCMI messaging: dispatches requests
- BL31 EL3 → SDEI exception interface: supports exceptions
- BL2 → BL2U update: optional update stage