vj-sim 0.3.0

//! Blocking DPI import-task calls (LRM 1800-2023 35.5.3, 35.7, 35.9).
//!
//! A [`TaskCall`] runs one C import-task call on a [`Fiber`]. When that C
//! code calls an exported SV task which consumes time, the export's thunk
//! calls [`sv_rt_dpi_export_task_call`], which parks the fiber and hands the
//! owner a [`ExportRequest`]: "run export `export` with the argument block
//! at `args`". The owner (the calling process's kernel) spawns the export's
//! task as a child process, copies `args` into its frame, waits for it, copies
//! the `output`/`inout` formals back into `args`, then polls again; the thunk
//! returns and the C code continues. [`TaskCall::poll`] reports
//! [`CallPoll::Finished`] with the import's `int` return (35.9: 0, or 1 when
//! the call was disabled) once the C function returns.
//!
//! `args` points into the parked fiber's own stack, so it stays valid exactly
//! as long as the request is outstanding.

use crate::fiber::{self, Fiber, FiberState};
use std::cell::{Cell, RefCell};
use std::rc::Rc;
use std::sync::atomic::{AtomicPtr, AtomicU8, Ordering};

/// What a parked call is asking the owner to run.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ExportRequest {
    /// The export's index in the program's timed-export table.
    pub export: u32,
    /// The argument block, laid out by the thunk (opaque here).
    pub args: *mut u8,
    /// The `SimHandle` of the instance of the C code's current `svScope`:
    /// the instance the export task runs in.
    pub handle: *mut core::ffi::c_void,
}

/// The outcome of one [`TaskCall::poll`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CallPoll {
    /// The C function returned this `int` (the disable status, 35.9).
    Finished(i32),
    /// The C code is blocked in an export task; see [`ExportRequest`].
    Request(ExportRequest),
}

/// Status [`sv_rt_dpi_export_task_call`] returns when the call was disabled.
pub const EXPORT_CALL_DISABLED: i32 = 1;
/// Status it returns when it ran off a fiber (a task export called from an
/// import *function*, or from C code outside any import call): illegal,
/// LRM 35.5.3 -- only an import task may call a task that consumes time.
pub const EXPORT_CALL_NOT_ON_FIBER: i32 = -1;

#[derive(Default)]
struct Shared {
    request: Cell<Option<ExportRequest>>,
    result: Cell<i32>,
    disabled: Cell<bool>,
    /// Whether the C code called `svAckDisabledState()` in the disabled state.
    acked: Cell<bool>,
    /// Whether the C code is inside an import *task* call (set by the call
    /// site, [`sv_rt_dpi_task_scope`]); an import function is not.
    in_task: Cell<bool>,
    /// The SV name of the import task being called ([`sv_rt_dpi_task_scope`]):
    /// what a `disable` of that task finds the call by (35.9).
    name: RefCell<String>,
}

thread_local! {
    /// The call being resumed on this thread, for the thunk to post to.
    static ACTIVE: RefCell<Option<Rc<Shared>>> = const { RefCell::new(None) };
}

/// One import-task call in flight.
pub struct TaskCall {
    fiber: Fiber,
    shared: Rc<Shared>,
}

// SAFETY: a call is created, polled and dropped by the one simulation thread
// that owns its process; the `Rc` is never shared with another thread (the
// fiber machinery itself is thread-affine for the same reason).
unsafe impl Send for TaskCall {}

impl TaskCall {
    /// Prepares `call` (the C import, returning its `int`) to run on its own
    /// stack at the first [`Self::poll`]. `None` when no stack can be mapped.
    pub fn new(call: impl FnOnce() -> i32 + 'static) -> Option<TaskCall> {
        let shared = Rc::new(Shared::default());
        let s = shared.clone();
        let fiber = Fiber::new(move || s.result.set(call()))?;
        Some(TaskCall { fiber, shared })
    }

    /// Runs the call until it finishes or blocks in an export task.
    pub fn poll(&mut self) -> CallPoll {
        let prev = ACTIVE.with(|a| a.replace(Some(self.shared.clone())));
        let state = self.fiber.resume();
        ACTIVE.with(|a| *a.borrow_mut() = prev);
        match state {
            FiberState::Finished => {
                let unacked = self.shared.disabled.get()
                    && !(self.shared.acked.get() || mirror_state() == MIRROR_ACKED);
                mirror(MIRROR_OFF);
                if unacked {
                    undisabled_return_error(&self.shared.name.borrow());
                }
                CallPoll::Finished(self.shared.result.get())
            }
            FiberState::Yielded => CallPoll::Request(
                self.shared
                    .request
                    .take()
                    .expect("a parked DPI call posted no export request"),
            ),
        }
    }

    /// Marks the call disabled (35.9): the blocked export call returns
    /// [`EXPORT_CALL_DISABLED`] on the next [`Self::poll`], and every export
    /// the C code calls after that returns it at once.
    pub fn disable(&mut self) {
        self.shared.disabled.set(true);
    }

    /// The SV name of the import task this call runs (set while it is inside
    /// the call, empty for a call outside any import task).
    pub fn import_name(&self) -> String {
        self.shared.name.borrow().clone()
    }

    /// Whether the C function has returned.
    pub fn is_finished(&self) -> bool {
        self.fiber.is_finished()
    }
}

/// A flag outside this copy of the crate that mirrors the disabled state: the
/// `vj run-aot` driver answers `svIsDisabledState()` itself, from a
/// library with a copy of this module of its own ([`set_disabled_flag`]).
static MIRROR: AtomicPtr<AtomicU8> = AtomicPtr::new(std::ptr::null_mut());

/// [`MIRROR`] values: no disable, disabled (35.9), disabled and acknowledged
/// by `svAckDisabledState()`.
pub const MIRROR_OFF: u8 = 0;
/// See [`MIRROR_OFF`].
pub const MIRROR_DISABLED: u8 = 1;
/// See [`MIRROR_OFF`].
pub const MIRROR_ACKED: u8 = 2;

/// Mirrors the disabled state of the running call into `flag` from now on.
///
/// # Safety
/// `flag` stays valid for the life of the process.
pub unsafe fn set_disabled_flag(flag: *const AtomicU8) {
    MIRROR.store(flag as *mut AtomicU8, Ordering::Relaxed);
}

fn mirror(state: u8) {
    let p = MIRROR.load(Ordering::Relaxed);
    if !p.is_null() {
        // SAFETY: `set_disabled_flag`'s contract.
        unsafe { (*p).store(state, Ordering::Relaxed) };
    }
}

fn mirror_state() -> u8 {
    let p = MIRROR.load(Ordering::Relaxed);
    if p.is_null() {
        MIRROR_OFF
    } else {
        // SAFETY: `set_disabled_flag`'s contract.
        unsafe { (*p).load(Ordering::Relaxed) }
    }
}

/// `svAckDisabledState()` (35.9) for the call running on this thread.
pub fn ack_disabled_state() {
    FN_DISABLE.with(|f| f.borrow_mut().acked = true);
    ACTIVE.with(|a| {
        if let Some(s) = a.borrow().as_ref() {
            s.acked.set(true);
        }
    });
}

/// 35.9: an import task whose call was disabled must call
/// `svAckDisabledState()` before it returns. Aborts the simulation.
fn undisabled_return_error(name: &str) -> ! {
    eprintln!(
        "error: DPI import task `{name}` was disabled but returned without calling \
         svAckDisabledState() (IEEE 1800-2023 35.9)"
    );
    std::process::abort();
}

/// The `disable` of a block outside the exported function that runs it, while
/// C code is in an import *function* call (LRM 35.9, 9.6.2).
#[derive(Default)]
struct FnDisable {
    /// The block the function disabled; the call site leaves it once the C
    /// call has returned ([`sv_rt_dpi_fn_disable_index`]).
    pending: Option<String>,
    /// Import-function calls in flight ([`sv_rt_dpi_fn_scope`]).
    in_c: u32,
    /// The disable came while C code was running: C must acknowledge it.
    from_c: bool,
    /// The C code called `svAckDisabledState()` in the disabled state.
    acked: bool,
}

thread_local! {
    static FN_DISABLE: RefCell<FnDisable> = RefCell::new(FnDisable::default());
}

/// `void sv_rt_dpi_fn_scope(int on)`: brackets the C call of an import
/// *function* in a design where an exported function disables a block
/// (35.9: the C code then sees the disabled state).
#[cfg_attr(feature = "aot-exports", unsafe(export_name = "sv_rt_dpi_fn_scope"))]
pub extern "C" fn sv_rt_dpi_fn_scope(on: i32) {
    FN_DISABLE.with(|f| {
        let mut f = f.borrow_mut();
        f.in_c = if on != 0 {
            f.in_c + 1
        } else {
            f.in_c.saturating_sub(1)
        };
    });
}

/// `void sv_rt_dpi_fn_disable_set(const char* label)`: `disable label;`
/// executed in a function while the block is not one of its own (LRM 9.6.2):
/// the function goes on to its end and the call site that reaches the block
/// leaves it ([`sv_rt_dpi_fn_disable_index`]). Inside an import-function call
/// this is the disabled state of 35.9 for the C code.
///
/// # Safety
/// `label` is a NUL-terminated string.
#[cfg_attr(
    feature = "aot-exports",
    unsafe(export_name = "sv_rt_dpi_fn_disable_set")
)]
pub unsafe extern "C" fn sv_rt_dpi_fn_disable_set(label: *const core::ffi::c_char) {
    // SAFETY: the caller's contract.
    let label = unsafe { std::ffi::CStr::from_ptr(label) }
        .to_string_lossy()
        .into_owned();
    FN_DISABLE.with(|f| {
        let mut f = f.borrow_mut();
        f.pending = Some(label);
        f.from_c = f.in_c > 0;
        f.acked = false;
        if f.from_c {
            mirror(MIRROR_DISABLED);
        }
    });
}

/// `int64_t sv_rt_dpi_fn_disable_index(const char* labels)`: after a
/// statement that called a subroutine. `labels` are the blocks enclosing the
/// statement, separated by `\n`. Returns the index of the one the call
/// disabled (the statement then leaves it), or -1. A C call that was disabled
/// and returned without `svAckDisabledState()` aborts (35.9).
///
/// # Safety
/// `labels` is a NUL-terminated string.
#[cfg_attr(
    feature = "aot-exports",
    unsafe(export_name = "sv_rt_dpi_fn_disable_index")
)]
pub unsafe extern "C" fn sv_rt_dpi_fn_disable_index(labels: *const core::ffi::c_char) -> i64 {
    let (pending, from_c, acked) = FN_DISABLE.with(|f| {
        let mut f = f.borrow_mut();
        let r = (f.pending.take(), f.from_c, f.acked);
        f.from_c = false;
        f.acked = false;
        r
    });
    let Some(label) = pending else {
        return -1;
    };
    let mirror_acked = mirror_state() == MIRROR_ACKED;
    mirror(MIRROR_OFF);
    if from_c && !(acked || mirror_acked) {
        eprintln!(
            "error: DPI import function was disabled (`disable {label};`) but returned without \
             calling svAckDisabledState() (IEEE 1800-2023 35.9)"
        );
        std::process::abort();
    }
    // SAFETY: the caller's contract.
    let labels = unsafe { std::ffi::CStr::from_ptr(labels) }.to_string_lossy();
    labels
        .split('\n')
        .position(|l| l == label)
        .map_or(-1, |i| i as i64)
}

/// Whether the import-task call running on this thread is in the disabled
/// state (35.9): what `svIsDisabledState()` reports.
pub fn active_call_disabled() -> bool {
    ACTIVE.with(|a| a.borrow().as_ref().is_some_and(|s| s.disabled.get()))
        || FN_DISABLE.with(|f| {
            let f = f.borrow();
            f.from_c && f.pending.is_some()
        })
}

/// `void sv_rt_dpi_task_scope(int on, const char* name)`: brackets the C call of an import
/// *task* (LRM 35.5.3). Only inside such a call may C code call an export
/// task which consumes time; the call site of an import function does not set
/// it, so the same call there is the runtime error of
/// [`EXPORT_CALL_NOT_ON_FIBER`]. `name` is the import task's SV name (null
/// when `on` is 0), which `disable <task>;` of another process matches (35.9).
///
/// # Safety
/// `name` is null or a NUL-terminated string valid for the call.
#[cfg_attr(feature = "aot-exports", unsafe(export_name = "sv_rt_dpi_task_scope"))]
pub unsafe extern "C" fn sv_rt_dpi_task_scope(on: i32, name: *const core::ffi::c_char) {
    if let Some(shared) = ACTIVE.with(|a| a.borrow().clone()) {
        shared.in_task.set(on != 0);
        // The name stays after the call's scope closes, for the 35.9 error.
        if on != 0 && !name.is_null() {
            // SAFETY: the call site passes a NUL-terminated constant, or null.
            *shared.name.borrow_mut() = unsafe { std::ffi::CStr::from_ptr(name) }
                .to_string_lossy()
                .into_owned();
        }
    }
}

/// `void sv_rt_dpi_export_task_error(const char* name)`: the runtime error of
/// a call of the timed export task `name` from outside an import task
/// (LRM 35.5.3: only an import task may wait, an import function may not).
/// Aborts the simulation.
///
/// # Safety
/// `name` is a NUL-terminated string.
#[cfg_attr(
    feature = "aot-exports",
    unsafe(export_name = "sv_rt_dpi_export_task_error")
)]
pub unsafe extern "C" fn sv_rt_dpi_export_task_error(name: *const core::ffi::c_char) {
    // SAFETY: the caller's contract.
    let name = unsafe { std::ffi::CStr::from_ptr(name) }.to_string_lossy();
    eprintln!(
        "error: DPI export task `{name}` consumes time, so it can only be called from an \
         import task (not from an import function): the call would block (IEEE 1800-2023 35.5.3)"
    );
    std::process::abort();
}

/// `int sv_rt_dpi_export_task_call(uint32_t export, void* args, void* handle)`: the call an
/// export thunk of a task that consumes time makes. Blocks the calling
/// import task until the owner has run the export; returns 0, or
/// [`EXPORT_CALL_DISABLED`], or [`EXPORT_CALL_NOT_ON_FIBER`].
///
/// # Safety
/// `args` must stay valid until this call returns (it normally points into
/// the caller's own, parked, stack frame).
#[cfg_attr(
    feature = "aot-exports",
    unsafe(export_name = "sv_rt_dpi_export_task_call")
)]
pub unsafe extern "C" fn sv_rt_dpi_export_task_call(
    export: u32,
    args: *mut u8,
    handle: *mut core::ffi::c_void,
) -> i32 {
    let Some(shared) = ACTIVE.with(|a| a.borrow().clone()) else {
        return EXPORT_CALL_NOT_ON_FIBER;
    };
    if !shared.in_task.get() {
        return EXPORT_CALL_NOT_ON_FIBER;
    }
    if shared.disabled.get() {
        mirror(MIRROR_DISABLED);
        return EXPORT_CALL_DISABLED;
    }
    shared.request.set(Some(ExportRequest {
        export,
        args,
        handle,
    }));
    if !fiber::yield_now() {
        shared.request.set(None);
        return EXPORT_CALL_NOT_ON_FIBER;
    }
    if shared.disabled.get() {
        mirror(MIRROR_DISABLED);
        EXPORT_CALL_DISABLED
    } else {
        0
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn blocking(export: u32, slot: *mut u8) -> i32 {
        unsafe { sv_rt_dpi_task_scope(1, std::ptr::null()) };
        // SAFETY: `slot` outlives the call in every test below.
        unsafe { sv_rt_dpi_export_task_call(export, slot, std::ptr::null_mut()) }
    }

    #[test]
    fn a_call_that_never_blocks_finishes_on_the_first_poll() {
        let mut c = TaskCall::new(|| 7).unwrap();
        assert_eq!(c.poll(), CallPoll::Finished(7));
        assert!(c.is_finished());
    }

    #[test]
    fn a_blocked_call_posts_its_request_and_continues_after_the_next_poll() {
        let mut c = TaskCall::new(|| {
            let mut buf = [1u8, 2, 3, 4];
            let st = blocking(3, buf.as_mut_ptr());
            // The owner writes an output through the block while we are parked.
            assert_eq!(st, 0);
            i32::from(buf[0]) + 100
        })
        .unwrap();
        let CallPoll::Request(r) = c.poll() else {
            panic!("expected a request")
        };
        assert_eq!(r.export, 3);
        // SAFETY: the fiber is parked with the block alive on its stack.
        unsafe { *r.args = 9 };
        assert_eq!(c.poll(), CallPoll::Finished(109));
    }

    #[test]
    fn two_sequential_exports_are_two_requests() {
        let mut c = TaskCall::new(|| {
            let mut b = [0u8; 1];
            blocking(1, b.as_mut_ptr());
            blocking(2, b.as_mut_ptr());
            0
        })
        .unwrap();
        let mut seen = vec![];
        loop {
            match c.poll() {
                CallPoll::Request(r) => seen.push(r.export),
                CallPoll::Finished(v) => {
                    assert_eq!(v, 0);
                    break;
                }
            }
        }
        assert_eq!(seen, [1, 2]);
    }

    #[test]
    fn disable_makes_the_blocked_export_return_the_disabled_status() {
        let mut c = TaskCall::new(|| {
            let mut b = [0u8; 1];
            if blocking(5, b.as_mut_ptr()) == EXPORT_CALL_DISABLED {
                // 35.9: the import returns 1 once it sees the disable.
                // A further export call returns disabled at once.
                assert_eq!(blocking(6, b.as_mut_ptr()), EXPORT_CALL_DISABLED);
                ack_disabled_state();
                return 1;
            }
            0
        })
        .unwrap();
        assert!(matches!(c.poll(), CallPoll::Request(_)));
        c.disable();
        assert_eq!(c.poll(), CallPoll::Finished(1));
    }

    #[test]
    fn two_concurrent_blocked_calls_resume_independently() {
        let mk = |tag: i32| {
            TaskCall::new(move || {
                let mut b = [0u8; 1];
                blocking(tag as u32, b.as_mut_ptr());
                tag * 10
            })
            .unwrap()
        };
        let (mut a, mut b) = (mk(1), mk(2));
        assert!(matches!(a.poll(), CallPoll::Request(r) if r.export == 1));
        assert!(matches!(b.poll(), CallPoll::Request(r) if r.export == 2));
        assert_eq!(b.poll(), CallPoll::Finished(20));
        assert_eq!(a.poll(), CallPoll::Finished(10));
    }

    #[test]
    fn an_export_task_called_from_an_import_function_is_refused() {
        // On a fiber, but outside an import task's scope bracket (an import
        // function): the thunk gets the not-on-fiber status, no request.
        let mut c = TaskCall::new(|| {
            let mut b = [0u8; 1];
            // SAFETY: `b` outlives the call.
            unsafe { sv_rt_dpi_export_task_call(0, b.as_mut_ptr(), std::ptr::null_mut()) }
        })
        .unwrap();
        assert_eq!(c.poll(), CallPoll::Finished(EXPORT_CALL_NOT_ON_FIBER));
    }

    #[test]
    fn an_export_task_called_off_a_fiber_is_refused() {
        let mut b = [0u8; 1];
        assert_eq!(blocking(0, b.as_mut_ptr()), EXPORT_CALL_NOT_ON_FIBER);
    }
}

#[cfg(test)]
mod ack_tests {
    use super::*;

    #[test]
    fn ack_before_returning_disabled_is_recorded() {
        let mut c = TaskCall::new(|| {
            let mut b = [0u8; 1];
            // SAFETY: `b` outlives the call.
            unsafe { sv_rt_dpi_task_scope(1, std::ptr::null()) };
            let st = unsafe { sv_rt_dpi_export_task_call(1, b.as_mut_ptr(), std::ptr::null_mut()) };
            assert_eq!(st, EXPORT_CALL_DISABLED);
            assert!(active_call_disabled());
            ack_disabled_state();
            1
        })
        .unwrap();
        assert!(matches!(c.poll(), CallPoll::Request(_)));
        c.disable();
        assert_eq!(c.poll(), CallPoll::Finished(1));
    }
}