# d-e-e-p-t-h-i/softtee architecture

> Architecture diagram of the GitHub repository d-e-e-p-t-h-i/softtee, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d-e-e-p-t-h-i/softtee
- Repository: https://github.com/d-e-e-p-t-h-i/softtee

## Overview

#### Purpose and Entry Points
PEX SofTEE is a Linux prototype for kernel-assisted, intra-process protected execution. A process creates a protected context, maps kernel-owned memory, and explicitly enters/exits it via `/dev/pex` ioctls. Primary entry points are the kernel module in `kernel/pex_main.c`, the user runtime in `libpex/src/pex.c`, and the public ABI in `libpex/include/pex.h` and `libpex/include/pex_uapi.h`.

#### Kernel Protection Authority
`kernel/pex_main.c` implements `pex.ko`, the authoritative isolation layer. It registers `/dev/pex`, owns protected-context lifecycle and memory mappings, and enforces access based on active context and thread ownership. Its ioctl control plane covers context creation, entry, exit, destruction, and state queries. It also exposes aggregate and per-context telemetry through `/proc/pex_stats`.
- `kernel/pex_main.c`
- `kernel/Makefile`

#### Context Lifecycle and Access Boundary
The core boundary is between ordinary process memory and a context’s protected mapping. User code allocates a context through the library, receives a mapping, calls enter before touching it, then exits and destroys it. Access outside an active context—or from a non-owner thread under `PEX_POLICY_OWNER_THREAD_ONLY`—faults through kernel mapping protections. This is software/kernel isolation, not hardware-backed TEE isolation.
- `libpex/include/pex_uapi.h`
- `kernel/pex_main.c`
- `libpex/src/pex.c`

#### User-Space Runtime Contract
`libpex` is the consumer-facing C API and translates runtime calls into device opens, ioctl operations, and mapping management. It is built as static and shared libraries, allowing examples, tests, and demos to share one ABI rather than duplicating device protocol logic.
- `libpex/include/pex.h`
- `libpex/src/pex.c`
- `libpex/Makefile`

#### Workloads, Validation, and Demonstration
Console workloads exercise the intended behavior: protected work while entered and fault-gated access while inactive or incorrectly threaded. The Tkinter viewer demonstrates a visible protected-reveal flow: it decrypts an asset at startup, copies plaintext into the protected mapping on entry, copies to a normal display buffer, then wipes buffers on exit. The display path is explicitly outside the protection boundary.
- `examples/protected_workload.c`
- `examples/showcase_blocking.c`
- `demo/pex_viewer.py`

#### Host Deployment Flow
The host workflow builds the library, module, and consumers from the top-level `Makefile`. Privileged setup loads/reloads `pex.ko`, creates `/dev/pex`, and assigns usable permissions; application execution then occurs as an ordinary user process against that device.
- `Makefile`
- `scripts/dev_setup.sh`
- `scripts/run_all.sh`

#### Reproducible Guest Integration
Buildroot packages the module and PEX artifacts into an AArch64 root filesystem for QEMU-based validation. The external package definition integrates PEX into the image; the rootfs init hook loads the module and invokes bundled validation scripts under `/opt/pex`. This provides a separate runtime environment from the host kernel/module workflow.
- `buildroot/package/pex/pex.mk`
- `buildroot/overlay/etc/init.d/S99pex`
- `buildroot/build_image.sh`

Main entry points: [`libpex/src/pex.c`](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/src/pex.c) (libpex runtime), [`kernel/pex_main.c`](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/pex_main.c) (pex.ko protection layer), [`buildroot/package/pex/pex.mk`](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/package/pex/pex.mk) (Buildroot PEX package), [`libpex/include/pex_uapi.h`](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/include/pex_uapi.h) (PEX UAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel["Kernel authority"]
  node_kernel_make["Module build<br/>kernel Makefile"]
  node_pex_module{{"pex.ko protection layer<br/>kernel module<br/>[pex_main.c]"}}
  node_pex_device[("/dev/pex ioctl plane<br/>character device")]
  node_proc_stats["/proc/pex_stats<br/>telemetry endpoint<br/>[pex_main.c]"]
end

subgraph group_user["User runtime and workloads"]
  node_public_api["libpex public API<br/>[pex.h]"]
  node_uapi["PEX UAPI<br/>ABI definitions<br/>[pex_uapi.h]"]
  node_libpex["libpex runtime<br/>C runtime<br/>[pex.c]"]
  node_lib_build["libpex artifacts<br/>library build"]
  node_console_workloads["Console workloads<br/>C examples"]
  node_blocking_demo["Thread-policy demo<br/>C example"]
  node_viewer["Protected reveal viewer<br/>Tkinter demo<br/>[pex_viewer.py]"]
end

subgraph group_host["Host deployment"]
  node_top_make["Top-level build<br/>build orchestrator"]
  node_dev_setup["Privileged device setup<br/>setup script<br/>[dev_setup.sh]"]
  node_run_all["Host validation runner<br/>run script<br/>[run_all.sh]"]
end

subgraph group_guest["Buildroot guest integration"]
  node_buildroot_pkg["Buildroot PEX package<br/>external package<br/>[pex.mk]"]
  node_guest_init["Guest init hook<br/>rootfs init script<br/>[S99pex]"]
  node_image_build["Guest image build<br/>Buildroot script<br/>[build_image.sh]"]
end

node_top_make -->|"builds"| node_kernel_make
node_top_make -->|"builds"| node_lib_build
node_kernel_make -->|"produces"| node_pex_module
node_dev_setup -->|"loads/reloads"| node_pex_module
node_dev_setup -->|"creates and permits"| node_pex_device
node_pex_module -->|"registers"| node_pex_device
node_pex_module -->|"exports"| node_proc_stats
node_public_api -->|"implemented by"| node_libpex
node_uapi -->|"defines ABI for"| node_libpex
node_uapi -->|"shared ioctl ABI"| node_pex_module
node_lib_build -->|"packages"| node_libpex
node_libpex -->|"opens, ioctls, maps"| node_pex_device
node_console_workloads -->|"uses"| node_libpex
node_blocking_demo -->|"uses"| node_libpex
node_viewer -->|"uses protected mapping"| node_libpex
node_run_all -->|"runs"| node_console_workloads
node_buildroot_pkg -.->|"packages"| node_pex_module
node_buildroot_pkg -.->|"packages"| node_libpex
node_image_build -->|"integrates"| node_buildroot_pkg
node_image_build -->|"installs overlay"| node_guest_init
node_guest_init -.->|"loads in guest"| node_pex_module

click node_top_make "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/Makefile"
click node_dev_setup "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/scripts/dev_setup.sh"
click node_run_all "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/scripts/run_all.sh"
click node_kernel_make "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/Makefile"
click node_pex_module "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/pex_main.c"
click node_proc_stats "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/pex_main.c"
click node_public_api "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/include/pex.h"
click node_uapi "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/include/pex_uapi.h"
click node_libpex "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/src/pex.c"
click node_lib_build "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/Makefile"
click node_console_workloads "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/examples/protected_workload.c"
click node_blocking_demo "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/examples/showcase_blocking.c"
click node_viewer "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/demo/pex_viewer.py"
click node_buildroot_pkg "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/package/pex/pex.mk"
click node_guest_init "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/overlay/etc/init.d/S99pex"
click node_image_build "https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/build_image.sh"

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_kernel_make,node_pex_module,node_pex_device,node_proc_stats toneBlue
class node_public_api,node_uapi,node_libpex,node_lib_build,node_console_workloads,node_blocking_demo,node_viewer toneAmber
class node_top_make,node_dev_setup,node_run_all toneMint
class node_buildroot_pkg,node_guest_init,node_image_build toneRose
```

## Components

### Kernel authority

Authoritative protection and device boundary.

- [Module build](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/Makefile): kernel Makefile · `kernel/Makefile`
- [pex.ko protection layer](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/pex_main.c): kernel module · Owns contexts, mappings, access enforcement, and telemetry. · `kernel/pex_main.c`
- **/dev/pex ioctl plane**: character device · Context lifecycle, entry/exit, destruction, and state queries.
- [/proc/pex_stats](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/kernel/pex_main.c): telemetry endpoint · Aggregate and per-context statistics. · `kernel/pex_main.c`

### User runtime and workloads

Consumer ABI and protected execution clients.

- [libpex public API](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/include/pex.h): C API · Consumer-facing protected-context contract. · `libpex/include/pex.h`
- [PEX UAPI](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/include/pex_uapi.h): ABI definitions · Shared ioctl and policy definitions. · `libpex/include/pex_uapi.h`
- [libpex runtime](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/src/pex.c): C runtime · Translates API calls into device ioctls and mapping management. · `libpex/src/pex.c`
- [libpex artifacts](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/libpex/Makefile): library build · Produces static and shared libraries. · `libpex/Makefile`
- [Console workloads](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/examples/protected_workload.c): C examples · Exercise entered access and fault-gated inactive or wrong-thread access. · `examples/protected_workload.c`
- [Thread-policy demo](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/examples/showcase_blocking.c): C example · Demonstrates owner-thread-only access behavior. · `examples/showcase_blocking.c`
- [Protected reveal viewer](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/demo/pex_viewer.py): Tkinter demo · Copies plaintext through protected memory into an unprotected display buffer, then wipes it. · `demo/pex_viewer.py`

### Host deployment

Build and privileged module setup.

- [Top-level build](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/Makefile): build orchestrator · Builds module, library, and consumers. · `Makefile`
- [Privileged device setup](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/scripts/dev_setup.sh): setup script · Loads the module and provisions /dev/pex. · `scripts/dev_setup.sh`
- [Host validation runner](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/scripts/run_all.sh): run script · `scripts/run_all.sh`

### Buildroot guest integration

Separate AArch64/QEMU image workflow.

- [Buildroot PEX package](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/package/pex/pex.mk): external package · Packages PEX artifacts into an AArch64 root filesystem. · `buildroot/package/pex/pex.mk`
- [Guest init hook](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/overlay/etc/init.d/S99pex): rootfs init script · Loads pex.ko and runs bundled validation under /opt/pex. · `buildroot/overlay/etc/init.d/S99pex`
- [Guest image build](https://github.com/d-e-e-p-t-h-i/softtee/blob/main/buildroot/build_image.sh): Buildroot script · Builds the QEMU-oriented AArch64 image. · `buildroot/build_image.sh`

## Connections

- Top-level build → Module build: builds
- Top-level build → libpex artifacts: builds
- Module build → pex.ko protection layer: produces
- Privileged device setup → pex.ko protection layer: loads/reloads
- Privileged device setup → /dev/pex ioctl plane: creates and permits
- pex.ko protection layer → /dev/pex ioctl plane: registers
- pex.ko protection layer → /proc/pex_stats: exports
- libpex public API → libpex runtime: implemented by
- PEX UAPI → libpex runtime: defines ABI for
- PEX UAPI → pex.ko protection layer: shared ioctl ABI
- libpex artifacts → libpex runtime: packages
- libpex runtime → /dev/pex ioctl plane: opens, ioctls, maps
- Console workloads → libpex runtime: uses
- Thread-policy demo → libpex runtime: uses
- Protected reveal viewer → libpex runtime: uses protected mapping
- Host validation runner → Console workloads: runs
- Buildroot PEX package → pex.ko protection layer: packages
- Buildroot PEX package → libpex runtime: packages
- Guest image build → Buildroot PEX package: integrates
- Guest image build → Guest init hook: installs overlay
- Guest init hook → pex.ko protection layer: loads in guest