Core Concepts: How PangeaOS Works From the Ground Up

1. What Does an Operating System Kernel Actually Do?

Before looking at how PangeaOS is built, it helps to step back and ask: What is an operating system kernel, and why does its design matter so much?

Inside your computer, there is physical hardware: the processor (CPU), memory chips (RAM), storage drives, and network cards. Running on top of that hardware are dozens of separate software components—file system drivers, network protocol handlers, audio services, and user applications.

If every program were allowed to access all of RAM and control hardware devices directly, two bad things would happen right away:

1. Accidental Corruption: A small bug in a background service could overwrite the memory being used by your web browser or by the operating system itself, causing an immediate crash.
2. Resource Monopolization: A program stuck in an endless loop (while (true) {}) would hold onto the CPU forever, freezing your mouse, keyboard, and screen.

The operating system kernel is the central referee that prevents both problems. Its job is to divide memory into safe compartments, share processor time fairly, and help components pass messages to one another.

---

2. Why Mainstream Operating Systems Pay a "Switching Tax"

For the last several decades, mainstream operating systems (such as Linux, Windows, and macOS) have protected programs from each other using two hardware mechanisms built into x86-64 processors: Privilege Rings and Separate Virtual Address Spaces.

2.1 Privilege Rings (User Mode vs. Kernel Mode)

x86-64 processors have hardware privilege levels numbered from Ring 0 (most privileged) to Ring 3 (least privileged):

• Ring 0 (Kernel Mode): The processor can execute any instruction, update memory maps, and talk directly to hardware.
• Ring 3 (User Mode): The processor blocks instructions that control hardware or change memory settings.

In a traditional operating system, only the core kernel runs in Ring 0. Applications and many system services run in Ring 3.

2.2 Separate Virtual Address Spaces (Separate Page Tables)

In addition to running programs in Ring 3, a traditional operating system gives every single program its own private Page Table—a multi-level lookup map in memory (pointed to by a special CPU register named CR3) that translates the virtual memory addresses a program sees into real physical RAM locations.

TRADITIONAL OS: SEPARATE ADDRESS SPACES (Slow Transitions)

  [ Service A (Ring 3) ]                  [ Service B (Ring 3) ]
  Private Address Map #1                  Private Address Map #2
           │                                       ▲
           │ 1. Trap into Ring 0 (syscall)         │ 4. Return to Ring 3
           ▼                                       │
  ┌─────────────────────────────────────────────────────────┐
  │               Operating System Kernel (Ring 0)          │
  │   2. Save registers & validate arguments                │
  │   3. Overwrite CR3 register to swap Address Map #1 -> #2│
  │      (Flushes cached address lookups in the CPU TLB!)   │
  └─────────────────────────────────────────────────────────┘

2.3 Where the Slowdown Happens

Giving every program its own separate address map is very effective at keeping programs apart, but it comes with a heavy cost whenever two components need to work together:

1. Mode Switching Overhead: Every time Service A wants to send data to Service B, the processor must stop executing Service A in Ring 3, transition into Ring 0, save registers, and validate the request.
2. Address Cache Flushing (TLB Misses): Because the processor's page tables live in RAM, looking up an address through a 4-level page table on every instruction would be terribly slow. To speed things up, the CPU caches recent address lookups inside a fast hardware cache called the TLB (Translation Lookaside Buffer). However, when the kernel overwrites the CR3 register to switch from Service A's address map to Service B's address map, cached lookups from the old map become invalid or require extra context tags, slowing down memory accesses after every switch.

---

3. The PangeaOS Approach: One Shared Floor With Smart Locks

PangeaOS asks a simple question: What if we stopped swapping out the address map?

Instead of creating a separate virtual address space for every program, PangeaOS places the core kernel (Domain 0) and up to twelve isolated service compartments (Domains 1 through 12) inside one shared 64-bit virtual address space (a design known as a Single Address Space Operating System, or SASOS). Furthermore, all verified components run in Ring 0 (CPL=0).

PANGEAOS v1.2.4b: ONE SHARED ADDRESS SPACE (Zero Map Swaps)

  ┌─────────────────────────────────────────────────────────────────────┐
  │            Single 64-Bit Virtual Address Space (Shared CR3)         │
  │                                                                     │
  │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────────┐  │
  │  │   Domain 1       │  │   Domain 2       │  │   Domain 3        │  │
  │  │ 1 TB Sandbox     │  │ 1 TB Sandbox     │  │ 1 TB Sandbox      │  │
  │  │ Locked by Key K1 │  │ Locked by Key K2 │  │ Locked by Key K3  │  │
  │  └────────┬─────────┘  └────────▲─────────┘  └───────────────────┘  │
  │           │                     │                                   │
  │           └── Fast Gate Call ───┘ (Updates PKRU keycard in ~cycles; │
  │                                    CR3 address map never changes!)  │
  │  ┌───────────────────────────────────────────────────────────────┐  │
  │  │         Domain 0: Core Kernel, Scheduler & Gates (Key K0)     │  │
  │  └───────────────────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────────────────┘

Because every component lives on the same shared map:

• The CR3 page-table register never changes during task switches.
• The processor's address translation cache (TLB) stays warm.
• Switching between components only requires changing a single 32-bit hardware keycard register (PKRU) inside an audited assembly gate.

---

4. How Do You Keep Programs Safe Without Separate Address Maps?

At this point, a natural question arises: If every service lives in the same address space and runs in Ring 0, what stops a buggy or malicious service from overwriting the kernel or crashing the computer?

PangeaOS solves this by replacing the traditional User/Kernel wall with four cooperating mechanisms that reinforce one another:

Mechanism 1: Pre-Launch Machine Code Inspection (bincheck-core)

In Ring 0, the processor allows special instructions that normal programs should never touch—such as cli (which turns off hardware interrupts so the timer stops working), mov cr3, rax (which changes the memory map), or wrpkru (which changes the hardware memory keycard).

In PangeaOS, no service binary is ever allowed to run until it passes a strict pre-launch inspection by bincheck-core and domain-verify:

1. Instruction-by-Instruction Decoding: The scanner decodes the compiled binary from the very first byte to the last. Every instruction must belong to an approved allowlist of safe arithmetic, logic, stack, and memory instructions. If a binary contains cli, wrpkru, iretq, or any other privileged instruction, PangeaOS rejects the binary before it can ever run.
2. 1-Terabyte Sandbox Enforcement (SFI): Each service domain $d$ ($1 \le d \le 12$) is assigned a 1-Terabyte slice of virtual memory where the top bits (47..40) equal $d$. For example, Domain 3 owns 0x0000_0300_0000_0000 through 0x0000_03FF_FFFF_FFFF. The scanner checks that direct memory operations stay inside that 1-Terabyte window.

Mechanism 2: Hardware Memory Keycards (MPK / PKRU)

Even after a program's code is verified, PangeaOS uses a live hardware protection feature built into modern x86-64 CPUs called Memory Protection Keys (MPK).

• Every 4-Kilobyte page in the page table is stamped with a 4-bit key number from 0 to 15 (K0 through K15).
• A 32-bit CPU register called PKRU acts as the active keycard. It holds 2 permission bits for each of the 16 keys (00 = Read/Write, 10 = Read-Only, 11 = No Access).
• When the kernel switches to Domain 3, the entry gate sets PKRU so that only K3 has Read/Write access (and K14, the message counter window, has Read-Only access). All other keys—including the core kernel's key (K0), the page-table vault (K13), and every other domain's key (K1, K2, K4..K12)—are set to 11 (No Access).
• On every single memory read or write instruction, the CPU hardware checks PKRU in parallel with the address lookup. If Domain 3 tries to read or write a K0 kernel page or a K4 page belonging to Domain 4, the processor blocks the access before a single byte is touched and triggers a hardware Page Fault (#PF).

Mechanism 3: The Two-Stack Emergency Crash Rescue Protocol (pangea-irq)

What happens right after the processor triggers a hardware fault inside Domain 3? In a naive Ring-0 kernel, taking an exception while running inside a domain is dangerous for two reasons:

1. The processor is still holding Domain 3's keycard (PKRU), which has kernel memory (K0) locked! If the exception handler tries to read or write kernel variables, it will trigger a second fault.
2. Domain 3's stack pointer (RSP) might be corrupted or pointing to unmapped memory.

PangeaOS v1.2.4b solves this hardware puzzle using the Two-Stack Supervisor IST Entry Protocol:

LIVE CRASH RECOVERY FLOW IN PANGEAOS v1.2.4b

  [ Domain 5 Running (PKRU = K5 only) ]
           │
           │ Executes invalid instruction (`ud2`) or touches locked memory
           ▼
  [ Step 1: Hardware Trap to IST 1 (Always-Unlocked Supervisor Stack) ]
           │ CPU automatically switches RSP to IST 1 (mapped U/S=0)
           ▼
  [ Step 2: Assembly Stub Resets PKRU -> 0xCBFF_FFFC ]
           │ Unlocks Kernel Key K0; locks all Domain Keys K1..K12
           ▼
  [ Step 3: Verify "PANGEAK0" Canary & Pivot RSP to k0_priv_rsp ]
           │ Copies 23-qword frame to private kernel stack (frees IST 1!)
           ▼
  [ Step 4: Rust Dispatcher Attributes Fault to Domain 5 (L1Domain) ]
           │ Quarantines Domain 5 & jumps to saved SchedulerContinuation
           ▼
  [ Scheduler Resumes Cleanly in Domain 0 — OS Never Reboots! ]

Because the scheduler saves a bookmark of its own registers (SchedulerContinuation) in K0 memory every time it enters a domain, recovering from a domain crash is as clean as jumping back to that bookmark and returning an error code (ABORT_REASON_DOMAIN_EXCEPTION = 2) to the scheduler loop.

Mechanism 4: Preemptive Stopwatches, Quotas & Safe Memory Wiping

Finally, PangeaOS ensures that a misbehaving service cannot starve the rest of the system:

• 1-Millisecond Timer Preemption: Every 1 millisecond, the Local APIC timer interrupts the running domain. If a domain is stuck in an infinite loop, it is paused on the first overrun so other domains can run, and quarantined on repeated overruns.
• 16-Megabyte Kernel Emergency Reserve: Every domain has a strict memory allocation cap. Even if multiple domains try to exhaust memory at the same time, 16 MiB of RAM are permanently reserved for Domain 0.
• Quarantine & Zeroization Before Reuse (pangea-pfndb & cmee): When a memory page is reclaimed from a quarantined domain, it is never handed straight to another domain. It stays locked in PfnState::Quarantine until all CPU cores and hardware devices confirm they have flushed their address caches, and the cmee module has overwritten all 4,096 bytes with zeros.