vj-codegen 0.1.0

//! Virtual interfaces (LRM 1800-2023 §25.9).
//!
//! A virtual interface value is an interface instance's id
//! (`sv_sim_sim::netlist::vif`: 1 + its position among its definition's
//! instances, 0 for `null`), held like a `chandle` -- a 2-state 64-bit
//! value. `vif.m` names member `m` of every candidate instance at once: a
//! process or subroutine naming it has all of them among its external
//! signals (`sv-sim-bin`'s `run` adds them as foreign signals), primed into
//! `cx.locals` like any other. A read selects the one the id names; a write
//! targets each candidate with every one but the selected one suppressed.
//! An event control on `vif.m` waits on the selected candidate only
//! (`process_lower`: the kernel returns a resume key carrying the id,
//! [`suspend_key`], one wait per candidate).

use inkwell::IntPredicate;
use inkwell::values::IntValue;
use sv_lang::Expression;
use sv_sim_sim::netlist::vif;
use sv_sim_sim::symid::SymbolUid;

use crate::error::LoweringError;
use crate::expr::{LowerCtx, LoweredValue, lower_expr};
use crate::ops::OpBuilder;
use crate::select::{Lvalue, LvalueRoot, RootMode};
use crate::types::TypeWidth;
use crate::value::PackedValue;

/// The bit a resume key keeps its virtual interface id above (a segment id
/// is far below it): see [`suspend_key`].
pub const KEY_SHIFT: u32 = 20;

/// The id (an `i64`) of the virtual interface `base`, being used: a `null`
/// one is a fatal run-time error (LRM 1800-2023 §25.9) that ends the
/// process here.
fn id_of<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    base: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let pv = lower_expr(cx, base)?.into_packed("a virtual interface", &cx.fn_sym)?;
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    let v = op.lane_val(pv);
    let id = if pv.width == 64 {
        v
    } else {
        cx.b.build_int_z_extend_or_bit_cast(v, cx.ctx.i64_type(), "vif_id")
            .unwrap()
    };
    let is_null =
        cx.b.build_int_compare(
            IntPredicate::EQ,
            id,
            cx.ctx.i64_type().const_zero(),
            "vif_null",
        )
        .unwrap();
    let r = base.source_range();
    let name = sv_sim_sim::process::cfg::source_text_range(r)
        .unwrap_or_else(|| "a virtual interface".to_string());
    crate::stmt_shared::fatal_if(
        cx,
        is_null,
        r.start,
        &format!("null virtual interface {name} used"),
    )?;
    Ok(id)
}

/// `inst` (an interface instance) as a virtual interface value.
pub(crate) fn instance_value<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    inst: &sv_lang::Symbol<'_>,
) -> Option<LoweredValue<'ctx>> {
    let id = vif::instance_id(inst)?;
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    Some(LoweredValue::Packed(op.pack(
        op.i_n(64).const_int(id, false),
        op.i_n(64).const_zero(),
        64,
        cx.repr,
        false,
    )))
}

/// The cell of candidate event member `sym` of a virtual interface.
fn event_cell<'ctx>(
    cx: &LowerCtx<'ctx, '_, '_>,
    sym: &sv_lang::Symbol<'_>,
    what: &str,
) -> Result<inkwell::values::PointerValue<'ctx>, LoweringError> {
    let (ptr, width, _) = *cx.locals.get(&sym.uid()).ok_or_else(|| {
        LoweringError::unsupported_at(
            &format!("{what}: a virtual interface event this process cannot reach"),
            sym,
        )
    })?;
    if width != sv_sim_sim::state::EVENT_CELL_WIDTH {
        return Err(LoweringError::unsupported_at(
            &format!("{what}: a virtual interface member that is not a named event"),
            sym,
        ));
    }
    Ok(ptr)
}

/// `-> vif.ev` (LRM 1800-2023 15.5.1, 25.9): triggers the event of the
/// instance the virtual interface selects; `null` is the fatal error of
/// [`id_of`].
pub(crate) fn event_trigger<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
) -> Result<(), LoweringError> {
    let targets = vif::member_targets(&target).ok_or_else(|| {
        LoweringError::unsupported_at("a virtual interface event trigger", &cx.fn_sym)
    })?;
    let base = vif::base(&target).ok_or_else(|| {
        LoweringError::unsupported_at("a virtual interface event trigger", &cx.fn_sym)
    })?;
    let id = id_of(cx, base)?;
    let f =
        cx.b.get_insert_block()
            .and_then(|bb| bb.get_parent())
            .expect("lowering happens inside a function");
    let merge = cx.ctx.append_basic_block(f, "vif_ev_done");
    let w = sv_sim_sim::state::EVENT_CELL_WIDTH;
    let packed_ty = crate::types::int_type(cx.ctx, w * 2);
    for (k, t) in targets.into_iter().enumerate() {
        let Some(sym) = t else { continue };
        let ptr = event_cell(cx, &sym, "-> (event trigger)")?;
        let arm = cx.ctx.append_basic_block(f, "vif_ev");
        let next = cx.ctx.append_basic_block(f, "vif_ev_next");
        let hit =
            cx.b.build_int_compare(
                IntPredicate::EQ,
                id,
                cx.ctx.i64_type().const_int(k as u64 + 1, false),
                "vif_ev_hit",
            )
            .unwrap();
        cx.b.build_conditional_branch(hit, arm, next).unwrap();
        cx.b.position_at_end(arm);
        let cur =
            cx.b.build_load(packed_ty, ptr, "event_cur")
                .unwrap()
                .into_int_value();
        let packed = crate::expr::event_triggered_value(cx, cur);
        cx.b.build_store(ptr, packed).unwrap();
        crate::expr::write_through_store(cx, ptr);
        cx.b.build_unconditional_branch(merge).unwrap();
        cx.b.position_at_end(next);
    }
    cx.b.build_unconditional_branch(merge).unwrap();
    cx.b.position_at_end(merge);
    Ok(())
}

/// `vif.ev.triggered` (LRM 15.5.3): 1 iff the selected instance's event was
/// triggered in the current time step (an `i1`).
pub(crate) fn event_triggered<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
) -> Result<IntValue<'ctx>, LoweringError> {
    let targets = vif::member_targets(&target).ok_or_else(|| {
        LoweringError::unsupported_at("a virtual interface event .triggered", &cx.fn_sym)
    })?;
    let base = vif::base(&target).ok_or_else(|| {
        LoweringError::unsupported_at("a virtual interface event .triggered", &cx.fn_sym)
    })?;
    let id = id_of(cx, base)?;
    let w = sv_sim_sim::state::EVENT_CELL_WIDTH;
    let packed_ty = crate::types::int_type(cx.ctx, w * 2);
    let mut acc = cx.ctx.bool_type().const_zero();
    for (k, t) in targets.into_iter().enumerate() {
        let Some(sym) = t else { continue };
        let ptr = event_cell(cx, &sym, ".triggered")?;
        let cur =
            cx.b.build_load(packed_ty, ptr, "event_cur")
                .unwrap()
                .into_int_value();
        let stamped = crate::expr::event_stamped_now(cx, cur);
        let sel =
            cx.b.build_int_compare(
                IntPredicate::EQ,
                id,
                cx.ctx.i64_type().const_int(k as u64 + 1, false),
                "vif_ev_sel",
            )
            .unwrap();
        let both = cx.b.build_and(stamped, sel, "vif_ev_both").unwrap();
        acc = cx.b.build_or(acc, both, "vif_ev_acc").unwrap();
    }
    Ok(acc)
}

/// `target` as an element of an event array member of a virtual interface
/// (`vif.ea[i]`): the virtual interface and every candidate's own member
/// array, in id order. `None` for anything else.
fn event_elem_targets<'d>(
    target: &Expression<'d>,
) -> Option<(Expression<'d>, Vec<Option<sv_lang::Symbol<'d>>>)> {
    if target.kind() != sv_lang::kinds::ExpressionKind::ElementSelect
        || !target.expr_type().is_some_and(|t| t.is_event())
    {
        return None;
    }
    let root = nested_root(target)?;
    Some((vif::base(&root)?, vif::member_targets(&root)?))
}

/// Runs `f` on element `target` (`vif.ea[i]`) of each candidate instance's
/// event array, its `valid` already narrowed to the candidate the id
/// selects. `None` if `target` is not such an element.
fn each_event_elem<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
    f: &mut dyn FnMut(usize, crate::arrays::EventElem<'ctx>) -> Result<(), LoweringError>,
) -> Option<Result<(), LoweringError>> {
    let (base, targets) = event_elem_targets(&target)?;
    Some((|| {
        let _once = hoist_selectors(cx, &target, targets.iter().flatten().count())?;
        let id = id_of(cx, base)?;
        for (k, t) in targets.iter().enumerate() {
            if t.is_none() {
                continue;
            }
            let prev = PICK.with(|p| p.replace(Some(k)));
            let el = crate::arrays::resolve_event_element(cx, target);
            PICK.with(|p| p.set(prev));
            let Some(mut el) = el? else {
                return Err(LoweringError::unsupported_at(
                    "an element of a virtual interface event array this process cannot reach",
                    &cx.fn_sym,
                ));
            };
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_ev_hit",
                )
                .unwrap();
            el.valid = cx.b.build_and(el.valid, hit, "vif_ev_sel").unwrap();
            f(k, el)?;
        }
        Ok(())
    })())
}

/// `-> vif.ea[i]` (LRM 1800-2023 15.5.1, 25.9, 7.4.6): triggers the element
/// of the selected instance's array; an index that is unknown or out of
/// range triggers nothing. `None` if `target` is not such an element.
pub(crate) fn event_elem_trigger<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
) -> Option<Result<(), LoweringError>> {
    each_event_elem(cx, target, &mut |_, el| {
        crate::arrays::when_valid(cx, el.valid, || {
            let cur = crate::arrays::load_event_elem(cx, &el)?;
            let triggered = crate::expr::event_triggered_value(cx, cur);
            crate::arrays::store_event_elem(cx, &el, triggered)
        })
    })
}

/// `vif.ea[i].triggered` (LRM 15.5.3): an `i1`, false for an unknown or
/// out-of-range index (`null` is fatal, [`id_of`]). `None` if `target` is
/// not a `vif.ea[i]`.
pub(crate) fn event_elem_triggered<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
) -> Option<Result<IntValue<'ctx>, LoweringError>> {
    let acc = std::cell::Cell::new(cx.ctx.bool_type().const_zero());
    let r = each_event_elem(cx, target, &mut |_, el| {
        let cur = crate::arrays::load_event_elem(cx, &el)?;
        let stamped = crate::expr::event_stamped_now(cx, cur);
        let both = cx.b.build_and(stamped, el.valid, "vif_ev_both").unwrap();
        acc.set(cx.b.build_or(acc.get(), both, "vif_ev_acc").unwrap());
        Ok(())
    })?;
    Some(r.map(|()| acc.get()))
}

/// `vif.m`'s value (`e`): the selected candidate's `m` (`x` for `null`).
/// `None` if `e` is not such an access.
pub(crate) fn read<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let targets = vif::member_targets(&e)?;
    Some((|| {
        let ty = e.expr_type().ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface member with no type", &cx.fn_sym)
        })?;
        let width = ty.value_width();
        let base = vif::base(&e).ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
        })?;
        let id = id_of(cx, base)?;
        let op = OpBuilder {
            ctx: cx.ctx,
            b: &cx.b,
        };
        // A whole fixed-size array member (`la = vif.a`): its flat packed
        // value (`arrays::pack_array_value`), each candidate's own rows.
        if ty.is_unpacked_array() && !sv_sim_sim::state::storage::is_collection(&ty) {
            let mut acc: Option<PackedValue<'ctx>> = None;
            for (k, target) in targets.iter().enumerate() {
                if target.is_none() {
                    continue;
                }
                let prev = PICK.with(|p| p.replace(Some(k)));
                let v = crate::arrays::pack_array_value(cx, e);
                PICK.with(|p| p.set(prev));
                let v = v?;
                let hit =
                    cx.b.build_int_compare(
                        IntPredicate::EQ,
                        id,
                        cx.ctx.i64_type().const_int(k as u64 + 1, false),
                        "vif_hit",
                    )
                    .unwrap();
                let base = acc.unwrap_or(v);
                acc = Some(op.select(hit, v, base));
            }
            return acc.map(LoweredValue::Packed).ok_or_else(|| {
                LoweringError::unsupported_at("a virtual interface array member", &cx.fn_sym)
            });
        }
        let mut acc = PackedValue {
            llvm: crate::arrays::default_value(cx, &ty),
            width,
            repr: cx.repr,
            signed: ty.is_signed(),
        };
        for (k, target) in targets.iter().enumerate() {
            let Some(sym) = target else {
                continue;
            };
            let (ptr, w, signed) = *cx.locals.get(&sym.uid()).ok_or_else(|| {
                LoweringError::unsupported_at(
                    "a virtual interface member this process cannot reach",
                    sym,
                )
            })?;
            let llvm =
                cx.b.build_load(op.packed_type(w, cx.repr), ptr, "vif_m")
                    .unwrap()
                    .into_int_value();
            let v = crate::select::fit_width(
                &op,
                PackedValue {
                    llvm,
                    width: w,
                    repr: cx.repr,
                    signed,
                },
                width,
            );
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_hit",
                )
                .unwrap();
            acc = op.select(hit, v, acc);
        }
        Ok(if ty.is_floating() {
            LoweredValue::Real(crate::real::bits_to_real(cx, acc))
        } else if ty.is_string() {
            LoweredValue::Str(crate::strings::from_storage(cx, acc))
        } else {
            LoweredValue::Packed(PackedValue {
                signed: ty.is_signed(),
                ..acc
            })
        })
    })())
}

/// For `vif.a[i]...` (`e`, element selects only) where `a` is a fixed-size
/// unpacked array member: the `vif.a` access's candidate `a`s, in id order.
/// `None` if `e` is not rooted that way.
fn array_member_targets<'d>(e: &Expression<'d>) -> Option<Vec<Option<sv_lang::Symbol<'d>>>> {
    let mut cur = *e;
    if cur.kind() != sv_lang::kinds::ExpressionKind::ElementSelect {
        return None;
    }
    while cur.kind() == sv_lang::kinds::ExpressionKind::ElementSelect {
        cur = cur.select_value()?;
        // A bit-select of an element (`vif.a[i][3]`) is not an element.
        if !cur.expr_type()?.is_unpacked_array() {
            return None;
        }
    }
    let ty = cur.expr_type()?;
    if !ty.is_unpacked_array() || sv_sim_sim::state::storage::is_collection(&ty) {
        return None;
    }
    vif::member_targets(&cur)
}

/// `vif.a[i]`'s value (`e`, LRM 1800-2023 25.9 with 7.4): the selected
/// candidate's element. Every candidate lowers the index expressions
/// itself (an index with a side effect is evaluated once per candidate).
/// `None` if `e` is not a fully indexed array member of a virtual interface.
pub(crate) fn read_element<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<LoweredValue<'ctx>, LoweringError>> {
    let targets = array_member_targets(&e)?;
    Some((|| {
        let op = OpBuilder {
            ctx: cx.ctx,
            b: &cx.b,
        };
        let _once = hoist_selectors(cx, &e, targets.iter().flatten().count())?;
        let id = id_of(cx, root_base(cx, &e)?)?;
        let mut acc: Option<PackedValue<'ctx>> = None;
        for (k, target) in targets.iter().enumerate() {
            let Some(sym) = target else {
                continue;
            };
            let Some(r) = crate::arrays::resolve_element_in(cx, e, Some(sym))? else {
                return Err(LoweringError::unsupported_at(
                    "a virtual interface array member that is not a fully indexed element",
                    &cx.fn_sym,
                ));
            };
            let v = crate::arrays::read_element(cx, &r)?;
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_hit",
                )
                .unwrap();
            let base = acc.unwrap_or(PackedValue {
                llvm: r.default,
                ..v
            });
            acc = Some(op.select(hit, v, base));
        }
        let acc = acc.ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface array member", &cx.fn_sym)
        })?;
        Ok(LoweredValue::Packed(acc))
    })())
}

/// The virtual interface expression under `vif.a[i]...` (`e`).
fn root_base<'d>(
    cx: &LowerCtx<'_, 'd, '_>,
    e: &Expression<'d>,
) -> Result<Expression<'d>, LoweringError> {
    let mut cur = *e;
    while cur.kind() == sv_lang::kinds::ExpressionKind::ElementSelect {
        cur = cur.select_value().ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface element select", &cx.fn_sym)
        })?;
    }
    vif::base(&cur).ok_or_else(|| {
        LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
    })
}

thread_local! {
    /// While a write target nested under `vif.m` is resolved once per
    /// candidate ([`nested_lvalues`]): the index of the candidate instance
    /// (in id order) every `vif.m` access inside it names.
    static PICK: std::cell::Cell<Option<usize>> = const { std::cell::Cell::new(None) };
}

/// `vif.m`'s candidate symbol while a nested target is resolved for one
/// candidate (see [`PICK`]); `None` outside that or if `e` is no `vif.m`.
pub(crate) fn picked_symbol<'d>(e: &Expression<'d>) -> Option<sv_lang::Symbol<'d>> {
    let k = PICK.with(std::cell::Cell::get)?;
    vif::member_targets(e)?.into_iter().nth(k)?
}

/// `e` as a write-target root: when `e` is `vif.m`, its storage under the
/// candidate [`PICK`] names. A `vif.m` reaching here with no candidate
/// picked would be mistaken for a field of the variable holding the
/// interface id, so it is refused by name. `None` if `e` is no `vif.m`.
pub(crate) fn picked_lvalue<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
    mode: RootMode<'_>,
) -> Option<Result<Lvalue<'ctx>, LoweringError>> {
    if !vif::is_member_access(&e) {
        return None;
    }
    let Some(sym) = picked_symbol(&e) else {
        return Some(Err(LoweringError::unsupported_at(
            "a virtual interface member as this kind of assignment target",
            &cx.fn_sym,
        )));
    };
    Some(candidate_lvalue(cx, &sym, mode))
}

/// The storage of candidate member `sym` as a write root.
fn candidate_lvalue<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    sym: &sv_lang::Symbol<'d>,
    mode: RootMode<'_>,
) -> Result<Lvalue<'ctx>, LoweringError> {
    let op = OpBuilder {
        ctx: cx.ctx,
        b: &cx.b,
    };
    // A clock variable (`vif.cb.d <= v`) drives the signal it names.
    let driven = (sym.kind() == sv_lang::kinds::SymbolKind::ClockVar)
        .then(|| sym.initializer().and_then(|e| e.referenced_symbol()))
        .flatten();
    let sym = driven.as_ref().unwrap_or(sym);
    let unreachable = || {
        LoweringError::unsupported_at("a virtual interface member this process cannot reach", sym)
    };
    let (root, width, signed) = match mode {
        RootMode::Shadow => {
            let (ptr, w, s) = *cx.locals.get(&sym.uid()).ok_or_else(unreachable)?;
            (LvalueRoot::Shadow { ptr }, w, s)
        }
        RootMode::Signal(signals) => {
            let info = signals.get(&sym.uid()).copied().ok_or_else(unreachable)?;
            (
                LvalueRoot::Signal { slot: info.slot },
                info.width,
                info.signed,
            )
        }
    };
    Ok(Lvalue {
        root,
        root_width: width,
        root_signed: signed,
        lo: op.i_n(width).const_zero(),
        width,
        bad: cx.ctx.bool_type().const_zero(),
        edge: None,
        pad: None,
    })
}

/// The `vif.m` access (not `lhs` itself) at the root of the select / field
/// chain `lhs` (`vif.m[i].f[3:0]`, `vif.a[i][j]`).
fn nested_root<'d>(lhs: &Expression<'d>) -> Option<Expression<'d>> {
    use sv_lang::kinds::ExpressionKind as K;
    if vif::is_member_access(lhs) {
        return None;
    }
    let mut cur = *lhs;
    loop {
        let kind = cur.kind();
        if matches!(kind, K::ElementSelect | K::RangeSelect) {
            cur = cur.select_value()?;
        } else if kind == K::MemberAccess && vif::is_member_access(&cur) {
            return Some(cur);
        } else if kind == K::MemberAccess {
            cur = cur.operand()?;
        } else {
            return None;
        }
    }
}

/// A hoisted index: its span, LLVM value, width, representation, signedness.
type HoistedIndex = (
    (u64, u64),
    llvm_sys::prelude::LLVMValueRef,
    u32,
    crate::value::ValueRepr,
    bool,
);

thread_local! {
    /// Select indices of the access being lowered that run code (`a[k++]`),
    /// evaluated once ahead of the per-candidate lowering
    /// ([`hoist_selectors`]): the source span they stand at, and the value
    /// as raw LLVM parts (the thread-local cannot name the context lifetime).
    static HOISTED: std::cell::RefCell<Vec<HoistedIndex>> =
        const { std::cell::RefCell::new(Vec::new()) };
}

/// Drops the hoisted indices of one access when it goes out of scope.
pub(crate) struct Hoisted(usize);

impl Drop for Hoisted {
    fn drop(&mut self) {
        HOISTED.with(|h| h.borrow_mut().truncate(self.0));
    }
}

fn span_key(e: &Expression<'_>) -> (u64, u64) {
    let r = e.source_range();
    (r.start.offset, r.end.offset)
}

/// The value of select index `e` if [`hoist_selectors`] already evaluated it.
pub(crate) fn hoisted<'ctx>(e: &Expression<'_>) -> Option<LoweredValue<'ctx>> {
    HOISTED.with(|h| {
        let h = h.borrow();
        if h.is_empty() {
            return None;
        }
        let key = span_key(e);
        h.iter()
            .rev()
            .find(|x| x.0 == key)
            .map(|&(_, v, width, repr, signed)| {
                // SAFETY: the value was an `IntValue` of this same function,
                // stored by `hoist_selectors` and dropped with its guard.
                let llvm = unsafe { IntValue::new(v) };
                LoweredValue::Packed(PackedValue {
                    llvm,
                    width,
                    repr,
                    signed,
                })
            })
    })
}

/// A select index along the chain `lhs` that runs code (`v.a[k++]`) would
/// run once per candidate instance when `lhs` is lowered for each: with
/// several candidates every such index is evaluated here once, in source
/// order, and the per-candidate lowering reads the result ([`hoisted`]).
fn hoist_selectors<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: &Expression<'d>,
    candidates: usize,
) -> Result<Hoisted, LoweringError> {
    let guard = hoist_begin();
    if candidates <= 1 {
        return Ok(guard);
    }
    // The chain was walked outside-in; evaluate innermost (leftmost) first.
    for p in side_effect_selectors(lhs).0.into_iter().rev() {
        let pv = lower_expr(cx, p)?.into_packed("a select index", &cx.fn_sym)?;
        hoist_push(&p, pv);
    }
    Ok(guard)
}

/// A guard that drops every index hoisted after this call.
pub(crate) fn hoist_begin() -> Hoisted {
    Hoisted(HOISTED.with(|h| h.borrow().len()))
}

/// Registers `pv` as the value of `p` for [`hoisted`].
pub(crate) fn hoist_push(p: &Expression<'_>, pv: PackedValue<'_>) {
    use inkwell::values::AsValueRef;
    let raw = pv.llvm.as_value_ref();
    HOISTED.with(|h| {
        h.borrow_mut()
            .push((span_key(p), raw, pv.width, pv.repr, pv.signed));
    });
}

/// The select indices along the access chain `lhs` (`v.a[k++]`, outside-in)
/// that run code, and the expression the chain ends in when that is not a
/// plain name (a call returning the handle `f().x[1]` selects from).
pub(crate) fn side_effect_selectors<'d>(
    lhs: &Expression<'d>,
) -> (Vec<Expression<'d>>, Expression<'d>) {
    use sv_lang::kinds::ExpressionKind as K;
    let mut parts = Vec::new();
    let mut cur = *lhs;
    loop {
        let kind = cur.kind();
        if matches!(kind, K::ElementSelect | K::RangeSelect) {
            for p in [cur.selector(), cur.range_left(), cur.range_right()]
                .into_iter()
                .flatten()
            {
                if crate::classes::has_side_effects(p) {
                    parts.push(p);
                }
            }
            match cur.select_value() {
                Some(n) => cur = n,
                None => break,
            }
        } else if kind == K::MemberAccess {
            match cur.operand() {
                Some(n) => cur = n,
                None => break,
            }
        } else {
            break;
        }
    }
    (parts, cur)
}

/// The targets of a write to a part of `vif.m` (`lhs` = `vif.m[i]`,
/// `vif.m.f`, `vif.a[i][3:0]`, ...): `lhs` resolved once per candidate
/// instance, each suppressed unless it is the one the id selects. An index
/// with a side effect would run once per candidate: refused by name. `None`
/// if `lhs` is not rooted at a `vif.m`.
pub(crate) fn nested_lvalues<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    mode: RootMode<'_>,
) -> Option<Result<Vec<Lvalue<'ctx>>, LoweringError>> {
    let root = nested_root(&lhs)?;
    let targets = vif::member_targets(&root)?;
    Some((|| {
        let _once = hoist_selectors(cx, &lhs, targets.iter().flatten().count())?;
        let id = id_of(
            cx,
            vif::base(&root).ok_or_else(|| {
                LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
            })?,
        )?;
        let mut out = Vec::new();
        for (k, target) in targets.iter().enumerate() {
            if target.is_none() {
                continue;
            }
            let prev = PICK.with(|p| p.replace(Some(k)));
            let lv = crate::select::resolve_lvalue(cx, lhs, mode);
            PICK.with(|p| p.set(prev));
            let mut lv = lv?;
            let miss =
                cx.b.build_int_compare(
                    IntPredicate::NE,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_miss",
                )
                .unwrap();
            lv.bad = cx.b.build_or(lv.bad, miss, "vif_nested_skip").unwrap();
            out.push(lv);
        }
        Ok(out)
    })())
}

/// The targets of a write to `vif.m` (`lhs`): every candidate's `m`, each
/// suppressed unless it is the one the id selects. `None` if `lhs` is not
/// such an access.
pub(crate) fn lvalues<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    mode: RootMode<'_>,
) -> Option<Result<Vec<Lvalue<'ctx>>, LoweringError>> {
    let targets = vif::member_targets(&lhs)?;
    Some((|| {
        let base = vif::base(&lhs).ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
        })?;
        let id = id_of(cx, base)?;
        let op = OpBuilder {
            ctx: cx.ctx,
            b: &cx.b,
        };
        let mut out = Vec::new();
        for (k, target) in targets.iter().enumerate() {
            let Some(sym) = target else {
                continue;
            };
            // A clock variable (`vif.cb.d <= v`) drives the signal it names.
            let driven = (sym.kind() == sv_lang::kinds::SymbolKind::ClockVar)
                .then(|| sym.initializer().and_then(|e| e.referenced_symbol()))
                .flatten();
            let sym = driven.as_ref().unwrap_or(sym);
            let unreachable = || {
                LoweringError::unsupported_at(
                    "a virtual interface member this process cannot reach",
                    sym,
                )
            };
            let (root, width, signed) = match mode {
                RootMode::Shadow => {
                    let (ptr, w, s) = *cx.locals.get(&sym.uid()).ok_or_else(unreachable)?;
                    (LvalueRoot::Shadow { ptr }, w, s)
                }
                RootMode::Signal(signals) => {
                    let info = signals.get(&sym.uid()).copied().ok_or_else(unreachable)?;
                    (
                        LvalueRoot::Signal { slot: info.slot },
                        info.width,
                        info.signed,
                    )
                }
            };
            let bad =
                cx.b.build_int_compare(
                    IntPredicate::NE,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_miss",
                )
                .unwrap();
            out.push(Lvalue {
                root,
                root_width: width,
                root_signed: signed,
                lo: op.i_n(width).const_zero(),
                width,
                bad,
                edge: None,
                pad: None,
            });
        }
        Ok(out)
    })())
}

/// For an edge output skew driven through `vif.cb.m` (`lhs`, LRM 1800-2023
/// 14.4): the state slot (an `i32`) of the clocking event's signal of the
/// candidate instance the id selects (0 for none -- every write is then
/// suppressed anyway). Every candidate has its own clock signal, so the
/// drive bracket's one clock slot is chosen at run time. `None` if `lhs` is
/// not such an access.
pub(crate) fn edge_clock_slot<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    signals: &std::collections::HashMap<
        sv_sim_sim::symid::SymbolId,
        crate::process_lower::SignalSlot,
    >,
    lhs: Expression<'d>,
    block_counter: bool,
) -> Option<Result<IntValue<'ctx>, LoweringError>> {
    let targets = vif::member_targets(&lhs)?;
    Some((|| {
        let base = vif::base(&lhs).ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
        })?;
        let id = id_of(cx, base)?;
        let i32t = cx.ctx.i32_type();
        let mut acc = i32t.const_zero();
        for (k, target) in targets.iter().enumerate() {
            let Some(sym) = target else {
                continue;
            };
            let slot_sym = if block_counter {
                // The clocking block's event counter (a drive without skew
                // matures at its next event).
                sym.parent().ok_or_else(|| {
                    LoweringError::unsupported_at("a clock variable with no clocking block", sym)
                })?
            } else {
                let ev = sym
                    .parent()
                    .and_then(|cb| cb.clocking_block_event())
                    .and_then(|n| n.as_timing_control())
                    .ok_or_else(|| {
                        LoweringError::unsupported_at("a clocking block with no event", sym)
                    })?;
                let clock = sv_sim_sim::sva::sampled::clock_event_of(ev)
                    .map_err(|e| LoweringError::unsupported_at(&e.0, sym))?;
                clock.signal.referenced_symbol().ok_or_else(|| {
                    LoweringError::unsupported_at(
                        "an edge output skew whose clocking event is not a plain signal",
                        sym,
                    )
                })?
            };
            let csym = slot_sym;
            let slot = signals
                .get(&csym.uid())
                .ok_or_else(|| {
                    LoweringError::unsupported_at(
                        "an edge output skew through a virtual interface whose clock is not a \
                         module-level signal",
                        &csym,
                    )
                })?
                .slot;
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_clk_hit",
                )
                .unwrap();
            acc =
                cx.b.build_select(hit, i32t.const_int(u64::from(slot), false), acc, "vif_clk")
                    .unwrap()
                    .into_int_value();
        }
        Ok(acc)
    })())
}

/// The virtual interface an edge event control waits through (`@(posedge
/// vif.clk)`), if `e` is such a member access.
pub(crate) fn event_base<'d>(e: &Expression<'d>) -> Option<Expression<'d>> {
    vif::is_member_access(e).then(|| vif::base(e)).flatten()
}

/// For a wait on `vif.ea[i]` (an element of an event array member of a
/// virtual interface), the `vif.ea` member access its candidates come from.
pub(crate) fn event_elem_root<'d>(e: &Expression<'d>) -> Option<Expression<'d>> {
    event_elem_targets(e)?;
    nested_root(e)
}

/// Every candidate's element `target` (`vif.ea[i]`) with the candidate's
/// code (its id, `k + 1`), its `valid` narrowed to the selected candidate:
/// what a wait on the element records (`process_lower`). `None` if `target`
/// is not such an element.
#[allow(clippy::type_complexity)]
pub(crate) fn event_elem_candidates<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    target: Expression<'d>,
) -> Option<Result<Vec<(crate::arrays::EventElem<'ctx>, u64)>, LoweringError>> {
    let mut out = Vec::new();
    let r = each_event_elem(cx, target, &mut |k, el| {
        out.push((el, k as u64 + 1));
        Ok(())
    })?;
    Some(r.map(|()| out))
}

/// The resume key of a suspend whose event list goes through SEVERAL virtual
/// interface variables (`@(posedge a.clk or negedge b.rst)`, LRM 25.9 +
/// 9.4.2): `resume` plus, above [`KEY_SHIFT`], one code for the whole tuple of
/// held instances. `vars` pairs each variable with its candidate count; the
/// code is `1 + sum((id_j - 1) * stride_j)` with `stride_j` the product of the
/// earlier variables' counts, and 0 when any variable is `null` or past its
/// last candidate (the wait then waits on nothing, like a one-variable wait).
/// For a single variable the code equals [`suspend_key`]'s id.
pub(crate) fn suspend_key_multi<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    vars: &[(Expression<'d>, usize)],
    resume: u32,
) -> Result<IntValue<'ctx>, LoweringError> {
    let i64t = cx.ctx.i64_type();
    let mut ok = cx.ctx.bool_type().const_int(1, false);
    let mut sum = i64t.const_zero();
    let mut stride = 1u64;
    for (base, n) in vars {
        let id = id_of(cx, *base)?;
        let off =
            cx.b.build_int_sub(id, i64t.const_int(1, false), "vif_id_off")
                .unwrap();
        let in_range =
            cx.b.build_int_compare(
                IntPredicate::ULT,
                off,
                i64t.const_int(*n as u64, false),
                "vif_in_range",
            )
            .unwrap();
        ok = cx.b.build_and(ok, in_range, "vif_all_in_range").unwrap();
        let scaled =
            cx.b.build_int_mul(off, i64t.const_int(stride, false), "vif_scaled")
                .unwrap();
        sum = cx.b.build_int_add(sum, scaled, "vif_sum").unwrap();
        stride *= *n as u64;
    }
    let code =
        cx.b.build_int_add(sum, i64t.const_int(1, false), "vif_code")
            .unwrap();
    let code =
        cx.b.build_select(ok, code, i64t.const_zero(), "vif_key_id")
            .unwrap()
            .into_int_value();
    let code =
        cx.b.build_int_truncate(code, cx.ctx.i32_type(), "vif_key_id32")
            .unwrap();
    let shifted =
        cx.b.build_left_shift(
            code,
            cx.ctx.i32_type().const_int(u64::from(KEY_SHIFT), false),
            "vif_key_hi",
        )
        .unwrap();
    Ok(cx
        .b
        .build_int_add(
            shifted,
            cx.ctx.i32_type().const_int(u64::from(resume), false),
            "vif_key",
        )
        .unwrap())
}

/// The resume key a suspend through the virtual interface `base` returns:
/// `resume` plus the id above [`KEY_SHIFT`] (0 -- `null` -- for an id past
/// the last candidate).
pub(crate) fn suspend_key<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    base: Expression<'d>,
    resume: u32,
    candidates: usize,
) -> Result<IntValue<'ctx>, LoweringError> {
    let id = id_of(cx, base)?;
    let i64t = cx.ctx.i64_type();
    let in_range =
        cx.b.build_int_compare(
            IntPredicate::ULE,
            id,
            i64t.const_int(candidates as u64, false),
            "vif_in_range",
        )
        .unwrap();
    let id =
        cx.b.build_select(in_range, id, i64t.const_zero(), "vif_key_id")
            .unwrap()
            .into_int_value();
    let id =
        cx.b.build_int_truncate(id, cx.ctx.i32_type(), "vif_key_id32")
            .unwrap();
    let shifted =
        cx.b.build_left_shift(
            id,
            cx.ctx.i32_type().const_int(u64::from(KEY_SHIFT), false),
            "vif_key_hi",
        )
        .unwrap();
    Ok(cx
        .b
        .build_int_add(
            shifted,
            cx.ctx.i32_type().const_int(u64::from(resume), false),
            "vif_key",
        )
        .unwrap())
}

/// A call through a virtual interface (`vif.t(...)`, `call`): branches on
/// its id to one block per candidate instance, each paired with that
/// instance's own `t`, and returns them with the block after the call
/// (reached directly for `null` or an instance lacking `t`). Each arm must
/// end by branching to that block. `None` if `call` is not such a call.
#[allow(clippy::type_complexity)]
pub(crate) fn call_arms<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    call: Expression<'d>,
) -> Option<
    Result<
        (
            Vec<(sv_lang::Symbol<'d>, inkwell::basic_block::BasicBlock<'ctx>)>,
            inkwell::basic_block::BasicBlock<'ctx>,
        ),
        LoweringError,
    >,
> {
    let (base, targets) = vif::call_targets(&call)?;
    Some((|| {
        let id = id_of(cx, base)?;
        let f =
            cx.b.get_insert_block()
                .and_then(|bb| bb.get_parent())
                .expect("lowering happens inside a function");
        let merge = cx.ctx.append_basic_block(f, "vif_call_done");
        let mut arms = Vec::new();
        for (k, target) in targets.into_iter().enumerate() {
            let Some(sym) = target else {
                continue;
            };
            let arm = cx.ctx.append_basic_block(f, "vif_call");
            let next = cx.ctx.append_basic_block(f, "vif_call_next");
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_call_hit",
                )
                .unwrap();
            cx.b.build_conditional_branch(hit, arm, next).unwrap();
            cx.b.position_at_end(next);
            arms.push((sym, arm));
        }
        cx.b.build_unconditional_branch(merge).unwrap();
        Ok((arms, merge))
    })())
}

/// Whether `call` is a call through a virtual interface ([`call_arms`]).
pub(crate) fn call_arms_apply(call: &Expression<'_>) -> bool {
    vif::call_targets(call).is_some()
}

/// A whole or partial fixed-size unpacked array assignment through a
/// virtual interface (`vif.a = rhs`, `vif.b[1] = row`, `vif.a[0:1] = ...`,
/// LRM 1800-2023 25.9 with 7.6): `rhs` is copied into each candidate
/// instance's array, every one but the id's suppressed. `None` if `lhs` is
/// not an unpacked-array target rooted at a `vif.m`.
pub(crate) fn assign_array<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    lhs: Expression<'d>,
    rhs: Expression<'d>,
) -> Option<Result<(), LoweringError>> {
    let ty = lhs.expr_type()?;
    if !ty.is_unpacked_array() || sv_sim_sim::state::storage::is_collection(&ty) {
        return None;
    }
    let root = if vif::is_member_access(&lhs) {
        lhs
    } else {
        nested_root(&lhs)?
    };
    let targets = vif::member_targets(&root)?;
    Some((|| {
        // A side-effecting value runs once, however many candidate instances
        // `v` may select (LRM 1800-2023 25.9, 11.4.12): it is evaluated into a
        // temporary and each candidate's copy is guarded on the selection.
        let staged = if targets.iter().flatten().count() > 1
            && crate::classes::has_side_effects(rhs)
        {
            let shape = crate::arrays::array_shape(&ty).ok_or_else(|| {
                LoweringError::unsupported_at("a virtual interface array assignment", &cx.fn_sym)
            })?;
            if !crate::collections::handle_offsets(&shape.elem).is_empty() {
                return Err(LoweringError::unsupported_at(
                    "a virtual interface array assignment of reference-holding elements whose \
                     value has a side effect (it would run once per candidate instance)",
                    &cx.fn_sym,
                ));
            }
            if let Some(call) = crate::arrays::array_call_value(cx, rhs)? {
                Some(call)
            } else {
                let tmp = crate::expr::entry_alloca(
                    cx,
                    crate::arrays::local_array_type(cx.ctx, &shape, cx.repr),
                    "vif_arr_once",
                );
                let tmp_ref =
                    crate::arrays::ArrayRef::whole(cx, crate::arrays::Backing::Local(tmp));
                crate::arrays::assign_array_into_fresh(cx, tmp_ref, &shape, rhs)?;
                Some((tmp_ref, shape))
            }
        } else {
            None
        };
        let _once = hoist_selectors(cx, &lhs, targets.iter().flatten().count())?;
        let id = id_of(
            cx,
            vif::base(&root).ok_or_else(|| {
                LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
            })?,
        )?;
        for (k, target) in targets.iter().enumerate() {
            if target.is_none() {
                continue;
            }
            let prev = PICK.with(|p| p.replace(Some(k)));
            let dst = crate::arrays::array_target(cx, lhs);
            PICK.with(|p| p.set(prev));
            let Some((mut dst, shape)) = dst? else {
                return Err(LoweringError::unsupported_at(
                    "a virtual interface array member this process cannot reach",
                    &cx.fn_sym,
                ));
            };
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    cx.ctx.i64_type().const_int(k as u64 + 1, false),
                    "vif_hit",
                )
                .unwrap();
            dst.valid = cx.b.build_and(dst.valid, hit, "vif_arr_sel").unwrap();
            match &staged {
                Some((src, src_shape)) => {
                    crate::arrays::copy_array(cx, dst, &shape, *src, src_shape)?;
                }
                None => crate::arrays::assign_array(cx, dst, &shape, rhs)?,
            }
        }
        Ok(())
    })())
}

/// The rows of a sub-array or slice read through a virtual interface
/// (`vif.b[1]`, `vif.a[2:3]` as an array value; LRM 1800-2023 25.9, 7.4.3,
/// 10.10) in row order: each candidate's rows resolved under [`PICK`], the
/// selected one chosen by the id. `None` if `e` is not a select chain rooted
/// at a `vif.m` array member.
pub(crate) fn array_values<'ctx, 'd>(
    cx: &LowerCtx<'ctx, 'd, '_>,
    e: Expression<'d>,
) -> Option<Result<Vec<PackedValue<'ctx>>, LoweringError>> {
    use sv_lang::kinds::ExpressionKind as K;
    if !matches!(e.kind(), K::ElementSelect | K::RangeSelect) {
        return None;
    }
    let root = nested_root(&e)?;
    let targets = vif::member_targets(&root)?;
    Some((|| {
        let op = OpBuilder {
            ctx: cx.ctx,
            b: &cx.b,
        };
        let _once = hoist_selectors(cx, &e, targets.iter().flatten().count())?;
        let id = id_of(
            cx,
            vif::base(&root).ok_or_else(|| {
                LoweringError::unsupported_at("a virtual interface member access", &cx.fn_sym)
            })?,
        )?;
        let i64t = cx.ctx.i64_type();
        let mut acc: Option<Vec<PackedValue<'ctx>>> = None;
        for (k, target) in targets.iter().enumerate() {
            if target.is_none() {
                continue;
            }
            let prev = PICK.with(|p| p.replace(Some(k)));
            let src = crate::arrays::array_target(cx, e);
            PICK.with(|p| p.set(prev));
            let Some((r, shape)) = src? else {
                return Err(LoweringError::unsupported_at(
                    "a virtual interface array member this process cannot reach",
                    &cx.fn_sym,
                ));
            };
            let hit =
                cx.b.build_int_compare(
                    IntPredicate::EQ,
                    id,
                    i64t.const_int(k as u64 + 1, false),
                    "vif_hit",
                )
                .unwrap();
            let mut rows = Vec::new();
            for row in 0..shape.rows() {
                rows.push(crate::arrays::load_row(
                    cx,
                    &r,
                    i64t.const_int(row, false),
                    &shape.elem,
                )?);
            }
            acc = Some(match acc {
                None => rows,
                Some(prev) => rows
                    .into_iter()
                    .zip(prev)
                    .map(|(v, p)| op.select(hit, v, p))
                    .collect(),
            });
        }
        acc.ok_or_else(|| {
            LoweringError::unsupported_at("a virtual interface array member", &cx.fn_sym)
        })
    })())
}