portugalfuturista/universalisos
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
universalisos/.hermes/plans/2025-07-10_223000-aarch64-pv-hypercall-abi.md

2.5 KiB
Raw Permalink Blame History

AArch64 Paravirtual Hypercall ABI

Goal: Define a PikeOS-style paravirtual hypercall ABI for AArch64 guests and dispatch it from the EL2 sync handler. Replace the ad-hoc HVC magic numbers (0xC0DE0001 putc, 0xBEEF vtimer-ack, 0xC0DE0002 park) with a numbered uos_hv_* ABI the guest calls through HVC #imm with x0=call number.

Why: The current guest uses hardcoded magic numbers. A numbered ABI matches PikeOS's P4_SYSCALL hypercall model and is the contract future guest OS ports (Linux, RTOS) will use. Same shape as the ARMv7 PV ABI (0xA0–0xAF range).

Files:

  • Create: kernel/src/arch/aarch64/inc/uos_hv_abi.h — the ABI contract (call numbers, args, return codes)
  • Modify: kernel/src/arch/aarch64/el2_guest.cpp — dispatch EC_HVC_AA64 by x0 call number
  • Modify: kernel/src/arch/aarch64/guest_payload/guest_payload.S — use the new ABI
  • Modify: kernel/src/arch/aarch64/guest_payload/guest.ld (if exists) — ensure payload layout unchanged

ABI:

Call x0 Args Return Description
UOS_HV_PUTC 0x00 x1 = char x0 = 0 Write one byte to HV console
UOS_HV_PUTS 0x01 x1 = IPA of NUL-terminated string x0 = bytes written Write string (HV reads guest IPA)
UOS_HV_GETTIME 0x02 — x0 = ticks (CNTPCT) Read physical counter
UOS_HV_YIELD 0x03 — x0 = 0 Hint: yield vCPU (no-op for now)
UOS_HV_SHUTDOWN 0x04 — no return Park vCPU
UOS_HV_ACK_VTIMER 0x05 — x0 = 0 Acknowledge injected vTimer vIRQ

HVC convention: HVC #imm with imm = 0x550S (='UOS'), x0 = call number. ELR_EL2 already points past the HVC, so the handler just resumes.

Step-by-step:

  1. Write uos_hv_abi.h with the call number enum + return codes + guest inline helpers (uos_hv_putc, etc.).
  2. Rewrite el2_guest.cpp HVC dispatch: switch on x0; for each call fill frame->x[0] with the return code and advance nothing (ELR already past HVC). Keep the PL011 emulation path unchanged.
  3. Rewrite guest_payload.S: use UOS_HV_PUTC for "G!\n", UOS_HV_GETTIME to read ticks, UOS_HV_ACK_VTIMER for the vtimer ack, UOS_HV_SHUTDOWN to park.
  4. Rebuild payload, rebuild kernel, boot -smp 4, verify the same "G!\n" + vtimer-ack + park sequence but driven by the new ABI.

Verification:

  • make ARCH=aarch64 PLATFORM=qemu-aarch64-virt clean
  • Boot shows "[hv] putc 'G'", "[hv] putc '!'", "[hv] putc '\n'" (or the guest string via PUTS), "[hv] ack_vtimer", "[hv] shutdown" — no raw "HVC from EL1, x0=..." lines.
  • ARMv7 unchanged.