feat: enable hyperlight-host compilation for aarch64 (#1285)

* refactor: move regs submodules into x86_64 subdirectory

Move debug_regs, fpu, special_regs, and standard_regs into
regs/x86_64/ and re-export through a new x86_64/mod.rs.
Update regs.rs to delegate to the x86_64 submodule.

This prepares the regs module for architecture-specific
register definitions.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* refactor: move kvm.rs and mshv.rs into subdirectories

Move kvm.rs → kvm/x86_64.rs and mshv.rs → mshv/x86_64.rs,
adding mod.rs files that re-export through the x86_64 submodule.

This prepares the virtual machine backends for
architecture-specific implementations.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* refactor: convert hyperlight_vm.rs to module directory

Rename hyperlight_vm.rs → hyperlight_vm/mod.rs with no
content changes. This prepares for splitting architecture-
specific code into separate submodules.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* refactor: split hyperlight_vm into shared and x86_64-specific code

Extract x86_64-specific methods (new, initialise,
dispatch_call_from_host, reset_vcpu, get_root_pt,
get_snapshot_sregs, handle_debug, crashdump_context)
and the debug submodule into hyperlight_vm/x86_64.rs.

Keep shared code in mod.rs: struct definition, error types,
helper functions, and architecture-independent methods
(map_region, unmap_region, run, handle_io, etc.).

Struct fields changed from private to pub(super) so the
x86_64 submodule can access them.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* feat: enable hyperlight-host cross-compilation for aarch64

Add conditional compilation gates and aarch64 stub modules so
that cargo build --target aarch64-unknown-linux-gnu -p
hyperlight-host succeeds.

No aarch64 implementation is added. All aarch64 code paths
are stubs that panic at runtime.

Changes:
- Add aarch64 register stub types (CommonRegisters, etc.)
- Add aarch64 KVM and MSHV backend stubs
- Add aarch64 HyperlightVm method stubs (new, initialise, etc.)
- Add aarch64 layout and vmem stubs in hyperlight_common
- Gate VmExit::Debug fields with target_arch
- Add hv_arm64_memory_intercept_message support
- Update Cargo.toml dependencies for aarch64
- Update build.rs cfg aliases for aarch64

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* refactor: move error types before struct in hyperlight_vm

Move all error type definitions (DispatchGuestCallError,
InitializeError, RunVmError, etc.) above the HyperlightVm
struct definition to group related error types together.

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

---------

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Author: ludfjig

src/hyperlight_common/src/arch/aarch64/layout.rs

@@ -0,0 +1,25 @@
+/*
+Copyright 2025  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+ */
+
+// TODO(aarch64): change these, they are only provided in order to compile
+pub const MAX_GVA: usize = 0xffff_ffff_ffff_efff;
+pub const SNAPSHOT_PT_GVA_MIN: usize = 0xffff_8000_0000_0000;
+pub const SNAPSHOT_PT_GVA_MAX: usize = 0xffff_80ff_ffff_ffff;
+pub const MAX_GPA: usize = 0x0000_000f_ffff_ffff;
+
+pub fn min_scratch_size(_input_data_size: usize, _output_data_size: usize) -> usize {
+    unimplemented!("min_scratch_size")
+}

src/hyperlight_common/src/arch/aarch64/vmem.rs

@@ -0,0 +1,52 @@
+/*
+Copyright 2025  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+ */
+
+// TODO(aarch64): implement real page table operations
+
+use crate::vmem::{Mapping, TableOps, TableReadOps, Void};
+
+pub const PAGE_SIZE: usize = 4096;
+pub const PAGE_TABLE_SIZE: usize = 4096;
+pub type PageTableEntry = u64;
+pub type VirtAddr = u64;
+pub type PhysAddr = u64;
+
+/// # Safety
+/// See `TableOps` documentation.
+#[allow(clippy::missing_safety_doc)]
+pub unsafe fn map<Op: TableOps>(_op: &Op, _mapping: Mapping) {
+    unimplemented!("map")
+}
+
+/// # Safety
+/// See `TableReadOps` documentation.
+#[allow(clippy::missing_safety_doc)]
+pub unsafe fn virt_to_phys<'a, Op: TableReadOps + 'a>(
+    _op: impl core::convert::AsRef<Op> + Copy + 'a,
+    _address: u64,
+    _len: u64,
+) -> impl Iterator<Item = Mapping> + 'a {
+    unimplemented!("virt_to_phys");
+    #[allow(unreachable_code)]
+    core::iter::empty()
+}
+
+pub trait TableMovability<Op: TableReadOps + ?Sized, TableMoveInfo> {}
+impl<Op: TableOps<TableMovability = crate::vmem::MayMoveTable>> TableMovability<Op, Op::TableAddr>
+    for crate::vmem::MayMoveTable
+{
+}
+impl<Op: TableReadOps> TableMovability<Op, Void> for crate::vmem::MayNotMoveTable {}

src/hyperlight_common/src/layout.rs

@@ -23,10 +23,14 @@ limitations under the License.
     all(target_arch = "x86_64", feature = "nanvix-unstable"),
     path = "arch/i686/layout.rs"
 )]
+#[cfg_attr(target_arch = "aarch64", path = "arch/aarch64/layout.rs")]
 mod arch;
 
 pub use arch::{MAX_GPA, MAX_GVA};
-#[cfg(all(target_arch = "x86_64", not(feature = "nanvix-unstable")))]
+#[cfg(any(
+    all(target_arch = "x86_64", not(feature = "nanvix-unstable")),
+    target_arch = "aarch64"
+))]
 pub use arch::{SNAPSHOT_PT_GVA_MAX, SNAPSHOT_PT_GVA_MIN};
 
 // offsets down from the top of scratch memory for various things

src/hyperlight_common/src/vmem.rs

@@ -16,6 +16,7 @@ limitations under the License.
 
 #[cfg_attr(target_arch = "x86_64", path = "arch/amd64/vmem.rs")]
 #[cfg_attr(target_arch = "x86", path = "arch/i686/vmem.rs")]
+#[cfg_attr(target_arch = "aarch64", path = "arch/aarch64/vmem.rs")]
 mod arch;
 
 /// This is always the page size that the /guest/ is being compiled

src/hyperlight_host/Cargo.toml

@@ -49,7 +49,7 @@ chrono = { version = "0.4", optional = true }
 anyhow = "1.0"
 metrics = "0.24.3"
 serde_json = "1.0"
-elfcore = "2.0"
+elfcore = { version = "2.0", optional = true }
 uuid = { version = "1.22.0", features = ["v4"] }
 
 [target.'cfg(windows)'.dependencies]
@@ -128,7 +128,7 @@ executable_heap = []
 # This feature enables printing of debug information to stdout in debug builds
 print_debug = []
 # Dumps the VM state to a file on unexpected errors or crashes. The path of the file will be printed on stdout and logged.
-crashdump = ["dep:chrono"]
+crashdump = ["dep:chrono", "dep:elfcore"]
 trace_guest = ["dep:opentelemetry", "dep:tracing-opentelemetry", "dep:hyperlight-guest-tracing", "hyperlight-common/trace_guest"]
 mem_profile = [ "trace_guest", "dep:framehop", "dep:fallible-iterator", "hyperlight-common/mem_profile" ]
 kvm = ["dep:kvm-bindings", "dep:kvm-ioctls"]

src/hyperlight_host/build.rs

@@ -99,10 +99,10 @@ fn main() -> Result<()> {
     // Essentially the kvm and mshv3 features are ignored on windows as long as you use #[cfg(kvm)] and not #[cfg(feature = "kvm")].
     // You should never use #[cfg(feature = "kvm")] or #[cfg(feature = "mshv3")] in the codebase.
     cfg_aliases::cfg_aliases! {
-        gdb: { all(feature = "gdb", debug_assertions) },
+        gdb: { all(feature = "gdb", debug_assertions, target_arch = "x86_64") },
         kvm: { all(feature = "kvm", target_os = "linux") },
         mshv3: { all(feature = "mshv3", target_os = "linux") },
-        crashdump: { all(feature = "crashdump") },
+        crashdump: { all(feature = "crashdump", target_arch = "x86_64") },
         // print_debug feature is aliased with debug_assertions to make it only available in debug-builds.
         print_debug: { all(feature = "print_debug", debug_assertions) },
     }

src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs

@@ -0,0 +1,99 @@
+/*
+Copyright 2025  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// TODO(aarch64): implement arch-specific HyperlightVm methods
+
+use std::sync::Arc;
+
+use super::{
+    AccessPageTableError, CreateHyperlightVmError, DispatchGuestCallError, HyperlightVm,
+    InitializeError,
+};
+#[cfg(gdb)]
+use crate::hypervisor::gdb::{DebugCommChannel, DebugMsg, DebugResponse};
+use crate::hypervisor::regs::CommonSpecialRegisters;
+use crate::hypervisor::virtual_machine::RegisterError;
+use crate::mem::mgr::SandboxMemoryManager;
+use crate::mem::shared_mem::{GuestSharedMemory, HostSharedMemory};
+use crate::sandbox::SandboxConfiguration;
+use crate::sandbox::host_funcs::FunctionRegistry;
+use crate::sandbox::snapshot::NextAction;
+#[cfg(feature = "mem_profile")]
+use crate::sandbox::trace::MemTraceInfo;
+#[cfg(crashdump)]
+use crate::sandbox::uninitialized::SandboxRuntimeConfig;
+
+impl HyperlightVm {
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn new(
+        _snapshot_mem: GuestSharedMemory,
+        _scratch_mem: GuestSharedMemory,
+        _pml4_addr: u64,
+        _entrypoint: NextAction,
+        _rsp_gva: u64,
+        _config: &SandboxConfiguration,
+        #[cfg(gdb)] _gdb_conn: Option<DebugCommChannel<DebugResponse, DebugMsg>>,
+        #[cfg(crashdump)] _rt_cfg: SandboxRuntimeConfig,
+        #[cfg(feature = "mem_profile")] _trace_info: MemTraceInfo,
+    ) -> std::result::Result<Self, CreateHyperlightVmError> {
+        unimplemented!("new")
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn initialise(
+        &mut self,
+        _peb_addr: crate::mem::ptr::RawPtr,
+        _seed: u64,
+        _page_size: u32,
+        _mem_mgr: &mut SandboxMemoryManager<HostSharedMemory>,
+        _host_funcs: &Arc<std::sync::Mutex<FunctionRegistry>>,
+        _guest_max_log_level: Option<tracing_core::LevelFilter>,
+        #[cfg(gdb)] _dbg_mem_access_fn: Arc<
+            std::sync::Mutex<SandboxMemoryManager<HostSharedMemory>>,
+        >,
+    ) -> Result<(), InitializeError> {
+        unimplemented!("initialise")
+    }
+
+    pub(crate) fn dispatch_call_from_host(
+        &mut self,
+        _mem_mgr: &mut SandboxMemoryManager<HostSharedMemory>,
+        _host_funcs: &Arc<std::sync::Mutex<FunctionRegistry>>,
+        #[cfg(gdb)] _dbg_mem_access_fn: Arc<
+            std::sync::Mutex<SandboxMemoryManager<HostSharedMemory>>,
+        >,
+    ) -> Result<(), DispatchGuestCallError> {
+        unimplemented!("dispatch_call_from_host")
+    }
+
+    pub(crate) fn get_root_pt(&self) -> Result<u64, AccessPageTableError> {
+        unimplemented!("get_root_pt")
+    }
+
+    pub(crate) fn get_snapshot_sregs(
+        &mut self,
+    ) -> Result<CommonSpecialRegisters, AccessPageTableError> {
+        unimplemented!("get_snapshot_sregs")
+    }
+
+    pub(crate) fn reset_vcpu(
+        &mut self,
+        _cr3: u64,
+        _sregs: &CommonSpecialRegisters,
+    ) -> std::result::Result<(), RegisterError> {
+        unimplemented!("reset_vcpu")
+    }
+}