universalisos/UNIVERSALISOS_FIX_DOCUMENT.md

UniversalisOS Fix Document

Generated by: Mycelium RL Loop (Aurelio Agent) Date: $(date) Status: Ready for implementation

---

Executive Summary

The Mycelium RL loop tested UniversalisOS across 5 architectures. 3 boot successfully on QEMU, 1 builds but needs GRUB/UEFI setup, and 1 is missing critical build files. This document describes all bugs found and how to fix them.

---

Architecture Status

Architecture	Build	QEMU Boot	Priority
ARMv7	✅	✅	—
AArch64	✅	✅	—
RISC-V	✅	✅	—
x86_64	✅	⚠️	Medium
PowerPC E500	❌	❌	High

---

Bug #1: x86_64 Scheduler — ARM-style Register Names

File: src/core/scheduler.cpp Lines: 985-1010 Severity: Build-breaking (x86_64 cannot compile)

Problem

The shared scheduler code uses ARM-style register names (pc, sp, lr) which don't exist in x86_64's task_context_t (which has rip, rsp, no lr).

// BROKEN: x86_64 has no 'lr' member
uint32_t uos_task_get_lr(uos_task_id_t id) {
    task_t* t = task_get_by_id(id);
    return t ? t->context.lr : 0;  // ERROR: no 'lr' on x86_64
}

Fix

Add #ifdef guards for architecture-specific register access:

#if defined(ARCH_X86_64)
uint64_t uos_task_get_pc(uos_task_id_t id) {
    task_t* t = task_get_by_id(id);
    return t ? t->context.rip : 0;
}
uint64_t uos_task_get_sp(uos_task_id_t id) {
    task_t* t = task_get_by_id(id);
    return t ? t->context.rsp : 0;
}
uint64_t uos_task_get_lr(uos_task_id_t id) {
    task_t* t = task_get_by_id(id);
    return t ? t->context.rip : 0; // x86_64: no LR, use RIP
}
void uos_task_set_regs(uos_task_id_t id, uint64_t pc, uint64_t sp, uint64_t lr) {
    task_t* t = task_get_by_id(id);
    if (t) {
        t->context.rip = pc;
        t->context.rsp = sp;
        // x86_64: lr parameter ignored
    }
}
#else
// ARM/RISC-V: existing code
uint32_t uos_task_get_pc(uos_task_id_t id) {
    task_t* t = task_get_by_id(id);
    return t ? t->context.pc : 0;
}
// ... etc
#endif

Status

Partially fixed — The lr and set_regs functions were fixed, but get_pc and get_sp may still need attention for x86_64 return types.

---

Bug #2: PowerPC Missing arch.mk

File: src/arch/ppc_e500/arch.mk Severity: Build-breaking (PowerPC cannot compile)

Problem

The PowerPC E500 architecture port is missing arch.mk, which the Makefile requires to set compiler flags and object lists.

Fix

Create src/arch/ppc_e500/arch.mk:

# PowerPC E500 architecture — MPC8544DS
ARCH_SUB ?= e500mc

CROSS_COMPILE ?= powerpc-linux-gnu-

arch-cppflags = -mcpu=e500mc -DARCH_PPC_E500
arch-cflags = -mno-sdata -ffixed-r2
arch-asflags =
arch-ldflags = -T $(SRC_DIR)/arch/ppc_e500/linker.ld
arch-ldlibs = /usr/lib/gcc/powerpc-linux-gnu/13/libgcc.a

# Core objects
core-objs-y := uos_elf.cpp
core-objs-y += adt/rbtree.c
core-objs-y += mm/physmem.c

# Platform objects
plat-objs-y := platform/$(PLATFORM)/boot.o

Also create src/arch/ppc_e500/linker.ld:

/* PowerPC E500 linker script */
ENTRY(_start)
MEMORY
{
    RAM (rwx) : ORIGIN = 0x0, LENGTH = 256M
}
SECTIONS
{
    .text : {
        *(.text.startup)
        *(.text .text.*) 
    } > RAM
    .rodata : { *(.rodata .rodata.*) } > RAM
    .data : { *(.data .data.*) } > RAM
    .bss : { *(.bss .bss.*) *(COMMON) } > RAM
}

Prerequisites

• powerpc-linux-gnu-gcc cross-compiler installed
• QEMU mpc8544ds machine available

---

Bug #3: RISC-V SMP UART Race Condition

File: src/arch/riscv/uart.cpp (or platform UART driver) Severity: Non-critical (output garbled, system works)

Problem

When running with 5 harts on QEMU Icicle Kit, multiple harts write to the UART simultaneously, causing garbled output (ABBA pattern).

Evidence

UniversalisOS RISC-V 64-bit hypervisor booted (Icicle Kit).
=== RISC-V Subsystem Tests ===
[OK] Sv39 page table map
[OK] p4map-style aspace map
[OK] Partition 0 create
[OK] Partition 1 create
=[[[=HHH=MMM ]]R]  Ie evvSeeevCnne-ttVn== 55tE  =xll5ceee vvleepllet==vi66oe  nlpp...

Fix

Add a spinlock to the UART output function:

// In uart.cpp or platform UART driver
static volatile int uart_lock = 0;

void uart_puts(const char* str) {
    while (__sync_lock_test_and_set(&uart_lock, 1) != 0) {
        // spin
    }
    while (*str) {
        uart_putc(*str++);
    }
    __sync_lock_release(&uart_lock);
}

Status

Found, not yet fixed. Affects both RISC-V and AArch64 SMP output.

---

Bug #4: AArch64 EL2 Trap During Guest Execution

File: src/arch/aarch64/el2_trap.cpp Severity: Non-critical (guest runs, trap is handled)

Problem

During AArch64 QEMU test, an EL2 trap occurs during guest execution:

### EL2 TRAP ### ESR=0x000000003A000000 PC=0x00000000500008C0

Analysis

ESR 0x3A000000 = Data Abort from current EL. The guest is trying to access a memory address that triggers a stage-2 page fault. This is likely a guest OS issue, not a hypervisor bug.

Fix

Not needed — this is expected behavior when the guest accesses unmapped memory. The hypervisor correctly traps and handles it.

---

Bug #5: x86_64 QEMU Boot Requires GRUB/OVMF

File: Makefile, src/arch/x86_64/boot.S Severity: Medium (builds, can't boot on QEMU)

Problem

x86_64 builds successfully but QEMU's -kernel flag requires a multiboot-compatible image or Linux bzImage. The UniversalisOS x86_64 kernel uses multiboot2 but QEMU doesn't load it directly.

Fix

Option A: Use GRUB with OVMF

# Create bootable ISO
grub-mkrescue -o universalisos-x86_64.iso \
    -boot-load-size 4 -boot-info-table \
    --modules="part_gpt fat ext2 multiboot2" \
    boot/

# Run QEMU
qemu-system-x86_64 -M q35 -m 512M -cdrom universalisos-x86_64.iso

Option B: Use direct multiboot loading

qemu-system-x86_64 -M q35 -m 512M \
    -kernel build/x86_64/qemu-x86_64-virt/universalisos.elf \
    -append "console=ttyS0,115200"

---

Implementation Priority

Bug	Priority	Effort	Assigned
#1 x86_64 scheduler	High	30 min	—
#2 PowerPC arch.mk	High	1 hour	—
#3 RISC-V UART lock	Medium	30 min	—
#4 AArch64 EL2 trap	Low	—	—
#5 x86_64 QEMU boot	Medium	1 hour	—

---

Testing After Fixes

# Build all architectures
cd kernel
make ARCH=armv7 PLATFORM=qemu-arm-virt clean all
make ARCH=aarch64 PLATFORM=qemu-aarch64-virt clean all
make ARCH=riscv PLATFORM=qemu-riscv-virt clean all
make ARCH=x86_64 PLATFORM=qemu-x86_64-virt clean all

# Test all on QEMU
make test-armv7
make test-aarch64
make test-riscv
# x86_64: requires GRUB setup

# Mycelium RL loop
cd /path/to/mycelium
./target/debug/mycelium universalisos --target=all --verify

---

Notes

• The x86_64 scheduler fix is partially applied (in the mycelium session). Check if it was committed to UniversalisOS.
• PowerPC requires powerpc-linux-gnu-gcc cross-compiler. Install with: apt install gcc-powerpc-linux-gnu
• The RISC-V UART lock should use the same pattern as ARM's UART driver.
• The AArch64 EL2 trap is expected behavior — no fix needed.

---

This document was generated by the Mycelium RL Loop (Aurelio Agent) on $(date). Fixes should be committed to UniversalisOS, not Mycelium.