LiteBox (virtual/bare-metal) machine platform and runner

Author: sangho2

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
           key: custom-out-${{ runner.os }}-${{ github.job }}-${{ hashFiles('**/Cargo.lock') }}-${{ hashFiles('**/litebox_syscall_rewriter/**/*.rs') }}
       - run: ./.github/tools/github_actions_run_cargo fmt
       - run: |
-          ./.github/tools/github_actions_run_cargo clippy --all-targets --all-features --workspace --exclude litebox_platform_lvbs --exclude litebox_runner_lvbs --exclude litebox_runner_optee_on_linux_userland --exclude litebox_runner_snp
+          ./.github/tools/github_actions_run_cargo clippy --all-targets --all-features --workspace --exclude litebox_platform_lvbs --exclude litebox_runner_lvbs --exclude litebox_runner_optee_on_linux_userland --exclude litebox_runner_snp --exclude litebox_platform --exclude litebox_runner_optee_on_machine
           ./.github/tools/github_actions_run_cargo clippy --all-targets --all-features -p litebox_runner_optee_on_linux_userland
           # We exclude `litebox_platform_lvbs` and `litebox_runner_lvbs` because we cannot build them with a stable toolchain.
           # They depend on the unstable `abi_x86_interrupt` feature. `build_and_test_nightly` cover them.
@@ -67,7 +67,7 @@ jobs:
           # aren't included in nextest at the moment. See relevant discussion at
           # https://github.com/nextest-rs/nextest/issues/16
       - name: Build documentation (fail on warnings)
-        run: ./.github/tools/github_actions_run_cargo doc --no-deps --all-features --document-private-items --workspace --exclude litebox_platform_lvbs --exclude litebox_runner_lvbs --exclude litebox_runner_snp
+        run: ./.github/tools/github_actions_run_cargo doc --no-deps --all-features --document-private-items --workspace --exclude litebox_platform_lvbs --exclude litebox_runner_lvbs --exclude litebox_runner_snp --exclude litebox_platform --exclude litebox_runner_optee_on_machine
 
   build_and_test_32bit:
     name: Build and Test (32-bit)
@@ -194,6 +194,36 @@ jobs:
       - name: Build documentation (fail on warnings)
         run: ./.github/tools/github_actions_run_cargo doc --no-deps --all-features --document-private-items
 
+  build_and_test_qemu:
+    name: Build and Test boot image with QEMU
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: -Dwarnings
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - run: sudo apt update && sudo apt install qemu-system-x86
+      - name: Set up Rust
+        run: |
+          RUST_CHANNEL=$(awk -F'"' '/channel/{print $2}' litebox_runner_optee_on_machine/rust-toolchain.toml)
+          rustup toolchain install ${RUST_CHANNEL} --profile minimal --no-self-update --component rustfmt,clippy --target x86_64-unknown-none
+          rustup component add rust-src --toolchain ${RUST_CHANNEL}-x86_64-unknown-linux-gnu
+          rustup default ${RUST_CHANNEL}
+          rustup override set ${RUST_CHANNEL}
+          rustup show
+      - uses: Swatinem/rust-cache@v2
+      - run: ./.github/tools/github_actions_run_cargo clippy --all-features --target litebox_runner_optee_on_machine/x86_64-unknown-litebox.json --manifest-path=litebox_runner_optee_on_machine/Cargo.toml -Zbuild-std=core,compiler_builtins,alloc
+      - run: |
+          ./.github/tools/github_actions_run_cargo build -Zbuild-std=core,compiler_builtins,alloc -Zbuild-std-features=compiler-builtins-mem --manifest-path=litebox_runner_optee_on_machine/Cargo.toml --target litebox_runner_optee_on_machine/x86_64-unknown-litebox.json
+      - run: |
+          rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu
+          rustup component add llvm-tools-preview --toolchain nightly-x86_64-unknown-linux-gnu
+          cargo +nightly install bootimage
+          cargo +nightly bootimage -Zbuild-std=core,compiler_builtins,alloc -Zbuild-std-features=compiler-builtins-mem --manifest-path=litebox_runner_optee_on_machine/Cargo.toml --target litebox_runner_optee_on_machine/x86_64-unknown-litebox.json
+          qemu-system-x86_64 -machine q35 -cpu max -m 256M -drive format=raw,file=target/x86_64-unknown-litebox/debug/bootimage-litebox_runner_optee_on_machine.bin -nographic -no-reboot -device isa-debug-exit,iobase=0xf4,iosize=0x04 || true
+      - name: Build documentation (fail on warnings)
+        run: ./.github/tools/github_actions_run_cargo doc --no-deps --all-features --document-private-items
+
   confirm_no_std:
     name: Confirm no_std
     runs-on: ubuntu-latest
@@ -288,6 +318,8 @@ jobs:
             -not -path './litebox_shim_optee/Cargo.toml' \
             -not -path './litebox_syscall_rewriter/Cargo.toml' \
             -not -path './litebox_runner_snp/Cargo.toml' \
+            -not -path './litebox_platform/Cargo.toml' \
+            -not -path './litebox_runner_optee_on_machine/Cargo.toml' \
             -not -path './dev_tests/Cargo.toml' \
             -print0 | \
               xargs -0 -I '{}' sh -c 'cd "$(dirname "{}")"; pwd; cargo build --locked --target x86_64-unknown-none || exit 1; echo; echo'

Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "litebox", 
     "litebox_common_linux",
     "litebox_common_optee",
+    "litebox_platform",
     "litebox_platform_linux_kernel",
     "litebox_platform_linux_userland",
     "litebox_platform_windows_userland",
@@ -13,6 +14,7 @@ members = [
     "litebox_runner_linux_on_windows_userland",
     "litebox_runner_lvbs",
     "litebox_runner_optee_on_linux_userland",
+    "litebox_runner_optee_on_machine",
     "litebox_shim_linux",
     "litebox_syscall_rewriter",
     "litebox_runner_snp",
@@ -24,6 +26,7 @@ default-members = [
     "litebox",
     "litebox_common_linux",
     "litebox_common_optee",
+    "litebox_platform",
     "litebox_platform_linux_kernel",
     "litebox_platform_linux_userland",
     "litebox_platform_windows_userland",

Cargo.toml

@@ -30,6 +30,7 @@ fn ratchet_globals() -> Result<()> {
             ("litebox_platform_linux_kernel/", 4),
             ("litebox_platform_linux_userland/", 6),
             ("litebox_platform_lvbs/", 18),
+            ("litebox_platform/", 9),
             ("litebox_platform_multiplex/", 1),
             ("litebox_platform_windows_userland/", 8),
             ("litebox_runner_linux_userland/", 1),
@@ -64,6 +65,7 @@ fn ratchet_maybe_uninit() -> Result<()> {
             ("litebox_platform_linux_kernel/", 1),
             ("litebox_platform_linux_userland/", 3),
             ("litebox_platform_lvbs/", 6),
+            ("litebox_platform/", 1),
             ("litebox_shim_linux/", 5),
         ],
         |file| {

dev_tests/src/ratchet.rs

@@ -273,7 +273,8 @@ where
         flags: CreatePagesFlags,
     ) -> Result<Platform::RawMutPointer<u8>, MappingError> {
         let perms = MemoryRegionPermissions::READ | MemoryRegionPermissions::WRITE;
-        let flags = CreatePagesFlags::IS_STACK | flags;
+        let flags =
+            CreatePagesFlags::IS_STACK | CreatePagesFlags::POPULATE_PAGES_IMMEDIATELY | flags;
         unsafe { self.create_pages(suggested_address, length, flags, perms, perms, |_| Ok(0)) }
     }
 

litebox/src/mm/mod.rs

@@ -0,0 +1,8 @@
+[profile.ci]
+# Do not cancel the test run on the first failure.
+fail-fast = false
+# Show all tests _including_ skipped tests in output.
+status-level = "all"
+# Output failures as soon as they happen _and_ at the end of the test run;
+# combination of "immediate" and "final".
+failure-output = "immediate-final"

litebox_platform/.config/nextest.toml

@@ -0,0 +1,41 @@
+[package]
+name = "litebox_platform"
+version = "0.1.0"
+edition = "2024"
+
+
+[dependencies]
+cfg-if = "1.0.0"
+bitflags = "2.9.0"
+buddy_system_allocator = { version = "0.11.0", default-features = false, features = ["use_spin"] }
+slabmalloc = { git = "https://github.com/gz/rust-slabmalloc.git", rev = "19480b2e82704210abafe575fb9699184c1be110" }
+litebox = { path = "../litebox/", version = "0.1.0" }
+litebox_common_linux = { path = "../litebox_common_linux/", version = "0.1.0" }
+litebox_common_optee = { path = "../litebox_common_optee/", version = "0.1.0" }
+spin = { version = "0.10.0", default-features = false, features = [
+  "spin_mutex",
+  "once",
+  "rwlock",
+] }
+libc = "0.2.169"
+arrayvec = { version = "0.7.6", default-features = false }
+rangemap = { version = "1.5.1", features = ["const_fn"] }
+thiserror = { version = "2.0.6", default-features = false }
+num_enum = { version = "0.7.3", default-features = false }
+once_cell = { version = "1.20.2", default-features = false, features = ["alloc", "race"] }
+modular-bitfield = { version = "0.12.0", default-features = false }
+hashbrown = "0.15.2"
+aligned-vec = { version = "0.6.4", default-features = false }
+raw-cpuid = "11.6.0"
+
+[target.'cfg(target_arch = "x86_64")'.dependencies]
+x86_64 = { version = "0.15.2", default-features = false, features = ["instructions"] }
+
+[features]
+default = ["optee_syscall"]
+optee_syscall = []
+linux_syscall = []
+interrupt = ["x86_64/abi_x86_interrupt"]
+
+[lints]
+workspace = true

litebox_platform/Cargo.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "nightly-2025-09-29"

litebox_platform/rust-toolchain.toml

@@ -0,0 +1,46 @@
+#[cfg(not(test))]
+mod alloc {
+    const HEAP_ORDER: usize = 25;
+
+    #[global_allocator]
+    static ALLOCATOR: litebox::mm::allocator::SafeZoneAllocator<
+        'static,
+        HEAP_ORDER,
+        crate::LiteBoxKernel,
+    > = litebox::mm::allocator::SafeZoneAllocator::new();
+
+    // TODO: these alloc and free functions are for dynamic memory management which are
+    // often meaningless if there is no host. In that sense, we might want to remove these from
+    // `SafeZoneAllocator`.
+    impl litebox::mm::allocator::MemoryProvider for crate::LiteBoxKernel {
+        fn alloc(_layout: &core::alloc::Layout) -> Option<(usize, usize)> {
+            // For a (virtual) machine, this might be memory ballooning or hotplugging.
+            unimplemented!()
+        }
+
+        unsafe fn free(_addr: usize) {
+            unimplemented!()
+        }
+    }
+
+    impl crate::mm::MemoryProvider for crate::LiteBoxKernel {
+        // TODO: this offset should be configurable
+        const GVA_OFFSET: x86_64::VirtAddr = x86_64::VirtAddr::new(0x18000000000);
+        // TODO: this mask should be configurable
+        const PRIVATE_PTE_MASK: u64 = 0;
+
+        fn mem_allocate_pages(order: u32) -> Option<*mut u8> {
+            ALLOCATOR.allocate_pages(order)
+        }
+
+        unsafe fn mem_free_pages(ptr: *mut u8, order: u32) {
+            unsafe {
+                ALLOCATOR.free_pages(ptr, order);
+            }
+        }
+
+        unsafe fn mem_fill_pages(start: usize, size: usize) {
+            unsafe { ALLOCATOR.fill_pages(start, size) };
+        }
+    }
+}

litebox_platform/src/alloc_impl.rs

@@ -0,0 +1,7 @@
+//! Arch-specific code
+
+#[cfg(target_arch = "x86_64")]
+mod x86;
+
+#[cfg(target_arch = "x86_64")]
+pub use x86::*;