vj_sim/state/

event_pool.rs

//! The event pool: event handles (LRM 1800-2023 15.5.2 - 15.5.5).
//!
//! A named event is an object; an `event` variable holds a handle to one. The
//! handle can be re-pointed by assignment (`e1 = e2` merges: both then name
//! the same object), cleared (`e = null`), compared (`e1 == e2`, `e == null`),
//! passed to a task, and an automatic `event` (a local of an automatic block
//! or task, an automatic task's formal, a local `event` array) is a new
//! object each time it is declared.
//!
//! None of that fits an event being one fixed STATE cell, so an instance body
//! that uses any of it ([`event_pool`]) keeps all its events in one hidden
//! memory of 128-bit event cells -- the layout of an event array's rows
//! (`state::EVENT_CELL_WIDTH`) -- addressed by an object id, the row number:
//!
//! - row 0 holds the dynamic allocation counter; id 0 is `null`;
//! - rows `1..=S` are the body's static event variables (`S` =
//!   [`EventPool::static_rows`]), an array's elements consecutive;
//! - rows `S+1..=2S` are the *handle cells* of those, row `S + id`: a static
//!   event variable's own handle, 0 until it is assigned (it names itself),
//!   then the target's id (all ones: `null`);
//! - the rest ([`EventPool::dynamic_base`] on) are the objects the automatic
//!   events of the running processes are allocated, one per declaration
//!   executed ([`DYNAMIC_ROWS`] in all).
//!
//! An automatic event variable is a 64-bit object id in the process frame.
//! A wait, a trigger, `.triggered` and `->>` all resolve the event expression
//! to an object id and act on that row (the per-element machinery of an
//! event array's rows).
//!
//! The pool's legacy per-variable cells are still laid out (so every other
//! consumer of the signal map keeps working), but a body in pool mode reads
//! and writes its events only through the pool: a hierarchical reference
//! from ANOTHER instance's code to such an event does not see the pool.

use sv_lang::kinds::{ExpressionKind, SymbolKind};
use sv_lang::{Symbol, Type};

use crate::symid::SymbolId;

/// Rows of the pool for the automatic events allocated at run time. An
/// allocation past them is a loud runtime error, never a reused object.
pub const DYNAMIC_ROWS: u32 = 1 << 14;

/// One static event variable (or array of them) of the pool.
#[derive(Clone, Copy)]
pub struct PoolStatic<'d> {
    pub var: Symbol<'d>,
    /// The object id of its (first) event.
    pub first: u32,
    /// How many events: 1, or an array's element count.
    pub count: u32,
}

/// An instance body's event pool.
pub struct EventPool<'d> {
    pub statics: Vec<PoolStatic<'d>>,
    /// `S`: the number of static event objects.
    pub static_rows: u32,
}

impl EventPool<'_> {
    /// Rows of the pool memory.
    pub fn total_rows(&self) -> u32 {
        self.dynamic_base() + DYNAMIC_ROWS
    }

    /// The first dynamic object id.
    pub fn dynamic_base(&self) -> u32 {
        2 * self.static_rows + 1
    }
}

/// The signal-map key of the pool memory itself.
pub fn pool_key() -> SymbolId {
    SymbolId::synthetic_tagged("event_pool")
}

/// The signal-map key of peer `j`'s pool (group mode, see
/// `event_plan::group_mode`): the pool memory of the `j`-th pool-mode instance,
/// as that instance's tag `j + 1` names it. Registered in EVERY pool-mode
/// instance (its own pool under its own tag too).
pub fn peer_key(j: u32) -> SymbolId {
    SymbolId::synthetic_tagged(&format!("event_pool_peer{j}"))
}

/// The signal-map key of the pool entry of static event variable `var`: a
/// memory entry sharing the pool's slot, `num_rows` its event count and
/// `lower_index` the id of its first event.
pub fn static_key(var: &SymbolId) -> SymbolId {
    var.derive("event_pool_static")
}

/// The signal-map key of the pool entry as seen from static event variable
/// `var`: the pool's memory (`lower_index` = `S`, the static count) under a
/// key unique to the variable, so another instance that names `var`
/// hierarchically (`s.ev`) can register the pool of the instance that owns it
/// beside [`static_key`] (the pool's own key, [`pool_key`], is the same in
/// every body).
pub fn pool_of_key(var: &SymbolId) -> SymbolId {
    var.derive("event_pool_of")
}

/// The number of events `ty` holds when it is an event or a fixed-size
/// array of events; `None` for any other type.
pub fn event_count(ty: &Type<'_>) -> Option<u32> {
    let mut rows: u32 = 1;
    let mut cur = *ty;
    while cur.is_unpacked_array() && !super::storage::is_collection(&cur) {
        rows = rows.checked_mul(cur.fixed_unpacked_array_range().width())?;
        cur = cur.element_type()?;
    }
    cur.is_event().then_some(rows)
}

/// The pool of `body`'s events, when its code needs one: it declares an
/// event formal or an automatic event (variable or array), assigns an event
/// or compares one.
pub fn event_pool<'d>(body: &Symbol<'d>) -> Option<EventPool<'d>> {
    if !needs_pool(body) && !super::event_plan::plan_forces_pool(body) {
        return None;
    }
    let mut statics = Vec::new();
    let mut next: u32 = 1;
    for v in crate::netlist::state_items(body) {
        if !matches!(v.kind(), SymbolKind::Variable | SymbolKind::FormalArgument) {
            continue;
        }
        let Some(count) = v.value_type().as_ref().and_then(event_count) else {
            continue;
        };
        statics.push(PoolStatic {
            var: v,
            first: next,
            count,
        });
        next += count;
    }
    Some(EventPool {
        statics,
        static_rows: next - 1,
    })
}

/// The static event variable that event expression `e` names through a
/// hierarchical reference (`s.ev`, `s.ea[i]`) when its instance keeps its
/// events in a pool ([`event_pool`]); `None` for anything else.
///
/// A pool-mode body reads and writes its events only through the pool (module
/// docs), so another instance's trigger, `.triggered` or wait on the legacy
/// cell would be silently lost: the callers refuse the construct by name.
pub fn hierarchical_pool_event<'d>(e: &sv_lang::Expression<'d>) -> Option<Symbol<'d>> {
    let mut e = *e;
    loop {
        if e.kind() == ExpressionKind::Conversion
            && let Some(inner) = e.conversion_operand()
        {
            e = inner;
        } else if e.kind() == ExpressionKind::ElementSelect
            && let Some(base) = e.select_value()
        {
            e = base;
        } else {
            break;
        }
    }
    if e.kind() != ExpressionKind::HierarchicalValue {
        return None;
    }
    let sym = e.referenced_symbol()?;
    if !sym.value_type().as_ref().and_then(event_count).is_some() {
        return None;
    }
    let owner = crate::netlist::enclosing_instance_body(&sym)?;
    event_pool(&owner).is_some().then_some(sym)
}

pub(super) fn needs_pool(body: &Symbol<'_>) -> bool {
    let automatic_event = |v: &Symbol<'_>| {
        matches!(v.kind(), SymbolKind::Variable | SymbolKind::FormalArgument)
            && v.value_type().as_ref().and_then(event_count).is_some()
            && (v.kind() == SymbolKind::FormalArgument
                || v.variable_lifetime() != sv_lang::VariableLifetime::Static)
    };
    for m in crate::netlist::module_items(body) {
        let kind = m.kind();
        if kind == SymbolKind::Subroutine && m.members().any(|v| automatic_event(&v)) {
            return true;
        }
        if kind != SymbolKind::Subroutine && kind != SymbolKind::ProceduralBlock {
            continue;
        }
        let Some(code) = crate::process::cfg::proc_body(&m) else {
            continue;
        };
        let mut stack = vec![code.as_sem_node()];
        while let Some(n) = stack.pop() {
            if let Some(s) = n.as_statement()
                && crate::process::cfg::block_scopes(&s)
                    .iter()
                    .any(|block| block.members().any(|v| automatic_event(&v)))
            {
                return true;
            }
            // `if (e)`, `while (e)`: an event as a condition (15.5.5.3).
            if let Some(s) = n.as_statement()
                && let Some(mut c) = s.condition()
            {
                while c.kind() == ExpressionKind::Conversion
                    && let Some(x) = c.conversion_operand()
                {
                    c = x;
                }
                if c.expr_type().is_some_and(|t| t.is_event()) {
                    return true;
                }
            }
            if let Some(e) = n.as_expression() {
                let event_typed = |x: Option<sv_lang::Expression<'_>>| {
                    x.and_then(|x| x.expr_type()).is_some_and(|t| t.is_event())
                };
                match e.kind() {
                    ExpressionKind::Assignment if event_typed(e.left()) => return true,
                    ExpressionKind::BinaryOp if event_typed(e.left()) || event_typed(e.right()) => {
                        return true;
                    }
                    ExpressionKind::UnaryOp if event_typed(e.operand()) => return true,
                    // `if (e)`: an event in a Boolean context (15.5.5.3).
                    ExpressionKind::Conversion
                        if event_typed(e.conversion_operand()) && !event_typed(Some(e)) =>
                    {
                        return true;
                    }
                    _ => {}
                }
            }
            stack.extend(crate::process::cfg::live_children(&n));
        }
    }
    false
}