godspeed_sdk/

adversarial.rs

// SPDX-License-Identifier: Apache-2.0
//! Adversarial test primitives for the §22 red-team / fuzz / chaos harness (the `probe` service).
//!
//! These are the one thing a test service legitimately needs that a safe wrapper cannot otherwise
//! express: issuing a RAW syscall with arbitrary (fuzzed) number + arguments, and executing a
//! DELIBERATE ring-3 fault to prove the kernel kills the faulting task rather than wedging the machine
//! (invariant 12; §22 A14 / A15 / C2). Isolating that `unsafe` HERE - a designated, audited SDK module,
//! every block carrying a `// SAFETY:` comment - keeps the test SERVICES themselves (`probe`)
//! `unsafe`-free (§18.2), exactly as the SDK's ABI / MMIO / DMA modules keep the driver services
//! `unsafe`-free (§18.1). This module is **test-only**: no production service should call it (a fault
//! primitive merely kills the caller, which the kernel handles; the fuzz primitive is a raw trap the
//! kernel validates). One production caller exists, by design: the SDK's own panic handler
//! (`lib.rs`) calls [`fault_null_read`] so that a panicking service dies and is restarted instead of
//! spinning.

/// Issue a RAW syscall with an arbitrary number and arguments and return the raw `i64` result. This is
/// the fuzz/adversarial entry point (F1/F2/A10/A15 ...): the kernel **validates every syscall**, so from
/// the caller's side this is memory-safe - it never dereferences anything itself. A bad pointer passed
/// as `a1` is the KERNEL's to validate and reject (or to attribute to this caller and kill it); it can
/// never corrupt this task's memory. The `unsafe` is purely the inline-asm ABI trap, which is sound for
/// any argument values, so it is isolated in [`crate::syscall::raw_syscall`] and wrapped safely here.
#[inline]
pub fn fuzz_syscall(nr: u64, a0: u64, a1: u64, a2: u64) -> i64 {
    // SAFETY: `raw_syscall` is the ABI trap (`ud2` on x86-64, `svc #0` on ARMv7, the native trap on the
    // other ports - `syscall.rs`). It is sound for ANY argument values -
    // it just transitions to the kernel, which validates. Fuzzing arbitrary nr/args cannot violate this
    // task's Rust memory safety; rejecting bad input is the kernel's responsibility (exactly what the
    // fuzz/adversarial suite verifies). The worst outcome is that the kernel kills this task, not UB.
    unsafe { crate::syscall::raw_syscall(nr, a0, a1, a2) }
}

/// Deliberately read through a NULL pointer, raising a ring-3 page fault (#PF) - §22 Chaos C2 / A14. A
/// conforming kernel kills this task at the fault and continues; it must never halt the machine
/// (invariant 12). Control does not return on a conforming kernel.
#[inline]
pub fn fault_null_read() {
    // SAFETY: an intentional fault for the C2/A14 regression. A conforming kernel kills this task at the
    // ring-3 #PF before the read yields a value, so nothing is truly observed; even if a (broken) kernel
    // wrongly resumed us, `read_volatile` of address 0 is a defined faulting operation, not UB we rely on.
    unsafe { core::ptr::read_volatile(core::ptr::null::<u8>()); }
}

/// Deliberately read a NON-CANONICAL address (bit 47 != bit 63), raising a ring-3 general-protection
/// fault (#GP(0)) at CPL3 - §22 A14. The kernel must kill this task, not halt (kernel-audit C1).
#[cfg(target_arch = "x86_64")]
#[inline]
pub fn fault_noncanonical_read() {
    // SAFETY: an intentional fault for the A14 regression; the kernel kills this task at the ring-3 #GP.
    // See `fault_null_read` - a conforming kernel never lets the read complete.
    unsafe { let _ = core::ptr::read_volatile(0x8000_0000_0000_0000 as *const u8); }
}

/// ARMv7 has no "non-canonical" address form (that is an x86-64 48-bit-VA concept). The equivalent
/// ring-3 CPU fault is a read of an **unmapped high address**, which takes a data abort the kernel
/// must handle by killing the task, not halting - the same A14/C1 property.
#[cfg(target_arch = "arm")]
#[inline]
pub fn fault_noncanonical_read() {
    // SAFETY: an intentional data-abort for the A14 regression; a conforming kernel kills this task at
    // the ring-3 abort. `0xFFFF_FFF0` is far above any mapped user or kernel page on this platform.
    unsafe { let _ = core::ptr::read_volatile(0xFFFF_FFF0 as *const u8); }
}

/// AArch64 has a genuine analog of x86's non-canonical address: the **VA hole**. With a 39-bit range
/// at each end (`T0SZ = T1SZ = 25`), addresses between the top of the `TTBR0` range and the bottom of
/// the `TTBR1` range belong to neither table and fault on any access, from any EL. `0x0000_8000_0000_0000`
/// sits squarely in that hole - the same "this address cannot possibly be valid" property #GP tests on
/// x86, rather than merely an address that happens to be unmapped today.
#[cfg(target_arch = "aarch64")]
#[inline]
pub fn fault_noncanonical_read() {
    // SAFETY: an intentional data abort for the A14 regression; a conforming kernel kills this task at
    // the EL0 abort. The address is in the architectural VA hole, so no mapping can ever make it valid.
    unsafe {
        let _ = core::ptr::read_volatile(0x0000_8000_0000_0000u64 as *const u8);
    }
}

/// Deliberately divide by zero, raising a ring-3 divide-error (#DE, vector 0) at CPL3 - §22 A14. Uses
/// raw asm because Rust inserts a divide guard that would PANIC (unwind) instead of faulting, and the
/// threat model includes adversarial asm services. The kernel must kill this task, not halt.
#[cfg(target_arch = "x86_64")]
#[inline]
pub fn fault_divide_by_zero() {
    // SAFETY: an intentional fault for the A14 regression; the kernel kills this task at the ring-3 #DE.
    // The asm touches no memory (nomem/nostack) and clobbers only the declared caller-saved registers.
    unsafe {
        core::arch::asm!(
            "xor eax, eax",
            "xor edx, edx",
            "xor ecx, ecx",
            "div ecx",   // (EDX:EAX)=0 / ECX=0 -> #DE (divide error)
            out("eax") _, out("edx") _, out("ecx") _,
            options(nostack, nomem),
        );
    }
}

/// ARMv7 has no trapping integer divide-by-zero by default (`sdiv`/`udiv` return 0 unless
/// `SCTLR.DZ` is set), so the equivalent ring-3 CPU fault is an **undefined instruction** (`udf`),
/// which the kernel's UND vector must handle by killing the task, not halting - the same A14/C1
/// property this primitive tests on x86.
#[cfg(target_arch = "arm")]
#[inline]
pub fn fault_divide_by_zero() {
    // SAFETY: an intentional undefined-instruction fault for the A14 regression. `udf #0` raises a
    // ring-3 undefined-instruction exception; a conforming kernel kills this task and never resumes it.
    unsafe {
        core::arch::asm!("udf #0", options(nostack, nomem));
    }
}

/// AArch64 has **no trapping integer divide** either - `sdiv`/`udiv` by zero return 0 rather than
/// faulting, with no control bit to change that (unlike ARMv7's `SCTLR.DZ`). So, as on the 32-bit port,
/// the equivalent EL0 CPU fault is an **undefined instruction**, which the kernel must handle by
/// killing the task rather than halting - the same A14/C1 property the x86 `#DE` tests.
///
/// The name is kept across all three architectures so the test suite names one behaviour rather than
/// three; what differs is only which instruction produces the fault.
#[cfg(target_arch = "aarch64")]
#[inline]
pub fn fault_divide_by_zero() {
    // SAFETY: an intentional undefined-instruction fault for the A14 regression. `udf #0` is the
    // permanently-undefined encoding; a conforming kernel kills this task and never resumes it.
    unsafe {
        core::arch::asm!("udf #0", options(nostack, nomem));
    }
}

/// A run of FRESH pages this task was just given by `AllocMem`, for the §22 P7 stale-translation test.
///
/// P7 asks whether a dead task's translations can outlive it (CLAUDE.md 10.5): a writer stamps its
/// pages, is killed, and a checker spawned after it, given the SAME virtual addresses (every task's
/// `AllocMem` grows from one base), must read the zeroes the kernel filled its new pages with. A
/// pattern word there means the checker read through a translation that belonged to the dead writer.
///
/// Reading and writing that memory needs a raw pointer, which a test SERVICE must not hold (18.2), so
/// it is wrapped here. The wrapper is sound because a `Region` can only be made from a successful
/// `AllocMem`: its pages are mapped, writable, private to this task, and referenced by nothing else -
/// the kernel has just created them, and no Rust object lives there.
pub struct Region {
    va: u64,
    words: usize,
}

impl Region {
    /// Ask the kernel for `pages` fresh 4 KiB pages. `None` if it refused.
    pub fn alloc(ctx: &crate::service_context::ServiceContext, pages: usize) -> Option<Region> {
        let len = pages.checked_mul(4096)?;
        let va = ctx.alloc_mem(len).ok()?;
        Some(Region { va, words: len / 4 })
    }

    /// The first virtual address of the region (the same in every task that asks first).
    pub fn base(&self) -> u64 { self.va }

    /// Write `word` into every 32-bit word of the region.
    pub fn stamp(&self, word: u32) {
        let p = self.va as *mut u32;
        for i in 0..self.words {
            // SAFETY: `p.add(i)` is inside the `words * 4` bytes `AllocMem` mapped for this task (the
            // constructor is the only way to make a Region), 4-aligned because the base is
            // page-aligned, and no Rust reference points there. Volatile, so every store is made.
            unsafe { core::ptr::write_volatile(p.add(i), word) };
        }
    }

    /// The byte offset and value of the first word that is not `want`, or `None` if every word is.
    pub fn first_not(&self, want: u32) -> Option<(usize, u32)> {
        let p = self.va as *const u32;
        for i in 0..self.words {
            // SAFETY: as `stamp`: inside the mapped region, aligned, aliased by no reference. Volatile,
            // so each word is really read through this task's own translation.
            let w = unsafe { core::ptr::read_volatile(p.add(i)) };
            if w != want {
                return Some((i * 4, w));
            }
        }
        None
    }
}