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/golden_model_template.py

View on GitHub
"""golden_model.py — Golden reference model for <design_name>.

Pure Python implementation. No external dependencies.
Provides: algorithm, test vectors, run() -> cycle-accurate expected values.

Two modes:
  - compute(inputs, trace=False) -> dict   : final outputs only (for testbench)
  - compute(inputs, trace=True)  -> list   : per-cycle state (for vcd2table diff)
  - run()                        -> list   : standard interface for pipeline
"""
from __future__ import annotations

# --- Constants ---
# (algorithm-specific constants: IV, T_j, state encodings, etc.)

MASK32 = 0xFFFFFFFF  # common for 32-bit datapaths; adjust per design


# --- Bit manipulation / helper functions ---
# (ROL, P0, P1, FF, GG, etc. — only what the algorithm needs)
# Keep these as standalone functions, not class methods.

def ROL(x: int, n: int, width: int = 32) -> int:
    """Left rotate for width-bit values."""
    n = n % width
    return ((x << n) | (x >> (width - n))) & ((1 << width) - 1)


# --- Core algorithm ---
def compute(inputs: dict, trace: bool = False) -> dict | list[dict]:
    """Execute the algorithm.

    Args:
        inputs: dict with input signal names -> values.
                Example for hash cores:
                  {"blocks": [block0_int, ...], "is_last_flags": [True, ...]}
        trace:  If False (default), return dict of final output values only.
                If True, return list[dict] — one dict per clock cycle, mapping
                signal_name -> int. This is used by vcd2table.py for cycle-by-cycle
                comparison against RTL waveform.

    Returns:
        trace=False -> dict: {"output_port": value, ...}
        trace=True  -> list[dict]: [{signal: value, ...}, ...] indexed by cycle

    Trace timing convention (CRITICAL — read carefully):
        The golden model uses SOFTWARE-INSTANTANEOUS semantics:
        each trace entry records the NEW values produced by step N of the
        algorithm. There is no NBA delay added inside the golden model.

        Cycle alignment with RTL is handled entirely by the cocotb testbench:
          drive_inputs() in the cocotb template holds inputs for
          DRIVE_PHASE_CYCLES posedges (sourced from
          spec.timing_convention.golden_to_rtl_offset_cycles =
          max(pipeline_delay_cycles)) BEFORE the compare loop starts.
          That advances the DUT past the input sampling latency so the
          per-cycle compare loop can read golden[N] and dut.<reg>.value
          at the same logical step.

        Implementation rule for the trace:
          - `cycles.append({...})` AFTER each computation step, recording the
            NEW register values produced by that step
          - Signal names must be **lower_snake_case** matching RTL register names
            (use the `_reg` suffix that VPI exposes, e.g. `a_reg`, `state_reg`,
            `round_reg`). NEVER use uppercase (e.g. A_reg) — Verilog convention
            is lower_snake_case, and cocotb VPI paths are case-sensitive.
          - Cycle 0 SHOULD record the post-reset state (all-zero or IV load)
            so RESET_CYCLE_SKIP=1 in the cocotb template aligns correctly

    CRITICAL: Registered outputs (ready, valid, etc.):
        Signals that are registered outputs (driven by a _reg flip-flop, not
        combinational assign) have a 1-cycle delay from the FSM state that
        computes them. For example, if IDLE state sets ready_next=1 and CALC
        state sets ready_next=0, the ready_reg transitions:
        - At IDLE→CALC posedge: ready_next=1 (from IDLE), so ready_reg becomes 1
        - At next CALC posedge: ready_next=0 (from CALC), so ready_reg becomes 0

        The golden model trace must record ready_reg=1 at the IDLE→CALC
        transition cycle, NOT ready_reg=0. The "0" appears one cycle later.

        Similarly, at DONE→IDLE transition: if DONE state sets ready_next=0,
        the trace records ready_reg=0 at the DONE→IDLE cycle. ready_reg=1
        appears one cycle later when IDLE sets ready_next=1.

    Implementation note:
        Write ONE algorithm implementation. When trace=True, record intermediate
        state at each cycle into a list. When trace=False, skip the recording
        and just return the final result. Do NOT write two separate implementations.
    """
    cycles = [] if trace else None

    # --- Algorithm implementation ---
    # For iterative/multi-cycle algorithms:
    #   for step in range(NUM_STEPS):
    #       # ... computation ...
    #       if trace:
    #           cycles.append({
    #               "output_signal": output_val,
    #               "intermediate_reg": reg_val,     # match RTL register names
    #               # IMPORTANT: include ALL registers that participate in the
    #               # computation — working regs, expansion regs,
    #               # combinational outputs. Omitting any register
    #               # creates a blind spot where bugs go undetected until final output.
    #               # Signal names should match RTL _reg names for VPI access.
    #           })
    #       # ... continue computation ...

    if trace:
        return cycles
    return {}  # {"output_port": final_value, ...}


# --- Test vectors ---
# Known correct input/output pairs from the standard specification.
TEST_VECTORS = [
    {
        "name": "<test_name>",
        "inputs": {},   # design-specific input format
        "expected": {},  # {"output_port": expected_value, ...}
    },
    # ... more vectors ...
]


# --- Multi-block chaining exports (ONLY for multi-block designs) ---
# Required when the design has an `is_last` / `*_last*` / `is_final` port, or is
# a hash / Merkle-Damgård / sponge / CBC-CTR chain / accumulator / streaming
# filter. The cocotb testbench's test_multi_block_chaining consumes these to
# exercise the 2nd+ block — where chaining-reset bugs (pattern 11) and
# valid-not-gated-by-is_last bugs (pattern 14) only manifest.
#
# For single-block designs, OMIT this section entirely (its absence is how
# vf-tb-gen detects single-block and skips the multi-block test).
MULTI_BLOCK_INPUTS = [
    # list of messages, each a list of per-block input dicts; at least one
    # message must have length >= 2.
    # [
    #     [{"data": 0x1122..., "is_last": False}, {"data": 0x3344..., "is_last": True}],
    # ],
]

MULTI_BLOCK_EXPECTED_DIGEST = [
    # final digest for each message above, parallel list, same length.
    # [0x<expected_hash>],
]


# --- Standard Interface ---

def run(test_vector_index: int = 0) -> list[dict]:
    """Run a test vector and return cycle-accurate expected values.

    This is the standard interface consumed by:
      - vcd2table.py (Strategy 2: import run(), get list[dict])
      - cocotb testbench (golden_run() for per-cycle comparison)
      - Verilog TB generation (extract expected final outputs)

    Args:
        test_vector_index: index into TEST_VECTORS (default: 0)

    Returns:
        list of dicts, one per clock cycle:
        [
            {"signal_name": int_value, ...},  # cycle 0
            {"signal_name": int_value, ...},  # cycle 1
            ...
        ]
        For multi-module designs, keys are "<module>.<signal>".
    """
    tv = TEST_VECTORS[test_vector_index]
    return compute(tv["inputs"], trace=True)


def get_test_vectors() -> list[dict]:
    """Return test vectors with final expected outputs (for testbench generation).

    Returns:
        list of {"name": str, "inputs": dict, "expected": dict}
    """
    results = []
    for tv in TEST_VECTORS:
        computed = compute(tv["inputs"], trace=False)
        results.append({
            "name": tv["name"],
            "inputs": tv["inputs"],
            "expected": tv.get("expected") or computed,
        })
    return results


if __name__ == "__main__":
    # Strategy 1 for vcd2table.py: print "cycle N: signal=0xVALUE" lines
    # Also used for standalone verification.
    #
    # Hex format note: we emit unpadded hex (`0x{v:x}`) so the same template
    # works for 32-bit, 64-bit, and 256-bit datapaths without truncation or
    # excess zero-padding. The vcd2table parser at vcd2table.py accepts any
    # length of hex digits.

    # Run default test vector with cycle trace
    cycles = run()
    for i, entry in enumerate(cycles):
        if entry:
            parts = [f"{k}=0x{v:x}" if isinstance(v, int) else f"{k}={v}"
                     for k, v in entry.items()]
            print(f"cycle {i}: {' '.join(parts)}")

    # Verify final outputs against expected
    print()
    for tv in get_test_vectors():
        computed = compute(tv["inputs"], trace=False)
        ok = computed == tv["expected"]
        name = tv["name"]
        parts = [f"{k}=0x{v:x}" if isinstance(v, int) and v > 0xFFFF else f"{k}={v}"
                 for k, v in tv["expected"].items()]
        print(f"[{'PASS' if ok else 'FAIL'}] {name}: {' '.join(parts)}")
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