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

runners/yosys_equiv.py

View on GitHub
#!/usr/bin/env python3
"""Yosys equivalence checker — lightweight formal verification for VeriFlow-CC.

Uses Yosys equiv_* commands to prove that two Verilog modules are
functionally equivalent.  Best suited for combinational or simple
sequential blocks (single clock, synchronous reset).

Usage:
    python yosys_equiv.py --ref ref.v --impl impl.v --top MODULE_NAME
    python yosys_equiv.py --ref ref.v --impl impl.v --ref-top REF_TOP --impl-top IMPL_TOP

Exit codes:
    0  — equivalence proved (or yosys not available, skipped)
    1  — equivalence NOT proved (or error)
    2  — file/environment error
"""

from __future__ import annotations

import argparse
import json
import shutil
import subprocess
import sys
import tempfile
import time
from pathlib import Path
from typing import Any


def _build_yosys_script(
    ref_path: str,
    impl_path: str,
    ref_top: str,
    impl_top: str | None = None,
    *,
    clk2fflogic: bool = False,
    async2sync: bool = False,
    flatten: bool = False,
) -> str:
    """Generate a Yosys script for equivalence checking.

    Args:
        ref_path: Path to reference Verilog.
        impl_path: Path to implementation Verilog.
        ref_top: Top module name in reference.
        impl_top: Top module name in implementation (defaults to ref_top).
        clk2fflogic: Handle async-reset FFs ($adff) — convert clocked FFs to
            formal logic on the equiv module (inserted after equiv_make).
        async2sync: Convert async resets to sync on each side (after read_verilog).
        flatten: Dissolve hierarchy so submodule cells match across the two
            designs (inserted after equiv_make; exposes hierarchical/blackbox cells).

    With all flags False the original fixed recipe is emitted.
    """
    if impl_top is None:
        impl_top = ref_top

    # Approach: prep each side in its own namespace via `design -stash`,
    # then combine. This is the only reliable way to handle the common
    # case where both files define a top module with the same name.
    async_cmd = "async2sync\n" if async2sync else ""
    post_equiv = ""
    if flatten:
        post_equiv += "flatten equiv\n"
    if clk2fflogic:
        post_equiv += "clk2fflogic equiv\n"

    return f"""# VeriFlow Yosys equivalence check
read_verilog "{ref_path}"
{async_cmd}prep -top {ref_top}
rename {ref_top} ref_top
design -stash veriflow_ref

design -reset
read_verilog "{impl_path}"
{async_cmd}prep -top {impl_top}
rename {impl_top} impl_top
design -stash veriflow_impl

design -copy-from veriflow_ref -as ref_top ref_top
design -copy-from veriflow_impl -as impl_top impl_top

equiv_make ref_top impl_top equiv
{post_equiv}opt -full equiv
equiv_simple equiv
equiv_induct equiv
equiv_status -assert equiv
"""


def _parse_equiv_output(output: str) -> dict:
    """Parse Yosys equiv_status output.

    Returns:
        {"equivalent": bool|None, "unproven": [str], "raw": output}
    """
    result: dict[str, Any] = {
        "equivalent": None,
        "unproven": [],
        "raw": output,
    }

    # 1. Scan for concrete unproven-cell lines FIRST. These are authoritative:
    #    if yosys lists unproven cells, the design is NOT equivalent even if a
    #    success banner also appears (some yosys builds print both on partial
    #    runs). This also stops "Found 0 unproven ..." from being misread below.
    #    Covers two yosys phrasings: the legacy "gold.x != gate.x" form and the
    #    modern "Unproven $equiv ... \\y_gold [i] \\y_gate [i]" form.
    for line in output.splitlines():
        s = line.strip()
        if (s.lower().startswith("unproven $equiv")
                or ("unproven" in s.lower() and "!=" in s)
                or (s.startswith("gold.") and "!=" in s)):
            result["unproven"].append(s)
    if result["unproven"]:
        result["equivalent"] = False
        return result

    # 2. Affirmative PASS — accept the legacy yosys phrasings AND common
    #    rewordings so a future yosys version doesn't silently fall to UNKNOWN.
    #    (Safe to check now: step 1 already returned if any unproven cell existed.)
    pass_phrases = (
        "Equivalence successfully proved",
        "Equivalence successfully proven",
        "Equivalence checking succeeded",
        "Equivalence checking was successful",
        "proved equivalence",
    )
    if any(p in output for p in pass_phrases):
        result["equivalent"] = True
        return result

    # 3. Fallback: a "Found N unproven" summary line without per-cell detail.
    if result["equivalent"] is None:
        for line in output.splitlines():
            if "unproven" in line.lower():
                result["equivalent"] = False
                break

    return result


# Ordered strategies, most-likely-to-succeed first. clk2fflogic/async2sync
# handle async reset ($adff); flatten exposes hierarchical/blackbox cells so
# they can be matched across the two designs.
STRATEGIES = [
    {"name": "base"},
    {"name": "clk2fflogic", "clk2fflogic": True},
    {"name": "flatten", "flatten": True},
    {"name": "async2sync", "async2sync": True},
    {"name": "flatten+clk2fflogic", "flatten": True, "clk2fflogic": True},
]


def _detect_async_reset(verilog_path, top, yosys_path, timeout=30) -> bool:
    """Quick yosys probe: does the design contain $adff (async-reset FF)?"""
    script = f'read_verilog "{verilog_path}"\nprep -top {top}\nstat\n'
    try:
        with tempfile.NamedTemporaryFile(mode="w", suffix=".ys", delete=False) as f:
            f.write(script)
            script_path = f.name
        try:
            r = subprocess.run([yosys_path, "-s", script_path],
                               capture_output=True, text=True, timeout=timeout)
            return "$adff" in (r.stdout or "")
        finally:
            Path(script_path).unlink(missing_ok=True)
    except Exception:
        return False


def _decide(tried: list[dict]) -> dict:
    """Pick the final verdict from a list of per-strategy attempts.

    Each attempt: {"name", "flatten", "equivalent", "unproven"}.
    Returns {equivalent, unproven, strategy_used, is_blackbox_limitation, message}.

    is_blackbox_limitation is True iff a non-flatten strategy reported unproven
    cells that then VANISHED under a flatten strategy — a hierarchical blackbox
    artifact (known yosys limitation), NOT functional inequivalence.
    """
    proven = [t for t in tried if t["equivalent"] is True]
    if proven:
        p = proven[0]
        non_flatten_had_unproven = any(
            (not t["flatten"]) and bool(t["unproven"]) for t in tried
        )
        is_bb = non_flatten_had_unproven and p["flatten"]
        return {
            "equivalent": True,
            "unproven": [],
            "strategy_used": p["name"],
            "is_blackbox_limitation": is_bb,
            "message": (
                "Equivalent after flattening hierarchy — earlier unproven cells "
                "were blackbox artifacts (known yosys limitation), not functional "
                "inequivalence."
            ) if is_bb else None,
        }
    counter = [t for t in tried if t["equivalent"] is False]
    if counter:
        return {
            "equivalent": False,
            "unproven": counter[0]["unproven"],
            "strategy_used": counter[0]["name"],
            "is_blackbox_limitation": False,
            "message": None,
        }
    return {
        "equivalent": None,
        "unproven": [],
        "strategy_used": tried[-1]["name"] if tried else None,
        "is_blackbox_limitation": False,
        "message": None,
    }


def _run_strategy(strat, ref_path, impl_path, top_name, impl_top,
                  yosys_path, timeout):
    """Run one yosys strategy. Returns (parsed, returncode, error_str|None)."""
    script = _build_yosys_script(
        str(ref_path), str(impl_path), top_name, impl_top,
        clk2fflogic=strat.get("clk2fflogic", False),
        async2sync=strat.get("async2sync", False),
        flatten=strat.get("flatten", False),
    )
    with tempfile.NamedTemporaryFile(mode="w", suffix=".ys", delete=False) as f:
        f.write(script)
        script_path = f.name
    try:
        _t0 = time.perf_counter()
        result = subprocess.run(
            [yosys_path, "-s", script_path],
            capture_output=True, text=True, timeout=timeout,
        )
        print(f"[TIMING] step=yosys_equiv strategy={strat.get('name')} "
              f"duration={time.perf_counter() - _t0:.2f}s", file=sys.stderr)
        rc = result.returncode
        err = None
    except subprocess.TimeoutExpired:
        return (_parse_equiv_output(""), None, f"Yosys timed out after {timeout}s")
    except Exception as e:
        return (_parse_equiv_output(""), None, str(e))
    finally:
        Path(script_path).unlink(missing_ok=True)

    combined = result.stdout
    if result.stderr:
        combined += "\n--- STDERR ---\n" + result.stderr
    parsed = _parse_equiv_output(combined)
    # equiv_status -assert exits non-zero on unproven; exit 0 with no unproven
    # means equivalence held even without a recognized success banner.
    if parsed["equivalent"] is None:
        if rc == 0 and not parsed["unproven"]:
            parsed["equivalent"] = True
        elif rc != 0:
            err = f"Yosys exited with code {rc}"
    return (parsed, rc, err)


def check_equivalence(
    ref_path: str | Path,
    impl_path: str | Path,
    top_name: str,
    impl_top: str | None = None,
    yosys_bin: str = "yosys",
    timeout: int = 60,
) -> dict:
    """Run Yosys equivalence check between two Verilog modules.

    Args:
        ref_path: Reference Verilog file.
        impl_path: Implementation Verilog file.
        top_name: Top module name in reference.
        impl_top: Top module name in implementation (defaults to top_name).
        yosys_bin: Yosys executable name or path.
        timeout: Max seconds to wait for Yosys.

    Returns:
        Dict with keys:
            - "equivalent": bool|None
            - "yosys_available": bool
            - "yosys_returncode": int|None
            - "unproven": list[str]
            - "error": str|None
    """
    ref_path = Path(ref_path)
    impl_path = Path(impl_path)

    for p in (ref_path, impl_path):
        if not p.exists():
            return {
                "equivalent": None,
                "yosys_available": False,
                "yosys_returncode": None,
                "unproven": [],
                "error": f"File not found: {p}",
                "strategy_used": None,
                "is_blackbox_limitation": False,
            }

    yosys_path = shutil.which(yosys_bin)
    if yosys_path is None:
        return {
            "equivalent": None,
            "yosys_available": False,
            "yosys_returncode": None,
            "unproven": [],
            "error": f"Yosys not found: {yosys_bin}",
            "strategy_used": None,
            "is_blackbox_limitation": False,
        }

    if impl_top is None:
        impl_top = top_name

    # Detect async-reset FFs; if present, try clk2fflogic-bearing strategies
    # first (they converge faster on $adff designs).
    has_async = (_detect_async_reset(ref_path, top_name, yosys_path) or
                 _detect_async_reset(impl_path, impl_top, yosys_path))
    strategies = list(STRATEGIES)
    if has_async:
        strategies.sort(key=lambda s: 0 if s.get("clk2fflogic") else 1)

    tried = []
    last_rc = None
    last_error = None
    for strat in strategies:
        parsed, rc, err = _run_strategy(
            strat, ref_path, impl_path, top_name, impl_top, yosys_path, timeout
        )
        last_rc = rc
        if err and last_error is None:
            last_error = err
        tried.append({
            "name": strat["name"],
            "flatten": strat.get("flatten", False),
            "equivalent": parsed["equivalent"],
            "unproven": parsed["unproven"],
        })
        if parsed["equivalent"] is True:
            break                       # proved — decide now
        # flatten couldn't clear the unproven cells → real counterexample; stop.
        if (parsed["equivalent"] is False and parsed["unproven"]
                and strat.get("flatten")):
            break

    decision = _decide(tried)
    result = {
        "equivalent": decision["equivalent"],
        "yosys_available": True,
        "yosys_returncode": last_rc,
        "unproven": decision["unproven"],
        "error": last_error,
        "strategy_used": decision["strategy_used"],
        "is_blackbox_limitation": decision["is_blackbox_limitation"],
    }
    if decision["message"]:
        result["message"] = decision["message"]
    return result


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Yosys equivalence checker for VeriFlow RTL"
    )
    parser.add_argument("--ref", required=True, help="Reference Verilog file")
    parser.add_argument("--impl", required=True, help="Implementation Verilog file")
    parser.add_argument("--top", required=True, help="Top module name in reference")
    parser.add_argument("--impl-top", help="Top module name in implementation (default: --top)")
    parser.add_argument("--yosys", default="yosys", help="Yosys executable (default: yosys)")
    parser.add_argument("--timeout", type=int, default=60, help="Timeout in seconds (default: 60)")
    parser.add_argument("--json", action="store_true", help="Output JSON")
    args = parser.parse_args(argv)

    result = check_equivalence(
        ref_path=args.ref,
        impl_path=args.impl,
        top_name=args.top,
        impl_top=args.impl_top,
        yosys_bin=args.yosys,
        timeout=args.timeout,
    )

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        if not result["yosys_available"]:
            print(f"SKIP: {result.get('error', 'Yosys not available')}")
        elif result["equivalent"] is True:
            print("PASS: Equivalence proved.")
        elif result["equivalent"] is False:
            print("FAIL: Equivalence NOT proved.")
            for line in result.get("unproven", []):
                print(f"  {line}")
        else:
            print(f"UNKNOWN: {result.get('error', 'Could not determine equivalence')}")

    if result["equivalent"] is True:
        return 0
    if result["yosys_available"] is False:
        return 2  # Tool not available — distinguish from equivalence failure
    return 1


if __name__ == "__main__":
    sys.exit(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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall