How op-tee/optee_os works
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: thread.c Kernel core · entry.c User TAs · attestation.c PTAs · Makefile Build tools
Components 23
External boundary
Normal-world and firmware interfaces that enter or depend on the secure OS
- Normal world · REE clients, firmware, and non-secure OS components that call into OP-TEE
- SMC / RPC · 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 · The secure-world half of OP-TEE
core/kernel/boot.c - Kernel core · Boot, traps, scheduling, interrupts, notifications, TA control, and common services
core/kernel/thread.c - Memory mgmt · Physical memory, page allocation, MMU, pageable memory, and shared memory objects
core/mm/core_mmu.c - TEE services · TEE storage, objects, crypto services, time, and secure service entry points
core/tee/tee_svc.c - PTAs · Privileged services exposed from secure context to normal-world clients
core/pta/attestation.c - Crypto core · Portable crypto primitives and RNG glue used by the secure OS
core/crypto/crypto.c - Crypto drivers · Hardware-backed accelerators, secure elements, and vendor crypto engines
core/drivers/crypto/sub.mk - HW drivers · Shared console, interrupt, clock, GPIO, storage, reset, and peripheral drivers
core/drivers/gic.c - 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 · ARM board and SoC integration, platform init, and vendor services
core/arch/arm/plat-stm32mp1/main.c - ARM monitor · ARM entry, exceptions, secure monitor interfaces, PSCI, and context switch paths
core/arch/arm/kernel/entry_a64.S - ARM 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 · RISC-V board integration, platform init, and console/boot support
core/arch/riscv/plat-virt/main.c - RISC-V monitor · RISC-V entry, SBI, OP-TEE ABI paths, and thread/context handling
core/arch/riscv/kernel/entry.S - RISC-V 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 · User-mode TA syscall stubs, internal API, and TA entry support
lib/libutee/tee_api.c - User TAs · 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 · Embedded third-party crypto library used by core and TA components
core/lib/libtomcrypt/tomcrypt.c - Mbed TLS · Embedded Mbed TLS core used by secure-world crypto and TA support
lib/libmbedtls/core/tomcrypt.c - QCBOR · 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 · Makefiles, helper scripts, signing, image generation, and CI tooling
Makefile
Connections 24
- 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