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

verify/formal_prove.py

View on GitHub
#!/usr/bin/env python3
"""Formal property prover for VeriFlow-CC.

Replaces the deleted no-op formal_property_gen with a REAL flow: generate
Verilog-2005 formal properties (assert/assume in clocked always blocks — NOT
SystemVerilog SVA, per the project's Verilog-2005-only rule) from spec.json,
then prove them with SymbiYosys (sby) + yosys smt.

Usage:
    python formal_prove.py --spec workspace/docs/spec.json --module top \\
        --rtl-dir workspace/rtl --output workspace/docs/top_formal.v
    # add --prove to run sby and write logs/formal.json
"""

from __future__ import annotations

import argparse
import json
import re
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path


# --- helpers --------------------------------------------------------------

def _find_module(spec: dict, module: str) -> dict | None:
    modules = spec.get("modules", [])
    if isinstance(modules, dict):
        modules = list(modules.values())
    for m in modules or []:
        if m.get("module_name") == module:
            return m
    return None


def _port_width(p: dict) -> int:
    w = p.get("width", 1)
    return w if isinstance(w, int) and w > 0 else 1


def _vtype(w: int) -> str:
    return "" if w == 1 else f"[{w - 1}:0] "


def _is_input(p: dict) -> bool:
    d = (p.get("direction") or p.get("dir") or "").lower()
    return d.startswith("in") or d == "input"


def _find_rtl(rtl_dir: str, module: str) -> str | None:
    d = Path(rtl_dir)
    # Match the actual module DECLARATION, not a substring — `--module top`
    # must not bind to a file that merely mentions "top" (e.g. top_wrapper).
    decl_re = re.compile(rf"\bmodule\s+{re.escape(module)}\b")
    for cand in (d / f"{module}.v", *sorted(d.glob("*.v"))):
        if cand.exists():
            try:
                if decl_re.search(cand.read_text(encoding="utf-8", errors="replace")):
                    return str(cand)
            except OSError:
                continue
    return None


# --- property generation --------------------------------------------------

def generate_properties(spec: dict, module: str) -> str:
    """Emit a Verilog-2005-formal wrapper proving spec-derived invariants.

    Instantiates the DUT and emits assert()/assume() in clocked always blocks.
    DUT data inputs are driven by (* anyseq *) free variables so the prover
    considers ALL input sequences — an undriven reg would be a constant and
    every property would hold vacuously. v1 properties: handshake
    valid-stability for output `valid` ports with an ack.
    Always returns a syntactically valid module (a useful artifact even with no
    derivable property — but then --prove reports NO_PROPERTIES, not PASS).
    """
    mod = _find_module(spec, module)
    if mod is None:
        mod = {"module_name": module, "ports": []}
    ports = mod.get("ports") or []

    lines = [
        f"// Auto-generated formal properties for {module}",
        "// Verilog-2005 + yosys -formal. assert()/assume() only (no SVA).",
        "// DUT data inputs are (* anyseq *) free variables — the prover",
        "// considers all input sequences (an undriven reg would be constant",
        "// and every property would pass vacuously).",
        "// Prove with: sby (see formal_prove.py --prove).",
        "`timescale 1ns/1ps",
        f"module {module}_formal(input wire clk, input wire rst);",
    ]

    # Declare wrapper signals for every non-clock/reset port. Inputs become
    # anyseq free variables; outputs are plain wires driven by the DUT.
    for p in ports:
        nm = p.get("name")
        if not nm or nm in ("clk", "clock", "rst", "reset"):
            continue
        vt = _vtype(_port_width(p))
        if _is_input(p):
            lines.append(f"    (* anyseq *) reg {vt}{nm};")
        else:
            lines.append(f"    wire {vt}{nm};")

    # Instantiate the DUT, wiring clk/rst to the wrapper's free clock/reset.
    conns = []
    for p in ports:
        nm = p.get("name")
        if nm in ("clk", "clock"):
            conns.append(f".{nm}(clk)")
        elif nm in ("rst", "reset"):
            conns.append(f".{nm}(rst)")
        elif nm:
            conns.append(f".{nm}({nm})")
    lines.append(f"    {module} dut ({', '.join(conns)});")

    # Environment assumption: reset is asserted in the initial state and
    # released afterwards (matches the pipeline TB convention of reset held
    # at cycle 0 then released — RESET_CYCLE_SKIP).
    lines += [
        "    // Environment: reset asserted at init, released afterwards.",
        "    always @(posedge clk) begin",
        "        if ($initstate) assume(rst);",
        "        else assume(!rst);",
        "    end",
    ]

    # Handshake valid-stability: an output valid that the DUT drives must stay
    # asserted until the ack (ready) is observed — the #1 handshake bug.
    # Guarded by reset: during/after reset the valid reg is cleared, so past
    # tracking must not carry across the reset boundary (spurious FAIL).
    # The ack port MUST itself be a declared port of this module: an ack that
    # exists only in the spec text would elaborate as an implicit undriven
    # wire (constant) and the property would hold vacuously.
    port_names = {p.get("name") for p in ports if p.get("name")}
    n_props = 0
    for p in ports:
        if (not _is_input(p)) and p.get("protocol") == "valid" and p.get("ack_port"):
            v = p.get("name")
            ack = p.get("ack_port")
            if ack not in port_names:
                lines.append(f"    // skipped handshake property for {v}: ack_port "
                             f"{ack!r} is not a declared port of {module}")
                continue
            lines.append(f"    // handshake: {v} (valid) held until {ack} (ready).")
            lines.append(f"    reg past_{v};")
            lines.append(f"    initial past_{v} = 1'b0;")
            lines.append("    always @(posedge clk) begin")
            lines.append(f"        if (rst) past_{v} <= 1'b0;")
            lines.append("        else begin")
            lines.append(f"            past_{v} <= {v};")
            lines.append(f"            if (past_{v}) assert({v} || {ack});")
            lines.append("        end")
            lines.append("    end")
            n_props += 1

    if n_props == 0:
        lines.append("    // No spec-derived output handshake property; wrapper is a")
        lines.append("    // structural harness. Add assert()/assume() here to prove more.")

    lines.append("endmodule")
    return "\n".join(lines) + "\n"


# --- sby run --------------------------------------------------------------

_STATUS_PATTERNS = [
    re.compile(r"status\s*=\s*(pass|fail|error)", re.IGNORECASE),
    re.compile(r"DONE\s*\(\s*(pass|fail|error)", re.IGNORECASE),
    re.compile(r"summary:\s*(pass|fail|error)", re.IGNORECASE),
]


def _parse_sby_output(text: str) -> dict:
    """Parse sby stdout/stderr into {status, proven}.

    sby prints status in several forms across versions — "engine_N.status = PASS",
    "DONE (PASS, rc=0)", or "summary: PASS" — so match all of them.
    """
    found: list[str] = []
    for pat in _STATUS_PATTERNS:
        found.extend(m.upper() for m in pat.findall(text or ""))
    if not found:
        return {"status": None, "proven": None}
    # Any FAIL or ERROR wins over PASS (a partial failure means not proven).
    status = "FAIL" if "FAIL" in found else ("ERROR" if "ERROR" in found else "PASS")
    return {"status": status, "proven": status == "PASS"}


def _sby_config(module: str, dut_file: str, props_file: str) -> str:
    return f"""[options]
mode prove
[engines]
smtbmc z3
[script]
read_verilog -formal {dut_file}
read_verilog -formal {props_file}
prep -top {module}_formal
[files]
{dut_file}
{props_file}
"""


def run_formal(dut_v: str, props_v: str, module: str,
               timeout: int = 120, sby_bin: str = "sby") -> dict:
    """Run sby to prove the generated properties. Mirrors yosys_equiv's pattern."""
    sby_path = shutil.which(sby_bin)
    if sby_path is None:
        return {"proven": None, "status": "SKIP",
                "error": f"sby not found: {sby_bin}"}

    with tempfile.TemporaryDirectory() as tmp:
        tmp_p = Path(tmp)
        dut_dst = tmp_p / Path(dut_v).name
        shutil.copy(dut_v, dut_dst)
        props_dst = tmp_p / f"{module}_formal.v"
        props_dst.write_text(props_v, encoding="utf-8")
        cfg = tmp_p / "formal.sby"
        cfg.write_text(_sby_config(module, dut_dst.name, props_dst.name), encoding="utf-8")

        try:
            proc = subprocess.run(
                [sby_path, "-f", str(cfg)],
                capture_output=True, text=True, timeout=timeout, cwd=str(tmp_p),
            )
        except subprocess.TimeoutExpired:
            return {"proven": None, "status": "TIMEOUT",
                    "error": f"sby timed out after {timeout}s"}
        except Exception as e:  # pragma: no cover - defensive
            return {"proven": None, "status": "ERROR", "error": str(e)}

        parsed = _parse_sby_output(proc.stdout + "\n" + proc.stderr)
        return {
            "status": parsed["status"] or ("ERROR" if proc.returncode != 0 else "UNKNOWN"),
            "proven": parsed["proven"],
            "returncode": proc.returncode,
            "raw_tail": (proc.stdout + proc.stderr)[-800:],
        }


# --- CLI ------------------------------------------------------------------

def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description="Generate + prove formal properties")
    parser.add_argument("--spec", required=True)
    parser.add_argument("--module", required=True)
    parser.add_argument("--rtl-dir", required=True, help="Dir with the DUT .v")
    parser.add_argument("--output", required=True, help="Path for the property .v file")
    parser.add_argument("--prove", action="store_true", help="Run sby to prove")
    parser.add_argument("--timeout", type=int, default=120)
    args = parser.parse_args(argv)

    spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
    props = generate_properties(spec, args.module)
    out = Path(args.output)
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(props, encoding="utf-8")
    print(f"[formal] properties -> {out}", file=sys.stderr)

    if not args.prove:
        print(json.dumps({"proven": None, "status": "GENERATED", "props_path": str(out)}))
        return 0

    # Vacuity guard: with zero assert()s, sby would trivially report PASS and
    # the pipeline would read an empty proof as "formally verified". Refuse
    # to claim anything instead. Count code lines only — the wrapper's own
    # comments mention "assert()" and would otherwise defeat the guard.
    code_only = "\n".join(
        ln for ln in props.splitlines() if not ln.strip().startswith("//")
    )
    n_asserts = len(re.findall(r"\bassert\s*\(", code_only))
    if n_asserts == 0:
        print(json.dumps({
            "proven": None,
            "status": "NO_PROPERTIES",
            "props_path": str(out),
            "note": "no spec-derived assert() properties for this module — "
                    "nothing to prove; NOT a verification pass",
        }, indent=2))
        return 0

    dut = _find_rtl(args.rtl_dir, args.module)
    if dut is None:
        print(json.dumps({"proven": None, "status": "SKIP",
                          "error": f"DUT .v for {args.module} not in {args.rtl_dir}"}))
        return 2
    result = run_formal(dut, props, args.module, timeout=args.timeout)
    result["props_path"] = str(out)
    print(json.dumps(result, indent=2))
    return _exit_code(result)


def _exit_code(result: dict) -> int:
    """Map a formal result to a process exit code.

    0 = proven OR genuinely unknown (couldn't prove either way — not an error).
    1 = FAIL (a real counterexample — equivalence/logic bug found).
    2 = ERROR/TIMEOUT (the tool itself crashed or hit the deadline; distinct
        from FAIL so callers gating on ``$?`` don't read a hard sby crash as
        success, which the old ``else 0`` branch did).
    """
    if result.get("proven") is True:
        return 0
    status = result.get("status")
    if status == "FAIL":
        return 1
    if status in ("ERROR", "TIMEOUT"):
        return 2
    return 0


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: 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