# Memory Protection & Isolation

*Revera's differentiator. See also [Memory Management and Footprint](memory-footprint.md) and
[Safety, Security, and Compliance](safety-security-compliance.md).*

> **The criterion.** How cleanly does the RTOS use the hardware (MPU / MMU / bus) to keep a fault or a
> compromise in one thread — or one whole scheduling domain — from reaching another's memory, and to separate
> privileged from unprivileged execution? On most kernels this boundary holds only by convention.

## How Revera answers it

Isolation is Revera's headline. It is a **ladder** — you enable exactly the rung your target's hardware
supports, and each rung is enforced by the CPU, not by convention:

1. a **software stack canary** on any target (post-hoc overflow detection),
2. a **hardware stack guard** that faults an overflow at the offending instruction,
3. **unprivileged threads** behind a syscall boundary, with **kernel-owned handles** so a forged handle from
   an unprivileged thread is rejected, never dereferenced (the property that makes unprivileged threads safe),
4. **full-lockdown** placement of each thread's stack and the kernel's own RAM in fenced regions,
5. a **per-island supervisor fence** that binds even *privileged* kernel code — island A's kernel cannot reach
   island B's RAM — proven across **five protection mechanisms and two classes** (region MPUs and paging), and
6. **TrustZone-AMP worlds** (Secure / Non-secure) on the system bus.

Ask the kernel what boundary a build actually enforces with `tk_kernel_isolation()` →
`TK_ISOLATION_NONE / _THREAD / _INSTANCE`; asking for a boundary the arch can't enforce fails **loud** at
compile time, never silently degrades.

## The ladder — what it enforces · how to turn it on · how to use it · where it works

| Rung | Enforces | Enable with | Use these APIs | Mechanism · architectures |
|---|---|---|---|---|
| **Stack canary** | Detects a stack overflow at the next context switch (software, any target) | `TK_CONFIG_ENABLE_STACK_CHECK` *(on by default)* | `tk_set_stack_overflow_hook`, `tk_thread_stack_peak` / `_free` | software — **all** targets |
| **MPU stack guard** | Faults an overflow in hardware, at the overflowing write | `TK_CONFIG_ENABLE_MPU_GUARD` | `TK_THREAD_STACK` (declare the stack) | region MPU/PMP — Cortex-M (v7/v8-M), RISC-V, AURIX |
| **Unprivileged threads** | App threads run in user mode; reach the kernel only through the SVC / ecall / trap syscall boundary | `TK_CONFIG_UNPRIV_THREADS` | `tk_thread_set_privileged`; all `tk_sem_*` / `tk_mutex_*` / `tk_cond_*` (kernel-owned handles) | Cortex-M (v7/v8-M), RISC-V S-mode, AURIX |
| **Full-lockdown isolation** | Each thread's stack + kernel RAM in MPU-fenced sections — touching a peer stack or kernel RAM faults | `TK_CONFIG_ENABLE_MPU_ISOLATION` *(board declares `BOARD_HAS_MPU_ZONES`)* | `TK_THREAD_STACK` | region MPU/PMP — same as above |
| **Supervisor fence (per island)** | Binds even the KERNEL: island A's privileged code cannot reach island B's RAM | `TK_CONFIG_ENABLE_INSTANCE_ISOLATION` | `tk_kernel_define`, `tk_kernel_set_ram`, `tk_kernel_set_trusted`; `tk_instance_fence_reject` *(weak hook)* | region MPU (v8-M, Cortex-R, AURIX) **+** paging (RISC-V Sv32, ARM VMSA) |
| **TrustZone-AMP worlds** | Secure / Non-secure domains attributed at the system bus | `TK_CONFIG_ENABLE_WORLD` *(board declares `BOARD_HAS_WORLD`)* | `tk_kernel_set_world`, `tk_kernel_world`, `tk_kernel_launch_secondary` | ARM v8-M TrustZone + system-side bus (e.g. MCXN947 AHBSC) |
| **Boundary query** | Report the boundary this build enforces (honest, runtime) | — | `tk_kernel_isolation()` → `TK_ISOLATION_*` | all |

*For the full signature and contract of any symbol above, see the
[API reference](../reference/api.md) (Threads · Kernel lifecycle & instances · Synchronization sections).*

## Limits & roadmap

- **Not every target can enforce it.** ARM Cortex-M0/M0+ (v6-M), TI C2000, and MSP430 have no
  privilege-binding protection unit — there an "island" or "thread boundary" is a scheduling + convention
  partition, **not** a hardware safety boundary. Revera says so at compile time rather than pretending.
- **The fence is a memory boundary, not a covert-channel or timing defense**, and the software stack canary is
  post-hoc (it catches the overflow at the next switch, not at the instruction — that's the MPU guard's job).
- **On the roadmap:** the secondary-core (Non-secure) system-side fence is proven on MCXN947 hardware but not
  yet grafted into the portable kernel; see [ADR 0005](../decisions/0005-system-side-secondary-core-fence.md).

## Learn more

- **How it works:** [per-thread stack isolation](../architecture/isolation/per-thread-stack-isolation.md) ·
  [kernel-RAM isolation](../architecture/isolation/kernel-ram-isolation.md) ·
  [kernel-owned sync](../architecture/isolation/kernel-owned-sync.md) · ADRs
  [0003](../decisions/0003-supervisor-fence-seam.md) / [0004](../decisions/0004-per-island-kernel-ram-fence.md)
  / [0005](../decisions/0005-system-side-secondary-core-fence.md).
- **The full API:** [API reference](../reference/api.md).
- **Run it:** `examples/isolation`, `examples/isolation_reject`, `examples/fault_contain`, the
  `examples/fence_*` demos, and `examples/amp_kernel_fence` — each builds on a listed board.
- **Per-target maturity:** the [readiness dashboard](../readiness-1.0.0/dashboard.md) isolation section.