rigless 0.0.5

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The emulator built into this crate, and the four calls it makes.
//!
//! The fork's proxy device calls `rigless_core_new` when the machine is realized, `rigless_core_access`
//! for every peripheral access, `rigless_core_stop` at every instant the models asked for, and
//! `rigless_core_free` never in practice: the process that prepared the core takes it back once the
//! emulator has cleaned up. Every call after the first is on the emulated core's thread, and nothing
//! else touches the core between the first and the last.
//!
//! [`run`] does what the fork's own `main` does, in this process: prepares the core, starts the
//! emulator with the machine module's arguments, runs its main loop with its two locks held as its
//! `main` holds them, cleans up, and returns instead of exiting. The emulator has one set of global
//! state, so it runs once per process.
#![expect(
    unsafe_code,
    reason = "the emulator is C: the four entry points it calls, the five it exports, and the host it lends"
)]

use std::any::Any;
use std::ffi::{CString, c_char, c_int, c_void};
use std::ptr;
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, AtomicPtr, Ordering};

use super::{
    Access, AccessKind, Alias, Driver, EmulatorCommand, Error, Finished, Host, InterruptLine,
    Memory, Start, Stop, StopReason,
};
use crate::device::Level;
use crate::machine::Board;
use crate::session::Session;
use crate::soc::{Region, RegionKind, Width};
use crate::time::VirtualNanos;

/// A deadline at or past this is none: the proxy leaves its timer unarmed.
const NO_DEADLINE_NS: u64 = i64::MAX as u64;

/// What the emulator lends the core, as `include/hw/misc/rigless-core.h` lays it out.
#[repr(C)]
struct CHost {
    opaque: *mut c_void,
    read_memory: unsafe extern "C" fn(*mut c_void, u64, u32) -> u64,
    write_memory: unsafe extern "C" fn(*mut c_void, u64, u32, u64),
    set_interrupt: unsafe extern "C" fn(*mut c_void, u32, u32),
}

unsafe extern "C" {
    fn qemu_init(argc: c_int, argv: *mut *mut c_char);
    fn qemu_main_loop() -> c_int;
    fn qemu_cleanup(status: c_int);
    fn bql_unlock();
    fn replay_mutex_unlock();
}

/// The host the proxy lent, held for the run.
struct Lent(*const CHost);

// SAFETY: the proxy's host outlives the run and is only ever called from the emulated core's thread,
// which is the one thread that holds this.
unsafe impl Send for Lent {}

impl Lent {
    fn host(&self) -> &CHost {
        // SAFETY: the proxy hands a pointer to its own state's host, which lives as long as the device.
        unsafe { &*self.0 }
    }
}

impl Memory for Lent {
    fn read(&mut self, address: u64, width: Width) -> Result<u64, Error> {
        let host = self.host();
        // SAFETY: the function pointers are the proxy's, taking its own opaque state.
        Ok(unsafe { (host.read_memory)(host.opaque, address, u32::from(width.bits())) })
    }

    fn write(&mut self, address: u64, width: Width, value: u64) -> Result<(), Error> {
        let host = self.host();
        // SAFETY: as for `read`.
        unsafe { (host.write_memory)(host.opaque, address, u32::from(width.bits()), value) };
        Ok(())
    }
}

impl Host for Lent {
    fn set_interrupt(&mut self, line: InterruptLine, level: Level) {
        let host = self.host();
        // SAFETY: as for `read`.
        unsafe {
            (host.set_interrupt)(
                host.opaque,
                u32::from(line.index()),
                u32::from(level == Level::High),
            );
        }
    }
}

/// A run as the entry points see it, without its types.
trait Driven: Send {
    fn first_deadline(&mut self) -> VirtualNanos;
    fn access(&mut self, access: Access, host: &mut dyn Host) -> (u64, VirtualNanos);
    fn stop(&mut self, stop: Stop, host: &mut dyn Host) -> Option<VirtualNanos>;
    fn into_any(self: Box<Self>) -> Box<dyn Any>;
}

struct Run<D: Board + ?Sized, R: Driver<D>> {
    session: Session<D>,
    driver: R,
    last: Option<Stop>,
}

impl<D: Board + ?Sized + 'static, R: Driver<D> + 'static> Driven for Run<D, R> {
    fn first_deadline(&mut self) -> VirtualNanos {
        self.session.next_deadline()
    }

    fn access(&mut self, access: Access, host: &mut dyn Host) -> (u64, VirtualNanos) {
        let (value, next) = self.session.access(access, host);
        self.driver.on_access(&access, value);
        (value, next)
    }

    fn stop(&mut self, stop: Stop, host: &mut dyn Host) -> Option<VirtualNanos> {
        let next = self.session.stop(stop, host);
        if !self.session.reached(&stop) {
            return Some(next);
        }
        self.last = Some(stop);
        let until = self.driver.on_stop(&mut self.session, stop)?;
        self.session.run_until(until);
        Some(self.session.next_deadline())
    }

    fn into_any(self: Box<Self>) -> Box<dyn Any> {
        self
    }
}

/// The core as the proxy holds it.
struct Core {
    driven: Box<dyn Driven>,
    host: Lent,
}

/// The run prepared for the proxy to take at realize.
static PREPARED: Mutex<Option<Box<dyn Driven>>> = Mutex::new(None);
/// The core the proxy took, to be taken back once the emulator has cleaned up.
static ACTIVE: AtomicPtr<Core> = AtomicPtr::new(ptr::null_mut());
/// Whether the emulator has run in this process.
static RAN: AtomicBool = AtomicBool::new(false);

#[unsafe(no_mangle)]
extern "C" fn rigless_core_new(host: *const CHost, first_deadline_ns: *mut u64) -> *mut c_void {
    let Some(mut driven) = PREPARED
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .take()
    else {
        return ptr::null_mut();
    };
    let first = driven.first_deadline();
    // SAFETY: the proxy passes a pointer to its own out-parameter.
    unsafe { *first_deadline_ns = first.0 };
    let core = Box::into_raw(Box::new(Core {
        driven,
        host: Lent(host),
    }));
    ACTIVE.store(core, Ordering::Release);
    core.cast()
}

// The proxy asks for a power of two up to its bus width; anything else is a header the two sides read
// differently, which a panic across the seam aborts on with this message.
fn width_of(bits: u32) -> Width {
    match bits {
        8 => Width::W8,
        16 => Width::W16,
        32 => Width::W32,
        64 => Width::W64,
        other => panic!("the proxy asked for a {other} bit access"),
    }
}

#[unsafe(no_mangle)]
extern "C" fn rigless_core_access(
    core: *mut c_void,
    writing: u32,
    address: u64,
    width_bits: u32,
    value: u64,
    now_ns: u64,
    instruction_count: u64,
    program_counter: u64,
    next_deadline_ns: *mut u64,
) -> u64 {
    // SAFETY: the proxy passes back what `rigless_core_new` gave it, from the one thread that calls.
    let core = unsafe { &mut *core.cast::<Core>() };
    let access = Access {
        kind: if writing == 0 {
            AccessKind::Read
        } else {
            AccessKind::Write
        },
        address,
        width: width_of(width_bits),
        value,
        instruction_count,
        virtual_time: VirtualNanos(now_ns),
        program_counter,
    };
    let (answer, next) = core.driven.access(access, &mut core.host);
    // SAFETY: the proxy passes a pointer to its own out-parameter.
    unsafe { *next_deadline_ns = next.0 };
    answer
}

#[unsafe(no_mangle)]
extern "C" fn rigless_core_stop(
    core: *mut c_void,
    reason: u32,
    now_ns: u64,
    instruction_count: u64,
    next_deadline_ns: *mut u64,
) -> u32 {
    // SAFETY: as for `rigless_core_access`.
    let core = unsafe { &mut *core.cast::<Core>() };
    let stop = Stop {
        at: VirtualNanos(now_ns),
        instruction_count,
        reason: StopReason::from_code(reason).unwrap_or_else(|| {
            panic!("the proxy stopped for a reason {reason} the header does not name")
        }),
    };
    let (next, finished) = match core.driven.stop(stop, &mut core.host) {
        Some(next) => (next.0, 0),
        None => (NO_DEADLINE_NS, 1),
    };
    // SAFETY: the proxy passes a pointer to its own out-parameter.
    unsafe { *next_deadline_ns = next };
    finished
}

/// The process that prepared the core takes it back after the run, so the proxy's release is nothing.
#[unsafe(no_mangle)]
extern "C" fn rigless_core_free(_core: *mut c_void) {}

/// Runs `session`'s target on the emulator built into this crate, driven by `driver`, and hands back
/// what the run left.
///
/// This is the fork's `main` in this process: it prepares the core, starts the emulator with the
/// arguments the target's machine module renders plus the firmware and the debugger of `start`, runs
/// the main loop, cleans up, and returns. The emulator runs once per process; a second call is
/// [`Error::AlreadyRan`].
///
/// # Panics
///
/// Panics when the emulator ends without the core having been taken back, which is a session in an
/// unknown state and not something to continue from.
pub fn run<D, R>(session: Session<D>, start: &Start<'_>, driver: R) -> Result<Finished<D, R>, Error>
where
    D: Board + ?Sized + 'static,
    R: Driver<D> + 'static,
{
    if RAN.swap(true, Ordering::AcqRel) {
        return Err(Error::AlreadyRan);
    }
    let mut session = session;
    let arguments = {
        let target = session.target();
        let mut targets = session.board_mut().targets();
        let command = targets.swap_remove(target);
        let memory = command.mcu.memory();
        arguments(&command.emulator, memory, start)?
    };
    *PREPARED
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(Box::new(Run {
        session,
        driver,
        last: None,
    }));
    let mut argv: Vec<*mut c_char> = arguments
        .iter()
        .map(|argument| argument.as_ptr().cast_mut())
        .chain(std::iter::once(ptr::null_mut()))
        .collect();
    let argc = c_int::try_from(arguments.len()).expect("a handful of arguments");
    // What the fork's `main` does, in order: init takes the two locks, the loop runs with them
    // held, cleanup runs, and they are released.
    // SAFETY: `argv` outlives the call and ends in a null.
    unsafe { qemu_init(argc, argv.as_mut_ptr()) };
    // SAFETY: init returned, so the emulator is set up and this thread holds its locks.
    let status = unsafe { qemu_main_loop() };
    // SAFETY: the loop returned, so nothing runs; cleanup is what follows it.
    unsafe { qemu_cleanup(status) };
    // SAFETY: this thread took the lock in init and has not released it.
    unsafe { bql_unlock() };
    // SAFETY: as for the other lock.
    unsafe { replay_mutex_unlock() };
    let core = ACTIVE.swap(ptr::null_mut(), Ordering::AcqRel);
    assert!(
        !core.is_null(),
        "the emulator ended with status {status} before the machine took the core"
    );
    // SAFETY: `rigless_core_new` made it with `Box::into_raw`, the emulator has cleaned up so the
    // core's thread no longer calls, and it is taken back exactly once.
    let core = unsafe { Box::from_raw(core) };
    let run = core
        .driven
        .into_any()
        .downcast::<Run<D, R>>()
        .unwrap_or_else(|_| unreachable!("the run that was prepared"));
    let Run {
        session,
        driver,
        last,
    } = *run;
    Ok(Finished {
        session,
        driver,
        stop: last,
    })
}

/// The emulator's argument list for one target: the machine and its properties, the core, the memory
/// map as `rigless-memory` devices, the firmware, the instruction rate, and the debugger if asked.
fn arguments(
    command: &EmulatorCommand,
    memory: &[Region],
    start: &Start<'_>,
) -> Result<Vec<CString>, Error> {
    let machine = std::iter::once(command.machine.to_owned())
        .chain(command.properties.iter().map(ToString::to_string))
        .collect::<Vec<_>>()
        .join(",");
    let mut arguments: Vec<String> = vec![
        "rigless".into(),
        "-M".into(),
        machine,
        "-cpu".into(),
        command.cpu.into(),
    ];
    for region in memory {
        arguments.push("-object".into());
        arguments.push(format!(
            "memory-backend-ram,id={},size={},share=on",
            region.name, region.size
        ));
        arguments.push("-device".into());
        arguments.push(memory_device(region, &command.aliases));
    }
    arguments.extend([
        "-kernel".into(),
        start.firmware.display().to_string(),
        "-icount".into(),
        format!("shift={},sleep=off,align=off", command.icount_shift),
        "-nographic".into(),
        "-display".into(),
        "none".into(),
        "-serial".into(),
        "none".into(),
        "-monitor".into(),
        "none".into(),
    ]);
    if let Some(port) = start.debugger_port {
        arguments.extend(["-gdb".into(), format!("tcp::{port}")]);
        // `-S` holds the CPU before its first instruction. Serving the stub does not imply it: a
        // debugger that attaches to a running target is the ordinary case, and waiting is the ask.
        if start.wait_for_debugger {
            arguments.push("-S".into());
        }
    }
    arguments
        .into_iter()
        .map(|argument| CString::new(argument.clone()).map_err(|_nul| Error::Argument(argument)))
        .collect()
}

fn memory_device(region: &Region, aliases: &[Alias]) -> String {
    let alias = aliases
        .iter()
        .find(|alias| alias.region == region.name)
        .map(|alias| format!(",alias-base={:#x}", alias.at))
        .unwrap_or_default();
    // Only read-write memory takes a guest's write; what the other kinds hold is what the image put there.
    let read_only = if region.kind == RegionKind::Ram {
        ""
    } else {
        ",readonly=on"
    };
    format!(
        "rigless-memory,memdev={},base={:#x}{alias}{read_only}",
        region.name, region.base
    )
}

#[cfg(test)]
mod tests {
    use std::path::Path;

    use super::*;
    use crate::emulator::Property;

    #[test]
    fn the_arguments_are_the_forks_own_with_the_memory_placed_and_the_boot_region_aliased() {
        let command = EmulatorCommand {
            machine: "rigless-armv7m",
            cpu: "cortex-m4",
            properties: vec![Property::new("num-irq", 91u8)],
            icount_shift: 2,
            aliases: vec![Alias {
                region: "flash",
                at: 0,
            }],
        };
        let memory = [
            Region::flash("flash", 0x0800_0000, 2 << 20),
            Region::ram("sram", 0x2000_0000, 192 << 10),
        ];
        let start = Start {
            firmware: Path::new("fw.elf"),
            debugger_port: Some(3333),
            wait_for_debugger: true,
        };
        let rendered: Vec<String> = arguments(&command, &memory, &start)
            .unwrap()
            .into_iter()
            .map(|argument| argument.into_string().unwrap())
            .collect();
        assert_eq!(
            rendered,
            [
                "rigless",
                "-M",
                "rigless-armv7m,num-irq=91",
                "-cpu",
                "cortex-m4",
                "-object",
                "memory-backend-ram,id=flash,size=2097152,share=on",
                "-device",
                "rigless-memory,memdev=flash,base=0x8000000,alias-base=0x0,readonly=on",
                "-object",
                "memory-backend-ram,id=sram,size=196608,share=on",
                "-device",
                "rigless-memory,memdev=sram,base=0x20000000",
                "-kernel",
                "fw.elf",
                "-icount",
                "shift=2,sleep=off,align=off",
                "-nographic",
                "-display",
                "none",
                "-serial",
                "none",
                "-monitor",
                "none",
                "-gdb",
                "tcp::3333",
                "-S",
            ]
        );
    }
}