# op-tee/optee_os architecture

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

- Interactive diagram: https://gitdiagram.com/op-tee/optee_os
- Repository: https://github.com/op-tee/optee_os

## Overview

1. This repository is the secure-world half of OP-TEE: a Trusted OS that runs on ARM and RISC-V systems and exposes a Trusted Execution Environment to normal-world clients. The main architectural boundary is between the normal world and secure world, with communication through TEE syscalls, SMC/FF-A calls, and RPC.

2. The runtime is split into a privileged kernel and user-mode Trusted Applications. The kernel lives under `core/`, while the user TA runtime and APIs live under `lib/libutee/` and TA sources live under `ta/`. The TA loader (`ldelf/`) loads user TAs into secure memory and provides the ELF/runtime support needed to execute them.

3. `core/kernel/` is the heart of the secure OS control plane: boot, traps, thread scheduling, interrupts, mutexes, notifications, TA management, RPC plumbing, and common services such as time, panic, and device-tree handling. `core/mm/` provides the memory-management boundary, including physical memory management, pageable memory, shared memory objects, and MMU support.

4. The architectural backends are in `core/arch/arm/` and `core/arch/riscv/`. These contain entry assembly, exception vectors, cache/TLB helpers, thread context switching, secure monitor interfaces, and CPU-specific boot code. This is where the repo adapts the generic kernel to each ISA and privilege model.

5. The secure-world API surface to the normal world is implemented through standard TEE concepts: SMC/OP-TEE message handling, FF-A support, pseudo TAs, and secure partitions. `core/arch/*/kernel/` and `core/arch/*/sm/` implement the low-level monitor and PSCI/SMCCC paths; `core/pta/` implements privileged services reachable from the normal world but running in secure context.

6. Crypto is layered in three tiers. `core/crypto/` holds generic crypto primitives and RNG glue, `core/drivers/crypto/` contains hardware-backed accelerators and vendor-specific engines, and `core/lib/libtomcrypt`, `core/lib/libmbedtls`, and `core/lib/qcbor` provide embedded third-party libraries used by the trusted core and TAs. This separation lets platform code choose hardware acceleration while keeping portable software fallbacks.

7. Storage and attestation are first-class subsystems. Secure storage, RPMB-backed persistence, object management, and filesystem support are in `core/tee/` and related kernel code, while attestation and device/security services live in PTAs such as `core/pta/attestation.c`, `core/pta/veraison_attestation/`, `core/pta/scp03.c`, and platform-specific PTA directories. These subsystems bridge secure state with normal-world clients and sometimes with secure storage or hardware roots of trust.

8. Platform integration is a major dimension of the codebase. `core/arch/arm/plat-*` and `core/arch/riscv/plat-*` hold board/SoC bring-up, low-level init, platform configs, and SoC-specific services. Most platforms also have local drivers for clocks, power, firewalls, reset controllers, RNGs, OTP/eFuse, mailbox, and vendor interconnects.

9. Hardware drivers under `core/drivers/` are intentionally shared across platforms when possible. They cover console/serial, GIC/PLIC/IMSIC interrupt controllers, clocks, regulators, RTC, watchdogs, GPIO, I2C, pinctrl, firewall/TZC blocks, remoteproc, and many SoC-specific crypto/RNG/OTP blocks. These drivers feed services used both by the kernel and by PTAs.

10. The TA side is a separate executable world within the secure OS. `ta/*` contains example and product TAs such as PKCS#11, remoteproc, Qualcomm PAS, AVB, and trusted keys. They build against the TA dev kit (`ta/mk/`) and use the public TEE Internal API exported by `lib/libutee/`.

11. The normal-world-facing client API is represented by the public headers in `lib/libutee/include/` and the syscall stubs in `lib/libutee/`. User TAs call into the core through these APIs; the core then enforces access control, memory isolation, and service routing before returning results or issuing RPCs back to the normal world.

12. The build system is a classic mixed C/assembly embedded build driven by `Makefile`, `core/*.mk`, `lib/*.mk`, `ta/*.mk`, and helper files under `mk/`. Platform selection is largely compile-time, with many SoC-specific sub-makes controlling which drivers, PTAs, and arch objects are linked into the final image.

13. A number of scripts support image generation, signing, and integration with platform boot chains. Notable ones include `scripts/gen_tee_bin.py`, `scripts/sign_encrypt.py`, `scripts/print_tee_hash.py`, and board-specific packaging helpers. These are important because the resulting secure-world binaries are usually signed and consumed by SoC boot ROMs or secure boot flows.

14. CI, formatting, and repository hygiene are also explicit. GitHub workflows, `checkpatch`, clang formatting, and the devcontainer are present, which suggests the project is maintained as a large upstream firmware/OS codebase with cross-platform support and strict coding conventions.

15. For diagram purposes, the main top-level blocks are: secure kernel, arch backends, shared drivers, crypto/storage subsystems, platform-specific bring-up, PTAs, user TA runtime, TA applications, and external normal-world/firmware interfaces. The key flows are normal-world requests into secure world, secure-world service dispatch inside the kernel/PTA layers, secure storage and hardware-backed crypto access downward, and RPC back to the normal world when the secure OS needs non-secure resources.

Main entry points: [`core/kernel/thread.c`](https://github.com/op-tee/optee_os/blob/master/core/kernel/thread.c) (Kernel core), [`ta/pkcs11/src/entry.c`](https://github.com/op-tee/optee_os/blob/master/ta/pkcs11/src/entry.c) (User TAs), [`core/pta/attestation.c`](https://github.com/op-tee/optee_os/blob/master/core/pta/attestation.c) (PTAs), [`Makefile`](https://github.com/op-tee/optee_os/tree/master/Makefile) (Build tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External boundary"]
  node_normal_world(("Normal world<br/>external client"))
  node_smc_ffa_rpc{{"SMC / RPC<br/>call interface<br/>[optee_msg.h]"}}
end

subgraph group_core["Secure OS core"]
  node_secure_os["Secure OS<br/>trusted OS<br/>[boot.c]"]
  node_kernel_ctrl["Kernel core<br/>privileged kernel<br/>[thread.c]"]
  node_mm_core["Memory mgmt<br/>mm subsystem<br/>[core_mmu.c]"]
  node_tee_services["TEE services<br/>storage/svc layer<br/>[tee_svc.c]"]
  node_pta_services["PTAs<br/>privileged TAs<br/>[attestation.c]"]
  node_crypto_core["Crypto core<br/>software crypto<br/>[crypto.c]"]
  node_crypto_hw["Crypto drivers<br/>hardware accel<br/>[sub.mk]"]
  node_hw_drivers["HW drivers<br/>shared drivers<br/>[gic.c]"]
  node_ldelf_loader["TA loader<br/>[main.c]"]
end

subgraph group_arch_arm["ARM backend"]
  node_plat_arm["ARM platforms<br/>platform bring-up<br/>[main.c]"]
  node_arm_monitor["ARM monitor<br/>ISA backend<br/>[entry_a64.S]"]
  node_arm_mmu["ARM MMU<br/>arch mmu<br/>[core_mmu.c]"]
end

subgraph group_arch_rv["RISC-V backend"]
  node_plat_rv["RISC-V platforms<br/>platform bring-up<br/>[main.c]"]
  node_rv_monitor["RISC-V monitor<br/>ISA backend<br/>[entry.S]"]
  node_rv_mmu["RISC-V MMU<br/>arch mmu<br/>[core_mmu_arch.c]"]
end

subgraph group_ta_layer["TA layer"]
  node_utee_runtime["UTEE runtime<br/>user TA runtime<br/>[tee_api.c]"]
  node_user_tas["User TAs<br/>trusted apps<br/>[entry.c]"]
end

subgraph group_shared_libs["Shared libs"]
  node_libtomcrypt["TomCrypt<br/>crypto lib<br/>[tomcrypt.c]"]
  node_libmbedtls["Mbed TLS<br/>crypto lib<br/>[tomcrypt.c]"]
  node_qcbor["QCBOR<br/>cbor lib<br/>[qcbor_encode.c]"]
end

subgraph group_build_tools["Build & tooling"]
  node_build_scripts["Build tools<br/>build system"]
end

node_normal_world -->|"calls"| node_smc_ffa_rpc
node_smc_ffa_rpc -->|"enters"| node_secure_os
node_secure_os -->|"dispatches"| node_kernel_ctrl
node_kernel_ctrl -->|"maps"| node_mm_core
node_kernel_ctrl -->|"serves"| node_tee_services
node_kernel_ctrl -->|"invokes"| node_pta_services
node_kernel_ctrl -->|"loads"| node_ldelf_loader
node_kernel_ctrl -->|"uses"| node_crypto_core
node_crypto_core -->|"accelerates"| node_crypto_hw
node_kernel_ctrl -->|"depends on"| node_hw_drivers
node_hw_drivers -->|"feeds"| node_pta_services
node_plat_arm -->|"binds"| node_arm_monitor
node_arm_monitor -->|"uses"| node_arm_mmu
node_plat_rv -->|"binds"| node_rv_monitor
node_rv_monitor -->|"uses"| node_rv_mmu
node_ldelf_loader -->|"executes"| node_utee_runtime
node_utee_runtime -->|"hosts"| node_user_tas
node_user_tas -->|"invokes"| node_pta_services
node_user_tas -->|"links"| node_libtomcrypt
node_kernel_ctrl -->|"links"| node_libmbedtls
node_pta_services -->|"formats"| node_qcbor
node_build_scripts -->|"builds"| node_secure_os
node_build_scripts -->|"builds"| node_user_tas
node_build_scripts -->|"packages"| node_ldelf_loader

click node_smc_ffa_rpc "https://github.com/op-tee/optee_os/blob/master/core/include/optee_msg.h"
click node_secure_os "https://github.com/op-tee/optee_os/blob/master/core/kernel/boot.c"
click node_kernel_ctrl "https://github.com/op-tee/optee_os/blob/master/core/kernel/thread.c"
click node_mm_core "https://github.com/op-tee/optee_os/blob/master/core/mm/core_mmu.c"
click node_tee_services "https://github.com/op-tee/optee_os/blob/master/core/tee/tee_svc.c"
click node_pta_services "https://github.com/op-tee/optee_os/blob/master/core/pta/attestation.c"
click node_crypto_core "https://github.com/op-tee/optee_os/blob/master/core/crypto/crypto.c"
click node_crypto_hw "https://github.com/op-tee/optee_os/blob/master/core/drivers/crypto/sub.mk"
click node_hw_drivers "https://github.com/op-tee/optee_os/blob/master/core/drivers/gic.c"
click node_plat_arm "https://github.com/op-tee/optee_os/blob/master/core/arch/arm/plat-stm32mp1/main.c"
click node_arm_monitor "https://github.com/op-tee/optee_os/blob/master/core/arch/arm/kernel/entry_a64.S"
click node_arm_mmu "https://github.com/op-tee/optee_os/blob/master/core/arch/arm/mm/core_mmu.c"
click node_plat_rv "https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/plat-virt/main.c"
click node_rv_monitor "https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/kernel/entry.S"
click node_rv_mmu "https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/mm/core_mmu_arch.c"
click node_ldelf_loader "https://github.com/op-tee/optee_os/blob/master/ldelf/main.c"
click node_utee_runtime "https://github.com/op-tee/optee_os/blob/master/lib/libutee/tee_api.c"
click node_user_tas "https://github.com/op-tee/optee_os/blob/master/ta/pkcs11/src/entry.c"
click node_libtomcrypt "https://github.com/op-tee/optee_os/blob/master/core/lib/libtomcrypt/tomcrypt.c"
click node_libmbedtls "https://github.com/op-tee/optee_os/blob/master/lib/libmbedtls/core/tomcrypt.c"
click node_qcbor "https://github.com/op-tee/optee_os/blob/master/core/lib/qcbor/src/qcbor_encode.c"
click node_build_scripts "https://github.com/op-tee/optee_os/tree/master/Makefile"

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_normal_world,node_smc_ffa_rpc,node_build_scripts toneBlue
class node_secure_os,node_kernel_ctrl,node_mm_core,node_tee_services,node_pta_services,node_crypto_core,node_crypto_hw,node_hw_drivers,node_ldelf_loader toneAmber
class node_plat_arm,node_arm_monitor,node_arm_mmu toneMint
class node_plat_rv,node_rv_monitor,node_rv_mmu toneRose
class node_utee_runtime,node_user_tas toneIndigo
class node_libtomcrypt,node_libmbedtls,node_qcbor toneTeal
```

## Components

### External boundary

Normal-world and firmware interfaces that enter or depend on the secure OS

- **Normal world**: external client · REE clients, firmware, and non-secure OS components that call into OP-TEE
- [SMC / RPC](https://github.com/op-tee/optee_os/blob/master/core/include/optee_msg.h): call interface · Secure monitor calls, FF-A messaging, and RPC back to the normal world · `core/include/optee_msg.h`

### Secure OS core

Kernel, memory, tee services, and privileged secure-world code

- [Secure OS](https://github.com/op-tee/optee_os/blob/master/core/kernel/boot.c): trusted OS · The secure-world half of OP-TEE · `core/kernel/boot.c`
- [Kernel core](https://github.com/op-tee/optee_os/blob/master/core/kernel/thread.c): privileged kernel · Boot, traps, scheduling, interrupts, notifications, TA control, and common services · `core/kernel/thread.c`
- [Memory mgmt](https://github.com/op-tee/optee_os/blob/master/core/mm/core_mmu.c): mm subsystem · Physical memory, page allocation, MMU, pageable memory, and shared memory objects · `core/mm/core_mmu.c`
- [TEE services](https://github.com/op-tee/optee_os/blob/master/core/tee/tee_svc.c): storage/svc layer · TEE storage, objects, crypto services, time, and secure service entry points · `core/tee/tee_svc.c`
- [PTAs](https://github.com/op-tee/optee_os/blob/master/core/pta/attestation.c): privileged TAs · Privileged services exposed from secure context to normal-world clients · `core/pta/attestation.c`
- [Crypto core](https://github.com/op-tee/optee_os/blob/master/core/crypto/crypto.c): software crypto · Portable crypto primitives and RNG glue used by the secure OS · `core/crypto/crypto.c`
- [Crypto drivers](https://github.com/op-tee/optee_os/blob/master/core/drivers/crypto/sub.mk): hardware accel · Hardware-backed accelerators, secure elements, and vendor crypto engines · `core/drivers/crypto/sub.mk`
- [HW drivers](https://github.com/op-tee/optee_os/blob/master/core/drivers/gic.c): shared drivers · Shared console, interrupt, clock, GPIO, storage, reset, and peripheral drivers · `core/drivers/gic.c`
- [TA loader](https://github.com/op-tee/optee_os/blob/master/ldelf/main.c): user TA loader · ELF loading, runtime setup, syscalls, and secure execution support for user TAs · `ldelf/main.c`

### ARM backend

ARM-specific entry, monitor, MMU, and platform code

- [ARM platforms](https://github.com/op-tee/optee_os/blob/master/core/arch/arm/plat-stm32mp1/main.c): platform bring-up · ARM board and SoC integration, platform init, and vendor services · `core/arch/arm/plat-stm32mp1/main.c`
- [ARM monitor](https://github.com/op-tee/optee_os/blob/master/core/arch/arm/kernel/entry_a64.S): ISA backend · ARM entry, exceptions, secure monitor interfaces, PSCI, and context switch paths · `core/arch/arm/kernel/entry_a64.S`
- [ARM MMU](https://github.com/op-tee/optee_os/blob/master/core/arch/arm/mm/core_mmu.c): arch mmu · ARM memory-management helpers and TEE memory mapping support · `core/arch/arm/mm/core_mmu.c`

### RISC-V backend

RISC-V-specific entry, SBI, MMU, and platform code

- [RISC-V platforms](https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/plat-virt/main.c): platform bring-up · RISC-V board integration, platform init, and console/boot support · `core/arch/riscv/plat-virt/main.c`
- [RISC-V monitor](https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/kernel/entry.S): ISA backend · RISC-V entry, SBI, OP-TEE ABI paths, and thread/context handling · `core/arch/riscv/kernel/entry.S`
- [RISC-V MMU](https://github.com/op-tee/optee_os/blob/master/core/arch/riscv/mm/core_mmu_arch.c): arch mmu · RISC-V memory-management helpers and TLB support · `core/arch/riscv/mm/core_mmu_arch.c`

### TA layer

User-mode Trusted Applications and TA runtime

- [UTEE runtime](https://github.com/op-tee/optee_os/blob/master/lib/libutee/tee_api.c): user TA runtime · User-mode TA syscall stubs, internal API, and TA entry support · `lib/libutee/tee_api.c`
- [User TAs](https://github.com/op-tee/optee_os/blob/master/ta/pkcs11/src/entry.c): trusted apps · Example and product TAs such as PKCS#11, AVB, remoteproc, and trusted keys · `ta/pkcs11/src/entry.c`

### Shared libs

Reusable libraries embedded into core and TAs

- [TomCrypt](https://github.com/op-tee/optee_os/blob/master/core/lib/libtomcrypt/tomcrypt.c): crypto lib · Embedded third-party crypto library used by core and TA components · `core/lib/libtomcrypt/tomcrypt.c`
- [Mbed TLS](https://github.com/op-tee/optee_os/blob/master/lib/libmbedtls/core/tomcrypt.c): crypto lib · Embedded Mbed TLS core used by secure-world crypto and TA support · `lib/libmbedtls/core/tomcrypt.c`
- [QCBOR](https://github.com/op-tee/optee_os/blob/master/core/lib/qcbor/src/qcbor_encode.c): cbor lib · CBOR encoding and decoding support for secure-world protocols · `core/lib/qcbor/src/qcbor_encode.c`

### Build & tooling

Build system, scripts, packaging, and CI

- [Build tools](https://github.com/op-tee/optee_os/tree/master/Makefile): build system · Makefiles, helper scripts, signing, image generation, and CI tooling · `Makefile`

## Connections

- Normal world → SMC / RPC: calls · Clients enter secure world through standard call mechanisms
- SMC / RPC → Secure OS: enters · Secure-world boundary into OP-TEE
- Secure OS → Kernel core: dispatches · Core control plane runs in the privileged kernel
- Kernel core → Memory mgmt: maps · Kernel relies on the memory-management boundary
- Kernel core → TEE services: serves · TEE APIs, storage, and service routing are managed here
- Kernel core → PTAs: invokes · Normal-world requests can be routed to PTAs
- Kernel core → TA loader: loads · User TA binaries are loaded and prepared for execution
- Kernel core → Crypto core: uses · Kernel services use portable crypto and RNG primitives
- Crypto core → Crypto drivers: accelerates · Hardware engines back selected crypto operations
- Kernel core → HW drivers: depends on · Kernel and PTAs share platform drivers and peripherals
- HW drivers → PTAs: feeds · PTAs consume shared hardware services such as RNG, storage, and secure monitors
- ARM platforms → ARM monitor: binds · ARM platforms supply board-specific code for the generic backend
- ARM monitor → ARM MMU: uses · ARM backend relies on MMU and cache helpers
- RISC-V platforms → RISC-V monitor: binds · RISC-V platforms supply board-specific code for the generic backend
- RISC-V monitor → RISC-V MMU: uses · RISC-V backend relies on MMU and TLB helpers
- TA loader → UTEE runtime: executes · Loaded user TAs run against the UTEE ABI and syscall layer
- UTEE runtime → User TAs: hosts · TAs build on the runtime and internal API
- User TAs → PTAs: invokes · User TAs can call privileged services exposed by PTAs
- User TAs → TomCrypt: links · Some TAs use the embedded crypto library
- Kernel core → Mbed TLS: links · Secure OS crypto paths can use the embedded Mbed TLS stack
- PTAs → QCBOR: formats · Attestation and service payloads may use CBOR
- Build tools → Secure OS: builds · Top-level build drives secure-world image assembly
- Build tools → User TAs: builds · TA build rules and packaging are driven from the repository build system
- Build tools → TA loader: packages · Loader binaries and signing helpers are part of the image flow
