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

analysis/vcd2table.py

View on GitHub
#!/usr/bin/env python3
"""vcd2table.py — Convert a VCD file to a cycle-accurate text table for LLM analysis.

Usage:
    python3 vcd2table.py <vcd_file> [options]
    python3 vcd2table.py --vcd <vcd_file> [options]

Options:
    --vcd <path>            VCD file path (alias for positional vcd_file)
    --sim-log <path>        sim.log or sim_<module>.log — extract failing signal names
    --signals <s1,s2,...>   comma-separated list of extra signals to always include
    --window <N>            cycles around each failure to show (default: 15)
    --module <name>         only show signals from this module scope
    --output <path>         write table to file instead of stdout
    --test-vector-index <N> golden model test vector index (default: 0)
    --apply-offset          apply detected golden/VCD cycle offset during diff

Output:
    A text table written to stdout (or --output), formatted for direct LLM reading.
    Columns: Cycle | <signal1> | <signal2> | ... | NOTES
    Rows: one per posedge clk
    NOTES column: flags assertion violations and [FAIL] markers.
"""

import os
import re
import sys
import argparse
import subprocess
from pathlib import Path
from collections import defaultdict


def has_unknown_bits(value: str) -> bool:
    """Return True when a VCD value contains x/z unknown bits."""
    val = str(value)
    if val.lower().startswith("0x"):
        val = val[2:]
    return any(c in "xXzZ" for c in val)


def format_vcd_value(value: str) -> str:
    """Format a VCD value for display without hiding x/z states.

    Binary vectors longer than 4 bits are shown as hex with explicit width
    prefix (e.g., 32'h00000001) to preserve bit-width information for
    accurate comparison with golden model values.
    """
    val = str(value)
    if has_unknown_bits(val):
        return val.lower()
    if len(val) > 4 and all(c in "01" for c in val):
        width = len(val)
        int_val = int(val, 2)
        hex_digits = (width + 3) // 4
        hex_str = format(int_val, f'0{hex_digits}x')
        return f"{width}'h{hex_str}"
    return val


def normalize_for_compare(value: object) -> tuple[str, object]:
    """Normalize VCD/golden values while preserving unknowns.

    VCD vectors are binary strings. Golden values are usually ints or hex
    strings. Returning typed tuples avoids ambiguous string comparison.
    """
    if isinstance(value, int):
        return ("int", value)

    val = str(value).strip().lower().replace("_", "")
    if val in ("", "?"):
        return ("missing", val)
    if has_unknown_bits(val):
        return ("unknown", val)
    if val.startswith("0x"):
        try:
            return ("int", int(val, 16))
        except ValueError:
            return ("text", val)
    if re.fullmatch(r"[01]+", val):
        return ("int", int(val, 2))
    if re.fullmatch(r"\d+", val):
        return ("int", int(val, 10))
    return ("text", val)


# ─── VCD Parser ───────────────────────────────────────────────────────────────

class VCDParser:
    """Minimal VCD parser. Handles scalar and vector signals."""

    def __init__(self, max_time_steps: int = 1_000_000):
        self.signals = {}       # id → {name, width, scope}
        self.id_to_name = {}    # id → full_name
        self.changes = defaultdict(dict)  # time → {full_name: value}
        self.timescale = "1ns"
        self._scope_stack = []
        self._max_time_steps = max_time_steps

    @staticmethod
    def _token_stream(path: str):
        """Yield VCD tokens line-by-line to avoid loading the entire file."""
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            for line in f:
                for tok in line.split():
                    yield tok

    def parse(self, path: str):
        file_size = os.path.getsize(path)
        max_size = 100 * 1024 * 1024  # 100 MB
        if file_size > max_size:
            raise ValueError(
                f"VCD file too large ({file_size / 1024 / 1024:.0f} MB, "
                f"max {max_size / 1024 / 1024:.0f} MB). "
                f"Use a smaller dump or trim the waveform first."
            )
        tokens = self._token_stream(path)
        current_time = 0
        time_step_count = 0

        try:
            tok = next(tokens)
            while True:
                if tok == "$timescale":
                    ts_parts = []
                    tok = next(tokens)
                    while tok != "$end":
                        ts_parts.append(tok)
                        tok = next(tokens)
                    self.timescale = " ".join(ts_parts)

                elif tok == "$scope":
                    next(tokens)  # scope type (e.g. "module") — advance, unused
                    scope_name = next(tokens)
                    self._scope_stack.append(scope_name)
                    next(tokens)  # $end

                elif tok == "$upscope":
                    if self._scope_stack:
                        self._scope_stack.pop()
                    next(tokens)  # $end

                elif tok == "$var":
                    next(tokens)  # var type (e.g. "reg"/"wire") — advance, unused
                    width = int(next(tokens))
                    var_id = next(tokens)
                    var_name = next(tokens)
                    # skip bit-select or $end
                    nxt = next(tokens)
                    if nxt != "$end":
                        next(tokens)  # $end
                    scope = ".".join(self._scope_stack)
                    full_name = f"{scope}.{var_name}" if scope else var_name
                    self.signals[var_id] = {
                        "name": var_name,
                        "full_name": full_name,
                        "width": width,
                        "scope": scope,
                    }
                    self.id_to_name[var_id] = full_name

                elif tok == "$dumpvars" or tok == "$dumpall":
                    tok = next(tokens)
                    while tok != "$end":
                        if tok[0] in "01xXzZ" and len(tok) > 1:
                            val = tok[0].lower()
                            var_id = tok[1:]
                            if var_id in self.id_to_name:
                                self.changes[current_time][self.id_to_name[var_id]] = val
                        elif tok[0] in "bBrR":
                            val = tok[1:]
                            var_id = next(tokens)
                            if var_id in self.id_to_name:
                                self.changes[current_time][self.id_to_name[var_id]] = val
                        tok = next(tokens)

                elif tok.startswith("#"):
                    current_time = int(tok[1:])
                    time_step_count += 1
                    if time_step_count > self._max_time_steps:
                        raise ValueError(
                            f"VCD has too many time steps (>{self._max_time_steps}). "
                            f"Use a smaller dump or increase max_time_steps."
                        )

                elif tok[0] in "01xXzZ":
                    # Scalar: 0/1/x/z followed by id
                    val = tok[0].lower()
                    var_id = tok[1:]
                    if var_id in self.id_to_name:
                        self.changes[current_time][self.id_to_name[var_id]] = val

                elif tok[0] in "bBrR":
                    # Vector: b<value> <id>
                    val = tok[1:]
                    var_id = next(tokens)
                    if var_id in self.id_to_name:
                        self.changes[current_time][self.id_to_name[var_id]] = val

                tok = next(tokens)

        except StopIteration:
            pass

        return self


# ─── Signal Selection ─────────────────────────────────────────────────────────

def extract_failing_signals_from_log(log_path: str) -> list[str]:
    """Parse sim.log / sim_<module>.log for signal names in [FAIL] lines."""
    signals = []
    if not Path(log_path).exists():
        return signals

    text = Path(log_path).read_text(encoding="utf-8", errors="replace")

    # Match patterns like: [FAIL] cycle=5 expected data_out=0xFF got 0x00
    # or: [FAIL] Test 3: state_reg expected IDLE got RUN
    fail_lines = [line for line in text.splitlines() if re.search(r'\[FAIL\]|FAILED:', line)]

    for line in fail_lines:
        # Extract identifiers that look like signal names (snake_case or mixed case)
        words = re.findall(r'\b([a-zA-Z][a-zA-Z0-9_]+(?:_reg|_next|_out|_in|_valid|_ready|_en|_flag)?)\b', line)
        signals.extend(words)

    # Remove common non-signal words
    noise = {"expected", "got", "test", "cycle", "failed", "assert", "module", "at", "in"}
    return [s for s in dict.fromkeys(signals) if s not in noise]


# ─── Waveform Table Builder ───────────────────────────────────────────────────

def find_clk_signal(all_signals: set[str]) -> str | None:
    # Exact conventional names first (deterministic), then a substring pass
    # so derived clock names (clk_cpu, pix_clk, ...) don't hard-exit the tool.
    for name in sorted(all_signals):
        basename = name.split(".")[-1]
        if basename in ("clk", "clock", "clk_i"):
            return name
    for name in sorted(all_signals):
        basename = name.split(".")[-1]
        if "clk" in basename or "clock" in basename:
            return name
    return None


def find_rst_signal(all_signals: set[str]) -> str | None:
    for name in sorted(all_signals):
        basename = name.split(".")[-1]
        if basename in ("rst", "reset", "rst_i", "rst_n"):
            return name
    return None


def find_fsm_signals(all_signals: set[str]) -> list[str]:
    fsm_signals = []
    for name in sorted(all_signals):
        basename = name.split(".")[-1]
        if re.search(r'state|fsm|phase|mode', basename, re.IGNORECASE):
            fsm_signals.append(name)
    return fsm_signals


def build_cycle_table(
    vcd: VCDParser,
    include_signals: list[str],
    window_cycles: list[tuple[int, int]],  # [(start_cycle, end_cycle), ...]
    annotations: dict[int, list[str]],     # cycle → [annotation strings]
    clk_name: str,
) -> tuple[str, list[tuple[int, dict[str, str]]]]:
    """Build a text cycle table from VCD data.

    Returns (formatted_string, cycle_snapshots) where cycle_snapshots is
    [(cycle_num, {signal_name: value})] for all cycles (not just the window).
    """
    if not include_signals:
        return "(no signals to display)\n", []

    # Build timeline: sort all timestamps, find posedge clk
    all_times = sorted(vcd.changes.keys())
    if not all_times:
        return "(VCD has no signal changes)\n", []

    # Reconstruct signal state across all time steps
    current_state: dict[str, str] = {}
    cycle_snapshots: list[tuple[int, dict[str, str]]] = []  # (cycle_num, state_at_posedge)
    cycle_num = -1

    for t in all_times:
        changes = vcd.changes[t]
        # Snapshot BEFORE applying this timestamp's changes: iverilog VCDs
        # record the posedge and its NBA updates at the same timestamp, so
        # applying first would capture post-NBA of edge N. The pipeline's
        # compare convention (bug_patterns.md Pattern 15) reads at posedge N
        # the state settled at edge N-1 (post-NBA of N-1 = pre-NBA of N) —
        # the same value cocotb's RisingEdge compare and an active-region
        # $display see. Snapshotting after the update shifted every signal
        # one cycle later than the golden trace.
        if clk_name in changes and changes[clk_name] == "1":
            cycle_num += 1
            cycle_snapshots.append((cycle_num, dict(current_state)))
        current_state.update(changes)

    if not cycle_snapshots:
        return "(No clock edges found in VCD)\n", []

    # Determine which cycles to show based on window
    if window_cycles:
        show_cycles = set()
        for start, end in window_cycles:
            for c in range(max(0, start), min(end + 1, len(cycle_snapshots))):
                show_cycles.add(c)
    else:
        show_cycles = set(range(len(cycle_snapshots)))

    if not show_cycles:
        return "(No cycles in display window)\n", cycle_snapshots

    # Shorten signal names — strip common scope prefix and Verilog _reg suffix
    def short_name(name: str) -> str:
        parts = name.split(".")
        base = parts[-1] if len(parts) > 1 else name
        # Strip Verilog _reg suffix (added by iverilog for registered outputs)
        if base.endswith("_reg") and not base.endswith("__reg"):
            base = base[:-4]
        return base

    col_names = ["Cycle"] + [short_name(s) for s in include_signals] + ["NOTES"]

    # Collect rows
    rows = []
    for cycle_num, state in cycle_snapshots:
        if cycle_num not in show_cycles:
            continue

        row = [str(cycle_num)]
        for sig in include_signals:
            val = state.get(sig, "?")
            # Format known binary vectors as hex, but preserve x/z exactly.
            val = format_vcd_value(val)
            row.append(val)

        notes = annotations.get(cycle_num, [])
        row.append(" | ".join(notes) if notes else "")
        rows.append(row)

    # Calculate column widths
    col_widths = [max(len(col_names[i]), max((len(r[i]) for r in rows), default=0))
                  for i in range(len(col_names))]

    # Format header
    sep = "+" + "+".join("-" * (w + 2) for w in col_widths) + "+"
    header = "|" + "|".join(f" {col_names[i]:<{col_widths[i]}} " for i in range(len(col_names))) + "|"

    lines = [sep, header, sep]
    for row in rows:
        padded = [f" {row[i]:<{col_widths[i]}} " for i in range(len(col_names))]
        lines.append("|" + "|".join(padded) + "|")
    lines.append(sep)

    return "\n".join(lines) + "\n", cycle_snapshots


# ─── Golden Model Comparison ──────────────────────────────────────────────────

def detect_cycle_offset(
    cycle_snapshots: list[tuple[int, dict[str, str]]],
    golden_cycles: dict[int, dict[str, str]],
    include_signals: list[str],
) -> int:
    """Auto-detect the VCD cycle offset where golden cycle 0 should align.

    Strategy: Find the first golden cycle with a non-trivial value, then find
    the first VCD cycle where a matching signal has the same value.
    Falls back to 0 offset if no clear alignment point is found.
    """
    short_names = {s: s.split(".")[-1] for s in include_signals}

    # Find the first golden cycle that has any non-zero, non-trivial value
    golden_start = None
    for gc in sorted(golden_cycles.keys()):
        vals = golden_cycles[gc]
        has_active = any(
            v not in ("0", "0x0", "0x00000000", "")
            for v in vals.values()
        )
        if has_active:
            golden_start = gc
            break

    if golden_start is None:
        return 0

    # Find the first VCD cycle where a signal matches the golden start cycle
    for vcd_cycle, state in cycle_snapshots:
        for sig in include_signals:
            short = short_names[sig]
            if short not in golden_cycles.get(golden_start, {}):
                continue
            vcd_val = state.get(sig, "0")
            golden_val = golden_cycles[golden_start].get(short, "0")
            vcd_norm = normalize_for_compare(vcd_val)
            golden_norm = normalize_for_compare(golden_val)
            if vcd_norm == golden_norm and vcd_norm != ("int", 0):
                offset = vcd_cycle - golden_start
                return max(0, offset)

    return 0


def run_golden_model_comparison(
    golden_path: str,
    cycle_snapshots: list[tuple[int, dict[str, str]]],
    include_signals: list[str],
    test_vector_index: int = 0,
    apply_offset: bool = False,
) -> str | None:
    """Run a golden model and compare outputs with RTL cycle-by-cycle.

    The golden model script can use either of two interfaces:
      Strategy 1: Run as standalone script producing stdout lines like:
          "cycle N: signal_name=0xVALUE signal2=0xVALUE"
      Strategy 2: Define a run() function returning list[dict] where each dict
          maps signal_name (short, no scope) -> integer value.

    Returns a diff report string, or None if the golden model cannot be loaded.
    """
    golden_path = str(Path(golden_path).resolve())
    if not Path(golden_path).exists():
        return f"ERROR: Golden model not found: {golden_path}\n"

    golden_cycles: dict[int, dict[str, str]] = {}

    # Strategy 1: Run as standalone script and parse stdout
    try:
        result = subprocess.run(
            [sys.executable, golden_path],
            capture_output=True, text=True, timeout=30,
            encoding="utf-8", errors="replace"
        )
        if result.returncode == 0 and result.stdout.strip():
            for line in result.stdout.splitlines():
                m = re.match(r'cycle\s+(\d+)\s*:\s+(.+)', line, re.IGNORECASE)
                if m:
                    cycle = int(m.group(1))
                    assignments = m.group(2)
                    golden_cycles[cycle] = {}
                    for assignment in re.finditer(
                        r'(\w+)\s*=\s*(0x[0-9a-fA-F_]+|\d+)', assignments
                    ):
                        golden_cycles[cycle][assignment.group(1)] = assignment.group(2)
    except Exception as e:
        print(f"[vcd2table] golden standalone run failed (strategy 1 skipped): {e}",
              file=sys.stderr)

    # Strategy 2: Import via canonical rtl_utils loader
    if not golden_cycles:
        try:
            from rtl_utils import load_golden_trace as _rtl_utils_load
            cycles_dict = _rtl_utils_load(golden_path, test_vector_index=test_vector_index)
            for i, entry in cycles_dict.items():
                golden_cycles[i] = {
                    k: hex(v) if isinstance(v, int) else str(v)
                    for k, v in entry.items()
                }
        except RuntimeError:
            pass
        except Exception as e:
            if not golden_cycles:
                return f"[GOLDEN] Could not load golden model: {e}\n"

    if not golden_cycles:
        return "[GOLDEN] Golden model produced no parseable cycle data.\n" \
               "[GOLDEN] Expected format: 'cycle N: signal_name=0xVALUE' on each line, " \
               "or a run() function returning list[dict].\n"

    # Build diff report
    lines = []
    lines.append("=" * 72)
    lines.append("GOLDEN MODEL DIFF REPORT")
    lines.append("=" * 72)
    lines.append("")

    # Build name mapping: golden signal name → VCD signal name
    # Accounts for: Verilog _reg suffix, u_ instance prefix, module hierarchy
    def _strip_reg(name: str) -> str:
        if name.endswith("_reg") and not name.endswith("__reg"):
            return name[:-4]
        return name

    def _fuzzy_match(golden_name: str, vcd_names: list[str]) -> str | None:
        """Find the VCD signal name that best matches a golden model signal name."""
        golden_stripped = _strip_reg(golden_name.split(".")[-1])
        golden_parts = golden_name.split(".")

        for vcd_name in vcd_names:
            vcd_stripped = _strip_reg(vcd_name.split(".")[-1])
            vcd_parts = vcd_name.split(".")

            # Exact basename match (after _reg stripping)
            if golden_stripped == vcd_stripped:
                return vcd_name

            # Module-qualified match: golden "module.signal" matches VCD "u_module.signal_reg"
            if len(golden_parts) >= 2 and len(vcd_parts) >= 2:
                golden_mod = golden_parts[-2]
                vcd_mod = vcd_parts[-2].removeprefix("u_")
                if golden_mod == vcd_mod and golden_stripped == vcd_stripped:
                    return vcd_name

        return None

    # Build mapping: golden_short → VCD full name
    short_to_vcd = {}
    for sig in include_signals:
        short = _strip_reg(sig.split(".")[-1])
        short_to_vcd[short] = sig

    # Map golden signal names to VCD signal names
    golden_to_vcd = {}
    for golden_key in set(k for gc in golden_cycles.values() for k in gc):
        match = _fuzzy_match(golden_key, list(include_signals))
        if match:
            golden_to_vcd[golden_key] = match
            continue
        # Fallback: try matching stripped basename
        stripped = _strip_reg(golden_key.split(".")[-1])
        if stripped in short_to_vcd:
            golden_to_vcd[golden_key] = short_to_vcd[stripped]

    first_divergence = None
    first_divergence_info = None
    divergence_count = 0

    # Detect, but do not silently apply, cycle offset. Applying it by default
    # can hide the exact early/late timing bugs this tool is meant to expose.
    offset_candidate = detect_cycle_offset(cycle_snapshots, golden_cycles, include_signals)
    offset = offset_candidate if apply_offset else 0
    if offset_candidate != 0:
        lines.append(
            f"CYCLE OFFSET CANDIDATE: +{offset_candidate} "
            f"(golden cycle N appears to align to VCD cycle N+{offset_candidate})"
        )
        if apply_offset:
            lines.append("OFFSET APPLIED because --apply-offset was requested.")
        else:
            lines.append("OFFSET NOT APPLIED by default; timing bugs remain visible.")
        lines.append("")

    for cycle_num, state in cycle_snapshots:
        golden_cycle = cycle_num - offset
        if golden_cycle not in golden_cycles:
            continue
        golden = golden_cycles[golden_cycle]

        for golden_name, golden_val in golden.items():
            # Map golden signal name to VCD signal name
            vcd_sig = golden_to_vcd.get(golden_name)
            if vcd_sig is None:
                continue

            raw_rtl_val = state.get(vcd_sig, "?")
            rtl_val = format_vcd_value(raw_rtl_val)

            rtl_norm = normalize_for_compare(raw_rtl_val)
            golden_norm = normalize_for_compare(golden_val)

            if rtl_norm != golden_norm:
                if first_divergence is None:
                    first_divergence = cycle_num
                    first_divergence_info = {
                        "cycle": cycle_num,
                        "signal": golden_name,
                        "golden": golden_val,
                        "rtl": rtl_val,
                        "rtl_kind": rtl_norm[0],
                        "golden_kind": golden_norm[0],
                    }
                divergence_count += 1
                lines.append(
                    f"  CYCLE {cycle_num}: {golden_name} — golden={golden_val} rtl={rtl_val}"
                )

    lines.append("")
    if first_divergence is not None:
        lines.append(f"FIRST DIVERGENCE: cycle {first_divergence}")
        lines.append(f"TOTAL MISMATCHES: {divergence_count}")
        if first_divergence_info:
            div = first_divergence_info
            if div["rtl_kind"] == "unknown":
                bug_type = "unknown-or-undriven"
            elif offset_candidate:
                bug_type = "possible-timing-offset"
            else:
                bug_type = "data-or-initialization"
            lines.append(
                "FIRST DIVERGENCE SUMMARY: "
                f"cycle={div['cycle']} signal={div['signal']} "
                f"golden={div['golden']} rtl={div['rtl']} type={bug_type}"
            )
        lines.append("")
        lines.append("DIAGNOSIS:")
        lines.append(f"  1. The first divergence at cycle {first_divergence} is the root cause.")
        lines.append("  2. Check if the divergence is a timing offset (value correct but")
        lines.append("     arrives 1 cycle early/late) or a computation error (value is wrong).")
        lines.append("  3. For timing offset: check shift register alignment and control")
        lines.append("     signal co-assertion between FSM and consumer modules.")
        lines.append("  4. For computation error: trace the exact formula producing the wrong value.")
    else:
        lines.append("NO DIVERGENCES FOUND — golden model matches RTL for the compared cycles.")
    lines.append("")

    return "\n".join(lines)


# ─── Main ─────────────────────────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(description="Convert VCD to LLM-readable cycle table")
    parser.add_argument("vcd_file", nargs="?", help="Path to .vcd file")
    parser.add_argument("--vcd", dest="vcd_file_alias", help="Path to .vcd file")
    parser.add_argument("--sim-log", help="sim.log path — extract failing signal names")
    parser.add_argument("--signals", help="Extra signals to always include (comma-separated)")
    parser.add_argument("--window", type=int, default=15, help="Cycles around each failure (default 15)")
    parser.add_argument("--module", help="Filter signals to this module scope")
    parser.add_argument("--output", help="Write output to file instead of stdout")
    parser.add_argument("--golden-model", help="Python golden model — compare RTL outputs cycle-by-cycle")
    parser.add_argument("--test-vector-index", type=int, default=0,
                        help="Golden model test vector index (default: 0)")
    parser.add_argument("--apply-offset", action="store_true",
                        help="Apply detected golden/VCD cycle offset during diff")
    args = parser.parse_args()

    args.vcd_file = args.vcd_file_alias or args.vcd_file
    if not args.vcd_file:
        parser.error("vcd_file is required (positional or --vcd)")

    if not Path(args.vcd_file).exists():
        print(f"ERROR: VCD file not found: {args.vcd_file}", file=sys.stderr)
        sys.exit(1)

    # 1. Parse VCD
    print(f"[vcd2table] Parsing {args.vcd_file}...", file=sys.stderr)
    vcd = VCDParser().parse(args.vcd_file)

    all_signal_names = set(vcd.id_to_name.values())
    if not all_signal_names:
        print("ERROR: No signals found in VCD file", file=sys.stderr)
        sys.exit(1)

    print(f"[vcd2table] Found {len(all_signal_names)} signals, "
          f"{len(vcd.changes)} time steps", file=sys.stderr)

    # 2. Find clk and rst
    clk_name = find_clk_signal(all_signal_names)
    if not clk_name:
        print("ERROR: Could not find clock signal (clk/clock/clk_i)", file=sys.stderr)
        sys.exit(1)

    rst_name = find_rst_signal(all_signal_names)
    fsm_signals = find_fsm_signals(all_signal_names)

    # 3. Determine signals to show
    include_signals = []
    if rst_name:
        include_signals.append(rst_name)

    # FSM signals always included
    include_signals.extend(fsm_signals[:3])  # cap at 3 FSM signals

    # Signals from failing assertions in sim.log
    if args.sim_log:
        failing_sigs = extract_failing_signals_from_log(args.sim_log)
        print(f"[vcd2table] Failing signals from log: {failing_sigs}", file=sys.stderr)
        for sig_basename in failing_sigs:
            # Find full name matching this basename
            matches = [n for n in all_signal_names if n.split(".")[-1] == sig_basename]
            if args.module:
                matches = [n for n in matches if args.module in n]
            include_signals.extend(matches[:2])  # cap at 2 matches per name

    # Extra signals from --signals flag
    if args.signals:
        for sig_basename in args.signals.split(","):
            sig_basename = sig_basename.strip()
            matches = [n for n in all_signal_names if n.split(".")[-1] == sig_basename]
            include_signals.extend(matches[:2])

    # Deduplicate, preserve order
    seen = set()
    include_signals = [s for s in include_signals if not (s in seen or seen.add(s))]

    if not include_signals:
        # Fallback: show all top-level port-like signals
        include_signals = sorted(
            [n for n in all_signal_names if n.split(".")[-1] not in ("clk", "clock")],
        )[:12]
        print("[vcd2table] No specific signals identified — showing first 12", file=sys.stderr)

    print(f"[vcd2table] Displaying {len(include_signals)} signals: "
          f"{[s.split('.')[-1] for s in include_signals]}", file=sys.stderr)

    # 4. Find failure cycles from sim.log
    fail_cycles: list[int] = []
    if args.sim_log and Path(args.sim_log).exists():
        log_text = Path(args.sim_log).read_text(encoding="utf-8", errors="replace")
        for line in log_text.splitlines():
            m = re.search(r'cycle[=:\s]+(\d+)', line, re.IGNORECASE)
            if m and re.search(r'\[FAIL\]|FAILED:', line):
                fail_cycles.append(int(m.group(1)))

    # 5. Build annotations from fail cycles
    annotations: dict[int, list[str]] = defaultdict(list)
    for fc in fail_cycles:
        annotations[fc].append("[FAIL]")

    # 6. Determine display windows
    if fail_cycles:
        window_cycles = [(max(0, fc - args.window // 2), fc + args.window // 2)
                         for fc in fail_cycles]
    else:
        # No specific failures found — show first 50 cycles
        window_cycles = [(0, 49)]

    # 7. Build table
    table, cycle_snapshots = build_cycle_table(vcd, include_signals, window_cycles, annotations, clk_name)

    # 8. Build header summary
    output_parts = []
    output_parts.append("=" * 72)
    output_parts.append("VCD WAVEFORM TABLE — for LLM timing analysis")
    output_parts.append(f"VCD file  : {args.vcd_file}")
    output_parts.append(f"Timescale : {vcd.timescale}")
    output_parts.append(f"Clock     : {clk_name}")
    output_parts.append(f"Signals   : {', '.join(s.split('.')[-1] for s in include_signals)}")
    if fail_cycles:
        output_parts.append(f"Fail cycles: {fail_cycles}  (window ±{args.window//2} cycles shown)")
    else:
        output_parts.append("No [FAIL] cycles detected — showing first 50 cycles")
    output_parts.append("=" * 72)
    output_parts.append("")

    output_parts.append(table)

    # 9. Golden model comparison (if available)
    if args.golden_model and Path(args.golden_model).exists():
        golden_diff = run_golden_model_comparison(
            args.golden_model,
            cycle_snapshots,
            include_signals,
            test_vector_index=args.test_vector_index,
            apply_offset=args.apply_offset,
        )
        if golden_diff:
            output_parts.append("")
            output_parts.append(golden_diff)
    elif args.golden_model:
        output_parts.append(f"\n[GOLDEN] Golden model not found: {args.golden_model}\n")

    # 10. Guidance for LLM
    if fail_cycles:
        output_parts.append("")
        output_parts.append("DIAGNOSIS HINTS:")
        output_parts.append("  1. Look at the [FAIL] row — note the cycle number.")
        output_parts.append("  2. Trace the failing signal backwards: when did it last change?")
        output_parts.append("  3. Check FSM state at [FAIL] cycle — is it the expected state?")
        output_parts.append("  4. Compare RTL register values against the golden_model trace.")
        output_parts.append("  5. Common causes: off-by-one pipeline stage, reset not clearing"
                             " output register, handshake held too long/short.")

    final_output = "\n".join(output_parts)

    # 10. Write output
    if args.output:
        Path(args.output).write_text(final_output, encoding="utf-8")
        print(f"[vcd2table] Written to {args.output}", file=sys.stderr)
    else:
        print(final_output)


if __name__ == "__main__":
    main()
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