Centralize snapshot utilities into snapshot_store module (#24)

- refactor: centralize snapshot utilities into `snapshot_store` module
- Moved snapshot-related logic (e.g., hashing, directory management, listing, deletion) into a new `snapshot_store` module for better modularity and cross-platform compatibility.
- Updated imports and restructured functions like `compute_config_hash` and `snapshot_dir_for_hash` to use the new module.
- Simplified platform-specific code paths in `cmd_snapshot` by isolating shared functionality in `snapshot_store`.
- Ensured comprehensive tests for `snapshot_store`, including VZ and KVM integration scenarios.
- add: enable CI support for Ubuntu 24.04 ARM configuration
- fix: include runner architecture in cargo cache keys in CI workflow
- add: architecture-specific serialization support for VM and vCPU state
- Implemented conditional handling for `x86_64` and `aarch64` architectures in snapshot serialization/deserialization tests (`test_vcpu_state_serde_roundtrip`, `test_vm_snapshot_serde_roundtrip`).
- Updated `capture_irqchip` and `restore_irqchip` functions to reduce unused variable warnings by changing parameter names to `_vm` and `_state`.
- refactor: clean up unused imports and improve arch-specific KVM handling
- Removed unnecessary `GuestMemoryMmap` import from `boot.rs`.
- Updated `kvm_bindings` device type constants to use aliased names for consistency.
- Enhanced vCPU configuration by initializing `kvm_vcpu_init` directly with `get_preferred_target`.
- Added conditional `SYS_poll` and `SYS_epoll_wait` handling for better architecture support.
- Fix kvm-bindings constant names (kvm_device_type_ prefix)
- Fix get_preferred_target API (takes &mut kvm_vcpu_init)
- Gate x86_64-only syscalls (SYS_epoll_wait, SYS_poll) with cfg
- Remove unused import (GuestMemoryMmap) and variables
- Make snapshot tests arch-conditional for VcpuState fields
- Add runner.arch to CI cache keys to prevent cross-arch pollution
- Add aarch64 cross-check instructions to AGENTS.md

Author: dpsoft

.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
             rust: stable
           - os: ubuntu-latest
             rust: beta
+          - os: ubuntu-24.04-arm
+            rust: stable
           - os: macos-latest
             rust: stable
 
@@ -38,19 +40,19 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.cargo/registry
-          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Cache cargo index
         uses: actions/cache@v4
         with:
           path: ~/.cargo/git
-          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Cache cargo build
         uses: actions/cache@v4
         with:
           path: target
-          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Run tests
         run: |
@@ -74,7 +76,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -102,7 +104,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest]
         rust: [stable]
 
     steps:
@@ -152,7 +154,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest]
 
     steps:
       - uses: actions/checkout@v4

AGENTS.md

@@ -343,6 +343,30 @@ cargo clippy --workspace --all-targets --all-features -- -D warnings
 cargo test --workspace --all-features
 ```
 
+### aarch64 cross-check (required when touching `src/vmm/arch/aarch64/` or arch-neutral VMM code)
+
+CI runs on native aarch64 (`ubuntu-24.04-arm`). To catch issues locally from an
+x86_64 host without waiting for CI:
+
+```bash
+# One-time setup (Fedora):
+#   sudo dnf install -y gcc-aarch64-linux-gnu sysroot-aarch64-fc43-glibc
+#   rustup target add aarch64-unknown-linux-gnu
+
+CFLAGS_aarch64_unknown_linux_gnu="--sysroot=/usr/aarch64-redhat-linux/sys-root/fc43" \
+  RUSTFLAGS="-D warnings" \
+  cargo check --target aarch64-unknown-linux-gnu -p void-box --lib --tests
+```
+
+Common aarch64 pitfalls:
+- `kvm-bindings` constants use `kvm_device_type_` prefix (e.g.
+  `kvm_device_type_KVM_DEV_TYPE_ARM_VGIC_V3`, not `KVM_DEV_TYPE_ARM_VGIC_V3`).
+- `kvm-ioctls` `get_preferred_target()` takes `&mut kvm_vcpu_init` out-param.
+- `libc::SYS_epoll_wait` and `libc::SYS_poll` don't exist on aarch64 — use
+  `SYS_epoll_pwait` and `SYS_ppoll`.
+- Unused variables/imports that are only used on x86_64 become errors with
+  `-D warnings` on aarch64.
+
 ### VM suites (required for VM/OCI/OpenClaw changes)
 
 Linux (KVM):

Cargo.toml

@@ -53,6 +53,7 @@ void-box-protocol = { path = "void-box-protocol" }
 voidbox-oci = { path = "voidbox-oci" }
 libc = "0.2"
 byteorder = "1"
+sha2 = "0.10"
 
 # --- Linux-only dependencies ---
 [target.'cfg(target_os = "linux")'.dependencies]
@@ -71,9 +72,6 @@ event-manager = "0.4"
 # SLIRP networking (smoltcp-based user-mode networking)
 smoltcp = { version = "0.11", default-features = false, features = ["std", "medium-ethernet", "proto-ipv4", "socket-tcp", "socket-udp", "socket-dns"] }
 
-# Stable hashing for OCI disk cache keys and snapshot config hashes
-sha2 = "0.10"
-
 # Binary serialization for VM snapshot state
 bincode = "1"
 

src/backend/mod.rs

@@ -78,6 +78,57 @@ pub struct BackendConfig {
     pub snapshot: Option<PathBuf>,
 }
 
+impl BackendConfig {
+    /// Create a minimal `BackendConfig` with sensible defaults.
+    ///
+    /// Only requires the fields that have no reasonable default (kernel path,
+    /// memory, vCPUs). Everything else is set to safe defaults with vsock
+    /// enabled and the default command allowlist.
+    pub fn minimal(kernel: impl Into<PathBuf>, memory_mb: usize, vcpus: usize) -> Self {
+        let mut session_secret = [0u8; 32];
+        getrandom::fill(&mut session_secret).expect("getrandom");
+        Self {
+            memory_mb,
+            vcpus,
+            kernel: kernel.into(),
+            initramfs: None,
+            rootfs: None,
+            network: false,
+            enable_vsock: true,
+            shared_dir: None,
+            mounts: Vec::new(),
+            oci_rootfs: None,
+            oci_rootfs_dev: None,
+            oci_rootfs_disk: None,
+            env: Vec::new(),
+            security: BackendSecurityConfig {
+                session_secret,
+                command_allowlist: DEFAULT_COMMAND_ALLOWLIST
+                    .iter()
+                    .map(|s| s.to_string())
+                    .collect(),
+                network_deny_list: Vec::new(),
+                max_connections_per_second: 0,
+                max_concurrent_connections: 0,
+                seccomp: false,
+            },
+            snapshot: None,
+        }
+    }
+
+    /// Set the initramfs path.
+    pub fn initramfs(mut self, path: impl Into<PathBuf>) -> Self {
+        self.initramfs = Some(path.into());
+        self
+    }
+
+    /// Enable or disable networking.
+    pub fn network(mut self, enabled: bool) -> Self {
+        self.network = enabled;
+        self
+    }
+}
+
 /// Security-relevant settings for the backend.
 #[derive(Debug, Clone)]
 pub struct BackendSecurityConfig {