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

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