universalisos/docs/arch_stubs_implementation_plan.md

Architecture Stubs Implementation Plan

This implementation plan identifies the existing stubs across the primary supported architectures: ARMv7, AArch64 / ARMv8, and RISC-V, outlining what is needed to complete these development phases.

Note

Per your instructions, Apple Silicon (M1) research code and the associated linux_stub payloads have been excluded from the AArch64 analysis.

User Review Required

Please review the identified stubs below and confirm if any specific category or architecture should be prioritized for implementation first. Once approved, we will break these down into concrete tasks.

---

Proposed Changes / Identified Stubs

1. ARMv7 (kernel/src/arch/armv7/)

The ARMv7 architecture contains several foundational memory management and exception handling stubs that need to be fully implemented.

• exceptions.cpp:
  • FIQ Handling: Platform-specific Fast Interrupt Request (FIQ) handling is currently marked as TODO.
• uos_cmm.cpp:
  • MMU Initialization: Contains link-stubs for uos_arm_init_mmu and _activate_mmu.
  • Page Table Setup: Writing to TTBR0/TTBR1, setting TTBCR=1, DACR=0x55555555, and executing TLBIALL is marked as a TODO D-1.3.
  • PSP Initialization: Contains a PSP (Processor State Parameter) init stub which needs its real body populated from UART, timer, and board halt signals.

2. AArch64 / ARMv8 (kernel/src/arch/aarch64/)

Excluding the Apple Silicon M1-specific payloads (guest_payload/, apple/, linux_stub), the mainline AArch64 hypervisor code contains the following stubs:

• context_switch.S:
  • Exception Vectors: Mentions that x0 itself is saved by the caller (the exception vector stub) before the branch, which indicates the exception vectors might currently be stubbed or rely on a minimal shim.
• el2_guest.cpp:
  • MMIO Emulation: The MMIO path contains a minimal probe-compatible stub for EL2 guest support that needs expansion for proper guest device emulation.
• kernel_aarch64.cpp & virtio_blk.cpp:
  • VBAR / Guest Booting: Currently references a stub payload supplying its own VBAR_EL1. This needs to be transitioned to adopt a real Image loaded by QEMU rather than relying on a standalone stub.

3. RISC-V (kernel/src/arch/riscv/)

The RISC-V architecture implementation has several features related to partition management and memory that are stubbed out.

• hm.cpp (Health Monitor):
  • Partition Control: The logic to stop partition and restart partition is marked as TODO.
• vm.cpp (Virtual Memory):
  • Memory Management: Both demand paging and MMIO emulation are marked as TODO and require full implementations to support advanced guest operating systems.
• guest_loader.cpp:
  • ELF Parsing: ELF parsing is explicitly noted as not implemented in this layer, meaning the hypervisor cannot currently parse and load standard ELF guests on RISC-V without relying on external payloads or flat binaries.

Verification Plan

Automated Tests

• Build verification for each architecture using existing Make targets (make ARCH=armv7, make ARCH=aarch64, make ARCH=riscv).
• Since there is no unit-test framework, verification relies heavily on successful compilation without linker errors.

Manual Verification

• Boot the generated binaries in QEMU (e.g., qemu-system-arm, qemu-system-aarch64, qemu-system-riscv64) according to the AGENTS.md verification workflow.
• Validate that the newly implemented subsystems (e.g., MMU for ARMv7, MMIO for RISC-V/AArch64) correctly output to UART and progress past their previous stubbed states without hanging or faulting.