# op-tee/optee_linuxdriver architecture

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

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

## Overview

##### Project type and purpose
- This is a Linux kernel driver module (“optee.ko”) that implements the client-side interface for OP-TEE (Open Portable Trusted Execution Environment).
- Purpose: facilitate communication between the Rich OS (normal world) applications, the secure world Trusted OS, and a user-space “tee-supplicant” daemon. It uses ARM TrustZone mechanisms (SMC calls) and shared memory to proxy requests.

##### File structure
- Top level:
- Makefile, Kconfig, .travis.yml – build and CI integration.
- arm tz folder (“armtz”) – ARM/ARM64 assembly stubs and transport layer implementing SMC calling conventions and memory setup.
- core folder – main kernel driver code: context, session, shared memory, sysfs/debugfs interfaces, mutex and wait-queue primitives, TEE kernel API.
- – public and internal headers: Linux TEE client APIs, OP-TEE message formats, SMCCC definitions.
- fdts – device tree snippets describing foundation models for FVP testing.
- Patterns:
- Kernel module layering: low-level transport (armtz) → core driver logic (core/) → user-space interface (ioctl, sysfs, debugfs).
- Clear separation of ark (transport), core (business logic), and includes (APIs).

##### Insights from README
- The module bridges secure and normal worlds via SMC and the tee-supplicant.
- It registers a character-device or ioctl interface for user-space clients.
- It relies on Linux kernel subsystems: sysfs, debugfs, wait queues, mutexes.
- Target hardware: ARM TrustZone platforms, FVP Foundation model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-space Layer
    subgraph "User-space" 
        ClientApp["RichOS Client Application"]:::user
        TeeSupp["tee-supplicant Daemon"]:::user
    end

    %% Configuration
    Build["Build & CI (Makefile, Kconfig, .travis.yml)"]:::config

    %% Device Tree
    DeviceTree["Device Tree Snippets"]:::config

    %% Kernel Driver
    subgraph "OP-TEE Linux Kernel Driver"
        subgraph "Transport Layer (armtz)"
            TeeSmcArm["tee_smc-arm.S"]:::transport
            TeeSmcArm64["tee_smc-arm64.S"]:::transport
            TeeTzDrv["tee_tz_drv.c"]:::transport
            TeeMem["tee_mem.c"]:::transport
            Handle["handle.c"]:::transport
        end
        subgraph "Core Logic (core)"
            CoreC["tee_core.c"]:::core
            Context["tee_context.c"]:::core
            Session["tee_session.c"]:::core
            Shm["tee_shm.c"]:::core
            KernelApi["tee_kernel_api.c"]:::core
            SuppCom["tee_supp_com.c"]:::core
            MutexWait["tee_mutex_wait.c"]:::core
            WaitQueue["tee_wait_queue.c"]:::core
            SysfsC["tee_sysfs.c"]:::core
            DebugfsC["tee_debugfs.c"]:::core
        end
        subgraph "Headers (include)"
            ApiH["tee_client_api.h"]:::include
            IocH["tee_ioc.h"]:::include
            CoreH["tee_core.h"]:::include
            KernelApiH["tee_kernel_api.h"]:::include
            MsgH["optee_msg.h"]:::include
            SmcH["optee_smc.h"]:::include
        end
    end

    %% Linux Kernel Subsystems
    LinuxInfra["Linux Kernel Subsystems\n(sysfs/debugfs, mutex, wait queues)"]:::infra

    %% Secure World
    SecureMon["Secure Monitor (SMC)"]:::secure
    SecureOS["Secure World OP-TEE OS"]:::secure

    %% Hardware
    Hardware["Hardware\n(TrustZone CPU, Shared DRAM)"]:::hardware

    %% Connections
    ClientApp -->|"uses API"| ApiH
    ApiH -->|"ioctl/TEE_IOC"| TeeTzDrv
    DeviceTree -->|"platform init"| TeeTzDrv
    Build -->|"build module"| TeeTzDrv

    TeeTzDrv -->|"invoke core logic"| CoreC
    CoreC --> Context
    CoreC --> Session
    CoreC --> Shm
    CoreC --> SuppCom
    CoreC --> MutexWait
    CoreC --> WaitQueue
    CoreC --> SysfsC
    CoreC --> DebugfsC

    TeeTzDrv -->|"SMC call"| SecureMon
    Shm -->|"shared memory IPC"| SecureMon
    SecureMon -->|"SMC forward"| SecureOS
    SecureOS -->|"RPC (FS/crypto)"| TeeSupp
    TeeSupp -->|"RPC response"| SecureOS
    SecureOS -->|"SMC return"| SecureMon
    SecureMon -->|"return message"| TeeTzDrv
    TeeTzDrv -->|"response via core"| CoreC
    CoreC -->|"return result"| ApiH
    ApiH -->|"result"| ClientApp

    LinuxInfra --> CoreC
    LinuxInfra --> SysfsC
    LinuxInfra --> DebugfsC

    SecureMon --> Hardware
    SecureOS --> Hardware

    %% Click Events - Transport
    click TeeSmcArm "https://github.com/op-tee/optee_linuxdriver/blob/master/armtz/tee_smc-arm.S"
    click TeeSmcArm64 "https://github.com/op-tee/optee_linuxdriver/blob/master/armtz/tee_smc-arm64.S"
    click TeeTzDrv "https://github.com/op-tee/optee_linuxdriver/blob/master/armtz/tee_tz_drv.c"
    click TeeMem "https://github.com/op-tee/optee_linuxdriver/blob/master/armtz/tee_mem.c"
    click Handle "https://github.com/op-tee/optee_linuxdriver/blob/master/armtz/handle.c"
    %% Click Events - Core
    click CoreC "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_core.c"
    click Context "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_context.c"
    click Session "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_session.c"
    click Shm "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_shm.c"
    click KernelApi "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_kernel_api.c"
    click SuppCom "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_supp_com.c"
    click MutexWait "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_mutex_wait.c"
    click WaitQueue "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_wait_queue.c"
    click SysfsC "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_sysfs.c"
    click DebugfsC "https://github.com/op-tee/optee_linuxdriver/blob/master/core/tee_debugfs.c"
    %% Click Events - Include
    click ApiH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/linux/tee_client_api.h"
    click IocH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/linux/tee_ioc.h"
    click CoreH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/linux/tee_core.h"
    click KernelApiH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/linux/tee_kernel_api.h"
    click MsgH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/arm_common/optee_msg.h"
    click SmcH "https://github.com/op-tee/optee_linuxdriver/blob/master/include/arm_common/optee_smc.h"
    %% Click Events - Config & DT
    click DeviceTree "https://github.com/op-tee/optee_linuxdriver/tree/master/fdts/"
    click Build "https://github.com/op-tee/optee_linuxdriver/tree/master/Makefile"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef transport fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef include fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#DCDCDC,stroke:#333,stroke-width:1px
    classDef secure fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef hardware fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef config fill:#FFD700,stroke:#333,stroke-width:1px
```
