CPU Architectures

x86_64, AArch64, and RISC-V 64 support through the Hardware Abstraction Layer.

Documentation

Architecture Comparison

Helix supports three CPU architectures. Each has a complete HAL backend in hal/src/<arch>/:

Featurex86_64AArch64RISC-V 64
Targetx86_64-unknown-noneaarch64-unknown-noneriscv64gc-unknown-none-elf
Source files~60~35~30
Estimated lines~25,000~14,000~12,000
MaturityPrimary — most testedSecondaryExperimental
Page table4-level (PML4)4-level (4KB granule)Sv39/48/57
Interrupt ctrlAPIC (Local + I/O)GICv2 / GICv3CLINT + PLIC
TimerTSC / HPET / APICGeneric TimerSBI Timer
SMP startupINIT-SIPI-SIPIPSCISBI HSM
SerialCOM1 (0x3F8)PL011 UARTSBI Console
KASLR entropyRDRAND / RDSEEDTimer jitterTimer jitter
FirmwareACPI / UEFIACPI / DeviceTreeDeviceTree / SBI
Boot protocolsLimine, Multiboot2, UEFIUEFI, DeviceTreeSBI, DeviceTree

x86_64

The x86_64 backend is the most complete and heavily tested architecture.

File Structure

x86_64 — Source Tree13N · 12E
▶hal/src/x86_64/x86_64 HAL backend12mod.rsX86_64Hal — root Hal…1cpu.rsMSR, control registe…1gdt.rsGlobal Descriptor Ta…1idt.rsIDT — 256 vectors1tss.rsTask State Segment —…1pic.rsLegacy 8259 PIC — 16…1apic.rsLocal APIC + I/O API…1paging.rs4-level page tables …1serial.rs16550 UART — COM1/CO…1smp.rsINIT-SIPI-SIPI proto…1boot.rsx86_64 early boot1timer/Timer subsystem1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Privilege Rings

x86_64 — Privilege Rings4N · 3E
▶Ring 0Kernel code (full ac…1Ring 1(unused)2Ring 2(unused)2■Ring 3User processes (rest…1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Helix uses only Ring 0 and Ring 3. The transition between rings happens via syscall/sysret instructions (fast path) or int 0x80/iret (legacy path).

GDT Layout

IndexSelectorDescription
00x00Null descriptor
10x08Kernel code (64-bit, Ring 0)
20x10Kernel data (Ring 0)
30x18User code (64-bit, Ring 3)
40x20User data (Ring 3)
50x28TSS descriptor (16 bytes)

IDT Vectors

RangeTypeDescription
0-31CPU ExceptionsDivision error, page fault, GPF, double fault, etc.
32-47PIC IRQsLegacy: keyboard, timer, serial, disk, etc.
48-255APICI/O APIC IRQs, IPIs, MSI, spurious

Key exception vectors:

VectorNameNotes
0#DE Divide ErrorInteger division by zero
6#UD Invalid OpcodeUndefined instruction
8#DF Double FaultException during exception handling — IST1 stack
13#GP General ProtectionSegment violation, privilege error
14#PF Page FaultMemory access violation — CR2 has faulting address

Page Table Structure

x86_64 — Page Table Structure7N · 6E
huge page▶CR3Page Table Base Regi…1PML4512 entries, 256 TB …2PDPT512 entries, 512 GB …2PD512 entries, 1 GB ea…3PT512 entries, 4 KB ea…2■Physical Frame4 KB page1■Huge Page (2 MB)Direct 2 MB mapping1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

APIC Architecture

x86_64 — APIC Architecture6N · 5E
Local APIC (CPU 0)Per-CPU interrupt co…1Local APIC (CPU 1)Per-CPU interrupt co…1Local APIC (CPU 2)Per-CPU interrupt co…1APIC BusInterconnect4I/O APIC24 IRQs2■External DevicesHardware IRQ sources1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Timer Selection Priority

  1. TSC — if invariant_tsc CPUID flag is present (preferred — ~1ns, per-core)
  2. HPET — if ACPI HPET table exists (100ns, system-wide)
  3. APIC Timer — calibrated against PIT/HPET (per-core, configurable)
  4. PIT — fallback (838ns, single channel, legacy)

AArch64

The AArch64 (ARM 64-bit) backend targets modern ARM server and embedded platforms.

File Structure

AArch64 — Source Tree10N · 9E
▶hal/src/aarch64/AArch64 HAL backend9mod.rsAArch64Hal — root Ha…1cpu.rsSystem registers, EL…1gic_v2.rsGICv2 — Distributor …1gic_v3.rsGICv3 — ITS, LPI, af…1mmu.rs4-level page tables …1timer.rsGeneric Timer — CNTP…1smp.rsPSCI-based AP startu…1exception.rsException vector tab…1boot.rsAArch64 early boot1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Exception Levels

AArch64 — Exception Levels4N · 3E
▶EL3Secure Monitor (Trus…1EL2Hypervisor (virtuali…2EL1Kernel (Helix runs h…2■EL0User processes1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Helix runs at EL1. EL2 and EL3 are managed by firmware (if present).

Exception Vector Table

AArch64 has 16 exception vectors organized in a 4x4 table:

FromSyncIRQFIQSError
Current EL, SP_EL00x0000x0800x1000x180
Current EL, SP_ELx0x2000x2800x3000x380
Lower EL, AArch640x4000x4800x5000x580
Lower EL, AArch320x6000x6800x7000x780

GIC Architecture

AArch64 — GIC Architecture (v3)5N · 4E
CPU 0 (Redistributor + CPU Intf)Per-CPU interrupt de…1CPU 1 (Redistributor + CPU Intf)Per-CPU interrupt de…1GIC DistributorIRQ routing3ITSInterrupt Translatio…2■External DevicesSPI, PPI, LPI, SGI1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Interrupt Types

TypeRangeDescription
SGI0-15Software Generated Interrupt (IPI)
PPI16-31Private Peripheral Interrupt (per-core timer, PMU)
SPI32-1019Shared Peripheral Interrupt (external devices)
LPI8192+Locality-specific (GICv3 ITS, MSI)

Page Table (4KB Granule)

AArch64 — Page Table (4KB Granule)6N · 5E
▶TTBR0 / TTBR1Page table base1Level 0512 entries, 512 GB …2Level 1512 entries, 1 GB ea…2Level 2512 entries, 2 MB ea…2Level 3512 entries, 4 KB ea…2■Physical Page4 KB1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

AArch64 uses two page table base registers:

  • TTBR0_EL1: Lower half (user space, 0x0000...)
  • TTBR1_EL1: Upper half (kernel space, 0xFFFF...)

RISC-V 64

The RISC-V backend targets the open RISC-V 64-bit ISA with GC (general + compressed) extensions.

File Structure

RISC-V — Source Tree10N · 9E
▶hal/src/riscv64/RISC-V HAL backend9mod.rsRiscv64Hal — root Ha…1cpu.rsCSR access, privileg…1clint.rsCore Local Interrupt…1plic.rsPlatform-Level Inter…1mmu.rsSv39/Sv48/Sv57 page …1timer.rsSBI timer extension1smp.rsSBI HSM hart managem…1trap.rsTrap handler (sync +…1boot.rsRISC-V early boot1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Privilege Modes

RISC-V — Privilege Modes3N · 2E
ecallsret▶M-modeMachine (firmware, S…1S-modeSupervisor (Helix ke…2■U-modeUser (applications)1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

Helix runs in S-mode and communicates with M-mode firmware via the SBI (Supervisor Binary Interface).

CSR (Control and Status Registers)

CSRNamePurpose
sstatusStatusInterrupt enable, previous privilege
sieInterrupt EnableEnable timer, external, software interrupts
sipInterrupt PendingPending interrupt bits
stvecTrap VectorTrap handler address
sscratchScratchPer-hart scratch register
sepcException PCPC at time of exception
scauseCauseException/interrupt cause code
stvalTrap ValueFaulting address or instruction
satpAddress TranslationPage table base + ASID + mode (Sv39/48/57)

Page Table Modes

ModeLevelsVirtual BitsAddress Space
Sv39339 bits512 GB
Sv48448 bits256 TB
Sv57557 bits128 PB

Helix uses Sv39 by default (sufficient for most use cases) with Sv48 as an option for large-memory systems.

Sv39 Page Table

RISC-V — Sv39 Page Table5N · 4E
▶satpAddress Translation …1Level 2512 entries, 1 GB ea…2Level 1512 entries, 2 MB ea…2Level 0512 entries, 4 KB ea…2■Physical Page4 KB1
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

PLIC Architecture

RISC-V — PLIC Architecture7N · 6E
▶External IRQ Sources1..1023 interrupt so…1Priority RegistersPer-source priority …2Pending BitsBitmap of pending IR…2Enable BitsPer-hart enable mask2Threshold + ClaimPer-hart priority th…3■Hart 0 (S-mode)CPU context 01■Hart 1 (S-mode)CPU context 11
100%
☝ Drag to pan·🤏 Pinch to zoom·Tap a node

SBI Interface

The Supervisor Binary Interface provides standardized firmware calls:

ExtensionEIDFunctions
Timer0x54494D45set_timer(deadline)
Console0x4442434Eputchar(c), getchar()
HSM0x48534Dhart_start, hart_stop, hart_get_status
IPI0x735049send_ipi(hart_mask)
RFENCE0x52464E43remote_sfence_vma(hart_mask, addr, size)

SBI calls use the ecall instruction with a7 = extension_id and a6 = function_id.

HAL Trait Unification

Despite vastly different hardware, all three architectures present the same interface to the kernel through the HAL traits.

Abstraction Boundaries

Conceptx86_64AArch64RISC-V
Enable interruptsstiMSR DAIF, #0csrsi sstatus, SIE
Disable interruptscliMSR DAIF, #0xFcsrci sstatus, SIE
Halthltwfiwfi
Page table switchWrite CR3Write TTBR0/1_EL1Write satp + sfence.vma
TLB flush (single)invlpgTLBI VAE1sfence.vma addr
TLB flush (all)Reload CR3TLBI VMALLE1sfence.vma
IPIAPIC writeGIC SGISBI send_ipi
Timer readrdtscMRS CNTPCT_EL0rdtime

Adding a New Architecture

To port Helix to a new architecture:

  1. Create hal/src/<arch>/mod.rs implementing HalImpl
  2. Implement CpuHal, InterruptHal, MmuHal, TimerHal
  3. Add a linker script in profiles/<arch>/linker.ld
  4. Add the target triple to rust-toolchain.toml
  5. Create a boot entry point (_start or equivalent)
  6. Add #[cfg(target_arch = "<arch>")] guards to the HAL root

The rest of the kernel (core, subsystems, modules, filesystem) requires zero changes — it programs against the HAL traits, not the concrete implementation.