chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/digital_rtl/targets/plan.yml

@@ -0,0 +1,11 @@
+# `chipgraph build plan:<block>` (and `chipgraph plan <block>`): a block's plan, up to and
+# including its gate (task M2-11a): the planner writes it, plan_check checks it, and the
+# build waits on the gate `plan:<block>` until a person approves it.
+schema_version: 1
+target: plan
+description: A block's plan, up to and including the gate plan:<block>.
+params:
+  - name: block
+    description: A block of the profile.
+select:
+  - select: "digital-rtl/plan_expand[block={block}]"

chipgraph/packs/digital_rtl/targets/rtl.yml

@@ -0,0 +1,20 @@
+# `chipgraph build rtl:<block>` (and `chipgraph rtl <block>`, MCP next_task(target=...)):
+# the RTL of one block, from its plan to a pull request (task M2-11a).
+#
+#   digital-rtl/plan -> plan_expand (gate plan:<block>) -> rtl_module, one per planned
+#   module (in dependency order) -> with dv/tb_module (independent of the RTL) ->
+#   digital-rtl/review -> open_pr -> pr_gate (gate pr:<block>)
+#
+# Before the plan is approved only the first selector matches: the build stops at the
+# plan gate and nothing after the plan runs. Once it is approved, `pr_gate` exists and
+# brings in everything it depends on (the modules, the testbench, the review, open_pr).
+schema_version: 1
+target: rtl
+description: The RTL of one block, from its plan to a pull request and its gate.
+params:
+  - name: block
+    description: A block of the profile.
+select:
+  - select: "digital-rtl/plan_expand[block={block}]"
+  - select: "digital-rtl/pr_gate[block={block}]"
+    optional: true

chipgraph/packs/digital_rtl/wrapper/__init__.py

@@ -0,0 +1,24 @@
+"""Wrappers around third-party (vendor) IP, in the emacs verilog-mode AUTO style (M2-12).
+
+A wrapper instantiates an IP module it never edits and maps the IP's ports to the
+project's names. The RTL Author writes only the wrapper's *source*,
+`<wrapper>.src.sv`: its port groups (`/*AUTOINPUT("regexp")*/`, ...), an `AUTO_TEMPLATE`
+that maps the IP's ports (regexps, tie-offs, `unused_*` sinks), the instance with its
+parameters and `/*AUTOINST*/`, and nothing expanded by hand. A generator runs emacs on
+it and writes the expanded `<wrapper>.sv`; a check regenerates and compares.
+
+- `common`: default paths, the profile's `blocks.<b>.wrappers`, path templates;
+- `lisp`: the Emacs Lisp a source may carry (`AUTO_LISP`, `@"(...)"` in a template),
+  allowed only from a small list of side-effect-free forms: emacs runs it;
+- `emacs`: the gen tool `emacs_auto` (rule `digital-rtl/wrapper_gen`): `emacs -Q --batch`
+  on a scratch copy, the verilog-mode variables pinned, through the `Runner`;
+- `expansion`: the expanded instance read back (its connections, `// Templated` or not)
+  and checked against the IP's port declaration (pyslang, header only);
+- `resolver`: the `foreach` selectors `wrappers` and `wrappers.vendor`;
+- `context`: the `rtl.wrapper` section of the author's context.
+
+The rules are `rules/wrapper.yml` (agent, `rtl-author`) and `rules/wrapper_gen.yml`
+(gen); the skill is `skills/wrapper-auto.md` (`rtl/wrapper-auto`); the check is
+`chipgraph.checks.wrap_check`, and `chipgraph.checks.vendor_guard` keeps the IP files
+as recorded.
+"""

chipgraph/packs/digital_rtl/wrapper/common.py

@@ -0,0 +1,171 @@
+"""Shared by the wrapper rules, tool, check and context: paths and the profile entries."""
+
+from __future__ import annotations
+
+import math
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from chipgraph.core.config.models import Profile, WrapperCfg
+
+DEFAULT_SRC = "rtl/emacs/{wrapper}.src.sv"
+"""Where a wrapper's source is, unless a rule or check names another template."""
+DEFAULT_OUT = "rtl/{wrapper}.sv"
+"""Where the generated wrapper is, unless a rule or check names another template."""
+RULE = "digital-rtl/wrapper"
+"""The author's rule: writes the source."""
+GEN_RULE = "digital-rtl/wrapper_gen"
+"""The generator's rule: writes the expanded wrapper."""
+
+
+class WrapperError(Exception):
+    """A wrapper that cannot be named: no such entry, a bad path template."""
+
+
+@dataclass(frozen=True)
+class Wrapper:
+    """One `blocks.<block>.wrappers` entry, with the block it belongs to."""
+
+    block: str
+    cfg: WrapperCfg
+
+    @property
+    def name(self) -> str:
+        return self.cfg.name
+
+    @property
+    def params(self) -> dict[str, str]:
+        """The params of its rule instances."""
+        return {"block": self.block, "wrapper": self.cfg.name}
+
+
+def all_wrappers(profile: Profile, block: str | None = None) -> list[Wrapper]:
+    """Every wrapper of the profile (of `block` only, when given), blocks sorted."""
+    blocks = [block] if block is not None else sorted(profile.blocks)
+    out: list[Wrapper] = []
+    for name in blocks:
+        override = profile.blocks.get(name)
+        if override is not None:
+            out.extend(Wrapper(block=name, cfg=cfg) for cfg in override.wrappers)
+    return out
+
+
+def find_wrapper(profile: Profile, params: Mapping[str, str]) -> Wrapper:
+    """The wrapper a task's params (`block`, `wrapper`) name; `WrapperError` if none."""
+    name = params.get("wrapper")
+    block = params.get("block")
+    if not name:
+        raise WrapperError("the task has no `wrapper` param")
+    for wrapper in all_wrappers(profile, block):
+        if wrapper.name == name:
+            return wrapper
+    where = f"blocks.{block}.wrappers" if block else "any block's wrappers"
+    raise WrapperError(f"no wrapper {name!r} in the profile's {where}")
+
+
+def fill(template: str, params: Mapping[str, str]) -> str:
+    """`template` with `{key}` / `{KEY}` from `params`; `WrapperError` if one is left."""
+    out = template
+    for key, value in params.items():
+        out = out.replace("{" + key + "}", value).replace("{" + key.upper() + "}", value.upper())
+    if "{" in out or "}" in out:
+        raise WrapperError(f"path template {template!r} has a placeholder no param fills")
+    return repo_rel(out)
+
+
+def repo_rel(path: str) -> str:
+    """`path` as a normalised repo-relative POSIX path; `WrapperError` if it is not one."""
+    text = path.replace("\\", "/").strip()
+    parts = [p for p in text.split("/") if p not in ("", ".")]
+    if not parts or text.startswith("/") or ".." in parts or (len(text) > 1 and text[1] == ":"):
+        raise WrapperError(f"{path!r} is not a repo-relative path")
+    return "/".join(parts)
+
+
+def inside(root: Path, rel: str) -> Path:
+    """The file `rel` of the repo at `root`, refused when it resolves outside it."""
+    path = root / repo_rel(rel)
+    real = Path(os.path.realpath(path))
+    if not real.is_relative_to(Path(os.path.realpath(root))):
+        raise WrapperError(f"{rel} resolves outside the repository")
+    return path
+
+
+MAX_TIMEOUT_S = 600.0
+"""The longest `timeout_s` a tool or check accepts."""
+_PROTECTED_DIRS = (".git", ".chipgraph")
+
+
+def timeout_arg(value: object, default: float) -> float:
+    """`timeout_s`: `default` when None, else a finite number, `0 < t <= MAX_TIMEOUT_S`
+    (never a bool or a string); `WrapperError` otherwise."""
+    if value is None:
+        value = default
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int | float)
+        or not math.isfinite(value)
+        or not 0 < value <= MAX_TIMEOUT_S
+    ):
+        raise WrapperError(
+            f"args['timeout_s'] must be a number of seconds, 0 < timeout_s <= {MAX_TIMEOUT_S:g}"
+        )
+    return float(value)
+
+
+def emacs_arg(value: str) -> str:
+    """`emacs`: a bare name (looked up on PATH) or an absolute path to an executable file;
+    `WrapperError` otherwise (a relative path would run a file the repository holds)."""
+    if "/" in value or "\\" in value or os.sep in value:
+        path = Path(value)
+        if not path.is_absolute() or not path.is_file() or not os.access(path, os.X_OK):
+            raise WrapperError(
+                "args['emacs'] must be a command name or an absolute path to an executable"
+            )
+    return value
+
+
+def guarded(root: Path, rel: str, key: str = "path") -> Path:
+    """The repo file `rel` (`inside`: refused outside the repository), refused too when any
+    part is `.git` (in any case) or it is under `.chipgraph/`, as written or as resolved."""
+    path = inside(root, rel)
+    real = Path(os.path.realpath(path)).relative_to(Path(os.path.realpath(root)))
+    for parts in (Path(repo_rel(rel)).parts, real.parts):
+        folded = [p.casefold() for p in parts]
+        if ".git" in folded or (folded and folded[0] in _PROTECTED_DIRS):
+            raise WrapperError(f"args[{key!r}] may not name a file under .git/ or .chipgraph/")
+    return path
+
+
+def paths(wrapper: Wrapper, src: str | None = None, out: str | None = None) -> tuple[str, str]:
+    """The wrapper's source and generated paths, from templates (default: the rules')."""
+    params = wrapper.params
+    return fill(src or DEFAULT_SRC, params), fill(out or DEFAULT_OUT, params)
+
+
+def instance_id(rule: str, wrapper: Wrapper) -> str:
+    """The id of `rule`'s instance for `wrapper` (as `RuleInstance.make_id` builds it)."""
+    return f"{rule}[block={wrapper.block},wrapper={wrapper.name}]"
+
+
+__all__ = [
+    "DEFAULT_OUT",
+    "DEFAULT_SRC",
+    "GEN_RULE",
+    "MAX_TIMEOUT_S",
+    "RULE",
+    "Wrapper",
+    "WrapperError",
+    "all_wrappers",
+    "emacs_arg",
+    "fill",
+    "find_wrapper",
+    "guarded",
+    "inside",
+    "instance_id",
+    "paths",
+    "repo_rel",
+    "timeout_arg",
+]

chipgraph/packs/digital_rtl/wrapper/context.py

@@ -0,0 +1,222 @@
+"""What an `rtl-author` task of rule `digital-rtl/wrapper` gets: the `rtl.wrapper` section.
+
+The author writes a wrapper's source, never its expansion, and cannot run emacs. Its
+context holds what the source is written from, and no IP body:
+
+- `wrapper`: the profile's entry (name, block, IP module, IP files), the source it writes
+  and the file the generator writes from it;
+- `vendor`: the IP module's declaration only, read here with pyslang from the IP files:
+  its parameters and its ports (name, direction, type, packed and unpacked dimensions),
+  never a line of its body, a comment or a line number;
+- `interface`: the wrapper's own ports when the project knows them: the Design Model's
+  (the block's spec ports when the wrapper is the block's top module, else the model's
+  RTL ports of the module), else the block's approved plan's entry of that name; else
+  none, and the author names them from the IP ports and the naming rules;
+- `naming` (next to `wrapper`, as for an RTL module): the project's naming rules as text;
+- `exemplar`: the profile's wrapper exemplar, when it lists one (its text is an input
+  of the task);
+- `generator`: how the source is expanded (the variables the generator pins, the Lisp
+  the source may carry), so the author knows what emacs will do with its template.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.contracts import RuleSpec
+from chipgraph.core.model import DesignModel
+from chipgraph.packs.digital_rtl.plan.model import Plan
+from chipgraph.packs.digital_rtl.rtl.context import _naming, approved_plan_path
+from chipgraph.packs.digital_rtl.wrapper import lisp
+from chipgraph.packs.digital_rtl.wrapper.common import (
+    GEN_RULE,
+    Wrapper,
+    WrapperError,
+    find_wrapper,
+    inside,
+    paths,
+)
+from chipgraph.packs.digital_rtl.wrapper.emacs import PINNED
+from chipgraph.packs.dv.declaration import ModuleDeclaration, extract_declaration
+from chipgraph.packs.dv.interface import _rtl_ports, interface_for, top_module
+
+INSTRUCTIONS = (
+    " Everything about the wrapper is in `rtl.wrapper`: the IP module's port declaration "
+    "(`vendor`), the wrapper's ports when the project knows them (`interface`), the naming "
+    "rules (`rtl.naming.text`) and how the generator expands your source (`generator`). Write "
+    "the source only (the template and the structure, never the expanded port list): on "
+    "submit the engine expands it with emacs and `wrap_check` reports what the expansion "
+    "got wrong, with the expanded lines."
+)
+"""What `get_context` adds to a wrapper task's instructions."""
+
+
+_SHOWN = frozenset(
+    {
+        "verilog-auto-inst-param-value",
+        "verilog-auto-inst-vector",
+        "verilog-auto-inst-sort",
+        "verilog-auto-arg-sort",
+        "verilog-auto-star-expand",
+        "verilog-auto-input-ignore-regexp",
+        "verilog-auto-output-ignore-regexp",
+        "verilog-case-fold",
+    }
+)
+"""The pinned variables the author's template can depend on (the rest is layout)."""
+
+
+def _vendor(root: Path, wrapper: Wrapper) -> tuple[dict[str, Any], ModuleDeclaration | None]:
+    files = []
+    for rel in wrapper.cfg.vendor_files:
+        try:
+            files.append(inside(root, rel))
+        except WrapperError:
+            continue
+    decl = extract_declaration(files, wrapper.cfg.vendor_module)
+    if decl is None:
+        return {
+            "module": wrapper.cfg.vendor_module,
+            "note": (
+                f"no declaration of `{wrapper.cfg.vendor_module}` was found in the IP files: "
+                "report needs_human"
+            ),
+        }, None
+    view = decl.model_dump(mode="json", exclude={"schema_version"})
+    for item in (*view["parameters"], *view["ports"]):
+        item.pop("schema_version", None)
+    view["note"] = (
+        "the IP module's header only (parameters and ports), read by the engine: map every "
+        "port in the AUTO_TEMPLATE; never edit the IP's files"
+    )
+    return view, decl
+
+
+def _plan_ports(root: Path, block: str, name: str) -> list[dict[str, Any]] | None:
+    rel = approved_plan_path(root, block)
+    if rel is None:
+        return None
+    try:
+        plan = Plan.model_validate(yaml.safe_load((root / rel).read_text(encoding="utf-8")))
+    except (OSError, ValueError, yaml.YAMLError):
+        return None
+    module = plan.module(name)
+    if module is None:
+        return None
+    return [
+        {"name": p.name, "direction": p.direction, "width": p.width, "source": "plan"}
+        for p in module.interface.ports
+    ]
+
+
+def _interface(root: Path, model: DesignModel | None, block: str, name: str) -> dict[str, Any]:
+    if model is not None:
+        if top_module(model, block) == name:
+            known = interface_for(name, model=model, block=block)
+            if known.source in ("spec", "model_rtl"):
+                return {
+                    "source": known.source,
+                    "ports": [
+                        {"name": p.name, "direction": p.direction, "width": p.width}
+                        for p in known.ports
+                    ],
+                    "note": "the wrapper is the block's top module: these are its ports",
+                }
+        rtl = _rtl_ports(model, name)
+        if rtl:
+            return {
+                "source": "model_rtl",
+                "ports": [
+                    {"name": p.name, "direction": p.direction, "width": p.width} for p in rtl
+                ],
+                "note": "the Design Model's ports of the existing wrapper: keep them",
+            }
+    planned = _plan_ports(root, block, name)
+    if planned:
+        return {"source": "plan", "ports": planned, "note": "the approved plan's ports"}
+    return {
+        "source": None,
+        "ports": [],
+        "note": (
+            "the project names no ports for this wrapper yet: derive each one from an IP "
+            "port, renamed by the naming rules (the AUTO_TEMPLATE does the renaming)"
+        ),
+    }
+
+
+def _out_template(rules: Sequence[RuleSpec]) -> str | None:
+    rule = next((r for r in rules if r.id == GEN_RULE), None)
+    if rule is None or rule.run is None:
+        return None
+    out = rule.run.args.get("out")
+    return out if isinstance(out, str) else None
+
+
+def wrapper_author_context(
+    root: Path,
+    resolved: ResolvedProfile,
+    rules: Sequence[RuleSpec],
+    *,
+    params: dict[str, str],
+    outputs: Sequence[str],
+    model: DesignModel | None,
+    is_denied: Callable[[str], bool],
+) -> dict[str, Any]:
+    """The `rtl` section of a wrapper task's context (see the module docstring)."""
+    block = params.get("block")
+    out: dict[str, Any] = {"block": block, "wrapper_name": params.get("wrapper")}
+    try:
+        wrapper = find_wrapper(resolved.profile, params)
+    except WrapperError as exc:
+        out["note"] = f"{exc}: report needs_human"
+        return out
+    src_default, gen_default = paths(wrapper, None, _out_template(rules))
+    source = outputs[0] if outputs else src_default
+    vendor, _ = _vendor(root, wrapper)
+    entry: dict[str, Any] = {
+        "name": wrapper.name,
+        "block": wrapper.block,
+        "source": source,
+        "generated": gen_default,
+        "vendor_module": wrapper.cfg.vendor_module,
+        "vendor_files": list(wrapper.cfg.vendor_files),
+        "vendor": vendor,
+        "interface": _interface(root, model, wrapper.block, wrapper.name),
+        "generator": {
+            "tool": "emacs_auto",
+            "command": "emacs -Q --batch <source copy> -f verilog-batch-auto",
+            "pinned": {k: v for k, v in PINNED if k in _SHOWN},
+            "pinned_others": f"{len(PINNED) - len(_SHOWN)} more verilog-mode variables, "
+            "at verilog-mode's defaults or fixed for layout only",
+            "library": "the IP files above (verilog-library-files); nothing else is read",
+            "file_local_variables": "ignored: do not write a Local Variables block",
+            "lisp_functions": sorted(lisp.FUNCTIONS),
+            "lisp_variables": sorted(lisp.VARIABLES),
+            "auto_lisp_may_set": lisp.SETQ_VARIABLE.pattern,
+        },
+    }
+    exemplar = wrapper.cfg.exemplar
+    if exemplar is not None:
+        entry["exemplar"] = (
+            {"path": exemplar, "refused": "a file this role must not read: it is not shown"}
+            if is_denied(exemplar)
+            else {
+                "path": exemplar,
+                "label": (
+                    "a wrapper of this project: imitate its structure (port groups, comments, "
+                    "template layout), not its IP or its names"
+                ),
+                "note": "its text is in this task's `inputs`",
+            }
+        )
+    out["wrapper"] = entry
+    out["naming"] = _naming(root, resolved, wrapper.block)
+    return out
+
+
+__all__ = ["INSTRUCTIONS", "wrapper_author_context"]