Platform and Hardware Layer

This section documents the code that sits between the axiomOS kernel core (scheduler, memory manager, BPF runtime) and physical or emulated hardware: CPU architecture support, interrupt controllers, boards, and device drivers.

Supported targets

Support tiers come from ADR-0003  (accepted 2026-07-14, marked source-of-truth) and are mirrored in ci/manifests/targets.toml.

“Supported after HIL” means the target is not considered supported until the hardware-in-the-loop evidence listed in the ADR exists. The hardware runbook (hardware-validation-and-benchmarking.md ) states that it does not authorize a safety-relevant robot deployment and that QEMU or RTL simulation numbers must not be turned into physical timing or safety claims.

RISC-V status

The main kernel supports only x86_64 and AArch64. Per ADR-0003, the alternate RISC-V manifest, entrypoints, linker, feature, null allocator and a dormant architecture module were retired from the main kernel. The only RISC-V artifact is kernel/demos/riscv, a standalone demo whose README lists boot assembly, OpenSBI console calls, DTB address capture, a linker script, hart ID handling and BSS clearing. It lives outside the production kernel and release artifact. A required CI check named target-boundary-static rejects drift back into the main kernel.

Layer overview

The architecture-neutral code in kernel/src calls into one architecture module selected by cfg(target_arch). On AArch64 a second axis, the board, is selected by Cargo features: rpi5 or virt (both imply aarch64_arch).

The Architecture trait

kernel/src/arch/traits.rs defines the contract:

pub trait Architecture {
    fn early_init();
    fn init();
    fn enable_interrupts();
    fn disable_interrupts();
    fn are_interrupts_enabled() -> bool;
    fn wait_for_interrupt();
    fn shutdown() -> !;
    fn reboot() -> !;
}

The same file defines TaskContext (stack pointer, instruction pointer and an ArchState), where ArchState is per-architecture:

Implementation status of the trait differs between architectures:

• AArch64 implements Architecture for the Aarch64 struct (aarch64/mod.rs): early_init installs the exception vector table; init runs memory initialization, GIC and timer initialization, and syscall setup; interrupt masking uses daifset/daifclr; shutdown and reboot go through PSCI.
• x86_64 does not implement the trait on a struct. arch/x86_64.rs re-exports free functions (shutdown, shootdown_tlb, handle_tlb_shootdown_ipi), and kernel::init calls mem::init, acpi::init, apic::init, hpet::init directly under cfg(target_arch = "x86_64"). Its shutdown writes to the QEMU debug-exit port 0xf4 and then halts, so it is an emulator-oriented shutdown, not an ACPI power-off.

Both architectures export a UserContext type and a restore_user_context function from arch/mod.rs; AArch64’s UserContext wraps an ExceptionContext plus sp.

Boot and initialization order

kernel::init in kernel/src/lib.rs is shared; the architecture-specific steps are:

Page map