bjwanneng/veriflow-cc / src/claude_skills/vf-rtl
vf-rtl
Verifiedtemplates/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)}")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |