# UniversalisOS — Current Status Report

> Audit date: 2026-07-09 | Source: full codebase scan + build verification

---

## Build Status

| Target | Command | Result |
|--------|---------|--------|
| **ARMv7 / QEMU virt** | `make ARCH=armv7 PLATFORM=qemu-arm-virt` | ✅ **BUILDS** (65 objects, 172 KB text) |
| **RISC-V / PolarFire** | `make ARCH=riscv PLATFORM=polarfire` | ✅ **BUILDS** (23 objects, 20 KB text) |
| **AArch64 / QEMU virt** | `make ARCH=aarch64 PLATFORM=qemu-aarch64-virt` | ❌ **FAILS** (`fdt_reader.h` missing) |

---

## Codebase Metrics

| Component | Lines of Code | Files |
|-----------|--------------|-------|
| **Core kernel** (`src/core/`) | 14,129 | 32 files + 7 subdirs |
| **ARMv7 arch** (`src/arch/armv7/`) | 3,390 | 13 files + 3 subdirs |
| **AArch64 arch** (`src/arch/aarch64/`) | 389 | 9 files |
| **RISC-V arch** (`src/arch/riscv/`) | 5,181 | 28 files + 1 subdir |
| **Shared platform drivers** (`src/platform/drivers/`) | 15,572 | 24 files |
| **Total** | **~41,790** | |

---

## Architecture Track Parity

### 1. ARMv7 / QEMU virt — 🟢 MATURE (the reference track)

This is the most complete track. The core kernel lives in `src/core/` and is compiled ONLY for this arch (RISC-V and AArch64 are self-contained).

| Subsystem | Status | Key Files |
|-----------|--------|-----------|
| Boot + exception vectors | ✅ Complete | [boot.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/boot.S), [exceptions.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/exceptions.cpp) |
| ARMv7 MMU (S1, flat 4GB map) | ✅ Complete | [mm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/mm.cpp) |
| GICv2 interrupt controller | ✅ Complete | [gic.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/gic.cpp) |
| Context switching (full register save/restore) | ✅ Complete | [context_switch_asm.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/context_switch_asm.S) |
| Cooperative + preemptive scheduler | ✅ Complete | [scheduler.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/scheduler.cpp), [sched_core.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/sched/sched_core.cpp) |
| VMIT XML config parser | ✅ Complete | [cfg_parser.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/config/cfg_parser.cpp), [sysmodel.h](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/config/sysmodel.h) |
| ARINC 653 sampling IPC | ✅ Complete | [uos_ipc_core.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/ipc/uos_ipc_core.cpp) |
| ARINC 653 queuing IPC | ✅ Complete | [uos_queuing.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/ipc/uos_queuing.cpp) |
| Shared memory + events | ✅ Complete | [uos_shmem.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/ipc/uos_shmem.cpp) |
| seL4-style capability MDB | ✅ Complete | [cap.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/cap/cap.cpp), [cap_compiler.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/cap/cap_compiler.cpp) |
| 3-tier health monitoring | ✅ Complete | [uos_hm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/hm/uos_hm.cpp) |
| Guest ABI (PV Linux ABI) | ✅ Complete | [uos_pv_abi.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/abi/uos_pv_abi.cpp) |
| PikeOS-class syscalls (task, TLS, ExRegs) | ✅ Complete | [uos_syscalls.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/uos_syscalls.cpp) |
| Partitions + VM contexts | ✅ Complete | [partition.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/partition.cpp), [vm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/vm.cpp) |
| MMU walk + address space | ✅ Complete | [uos_mmu_walk.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/uos_mmu_walk.cpp), [uos_adspace.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/uos_adspace.cpp) |
| FPU context save/restore | ✅ Complete | [uos_fpu.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/uos_fpu.cpp) |
| SMP framework | ✅ Framework | [uos_smp.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/core/uos_smp.cpp) |
| **Device drivers** | ✅ Complete | PCI/PCIe, USB (EHCI), block, network, GPIO, I2C, SPI, UART, timer, framebuffer |

**Verdict: ~60–70% of PikeOS kernel-core layer, ~5–10% of system-software layer.** This matches the plan's assessment.

---

### 2. AArch64 / QEMU virt — 🟡 MP0 BRING-UP (early)

> [!WARNING]
> Build is **BROKEN** — `fdt_reader.h` referenced in [kernel_aarch64.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/aarch64/kernel_aarch64.cpp) does not exist anywhere in the tree.

| Subsystem | Status | Notes |
|-----------|--------|-------|
| EL2 boot + EL3→EL2 drop | ✅ Complete | [boot.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/aarch64/boot.S) (67 lines) — QEMU hands EL2 |
| Exception vector table (VBAR_EL2) | ✅ Complete | [exceptions.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/aarch64/exceptions.S) (2.5 KB) |
| EL2 trap handler (sync abort) | ✅ Stub | [el2_trap.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/aarch64/el2_trap.cpp) — prints ESR then halts |
| LPAE S1 MMU (identity map) | ✅ Complete | [mmu_lpae.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/aarch64/mmu_lpae.cpp) — Bao-proven constants, L0→L1 1GiB blocks |
| UART (PL011 direct) | ✅ Inline | Hardcoded in kernel_aarch64.cpp (not abstracted) |
| FDT reader | ❌ **MISSING** | `fdt_reader.h` / `fdt_reader.cpp` do not exist |
| GICv3 | ❌ Not started | |
| Stage-2 MMU (VTTBR_EL2) | ❌ Not started | |
| vCPU context / ERET | ❌ Not started | |
| Virtual timer (CNTVOFF) | ❌ Not started | |
| Scheduler | ❌ Not started | |
| IPC | ❌ Not started | |

**Verdict: ~15% of MP0 is done.** The EL2 entry + LPAE flat map is proven but everything beyond that is TODO. The `kernel_aarch64.cpp` is explicitly marked as "TEMPORARY harness" to be replaced once the real subsystems are ported.

---

### 3. RISC-V / PolarFire — 🟢 FUNCTIONAL (parallel agent track)

Self-contained under `src/arch/riscv/` (does NOT use any `src/core/` files).

| Subsystem | Status | Key Files |
|-----------|--------|-----------|
| Boot (S-mode, multi-HART) | ✅ Complete | [boot.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/boot.S) (6.9 KB) |
| UART (MMUART/NS16550) | ✅ Complete | [uart.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uart.cpp) |
| Exception/trap handling | ✅ Complete | [trap.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/trap.S) + [uos_trap.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uos_trap.S) (14 KB combined) |
| PLIC (interrupt controller) | ✅ Complete | [plic.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/plic.cpp) (4.5 KB) |
| Timer (mtime/mtimecmp) | ✅ Complete | [timer.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/timer.cpp) |
| Sv39 page tables | ✅ Complete | [page_table.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/page_table.cpp) |
| Context switching | ✅ Complete | [context_switch_asm.S](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/context_switch_asm.S) |
| PikeOS-style scheduler (time partitions) | ✅ Complete | [task_sched.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/task_sched.cpp) (13 KB) |
| Partition management | ✅ Complete | [vm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/vm.cpp) (8.6 KB) |
| SBI interface | ✅ Complete | [sbi.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/sbi.cpp) |
| Hypercalls (ecall ABI) | ✅ Complete | [hypercall.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/hypercall.cpp) (6.2 KB) |
| Guest loading | ✅ Complete | [guest_loader.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/guest_loader.cpp) |
| Health monitoring | ✅ Complete | [hm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/hm.cpp) |
| SMP (secondary HART wake) | ✅ Framework | [smp.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/smp.cpp) |
| Bao-style VMM | ✅ Complete | [uos_vmm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uos_vmm.cpp), [uos_vm.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uos_vm.cpp) |
| CPU/emulation | ✅ Complete | [uos_cpu.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uos_cpu.cpp), [uos_emul.cpp](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/riscv/uos_emul.cpp) |

**Verdict: RISC-V has its own scheduler, partitions, VMM, hypercalls, and page tables. Independently functional but doesn't share the ARMv7 core subsystems (no ARINC IPC, no cap MDB, no HM 3-tier).** This is by design — it's the parallel-agent track you mentioned.

---

## Plan Milestone Status (MP0–MP5)

| Milestone | Description | Status | Details |
|-----------|-------------|--------|---------|
| **MP0** | AArch64/EL2 foundation (LPAE S1, DTB, QEMU cortex-a53 gate) | 🟡 **~30%** | EL2 entry + boot ✅, exception vectors ✅, LPAE S1 flat map ✅, UART ✅. **Missing**: FDT reader (build broken), GICv3 init, timer, scheduler wiring. The "QEMU gate" test cannot run because the build is broken. |
| **MP1** | Hardware virtualization (Stage-2, GICv3 VGIC, vCPU ERET, virtual timer) | ❌ **Not started** | No Stage-2 page tables (VTTBR_EL2). No GICv3 at all. No vCPU struct. |
| **MP2** | i.MX 8M Plus + STM32MP257 + i.MX6 platform ports | 🟡 **Scaffolding only** | `qemu-aarch64-virt` platform exists. `zybo` (Zynq-7010) platform exists with its own linker script. No i.MX or STM32MP platform dirs yet. |
| **MP3** | Linux guest via Yocto | ❌ **Not started** | Depends on MP1 + MP2. |
| **MP4** | M33 TrustZone-M / M7 MPU + RPMsg | ❌ **Not started** | |
| **MP5** | SMP | 🟡 **Framework** | `uos_smp.cpp` exists for ARMv7. RISC-V has `smp.cpp` with secondary HART wake. Neither is a full SMP scheduler. |

---

## Platform Ports

| Platform | Arch | Status | Key Config |
|----------|------|--------|------------|
| `qemu-arm-virt` | ARMv7 | ✅ Builds + runs | Cortex-A15, GICv2, PL011 |
| `qemu-aarch64-virt` | AArch64 | ❌ Build broken | Cortex-A53, EL2, PL011 |
| `qemu-riscv-virt` | RISC-V | ⚪ Scaffold only | Empty platform.mk |
| `qemu-riscv64-virt` | RISC-V | ⚪ Scaffold only | Empty dir |
| `polarfire` | RISC-V | ✅ Builds | PolarFire Icicle Kit (parallel track) |
| `polarfire-soc` | RISC-V | ⚪ Scaffold only | Empty dir |
| `zybo` | ARMv7 | ✅ Configured | Zynq-7010, Cortex-A9, custom linker |

---

## Build System Health

The Bao-style Makefile is **solid and well-designed**:

- ✅ Per `(ARCH, PLATFORM)` isolated build trees (`build/armv7/qemu-arm-virt/`, `build/riscv/polarfire/`, etc.)
- ✅ `cpu-skip-y` mechanism for platform driver substitution
- ✅ `drv-objs-y` opt-in for shared drivers (ARMv7 uses them; RISC-V/AArch64 skip them)
- ✅ `UOS_LDSCRIPT` override per platform
- ✅ `UOS_CPU` override per platform (zybo → cortex-a9)
- ✅ `clean` per-target, `clean-all` for everything

---

## What the "60–70% kernel-core / 5–10% system-software" Verdict Means

### ✅ What EXISTS (~60–70% of kernel core)

1. Boot + MMU + exception handling (ARMv7 + RISC-V proven)
2. Cooperative + preemptive scheduler with ARINC 653 time partitions
3. ARINC 653 IPC: sampling ports, queuing ports, shared memory, events
4. seL4-style capability system with derivation tree (MDB)
5. 3-tier health monitoring (PAC/MultiMAC/ModuleMAC)
6. PV guest ABI (hypercall path 0xA0–0xAF)
7. PikeOS-class syscalls (task lifecycle, TLS, ExRegs, attributes)
8. Full device driver suite (PCI/PCIe, USB EHCI, block, network, GPIO, I2C, SPI)
9. VMIT XML configuration parser

### ❌ What's MISSING (~5–10% system software + ~30% kernel features)

1. **No hardware-assisted virtualization** — no Stage-2 (VTTBR), no GICv3 VGIC, no vCPU ERET
2. **No personalities** — no APEX/POSIX/Linux/Ada/Android SSW partitions
3. **No host tooling** — no Eclipse integration, no VMIT IDE, no debugger stubs
4. **No certified file systems** (PikeOS ships DDC-I Deos FS, FATFS, JFFS2)
5. **No network stack** (PikeOS ships lwIP, a full TCP/IP personality)
6. **No AArch64 subsystems** beyond boot+MMU (the MP1–MP5 gap)
7. **No real Linux guest boot** — the PV ABI exists but no actual kernel loading path

---

## Immediate Blockers

| # | Blocker | Impact | Fix |
|---|---------|--------|-----|
| 1 | `fdt_reader.h` missing | AArch64 build broken | Create a minimal FDT reader, or remove the `#include` if DTB parsing isn't needed yet |
| 2 | ARMv7 linker warning: `cannot find entry symbol _start` | Boot entry might be wrong | Add `ENTRY(_start)` to [linker.ld](file:///home/fabiorafaelcoutada/portugalfuturista/universalisos/kernel/src/arch/armv7/linker.ld) or rename the entry symbol |
| 3 | 20 MB BSS in ARMv7 build | Huge ELF, wastes QEMU RAM | Reduce static allocations (e.g. `vm_page_tables[16][4096]` in mm.cpp) |