universalisos/.hermes/plans/2025-07-10_224500-aarch64-guest-c-runtime.md

AArch64 Guest-Side C Runtime

Goal: Convert the AArch64 guest payload from hand-written assembly to a real freestanding C program that links against uos_hv_abi.h, proving the guest-side inline helpers compile and work, and laying the foundation for richer guests (tiny RTOS, eventually Linux usermode-style payloads).

Why: The current payload is ~100 lines of asm. To write a guest that does IPC, scheduling, or device I/O, we need C. The uos_hv_abi.h already ships guest-side inline helpers (uos_hv_putc/puts/gettime/shutdown/ack_vtimer); this phase wires them into a buildable C guest with a minimal vector table + crt0.

Files:

• Create: kernel/src/arch/aarch64/guest_payload/crt0.S — minimal EL1 vector table + entry that calls guest_main()
• Create: kernel/src/arch/aarch64/guest_payload/guest_main.c — the C guest (puts/gettime/vtimer/shutdown via the ABI)
• Modify: kernel/src/arch/aarch64/guest_payload/linker.ld — set entry to guest_crt0, place .rodata for the string
• Modify: kernel/src/arch/aarch64/guest_payload/Makefile — compile crt0.S + guest_main.c, link
• Delete: kernel/src/arch/aarch64/guest_payload/guest_payload.S (superseded)

C guest behavior (parity with the asm payload):

1. uos_hv_puts("guest C runtime online\n")
2. print the value from uos_hv_gettime() formatted via a tiny itoa (proves GETTIME returns the physical counter)
3. arm CNTV for ~10 ms, unmask IRQs, wfi loop
4. guest_irq_handler() (C): disable CNTV, uos_hv_ack_vtimer(), EOI INTID 27, then uos_hv_shutdown()

crt0.S:

• 2 KiB vector table (16 slots); slot 0x200 = guest_main, slot 0x280 = guest_irq_handler
• guest_crt0: set SP to top of guest RAM (0x60000000), zero BSS, bl guest_main, then wfe loop if it returns.

Verification:

• make ARCH=aarch64 PLATFORM=qemu-aarch64-virt clean (rebuilds payload + kernel)
• -smp 4 boot shows "guest C runtime online", a non-zero tick count, "[hv] guest shutdown", interleaved A/B
• ARMv7 build clean