Skip to content

bjwanneng/veriflow-cc / src/claude_skills/vf-rtl

vf-rtl

Verified

FileKindSize
SELF_IMPROVE.mdmarkdown3.8 KB
SKILL.mdskill md11.2 KB
SKILL_INDEX.mdmarkdown5.5 KB
analysis/bug_pattern_match.pyscript26.9 KB
analysis/corner_case_generator.pyscript4.9 KB
analysis/coverage_analyzer.pyscript5.3 KB
analysis/design_graph.pyscript8.9 KB
analysis/expected_trace_gen.pyscript12.5 KB
analysis/timing_contract_checker.pyscript25.4 KB
analysis/timing_diagnostic.pyscript21.1 KB
analysis/vcd2table.pyscript31.3 KB
bug_patterns.mdmarkdown23.2 KB
coding_style.mdmarkdown9.4 KB
core/init.pyscript13.8 KB
core/rtl_utils.pyscript7.5 KB
core/state.pyscript38.9 KB
design_rules.mdmarkdown2.9 KB
error_recovery.mdmarkdown7.0 KB
kb/knowledge_base.pyscript11.7 KB
kb/reference_kb.pyscript5.6 KB
kb/self_improve.pyscript24.4 KB
references/arbiter_round_robin.vother1.4 KB
references/counter.vother545 B
references/fifo.vother1.3 KB
references/fsm_moore.vother847 B
references/handshake_valid_ready.vother1.1 KB
references/pipeline_aligner.vother760 B
runners/benchmark_runner.pyscript23.6 KB
runners/cocotb_runner.pyscript26.3 KB
runners/iverilog_runner.pyscript26.3 KB
runners/yosys_equiv.pyscript14.2 KB
stage1_spec_golden.mdmarkdown6.1 KB
stage2_codegen.mdmarkdown5.9 KB
stage3_verify_fix.mdmarkdown17.0 KB
stage4_lint_synth.mdmarkdown6.3 KB
templates/cocotb_template.pyscript42.4 KB
templates/golden_model_template.pyscript8.7 KB
templates/spec_template.jsonconfig8.5 KB
templates/tb_integration_template.vother12.4 KB
verify/candidate_selector.pyscript7.0 KB
verify/formal_prove.pyscript12.1 KB
verify/synth_score.pyscript4.4 KB

templates/cocotb_template.py

View on GitHub
"""cocotb integration testbench for <design_name> — golden model cross-check.
Generated by VeriFlow-CC.

Timing convention (IMPORTANT):
  cocotb + iverilog via VPI: after `await RisingEdge(dut.clk)`, cocotb reads
  values produced by the PREVIOUS posedge's NBA. Equivalently: at RisingEdge N,
  cocotb sees POST-NBA of posedge N-1 = PRE-NBA of posedge N.

  The golden model trace records the register state AFTER each posedge's NBA.
  The cocotb comparison loop reads each trace entry at the NEXT RisingEdge.

  Practical effect: the golden model records the NEW register values after each
  computation step. The comparison is aligned by DRIVE_PHASE_CYCLES offset.

  Registered outputs (ready, valid_out, etc.) have a 1-cycle delay: they
  reflect the combinational _next signal from the PREVIOUS posedge's state.

Clock management (IMPORTANT):
  In cocotb v2.0+, background tasks (including Clock) are killed between tests.
  Each test MUST call ensure_clock() to start a fresh clock instance.
  Do NOT use a global _CLOCK_STARTED flag.

Two verification modes:
- test_layered: Golden model cycle-by-cycle output port comparison (algorithm designs)
- test_internal_signals: Per-cycle internal register comparison against golden model
- test_protocol: Protocol compliance checks (all designs)

Port configuration constants below are populated from spec.json by the codegen
stage. If codegen does not populate them, defaults are used and only
top-level port signals are checked.
"""

import os
import sys
from pathlib import Path
import cocotb
from cocotb.clock import Clock
from cocotb.triggers import RisingEdge, FallingEdge, ClockCycles  # noqa: F401  (FallingEdge used by codegen-inserted test_timing_contract body)
import atexit
import contextlib
import json

# ─── Functional coverage (coverage-driven verification) ─────────────────
# Codegen inserts _cover(...) calls at observed FSM states / handshake combos.
# Analyzed post-sim by coverage_analyzer.py; a no-op if COVER stays empty.
COVER: dict = {}


def _cover(key) -> None:
    COVER[key] = COVER.get(key, 0) + 1


_COVERAGE_FILE = os.environ.get(
    "COVERAGE_FILE", os.path.join(os.getcwd(), "coverage.json")
)


def _dump_coverage() -> None:
    try:
        with open(_COVERAGE_FILE, "w") as _f:
            json.dump(COVER, _f, indent=2)
    except OSError:
        pass


atexit.register(_dump_coverage)

CLK_PERIOD_NS = None  # codegen: MUST set FULL period from spec.timing.target_frequency_mhz
                      # (period_ns = 1000 / target_frequency_mhz). cocotb's Clock()
                      # takes the FULL period, NOT half-period.
RESET_CYCLE_SKIP = 1  # codegen: set from spec.timing_convention.reset_cycle_skip (default 1; cycle 0 is reset)
TIMEOUT_CYCLES = 500
FAIL_COUNT = 0  # Accumulates across ALL tests; do NOT reset inside individual tests
_STIMULUS_DELIVERED = False  # Set True by drive_inputs(); checked by comparison tests

# ─── Golden model import ────────────────────────────────────────────────
GOLDEN_AVAILABLE = False
GM_PATH = Path(__file__).parent.parent / "docs" / "golden_model.py"
if GM_PATH.exists():
    sys.path.insert(0, str(GM_PATH.parent))
    try:
        from golden_model import run as golden_run
        GOLDEN_AVAILABLE = True
    except ImportError as _e:
        import warnings
        warnings.warn(f"[GOLDEN] Import failed: {_e}. Per-cycle tests will be skipped.", stacklevel=2)

# ─── Port configuration ─────────────────────────────────────────────────
# Populated from spec.json by the codegen stage.
# Codegen MUST fill these in — they are NOT optional.
# If a port category is empty for this design, codegen sets it to {}.
INPUT_PORTS = {}          # {"port_name": width_bits, ...}
OUTPUT_PORTS = {}         # {"port_name": width_bits, ...}
VALID_OUTPUT_PORTS = []   # ["valid_out", ...] — output ports indicating valid data
HANDSHAKE_PORTS = {}      # {"valid_in": "ready_out"} — valid -> ack mapping
HOLD_UNTIL_ACK_PORTS = [] # ["valid_in", ...] — ports with hold_until_ack protocol

# DRIVE_PHASE_CYCLES: offset between golden model (software instantaneous) and RTL
# (post-NBA registered). Populated from spec.json timing_convention field:
#   spec.timing_convention.golden_to_rtl_offset_cycles
# Falls back to max(pipeline_delay_cycles) from module_connectivity timing_contract
# if timing_convention is not set (backward compat).
#
# Codegen MUST set this from spec.json. If codegen doesn't, the fallback below
# reads spec.json at import time to compute a reasonable default.
DRIVE_PHASE_CYCLES = 0    # codegen: set from spec.timing_convention.golden_to_rtl_offset_cycles

# Fallback: if codegen didn't set DRIVE_PHASE_CYCLES, try reading spec.json
if DRIVE_PHASE_CYCLES == 0:
    try:
        _spec_path = Path(__file__).parent.parent / "docs" / "spec.json"
        if _spec_path.exists():
            import json as _json
            _spec = _json.loads(_spec_path.read_text())
            _tc = _spec.get("timing_convention", {})
            _offset = _tc.get("golden_to_rtl_offset_cycles")
            if isinstance(_offset, int) and _offset > 0:
                DRIVE_PHASE_CYCLES = _offset
            else:
                # Fallback: max pipeline_delay_cycles across all modules
                _delays = []
                for _m in _spec.get("modules", []):
                    _d = _m.get("timing_contract", {}).get("pipeline_delay_cycles")
                    if isinstance(_d, (int, float)):
                        _delays.append(int(_d))
                if _delays:
                    DRIVE_PHASE_CYCLES = max(_delays)
    except Exception:
        pass

# ─── RESET_CYCLE_SKIP resolution (begin) ───
# Mirror of DRIVE_PHASE_CYCLES: if codegen didn't override (still default 1),
# read spec.timing_convention.reset_cycle_skip so both alignment knobs are
# spec-driven. 0 = compare from the reset cycle, 1 = skip reset cycle (default).
if RESET_CYCLE_SKIP == 1:
    try:
        _rcs_spec_path = Path(__file__).parent.parent / "docs" / "spec.json"
        if _rcs_spec_path.exists():
            import json as _rcs_json
            _rcs_spec = _rcs_json.loads(_rcs_spec_path.read_text())
            _rcs = _rcs_spec.get("timing_convention", {}).get("reset_cycle_skip")
            if isinstance(_rcs, int) and _rcs >= 0:
                RESET_CYCLE_SKIP = _rcs
    except Exception:
        pass
# ─── RESET_CYCLE_SKIP resolution (end) ───


# ─── Divergence collection ──────────────────────────────────────────────
# By default the comparison loops collect up to MAX_COLLECTED_DIVERGENCES
# mismatches before raising. This surfaces *patterns* (same-cycle siblings
# and steady-state offsets) instead of only the first signal that drifts.
#
# Env knobs:
#   COCOTB_MAX_DIVERGENCES=N   raise the cap (default 8)
#   COCOTB_FAIL_FAST=1         restore old behavior (stop at first mismatch)
MAX_COLLECTED_DIVERGENCES = int(os.environ.get("COCOTB_MAX_DIVERGENCES", "8"))
FAIL_FAST = os.environ.get("COCOTB_FAIL_FAST", "0") == "1"


def _record_divergence(divergences, sig_name, expected_val, actual_val,
                       cycle_idx, width, kind=None):
    """Append a divergence dict to `divergences`.

    Returns True when the caller should stop collecting (cap reached or
    fail-fast mode). The divergence shape is the same dict that the
    pre-collect implementation used, so downstream formatting code is
    unchanged.
    """
    div = {
        "cycle": cycle_idx,
        "signal": sig_name,
        "expected": expected_val,
        "actual": actual_val,
        "width": width,
    }
    if kind:
        div["kind"] = kind
    divergences.append(div)
    return FAIL_FAST or len(divergences) >= MAX_COLLECTED_DIVERGENCES


def _format_divergence_block(div, tag):
    """Format one divergence as a [tag] FIRST DIVERGENCE-shaped block.

    timing_diagnostic.parse_divergence regex matches the FIRST entry of
    this block in the cocotb log, so the per-divergence emission MUST
    keep this exact shape.
    """
    width = div.get("width") or 32
    hex_digits = max((width + 3) // 4, 1)
    kind = div.get("kind")
    kind_tag = f" kind={kind}" if kind else ""
    hint = (
        "\n  (testbench driver wrong — DUT input doesn't match golden stimulus)"
        if kind == "stimulus_mismatch" else ""
    )
    return (
        f"[{tag}] FIRST DIVERGENCE at cycle={div['cycle']} "
        f"signal={div['signal']} (width={width}b){kind_tag}:\n"
        f"  expected = 0x{div['expected']:0{hex_digits}x}\n"
        f"  actual   = 0x{div['actual']:0{hex_digits}x}\n"
        f"  xor diff = 0x{div['expected'] ^ div['actual']:0{hex_digits}x}"
        f"{hint}"
    )


def _finalize_divergences(dut, divergences, tag):
    """Emit each divergence and raise AssertionError with a summary.

    Caller must check `if divergences:` before invoking — this always
    raises. The first block is reused as the assertion message so
    timing_diagnostic's regex (which uses `search`, not `findall`) still
    anchors on the chronologically first divergence.
    """
    blocks = [_format_divergence_block(d, tag) for d in divergences]
    # Log every block separately so test logs show each mismatch on its own.
    for b in blocks:
        dut._log.error(b)
    head = blocks[0]
    if len(blocks) > 1:
        more = "\n\n".join(blocks[1:])
        msg = (
            f"{head}\n\n"
            f"(+{len(blocks) - 1} additional divergence(s) collected; "
            f"set COCOTB_FAIL_FAST=1 to stop at the first):\n\n{more}"
        )
    else:
        msg = head
    raise AssertionError(msg)


# ─── Clock management ───────────────────────────────────────────────────
# CRITICAL: In cocotb v2.0+, background tasks (including Clock) are killed
# between tests. Each test MUST call ensure_clock() to start a fresh clock.

async def ensure_clock(dut):
    """Start clock. Must be called at the start of every test."""
    assert CLK_PERIOD_NS is not None, (
        "CLK_PERIOD_NS not populated — codegen must set from spec.timing.target_frequency_mhz"
    )
    clock = Clock(dut.clk, CLK_PERIOD_NS, unit="ns")
    cocotb.start_soon(clock.start())
    await RisingEdge(dut.clk)


# ─── Helpers ────────────────────────────────────────────────────────────

def _lookup_signal_width(sig_name: str, default: int = 32) -> int:
    """Best-effort width lookup from spec-populated port dicts.

    Used when cocotb's `len(sig)` fails (e.g., VPI internal signal whose
    handle does not expose a width). The default `32` is a last resort —
    it truncates 256-bit hash signals and was the root cause of misleading
    [INTERNAL] FIRST DIVERGENCE messages where expected hex was correct
    but actual hex was zero-padded to 32 bits.

    Generates all combinations of these strip operations:
      - Strip module-qualified prefix (`u_x.y_reg` -> `y_reg`)
      - Strip `_reg` suffix (`y_reg` -> `y`)
      - Strip `[N]` array suffix (`y[0]` -> `y`)
    Returns the first matching width in OUTPUT_PORTS, then INPUT_PORTS,
    or `default` if nothing matches.
    """
    seen: set[str] = {sig_name}
    candidates: list[str] = [sig_name]
    cursor = 0
    while cursor < len(candidates):
        n = candidates[cursor]
        cursor += 1
        for stripped in (
            n.rsplit(".", 1)[-1] if "." in n else "",
            n[:-4] if n.endswith("_reg") else "",
            n.split("[", 1)[0] if "[" in n else "",
        ):
            if stripped and stripped not in seen:
                seen.add(stripped)
                candidates.append(stripped)

    for name in candidates:
        if name in OUTPUT_PORTS:
            return OUTPUT_PORTS[name]
    for name in candidates:
        if name in INPUT_PORTS:
            return INPUT_PORTS[name]
    return default


async def reset_dut(dut):
    """Apply synchronous reset and wait for outputs to settle."""
    global FAIL_COUNT
    global _STIMULUS_DELIVERED
    _STIMULUS_DELIVERED = False  # Reset per-test stimulus flag
    dut.rst.value = 1
    # Zero all input ports only (not outputs — outputs are driven by DUT)
    for name in INPUT_PORTS:
        try:
            sig = getattr(dut, name)
            if hasattr(sig, 'value') and hasattr(sig, 'setimmediatevalue'):
                sig.value = 0
        except Exception:
            pass
    # Also zero any valid input ports from HANDSHAKE_PORTS
    for valid_name in HANDSHAKE_PORTS:
        with contextlib.suppress(Exception):
            getattr(dut, valid_name).value = 0
    await ClockCycles(dut.clk, 3)
    dut.rst.value = 0
    await RisingEdge(dut.clk)  # rst deassert sampled, outputs stable


def check(dut, expected, signal, test_name, cycle):
    """Raise AssertionError on mismatch. signal is a dut handle."""
    global FAIL_COUNT
    actual = int(signal.value)
    if expected != actual:
        FAIL_COUNT += 1
        width = len(signal)
        msg = (
            f"[FAIL] {test_name} cycle={cycle} {signal._name}: "
            f"expected=0x{expected:0{(width + 3) // 4}x} got=0x{actual:0{(width + 3) // 4}x}"
        )
        dut._log.error(msg)
        raise AssertionError(msg)


def _validate_trace_signal_names(expected_cycles, dut, test_name):
    """Pre-check that golden trace signal names exist in DUT hierarchy.

    Returns (found_signals, missing_signals). Logs warnings for missing.
    """
    if not expected_cycles:
        return [], []

    all_trace_keys = set()
    for entry in expected_cycles:
        if isinstance(entry, dict):
            all_trace_keys.update(entry.keys())

    found = []
    missing = []
    for sig_name in sorted(all_trace_keys):
        try:
            if '.' in sig_name:
                parts = sig_name.split('.')
                obj = dut
                for part in parts:
                    while '[' in part:
                        arr_name, rest = part.split('[', 1)
                        if arr_name:
                            obj = getattr(obj, arr_name)
                        idx_str, part = rest.split(']', 1)
                        obj = obj[int(idx_str)]
                    if part:
                        obj = getattr(obj, part)
            elif '[' in sig_name:
                base, rest = sig_name.split('[', 1)
                obj = getattr(dut, base)
                idx_str, _ = rest.split(']', 1)
                obj = obj[int(idx_str)]
            else:
                getattr(dut, sig_name)
            found.append(sig_name)
        except (AttributeError, IndexError):
            missing.append(sig_name)

    if missing:
        dut._log.warning(
            f"[{test_name}] {len(missing)} golden trace signal(s) not found in DUT: "
            f"{missing[:10]}"
        )
    return found, missing


def _align_trace(expected_cycles):
    """Slice the golden trace to skip the reset state (cycle 0).

    DRIVE_PHASE_CYCLES is consumed entirely inside drive_inputs() via its
    hold_data_cycles parameter. This function only skips golden cycle 0.
    Do NOT re-add DRIVE_PHASE_CYCLES to this slice.
    """
    return expected_cycles[RESET_CYCLE_SKIP:]


async def drive_inputs(dut, input_values, valid_name='valid_in',
                       ready_name='ready_out',
                       hold_data_cycles=None):
    """Wait for ready, then drive valid=1 with input values.

    Timing (POST-NBA):
    1. Wait for ready=1
    2. Drive ALL inputs simultaneously (valid + data)
    3. Wait ONE RisingEdge — DUT samples inputs at this posedge, NBA fires
    4. Deassert valid. For data inputs, hold for additional cycles based on
       pipeline_delay_cycles to ensure downstream modules have sampled.

    Args:
        dut: cocotb DUT handle
        input_values: dict mapping port names to integer values
        valid_name: name of the valid input port
        ready_name: name of the ready/ack output port
        hold_data_cycles: extra cycles to hold data after deasserting valid.
            Defaults to DRIVE_PHASE_CYCLES. If the control signal that triggers
            sampling has pipeline_delay_cycles=N, data must remain stable for
            N+1 cycles after valid is deasserted.
    """
    if hold_data_cycles is None:
        hold_data_cycles = DRIVE_PHASE_CYCLES

    # Wait for ready
    timeout = TIMEOUT_CYCLES
    ready_sig = getattr(dut, ready_name)
    while int(ready_sig.value) != 1 and timeout > 0:
        await RisingEdge(dut.clk)
        timeout -= 1
    assert timeout > 0, "Timeout waiting for ready before drive_inputs"

    # Drive all inputs at once
    for port_name, value in input_values.items():
        getattr(dut, port_name).value = value
    getattr(dut, valid_name).value = 1

    # Wait one rising edge — DUT samples inputs at this posedge
    await RisingEdge(dut.clk)

    # Mark that stimulus was delivered (for post-loop sanity check in tests)
    global _STIMULUS_DELIVERED
    _STIMULUS_DELIVERED = True

    # Deassert based on handshake protocol
    if valid_name in HOLD_UNTIL_ACK_PORTS:
        # hold_until_ack: keep valid high until DUT asserts ready
        pass  # caller is responsible for deasserting after ack
    else:
        # single_cycle / pulse: deassert valid immediately after sampling
        getattr(dut, valid_name).value = 0
        # Hold data for pipeline_delay_cycles so downstream consumers
        # (e.g., w_gen that sees load_en 2 cycles late) still see stable data.
        for _ in range(hold_data_cycles):
            await RisingEdge(dut.clk)
        for port_name in input_values:
            getattr(dut, port_name).value = 0


async def wait_valid(dut, valid_name='valid_out', max_cycles=200):
    """Poll for valid=1, return cycle count waited, or -1 on timeout.

    Raises a clear RuntimeError if `valid_name` is not a real port instead of
    a cryptic cocotb AttributeError (which masks the real cause: codegen didn't
    set DONE_SIGNAL_PORT for a non-'valid*' done signal like `hash_valid`).
    """
    if not hasattr(dut, valid_name):
        raise RuntimeError(
            f"wait_valid: done/valid port '{valid_name}' not found on DUT. "
            f"Set DONE_SIGNAL_PORT in the testbench to the design's 1-bit "
            f"done/valid signal name.")
    valid_sig = getattr(dut, valid_name)
    for i in range(max_cycles):
        await RisingEdge(dut.clk)
        if int(valid_sig.value) == 1:
            return i + 1
    return -1  # timeout


async def drive_block_sequence(
    dut,
    blocks: list[dict],
    valid_name: str = "valid_in",
    ready_name: str = "ready_out",
    is_last_name: str = "is_last",
    done_name: str = "valid_out",
    wait_for_done_each_block: bool = True,
    max_wait_per_block: int = 200,
):
    """Drive a sequence of blocks back-to-back through a multi-block design.

    For each block in `blocks`:
      1. Wait for ready=1
      2. Drive block inputs simultaneously, with `is_last` set to 1 only for
         the final block. If the DUT does not have an `is_last_name` port,
         it is skipped silently.
      3. If `wait_for_done_each_block` is True, await done_name=1 before
         starting the next block. Otherwise just hand off after the input
         is sampled.

    Returns the cycle index at which the FINAL block's done asserted (or -1
    on timeout). After return, the DUT output ports hold the final result.

    This helper is the build-time guard against Pattern 14 (valid not gated
    by is_last) and Pattern 11 (Merkle-Damgård chaining reset): if either
    bug is present, comparison of the final-block output against the golden
    multi-block digest will mismatch.
    """
    has_is_last = hasattr(dut, is_last_name)
    final_done_cycle = -1
    for i, block in enumerate(blocks):
        is_last = (i == len(blocks) - 1)
        inputs = dict(block)
        if has_is_last:
            inputs[is_last_name] = int(is_last)
        await drive_inputs(
            dut, inputs,
            valid_name=valid_name, ready_name=ready_name,
        )
        if wait_for_done_each_block:
            waited = await wait_valid(dut, valid_name=done_name,
                                      max_cycles=max_wait_per_block)
            if waited < 0:
                dut._log.error(
                    f"[MULTI_BLOCK] block {i}/{len(blocks)-1} timed out "
                    f"waiting for {done_name}=1"
                )
                return -1
            if is_last:
                final_done_cycle = waited
            elif int(getattr(dut, done_name).value) == 1:
                # Pattern 14 detection: intermediate block fired done.
                # We don't fail here — the test owning this call decides
                # whether the design is supposed to assert done per block
                # or only at the end. Log it for visibility.
                dut._log.warning(
                    f"[MULTI_BLOCK] {done_name}=1 after intermediate block "
                    f"{i} (is_last=0). Verify the design gates done with is_last."
                )
    return final_done_cycle


# ─── VCD capture ──────────────────────────────────────────────────────
# VCD is handled by cocotb_runner.py (waves=True) or the Makefile.
# No in-test action needed — the runner configures iverilog to dump VCD.


# ─── Tests ──────────────────────────────────────────────────────────────

@cocotb.test()
async def test_reset(dut):
    """Test 1: Reset behavior — outputs quiescent after reset."""
    global FAIL_COUNT
    # NOTE: do NOT reset FAIL_COUNT here; it accumulates across all tests.
    await ensure_clock(dut)
    await reset_dut(dut)

    # After reset: verify all output ports are 0
    reset_ok = True
    for port_name in OUTPUT_PORTS:
        try:
            sig = getattr(dut, port_name)
            val = int(sig.value)
            if val != 0:
                FAIL_COUNT += 1
                dut._log.error(f"[RESET] {port_name}={val} after reset, expected 0")
                reset_ok = False
        except AttributeError:
            dut._log.warning(f"[RESET] Port {port_name} not found in DUT")

    if reset_ok:
        dut._log.info("[PASS] reset behavior correct")


@cocotb.test()
async def test_protocol(dut):
    """Test 2: Protocol compliance — handshake and valid behavior.

    Checks that apply to ALL designs regardless of golden model availability:
    1. Reset clears all valid output ports
    2. hold_until_ack: valid stays high until ack received
    3. single_cycle: valid is high for exactly one cycle
    4. No stale valid after operation completes

    Note: Checks 2-4 require stimulus. Codegen adds design-specific
    protocol monitors. This test provides the framework.
    """
    global FAIL_COUNT
    await ensure_clock(dut)
    await reset_dut(dut)

    # Check 1: After reset, all valid output ports must be 0
    for valid_name in VALID_OUTPUT_PORTS:
        try:
            sig = getattr(dut, valid_name)
            val = int(sig.value)
            if val != 0:
                FAIL_COUNT += 1
                dut._log.error(
                    f"[PROTOCOL] {valid_name}={val} after reset, expected 0"
                )
        except AttributeError:
            pass  # port not found in DUT, skip

    # Check 2-4: Design-specific protocol monitors added by codegen
    # Example for hold_until_ack monitoring:
    #   prev_valid = 0
    #   for cycle in range(MAX_CYCLES):
    #       await RisingEdge(dut.clk)
    #       cur_valid = int(dut.valid_out.value)
    #       cur_ready = int(dut.ready_out.value)
    #       if prev_valid == 1 and cur_valid == 0 and cur_ready == 0:
    #           dut._log.error("[PROTOCOL] valid dropped before ready")
    #       prev_valid = cur_valid

    if FAIL_COUNT == 0:
        dut._log.info("[PASS] protocol compliance checks passed")


@cocotb.test()
async def test_layered(dut):
    """Test 3: Layered verification — golden model cycle-by-cycle comparison.

    For algorithm designs with a golden model:
    1. Drive input stimulus from golden model test vectors
    2. Compare DUT output signals against golden model per-cycle expected values
    3. Fail-fast on first mismatch: report cycle, signal, expected vs actual
    4. This quickly isolates WHERE the first computation error occurs

    Skipped if golden_model.py is not available (non-algorithm designs).
    """
    global FAIL_COUNT

    if not GOLDEN_AVAILABLE:
        dut._log.info("[SKIP] test_layered: golden_model.py not available")
        return

    await ensure_clock(dut)
    await reset_dut(dut)

    # Get golden model expected values
    expected_cycles = golden_run()
    if not expected_cycles:
        dut._log.info("[SKIP] test_layered: golden model returned no data")
        return

    dut._log.info(f"[LAYERED] Comparing {len(expected_cycles)} cycles against golden model")

    # Pre-validate golden trace signal names against DUT hierarchy
    _validate_trace_signal_names(expected_cycles, dut, "test_layered")

    # IMPORTANT: codegen MUST add drive_inputs() call here with golden model
    # test vectors before the comparison loop. Without driving inputs,
    # the DUT has no stimulus and all outputs will be initial values.
    #
    # Example (codegen fills in):
    #   test_vectors = golden_model.TEST_VECTORS
    #   for vec in test_vectors:
    #       await drive_inputs(dut, vec["inputs"], valid_name="valid_in",
    #                         ready_name="ready_out")
    #
    # If golden_model.py provides input data per cycle, drive it here.
    # If the design processes a single input block, drive once then wait.
    # <CODEGEN: drive_inputs() call here>

    # Map golden trace signal names to DUT port names.
    # Golden model uses "_reg" suffix; DUT output ports don't.
    # Codegen populates this from spec.json port names.
    GOLDEN_TO_PORT = {}  # {"ready_reg": "ready", "valid_out_reg": "valid_out", ...}

    if not GOLDEN_TO_PORT:
        raise AssertionError(
            "test_layered: GOLDEN_TO_PORT is empty — codegen did not populate port mapping"
        )

    divergences: list[dict] = []
    cycles_checked = 0
    signals_compared = 0
    signals_not_found = []

    # Alignment: skip golden cycle 0 (reset state). See _align_trace() for rationale.
    compare_cycles = _align_trace(expected_cycles)

    for cycle_idx, expected in enumerate(compare_cycles):
        # Compare each output signal against golden model — DUT state already
        # reflects this golden cycle, so do NOT await before comparing.
        stop_outer = False
        for sig_name, expected_val in expected.items():
            # Map golden trace name to DUT port name
            dut_name = GOLDEN_TO_PORT.get(sig_name)
            if dut_name is None:
                continue  # not a mapped output port
            try:
                sig = getattr(dut, dut_name)
                actual_val = int(sig.value)
                signals_compared += 1
                if actual_val != expected_val and _record_divergence(
                    divergences, sig_name, expected_val, actual_val,
                    cycle_idx, len(sig),
                ):
                    stop_outer = True
                    break
            except AttributeError:
                if dut_name not in signals_not_found:
                    signals_not_found.append(dut_name)

        cycles_checked += 1

        if stop_outer:
            break

        # Advance DUT one cycle for the NEXT golden entry.
        await RisingEdge(dut.clk)

    # Stimulus sanity check — uses flag set by drive_inputs()
    if INPUT_PORTS and not _STIMULUS_DELIVERED:
        raise AssertionError(
            "test_layered: drive_inputs() was never called (no stimulus delivered)"
        )

    # Warn about ports that could not be found
    if signals_not_found:
        dut._log.warning(
            f"[LAYERED] {len(signals_not_found)} port(s) not found in DUT, "
            f"skipped: {signals_not_found[:5]}"
            + (f" ... and {len(signals_not_found)-5} more" if len(signals_not_found) > 5 else "")
        )

    # Report results
    if signals_compared == 0:
        raise AssertionError(
            "test_layered: ZERO signals were compared — GOLDEN_TO_PORT keys "
            "do not match any golden trace signal names"
        )
    if divergences:
        FAIL_COUNT += len(divergences)
        _finalize_divergences(dut, divergences, "LAYERED")
    else:
        dut._log.info(
            f"[LAYERED] PASS — {cycles_checked} cycles, "
            f"{signals_compared} signal values matched"
        )


@cocotb.test()
async def test_internal_signals(dut):
    """Test 4: Per-cycle internal signal comparison against golden model.

    This is the KEY verification test. It reads RTL internal registers
    via VPI (cocotb's dut.hierarchy.signal.value) and compares them
    against golden model trace on EVERY clock cycle.

    This test catches bugs that test_layered misses — test_layered only
    compares top-level output ports, missing internal register divergences.

    Timing semantics:
        After `await RisingEdge(dut.clk)`, cocotb + iverilog VPI reads values
        produced by the PREVIOUS posedge's NBA. Equivalently: at RisingEdge N,
        cocotb sees POST-NBA of posedge N-1.

        The golden model trace records POST-NBA state for each posedge.
        The comparison loop reads trace[N] at RisingEdge N, which shows the
        results of posedge N-1's computation.

        Registered outputs (ready, valid, etc.) have a 1-cycle delay from
        the FSM state that computes them — the golden model must track this.

        Alignment rule (single source of truth — do NOT add offsets elsewhere):
        DRIVE_PHASE_CYCLES is consumed entirely inside `drive_inputs()` via
        its `hold_data_cycles` parameter. When drive_inputs() returns, the
        DUT register state corresponds to golden cycle 1. The comparison
        loop therefore slices the trace as `expected_cycles[RESET_CYCLE_SKIP:]`
        (skip ONLY the reset state) and compares BEFORE the next await —
        do not re-add DRIVE_PHASE_CYCLES to this slice.

    Skipped if golden_model.py trace mode does not include internal signals.
    """
    global FAIL_COUNT

    if not GOLDEN_AVAILABLE:
        dut._log.info("[SKIP] test_internal_signals: golden_model.py not available")
        return

    await ensure_clock(dut)
    await reset_dut(dut)

    expected_cycles = golden_run()
    if not expected_cycles:
        dut._log.info("[SKIP] test_internal_signals: golden model returned no data")
        return

    # Check if trace includes internal signals (any key containing '.' or ending with _reg)
    has_internal = any('.' in k or k.endswith('_reg')
                       for entry in expected_cycles for k in entry)
    if not has_internal:
        dut._log.info("[SKIP] test_internal_signals: golden trace has no internal signals")
        return

    dut._log.info(f"[INTERNAL] Comparing {len(expected_cycles)} cycles, internal signals")

    # Pre-validate golden trace signal names against DUT hierarchy
    _validate_trace_signal_names(expected_cycles, dut, "test_internal_signals")

    # IMPORTANT: codegen MUST add drive_inputs() call here with golden model
    # test vectors before the comparison loop. Without driving inputs,
    # the DUT has no stimulus and all outputs will be initial values.
    # <CODEGEN: drive_inputs() call here — same as test_layered>

    divergences: list[dict] = []
    cycles_checked = 0
    signals_compared = 0
    signals_not_found = []

    # Alignment: skip golden cycle 0 (reset state). See _align_trace() for rationale.
    compare_cycles = _align_trace(expected_cycles)

    for cycle_idx, expected in enumerate(compare_cycles):
        stop_outer = False
        for sig_name, expected_val in expected.items():
            if sig_name in INPUT_PORTS:
                # Stimulus comparison: golden trace recorded the input value
                # the DUT is expected to see this cycle. If RTL input doesn't
                # match, the testbench driver is wrong (not the DUT).
                try:
                    actual_val = int(getattr(dut, sig_name).value)
                    signals_compared += 1
                    if actual_val != expected_val:  # noqa: SIM102 — nested for readability in rendered TB
                        if _record_divergence(
                            divergences, sig_name, expected_val, actual_val,
                            cycle_idx, _lookup_signal_width(sig_name),
                            kind="stimulus_mismatch",
                        ):
                            stop_outer = True
                            break
                except (AttributeError, ValueError):
                    pass
                continue

            try:
                # Navigate VPI hierarchy for module-qualified names
                if '.' in sig_name:
                    parts = sig_name.split('.')
                    obj = dut
                    for part in parts:
                        # Handle array indexing: w_reg[0], mem[3][7]
                        while '[' in part:
                            arr_name, rest = part.split('[', 1)
                            if arr_name:
                                obj = getattr(obj, arr_name)
                            idx_str, part = rest.split(']', 1)
                            idx = int(idx_str)
                            obj = obj[idx]
                        if part:  # remaining non-index part
                            obj = getattr(obj, part)
                    actual_val = int(obj.value)
                else:
                    # Handle top-level array signals: sig_name[0]
                    if '[' in sig_name:
                        base, rest = sig_name.split('[', 1)
                        obj = getattr(dut, base)
                        idx_str, _ = rest.split(']', 1)
                        obj = obj[int(idx_str)]
                        actual_val = int(obj.value)
                    else:
                        sig = getattr(dut, sig_name)
                        actual_val = int(sig.value)

                signals_compared += 1
                if actual_val != expected_val:
                    # Try to get signal width for proper hex formatting
                    try:
                        sig_width = len(obj if '.' in sig_name else sig)
                    except Exception:
                        sig_width = _lookup_signal_width(sig_name)
                    if _record_divergence(
                        divergences, sig_name, expected_val, actual_val,
                        cycle_idx, sig_width,
                    ):
                        stop_outer = True
                        break
            except (AttributeError, IndexError):
                if sig_name not in signals_not_found:
                    signals_not_found.append(sig_name)

        cycles_checked += 1
        if stop_outer:
            break

        # Advance DUT one cycle for the NEXT golden entry.
        await RisingEdge(dut.clk)

    # Stimulus sanity check — uses flag set by drive_inputs()
    if INPUT_PORTS and not _STIMULUS_DELIVERED:
        raise AssertionError(
            "test_internal_signals: drive_inputs() was never called (no stimulus delivered)"
        )

    # Warn about signals that could not be found in DUT hierarchy
    if signals_not_found:
        dut._log.warning(
            f"[INTERNAL] {len(signals_not_found)} signal(s) not found in DUT, "
            f"skipped: {signals_not_found[:5]}"
            + (f" ... and {len(signals_not_found)-5} more" if len(signals_not_found) > 5 else "")
        )

    # Safety check: verify we actually compared something
    if signals_compared == 0:
        dut._log.error(
            "[INTERNAL] ZERO signals were compared — golden trace signal names "
            "do not match any DUT signals. Check naming convention."
        )
        raise AssertionError(
            "test_internal_signals: no signals compared, trace names may not match RTL"
        )

    if divergences:
        FAIL_COUNT += len(divergences)
        _finalize_divergences(dut, divergences, "INTERNAL")
    else:
        dut._log.info(
            f"[INTERNAL] PASS — {cycles_checked} cycles, "
            f"{signals_compared} signal values matched"
        )


# ─── Multi-block chaining ─────────────────────────────────────────────
# Mandatory for designs that consume multiple input blocks per operation
# (Merkle-Damgård hashes, block ciphers, accumulator-style filters). Catches
# Patterns 11 and 14 at testbench-time instead of at integration-time.
#
# Activation: golden_model.py MUST export:
#   MULTI_BLOCK_INPUTS         : list[list[dict]] — one outer entry per test
#                                message, each inner list is the per-block
#                                input port dict (excluding `is_last`).
#   MULTI_BLOCK_EXPECTED_DIGEST: list[int]       — final-block expected
#                                output integer per message. Compared against
#                                `dut.<DIGEST_OUTPUT_PORT>.value` after the
#                                last block.
#
# DIGEST_OUTPUT_PORT below MUST be set by codegen to the name of the design's
# final output port (e.g. "result_out", "ciphertext_out"). Leave None and the
# test SKIPs.

DIGEST_OUTPUT_PORT = None  # codegen: set to the design's final output port name

# DONE_SIGNAL_PORT: name of the 1-bit signal that asserts when a block's result
# is ready (e.g. "valid_out", "hash_valid", "done"). Codegen MUST set this for
# any design whose done signal is not literally "valid_out" — otherwise the
# multi-block driver can't tell when each block finishes. Defaults to None, in
# which case the test falls back to DIGEST_OUTPUT_PORT (if it looks like a
# valid signal) and finally to "valid_out".
DONE_SIGNAL_PORT = None  # codegen: set to the design's 1-bit done/valid signal


@cocotb.test()
async def test_multi_block_chaining(dut):
    """Test 5: Multi-block chaining behavior — catches Patterns 11 & 14.

    For multi-block designs (Merkle-Damgård hashes, block ciphers), drives
    each test vector's blocks back-to-back and compares the FINAL output
    against the golden expected digest. Verifies:
      - Chaining registers are correctly re-initialized for a new message
        (Pattern 11): if V0-V7 retain stale state, test 2's final digest
        will differ from MULTI_BLOCK_EXPECTED_DIGEST[1].
      - `done`/`valid_out` is correctly gated by `is_last` (Pattern 14):
        a warning is logged if done asserts after an intermediate block.
    """
    global FAIL_COUNT

    if not GOLDEN_AVAILABLE:
        dut._log.info("[SKIP] test_multi_block_chaining: golden_model.py not available")
        return
    if DIGEST_OUTPUT_PORT is None:
        dut._log.info(
            "[SKIP] test_multi_block_chaining: DIGEST_OUTPUT_PORT not set "
            "(codegen did not identify a digest port for this design)"
        )
        return

    try:
        from golden_model import MULTI_BLOCK_INPUTS, MULTI_BLOCK_EXPECTED_DIGEST
    except ImportError:
        dut._log.info(
            "[SKIP] test_multi_block_chaining: MULTI_BLOCK_INPUTS / "
            "MULTI_BLOCK_EXPECTED_DIGEST not exported by golden_model.py "
            "(single-block design or codegen did not add multi-block vectors)"
        )
        return

    if len(MULTI_BLOCK_INPUTS) != len(MULTI_BLOCK_EXPECTED_DIGEST):
        raise AssertionError(
            f"test_multi_block_chaining: MULTI_BLOCK_INPUTS len="
            f"{len(MULTI_BLOCK_INPUTS)} != MULTI_BLOCK_EXPECTED_DIGEST len="
            f"{len(MULTI_BLOCK_EXPECTED_DIGEST)} — golden_model.py mismatch."
        )
    # Force at least one message with 2+ blocks; a 1-block-only matrix
    # cannot exercise the chaining path that this test exists to cover.
    if not any(len(blocks) >= 2 for blocks in MULTI_BLOCK_INPUTS):
        raise AssertionError(
            "test_multi_block_chaining: no test vector has 2+ blocks — "
            "MULTI_BLOCK_INPUTS must include at least one message that "
            "exercises chaining."
        )

    await ensure_clock(dut)

    for msg_idx, blocks in enumerate(MULTI_BLOCK_INPUTS):
        # Reset between messages to test re-initialization of chaining state.
        await reset_dut(dut)
        dut._log.info(
            f"[MULTI_BLOCK] msg {msg_idx}: driving {len(blocks)} block(s)"
        )
        final_done = await drive_block_sequence(
            dut, blocks,
            done_name=(DONE_SIGNAL_PORT
                       or (DIGEST_OUTPUT_PORT if DIGEST_OUTPUT_PORT.startswith("valid") else None)
                       or "valid_out"),
        )
        if final_done < 0:
            FAIL_COUNT += 1
            dut._log.error(
                f"[MULTI_BLOCK] msg {msg_idx}: timed out before final block done"
            )
            continue

        actual = int(getattr(dut, DIGEST_OUTPUT_PORT).value)
        expected = MULTI_BLOCK_EXPECTED_DIGEST[msg_idx]
        if actual != expected:
            FAIL_COUNT += 1
            try:
                width = len(getattr(dut, DIGEST_OUTPUT_PORT))
            except Exception:
                width = _lookup_signal_width(DIGEST_OUTPUT_PORT)
            hex_digits = max((width + 3) // 4, 1)
            dut._log.error(
                f"[MULTI_BLOCK] msg {msg_idx} digest mismatch "
                f"(width={width}b):\n"
                f"  expected = 0x{expected:0{hex_digits}x}\n"
                f"  actual   = 0x{actual:0{hex_digits}x}\n"
                f"  xor diff = 0x{expected ^ actual:0{hex_digits}x}\n"
                f"  ➜ Likely Pattern 11 (chaining reset) — chaining registers "
                f"may not be re-initialized for the new message."
            )
        else:
            dut._log.info(
                f"[MULTI_BLOCK] msg {msg_idx}: digest matches "
                f"(0x{actual:x})"
            )


@cocotb.test()
async def test_summary(dut):
    """Final test: reports overall pass/fail.

    MUST be the last test defined in this file — cocotb runs tests in
    definition order. This test reads the accumulated FAIL_COUNT.
    """
    global FAIL_COUNT
    await ensure_clock(dut)
    await RisingEdge(dut.clk)
    if FAIL_COUNT == 0:
        dut._log.info("ALL TESTS PASSED")
    else:
        dut._log.error(f"FAILED: {FAIL_COUNT} assertion(s) failed")
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall