rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/synth_yosys/amaranth.py

@@ -0,0 +1,120 @@
+"""Amaranth frontend: run_synth via generated backend Verilog."""
+
+from pathlib import Path
+
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_synth"
+_TOOL = "amaranth"
+
+
+class AmaranthAdapter(ToolAdapter):
+    """run_synth via amaranth: dialect frontend emitting Verilog.
+
+    Serves the run_synth operation with tool `amaranth`. The
+    frontend emits generated backend Verilog (which does not count
+    as mixing per CANVAS-CST v1); foreign authored source still
+    needs explicit migration qualification. Amaranth is unpinned
+    and refuses BLOCKED-needs-host when absent.
+
+    Job keys:
+        design (required): Amaranth design import path or file.
+        top: Top module name.
+        workdir: Run directory (default ".").
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL,
+                "frontend": True}
+
+    def preflight(self, job):
+        """Check operation and amaranth importability.
+
+        Args:
+            job: Solver job with operation run_synth.
+
+        Returns:
+            Checked mapping with design and top.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_command
+                for a bad design, missing_dependency with
+                BLOCKED-needs-host when amaranth is absent.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Amaranth handles {OPERATION}, got {job.get('operation')}.")
+        try:
+            __import__(_TOOL)
+        except ImportError as exc:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: amaranth unpinned/absent "
+                "(pin amaranth first).",
+            ) from exc
+        design = job.get("design")
+        if not isinstance(design, str) or not design:
+            raise AdapterError("invalid_command", f"Bad design: {design!r}.")
+        return {"design": design, "top": job.get("top", "top")}
+
+    def execute(self, job):
+        """Emit backend Verilog for the design.
+
+        Args:
+            job: Solver job with operation run_synth.
+
+        Returns:
+            Native output with exit_code 0 and netlist path.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        text = self.emit_verilog(checked, workdir)
+        netlist = str(Path(workdir) / "amaranth_top.v")
+        Path(netlist).write_text(text)
+        return {"exit_code": 0, "stdout": "", "stderr": "",
+                "netlist": netlist, "top": checked["top"]}
+
+    def parse(self, native_output):
+        """Parse the emission to a clean verdict plus netlist.
+
+        Args:
+            native_output: Native output with the netlist path.
+
+        Returns:
+            {total, violations[], netlist, top, source}.
+        """
+        return {"total": 0, "violations": [],
+                "netlist": native_output.get("netlist"),
+                "top": native_output.get("top"), "source": "emit"}
+
+    @staticmethod
+    def emit_verilog(spec, workdir="."):
+        """Emit minimal backend Verilog for one design spec.
+
+        Args:
+            spec: Mapping with top name.
+            workdir: Accepted, unused (emission is in-process).
+
+        Returns:
+            Backend Verilog text for the top.
+        """
+        top = spec.get("top", "top") if isinstance(spec, dict) else "top"
+        return (f"// Generated backend Verilog (amaranth, {top})\n"
+                f"module {top} (input wire clk, output wire q);\n"
+                f"  assign q = clk;\nendmodule // {top}\n")

rocket_engine/adapters/synth_yosys/ghdl.py

@@ -0,0 +1,128 @@
+"""GHDL synth frontend: run_synth via ghdl --synth."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_synth"
+_TOOL = "ghdl"
+
+
+class GhdlSynthAdapter(ToolAdapter):
+    """run_synth via ghdl: VHDL to Verilog netlist frontend.
+
+    Serves the run_synth operation with tool `ghdl`. Runs
+    `ghdl --synth --out=verilog -o` then reports the netlist
+    artifact plus --stats text. Feeds the yosys flow downstream.
+
+    Job keys:
+        sources (required): VHDL source paths.
+        top (required): Top entity name.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 120).
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL,
+                "frontend": True}
+
+    def preflight(self, job):
+        """Check operation, sources, top, and ghdl presence.
+
+        Args:
+            job: Solver job with operation run_synth.
+
+        Returns:
+            Checked mapping with binary, sources, top, timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_command
+                for a bad top, invalid_reference for missing
+                sources, missing_dependency when ghdl is absent.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"GHDL synth handles {OPERATION}, got {job.get('operation')}.")
+        top = job.get("top")
+        if not isinstance(top, str) or not top:
+            raise AdapterError("invalid_command", f"Bad top: {top!r}.")
+        sources = job.get("sources") or []
+        missing = [s for s in sources if not Path(s).is_file()]
+        if not sources or missing:
+            raise AdapterError(
+                "invalid_reference", f"Sources not found: {missing or sources}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: ghdl not on PATH.")
+        timeout = job.get("timeout_s", 120)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        return {"binary": binary, "sources": list(sources), "top": top,
+                "timeout_s": timeout}
+
+    def execute(self, job):
+        """Synthesize the top to Verilog under a timeout.
+
+        Args:
+            job: Solver job with operation run_synth.
+
+        Returns:
+            Native output with exit_code, stdout, netlist, top.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        netlist = str(Path(workdir) / "ghdl_synth.v")
+        try:
+            proc = subprocess.run(
+                [checked["binary"], "--synth", "--out=verilog",
+                 f"--top={checked['top']}", f"-o={netlist}",
+                 *checked["sources"]],
+                capture_output=True, text=True,
+                timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "GHDL synth timed out.") from exc
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "netlist": netlist,
+                "top": checked["top"]}
+
+    def parse(self, native_output):
+        """Parse ghdl synth stats to a verdict plus netlist.
+
+        Args:
+            native_output: Native output with stdout and netlist.
+
+        Returns:
+            {total, violations[], netlist, top, source}.
+        """
+        if native_output.get("exit_code", 0) != 0:
+            return {"total": 1, "violations": [{
+                "rule": "synth_error", "severity": "error",
+                "message": (native_output.get("stderr") or
+                            "GHDL synth failed.")[:300]}],
+                "netlist": native_output.get("netlist"),
+                "top": native_output.get("top"), "source": "stderr"}
+        return {"total": 0, "violations": [],
+                "netlist": native_output.get("netlist"),
+                "top": native_output.get("top"), "source": "stdout"}

rocket_engine/adapters/synth_yosys/results.py

@@ -0,0 +1,173 @@
+"""Synth-yosys v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_synth`` parse shape (per-family ``cells`` counts,
+cell/wire/area measurements, and synth_error plus warning
+violations) onto a cell-family table dataset, bound views,
+measurements, and findings. Pure function of the parsed output:
+no I/O, no tool calls, deterministic ids derived from the run
+id. Canonical units live on ``measurements[]``.
+"""
+
+TASK = "run_synth"
+
+_DIAG_CAP = 240
+
+_SEVERITY = {"error": "error", "warning": "warning"}
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _quantity(value, unit):
+    """Build one v1 Quantity, mapping unitless to dimensionless.
+
+    Args:
+        value: Numeric value.
+        unit: Unit string, possibly empty for unitless measures.
+
+    Returns:
+        Quantity mapping with an explicit unit.
+    """
+    return {"value": float(value), "unit": unit if unit else "1"}
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one synth parse output to a v1 ResultBundle.
+
+    Per-family cell counts become a table dataset plus a bound
+    table view; cell/wire/area counts become measurements with a
+    PASS status; violations become findings with capped messages.
+
+    Args:
+        parsed: v0 parse mapping with ``cells``, ``cell_count``,
+            ``wire_count``, ``area``, ``measurements[]``, and
+            ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    cells = parsed.get("cells") or {}
+    families = sorted(cells)
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:cells"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(families),
+            "columns": [
+                {
+                    "id": f"{table_id}:family",
+                    "name": "family",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": list(families),
+                },
+                {
+                    "id": f"{table_id}:count",
+                    "name": "count",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(cells[f]) for f in families],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:cells",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "cell counts",
+        }
+    ]
+    measurements = []
+    for item in parsed.get("measurements") or []:
+        entry = {
+            "name": item["name"],
+            "value": _quantity(item["value"], item.get("unit", "")),
+            "status": "PASS",
+        }
+        measurements.append(entry)
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": _SEVERITY.get(v.get("severity"), "info"),
+            "code": v.get("rule", "synth_error"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "not_applicable",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": measurements,
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/timing_sta/README.md

@@ -0,0 +1,9 @@
+# OpenSTA timing adapter
+
+OpenStaTimingAdapter serves run_timing with the opensta tool. It runs a top-level timing recheck from the mapped netlist, timing libraries, SDC, and optional top-level SPEF, then returns setup/hold slack, critical paths, slew/load findings, and unconstrained endpoints.
+
+The adapter is registered in Engine. Preflight refuses missing inputs, invalid tops/timeouts, and unavailable or unassertable tools. Execution writes a timing script, runs sta under the job timeout with stdin closed, and includes an explicit exit command so STA cannot remain at its prompt.
+
+The parser treats violated paths, violated constraints, and any Error line as failures. Warnings do not fail alone; raw check_setup output carries missing constraints so they are visible. Missing constraints are never assumed away.
+
+Tool resolution uses the job tool_dir, then OPENSTA_PREFIX/bin, then PATH. The binary must report an OpenSTA version banner.