chipgraph 0.1.0rc1__py3-none-any.whl

chipgraph/__init__.py

@@ -0,0 +1,7 @@
+"""chipgraph: AI agent system for chip (IC) design."""
+
+from importlib.metadata import version
+
+__version__ = version("chipgraph")
+
+__all__ = ["__version__"]

chipgraph/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters: tools, formats, LLMs, runners, VCS, review. Core never imports this package."""

chipgraph/adapters/format/__init__.py

@@ -0,0 +1,6 @@
+"""Format adapters: load facts from domain-specific file formats into the Design Model."""
+
+from chipgraph.adapters.format.chip_yaml import ChipYamlAdapter
+from chipgraph.adapters.format.qsoc_contract import QSocContractAdapter
+
+__all__ = ["ChipYamlAdapter", "QSocContractAdapter"]

chipgraph/adapters/format/__main__.py

@@ -0,0 +1,16 @@
+"""`python -m chipgraph.adapters.format [PATH]`: write the chip.yml JSON Schema."""
+
+import sys
+from pathlib import Path
+
+from chipgraph.adapters.format.chip_yaml import schema_json
+
+
+def main() -> None:
+    out = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("schemas/formats/chip.schema.json")
+    out.write_text(schema_json(), encoding="utf-8")
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    main()

chipgraph/adapters/format/_yaml_lines.py

@@ -0,0 +1,54 @@
+"""YAML loading that remembers the source line of every mapping key and list item."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+type YamlPath = tuple[str | int, ...]
+
+
+class LinedYaml:
+    """A parsed YAML document plus the 1-based line of every node, by path.
+
+    `data` is what `yaml.safe_load` returns. `line(("memory_map", 3, "base"))` is the line
+    of that node; a path that is not found falls back to its longest known prefix, so an
+    error about a missing field still points at the item that lacks it.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        text = path.read_text(encoding="utf-8")
+        self.data: Any = yaml.safe_load(text)
+        self._lines: dict[YamlPath, int] = {}
+        root = yaml.compose(text, Loader=yaml.SafeLoader)
+        if root is not None:
+            self._index(root, ())
+
+    def _index(self, node: yaml.Node, at: YamlPath) -> None:
+        self._lines[at] = node.start_mark.line + 1
+        if isinstance(node, yaml.MappingNode):
+            for key_node, value_node in node.value:
+                key = str(key_node.value)
+                self._lines[(*at, key)] = key_node.start_mark.line + 1
+                self._index(value_node, (*at, key))
+                # A key's own line, not its value's (which may start on the next line).
+                self._lines[(*at, key)] = key_node.start_mark.line + 1
+        elif isinstance(node, yaml.SequenceNode):
+            for i, item in enumerate(node.value):
+                self._index(item, (*at, i))
+
+    def line(self, path: Sequence[str | int]) -> int:
+        """The line of `path`, or of its longest known prefix (1 for the document)."""
+        at = tuple(path)
+        while at:
+            if at in self._lines:
+                return self._lines[at]
+            at = at[:-1]
+        return self._lines.get((), 1)
+
+
+__all__ = ["LinedYaml", "YamlPath"]

chipgraph/adapters/format/chip_yaml.py

@@ -0,0 +1,323 @@
+"""Format adapter `chip-yaml`: chipgraph's own generic chip description (`chip.yml`).
+
+`chip.yml` names a chip's buses, blocks, clocks and resets. Numbers that code can work
+out may be left as `auto` (DESIGN.md 4.3, "code computes"):
+
+- **base address** `auto`: blocks are placed in file order at the lowest free address
+  that is aligned to the block's size (a power of two) and overlaps no fixed or already
+  placed block. Needs `size`.
+- **interrupt line** `auto`: interrupts get the lowest line number not used by a fixed
+  line or an earlier `auto`, in file order.
+
+The model: a `project`; per block a `block` (ip, bus in `attrs`), a `memory_region` and
+its `interrupt`s; per bus an `interface` (protocol as data); `clock`s and `reset`s.
+Relations: `contains` project→block, block→region and block→interrupt, and `connects`
+bus→block for each bus slave. A validation error names the file and the line of the item.
+`load_model` also warns about overlapping regions and duplicate interrupt lines.
+
+Regenerate `schemas/formats/chip.schema.json` with `python -m chipgraph.adapters.format`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from chipgraph.adapters.format._yaml_lines import LinedYaml
+from chipgraph.adapters.format.qsoc_contract import (
+    Region,
+    _display_path,
+    contains,
+    duplicate_line_warnings,
+    model_facts,
+    overlap_warnings,
+)
+from chipgraph.core.model import (
+    BlockEntity,
+    ClockEntity,
+    DesignModel,
+    EntityBase,
+    InterfaceEntity,
+    InterruptEntity,
+    MemoryRegionEntity,
+    ProjectEntity,
+    Provenance,
+    Relation,
+    ResetEntity,
+    make_key,
+)
+
+_EXTRACTOR = "chip-yaml"
+
+type Auto = Literal["auto"]
+
+
+class _Spec(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class ClockSpec(_Spec):
+    """A clock."""
+
+    name: str
+    frequency_hz: float | None = Field(default=None, ge=0)
+
+
+class ResetSpec(_Spec):
+    """A reset."""
+
+    name: str
+    active_low: bool | None = None
+    sync: bool | None = None
+
+
+class InterruptSpec(_Spec):
+    """One interrupt output of a block."""
+
+    name: str
+    line: int | Auto = Field(default="auto", description="Interrupt line, or 'auto'.")
+
+
+class BlockSpec(_Spec):
+    """A block: an IP instance on a bus."""
+
+    name: str
+    ip: str | None = Field(default=None, description="The IP it instantiates.")
+    bus: str | None = Field(default=None, description="The bus it is a slave of.")
+    base: int | Auto | None = Field(default=None, description="Base address, or 'auto'.")
+    size: int | None = Field(default=None, gt=0, description="Size of its window in bytes.")
+    interrupts: tuple[InterruptSpec, ...] = ()
+    clock: str | None = None
+    reset: str | None = None
+    owner: str | None = None
+
+
+class BusSpec(_Spec):
+    """A bus; the protocol is data (for example 'APB', 'AXI4')."""
+
+    name: str
+    protocol: str
+    masters: tuple[str, ...] = ()
+    slaves: tuple[str, ...] = ()
+
+
+class ChipYaml(_Spec):
+    """The `chip.yml` schema."""
+
+    project: str
+    data_width: int = Field(ge=1)
+    addr_width: int = Field(ge=1)
+    buses: tuple[BusSpec, ...] = ()
+    blocks: tuple[BlockSpec, ...] = ()
+    clocks: tuple[ClockSpec, ...] = ()
+    resets: tuple[ResetSpec, ...] = ()
+
+
+class ChipYamlAdapter:
+    """`FormatAdapter` for `chip.yml`."""
+
+    name = "chip-yaml"
+
+    def load(self, path: Path) -> Iterable[Mapping[str, object]]:
+        """The `FormatAdapter` protocol: every entity and relation as a plain mapping."""
+        model, _ = self.load_model(path)
+        return model_facts(model)
+
+    def load_model(self, path: Path, root: Path | None = None) -> tuple[DesignModel, list[str]]:
+        """Load `path` into a `DesignModel`; raise `ValueError` naming file:line if invalid.
+
+        When `root` is given and `path` is under it, provenance `file` is written relative
+        to `root` (POSIX); otherwise it is `path.as_posix()` as before.
+        """
+        doc = LinedYaml(path)
+        file = _display_path(path, root)
+        try:
+            chip = ChipYaml.model_validate(doc.data or {})
+        except ValidationError as exc:
+            problems = "; ".join(
+                f"{file}:{doc.line(err['loc'])}: {'.'.join(map(str, err['loc']))}: {err['msg']}"
+                for err in exc.errors()
+            )
+            raise ValueError(f"Invalid chip.yml {file}: {problems}") from exc
+
+        def src(*at: str | int) -> Provenance:
+            return Provenance(file=file, line=doc.line(at), extractor=_EXTRACTOR)
+
+        entities: list[EntityBase] = []
+        relations: list[Relation] = []
+        project_key = make_key("project", chip.project)
+        entities.append(
+            ProjectEntity(
+                key=project_key,
+                name=chip.project,
+                source=src("project"),
+                attrs={"data_width": chip.data_width, "addr_width": chip.addr_width},
+            )
+        )
+
+        bases = resolve_bases(chip.blocks)
+        lines = resolve_lines(chip.blocks)
+        regions: list[Region] = []
+        numbered: list[tuple[str, int, int]] = []
+        for i, block in enumerate(chip.blocks):
+            block_key = make_key("block", block.name)
+            entities.append(
+                BlockEntity(
+                    key=block_key,
+                    name=block.name,
+                    owner=block.owner,
+                    source=src("blocks", i),
+                    attrs={
+                        "ip": block.ip,
+                        "bus": block.bus,
+                        "clock": block.clock,
+                        "reset": block.reset,
+                    },
+                )
+            )
+            relations.append(contains(project_key, block_key, src("blocks", i)))
+            if block.size is not None:
+                region_key = make_key("memory_region", block.name)
+                base = bases[i]
+                entities.append(
+                    MemoryRegionEntity(
+                        key=region_key,
+                        name=block.name,
+                        base=base if base is not None else "auto",
+                        size=block.size,
+                        block=block_key,
+                        source=src("blocks", i, "base"),
+                        attrs={"auto": block.base == "auto"},
+                    )
+                )
+                relations.append(contains(block_key, region_key, src("blocks", i)))
+                if base is not None:
+                    regions.append(Region(block.name, base, block.size, doc.line(("blocks", i))))
+            for j, irq in enumerate(block.interrupts):
+                irq_key = make_key("interrupt", block.name, irq.name)
+                number = lines[(i, j)]
+                entities.append(
+                    InterruptEntity(
+                        key=irq_key,
+                        name=irq.name,
+                        line=number,
+                        block=block_key,
+                        source=src("blocks", i, "interrupts", j),
+                        attrs={"auto": irq.line == "auto"},
+                    )
+                )
+                relations.append(contains(block_key, irq_key, src("blocks", i, "interrupts", j)))
+                numbered.append(
+                    (f"{block.name}.{irq.name}", number, doc.line(("blocks", i, "interrupts", j)))
+                )
+
+        block_keys = {b.name: make_key("block", b.name) for b in chip.blocks}
+        for i, bus in enumerate(chip.buses):
+            bus_key = make_key("interface", bus.name)
+            entities.append(
+                InterfaceEntity(
+                    key=bus_key,
+                    name=bus.name,
+                    protocol=bus.protocol,
+                    source=src("buses", i),
+                    attrs={"masters": list(bus.masters), "slaves": list(bus.slaves)},
+                )
+            )
+            for slave in bus.slaves:
+                if slave in block_keys:
+                    relations.append(
+                        Relation(
+                            kind="connects",
+                            src=bus_key,
+                            dst=block_keys[slave],
+                            source=src("buses", i, "slaves"),
+                        )
+                    )
+
+        for i, clock in enumerate(chip.clocks):
+            entities.append(
+                ClockEntity(
+                    key=make_key("clock", clock.name),
+                    name=clock.name,
+                    frequency_hz=clock.frequency_hz,
+                    source=src("clocks", i),
+                )
+            )
+        for i, reset in enumerate(chip.resets):
+            entities.append(
+                ResetEntity(
+                    key=make_key("reset", reset.name),
+                    name=reset.name,
+                    active_low=reset.active_low,
+                    sync=reset.sync,
+                    source=src("resets", i),
+                )
+            )
+
+        warnings = overlap_warnings(regions, file) + duplicate_line_warnings(numbered, file)
+        return DesignModel.build(entities, relations), warnings
+
+
+def resolve_bases(blocks: tuple[BlockSpec, ...]) -> list[int | None]:
+    """Base address per block: fixed ones as given, `auto` ones by the module rule."""
+    placed = [(b.base, b.size) for b in blocks if isinstance(b.base, int) and b.size]
+    result: list[int | None] = []
+    for block in blocks:
+        if isinstance(block.base, int):
+            result.append(block.base)
+            continue
+        if block.base != "auto" or not block.size:
+            result.append(None)
+            continue
+        addr = 0
+        while clash := next(
+            ((b, s) for b, s in placed if addr < b + s and b < addr + block.size), None
+        ):
+            addr = _align_up(clash[0] + clash[1], block.size)
+        placed.append((addr, block.size))
+        result.append(addr)
+    return result
+
+
+def resolve_lines(blocks: tuple[BlockSpec, ...]) -> dict[tuple[int, int], int]:
+    """Interrupt line per (block index, interrupt index), `auto` ones by the module rule."""
+    used = {irq.line for b in blocks for irq in b.interrupts if isinstance(irq.line, int)}
+    result: dict[tuple[int, int], int] = {}
+    next_free = 0
+    for i, block in enumerate(blocks):
+        for j, irq in enumerate(block.interrupts):
+            if isinstance(irq.line, int):
+                result[(i, j)] = irq.line
+                continue
+            while next_free in used:
+                next_free += 1
+            result[(i, j)] = next_free
+            used.add(next_free)
+    return result
+
+
+def _align_up(addr: int, size: int) -> int:
+    return -(-addr // size) * size
+
+
+def schema_json() -> str:
+    """The JSON Schema of `chip.yml`, as committed in `schemas/formats/chip.schema.json`."""
+    return json.dumps(ChipYaml.model_json_schema(), indent=2, sort_keys=True) + "\n"
+
+
+__all__ = [
+    "BlockSpec",
+    "BusSpec",
+    "ChipYaml",
+    "ChipYamlAdapter",
+    "ClockSpec",
+    "InterruptSpec",
+    "ResetSpec",
+    "resolve_bases",
+    "resolve_lines",
+    "schema_json",
+]

chipgraph/adapters/format/qsoc_contract.py

@@ -0,0 +1,246 @@
+"""Format adapter `qsoc-contract`: a QSoC-style inter-block contract into the Design Model.
+
+The contract (`util/qsoc_contract.yml` in QSoC) is the single source of the numbers that
+more than one block shares. It maps to the model as follows:
+
+| Contract | Model |
+|---|---|
+| `meta` | one `project` (widths, clock, chip id in `attrs`) |
+| each `memory_map` row | a `block` and its `memory_region` (base, size; port, kind in `attrs`) |
+| each `interrupts.lines` item | an `interrupt` (line; peripheral, ports in `attrs`) |
+| each `clock_domains.clusters` item | a `clock` (the chip frequency from `meta.clock_mhz`) |
+| each `reset_sources` item | a `reset` |
+
+An interrupt's `block` is the memory-map row of the same name, when there is one (the
+contract names interrupts by peripheral, not always by row). Relations: `contains` from
+the project to each block, and from a block to its region and
+interrupts. Values the contract marks `tbd: true` are kept in `attrs` as they are and never
+filled in. Unknown top-level keys are reported as warnings. `load_model` also warns about
+overlapping memory regions and duplicate interrupt lines.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+from chipgraph.adapters.format._yaml_lines import LinedYaml
+from chipgraph.core.model import (
+    BlockEntity,
+    ClockEntity,
+    DesignModel,
+    EntityBase,
+    InterruptEntity,
+    JSONValue,
+    MemoryRegionEntity,
+    ProjectEntity,
+    Provenance,
+    Relation,
+    ResetEntity,
+    make_key,
+)
+
+_EXTRACTOR = "qsoc-contract"
+_KNOWN_TOP = {"meta", "memory_map", "interrupts", "clock_domains", "reset_sources", "tbd"}
+
+
+class QSocContractAdapter:
+    """`FormatAdapter` for a QSoC-style `qsoc_contract.yml`."""
+
+    name = "qsoc-contract"
+
+    def load(self, path: Path) -> Iterable[Mapping[str, object]]:
+        """The `FormatAdapter` protocol: every entity and relation as a plain mapping."""
+        model, _ = self.load_model(path)
+        return model_facts(model)
+
+    def load_model(self, path: Path, root: Path | None = None) -> tuple[DesignModel, list[str]]:
+        """Load `path` into a `DesignModel`, with warnings for anything suspicious.
+
+        When `root` is given and `path` is under it, provenance `file` is written relative
+        to `root` (POSIX); otherwise it is `path.as_posix()` as before.
+        """
+        doc = LinedYaml(path)
+        data: dict[str, Any] = doc.data if isinstance(doc.data, dict) else {}
+        file = _display_path(path, root)
+        warnings: list[str] = []
+        entities: list[EntityBase] = []
+        relations: list[Relation] = []
+
+        def src(*at: str | int) -> Provenance:
+            return Provenance(file=file, line=doc.line(at), extractor=_EXTRACTOR)
+
+        for key in sorted(set(data) - _KNOWN_TOP):
+            warnings.append(f"{file}:{doc.line((key,))}: unknown top-level key {key!r} ignored")
+
+        meta: dict[str, Any] = data.get("meta") or {}
+        project_name = str(meta.get("project", path.stem))
+        project_key = make_key("project", project_name)
+        entities.append(
+            ProjectEntity(
+                key=project_key,
+                name=project_name,
+                source=src("meta", "project"),
+                attrs={k: to_json(v) for k, v in meta.items() if k != "project"},
+            )
+        )
+
+        block_keys: dict[str, str] = {}
+        regions: list[Region] = []
+        for i, row in enumerate(data.get("memory_map") or []):
+            name = str(row["name"])
+            block_key = make_key("block", name)
+            region_key = make_key("memory_region", name)
+            block_keys[name] = block_key
+            extra = {k: to_json(v) for k, v in row.items() if k not in ("name", "base", "size")}
+            entities.append(BlockEntity(key=block_key, name=name, source=src("memory_map", i)))
+            entities.append(
+                MemoryRegionEntity(
+                    key=region_key,
+                    name=name,
+                    base=int_or_str(row.get("base")),
+                    size=int_or_str(row.get("size")),
+                    block=block_key,
+                    source=src("memory_map", i),
+                    attrs=extra,
+                )
+            )
+            relations.append(contains(project_key, block_key, src("memory_map", i)))
+            relations.append(contains(block_key, region_key, src("memory_map", i)))
+            base, size = row.get("base"), row.get("size")
+            if isinstance(base, int) and isinstance(size, int):
+                regions.append(Region(name, base, size, doc.line(("memory_map", i))))
+
+        interrupts: dict[str, Any] = data.get("interrupts") or {}
+        numbered: list[tuple[str, int, int]] = []  # name, line number, source line
+        for i, item in enumerate(interrupts.get("lines") or []):
+            peripheral = str(item.get("peripheral", f"line{i}"))
+            number = item.get("line")
+            key = make_key("interrupt", peripheral)
+            owner = block_keys.get(peripheral)
+            entities.append(
+                InterruptEntity(
+                    key=key,
+                    name=peripheral,
+                    line=number if isinstance(number, int) else None,
+                    block=owner,
+                    source=src("interrupts", "lines", i),
+                    attrs={k: to_json(v) for k, v in item.items() if k != "line"},
+                )
+            )
+            if owner is not None:
+                relations.append(contains(owner, key, src("interrupts", "lines", i)))
+            if isinstance(number, int):
+                numbered.append((peripheral, number, doc.line(("interrupts", "lines", i))))
+
+        frequency = meta.get("clock_mhz")
+        clocks: dict[str, Any] = data.get("clock_domains") or {}
+        for i, cluster in enumerate(clocks.get("clusters") or []):
+            name = str(cluster["name"])
+            entities.append(
+                ClockEntity(
+                    key=make_key("clock", name),
+                    name=name,
+                    frequency_hz=float(frequency) * 1e6 if isinstance(frequency, int) else None,
+                    source=src("clock_domains", "clusters", i),
+                    attrs={k: to_json(v) for k, v in cluster.items() if k != "name"},
+                )
+            )
+
+        for i, name in enumerate(data.get("reset_sources") or []):
+            entities.append(
+                ResetEntity(
+                    key=make_key("reset", str(name)),
+                    name=str(name),
+                    source=src("reset_sources", i),
+                )
+            )
+
+        warnings.extend(overlap_warnings(regions, file))
+        warnings.extend(duplicate_line_warnings(numbered, file))
+        return DesignModel.build(entities, relations), warnings
+
+
+class Region:
+    """A memory region with a known base and size, for overlap checks."""
+
+    __slots__ = ("base", "line", "name", "size")
+
+    def __init__(self, name: str, base: int, size: int, line: int) -> None:
+        self.name, self.base, self.size, self.line = name, base, size, line
+
+
+def overlap_warnings(regions: list[Region], file: str) -> list[str]:
+    """One warning for every pair of memory regions that share an address."""
+    found: list[str] = []
+    ordered = sorted(regions, key=lambda r: (r.base, r.name))
+    for i, a in enumerate(ordered):
+        for b in ordered[i + 1 :]:
+            if b.base >= a.base + a.size:
+                break
+            found.append(
+                f"{file}:{b.line}: memory regions {a.name!r} "
+                f"[{a.base:#x}, {a.base + a.size:#x}) (line {a.line}) and {b.name!r} "
+                f"[{b.base:#x}, {b.base + b.size:#x}) are overlapping"
+            )
+    return found
+
+
+def duplicate_line_warnings(numbered: list[tuple[str, int, int]], file: str) -> list[str]:
+    """One warning for every interrupt line number used more than once."""
+    found: list[str] = []
+    first: dict[int, tuple[str, int]] = {}
+    for name, number, line in numbered:
+        if number in first:
+            other, other_line = first[number]
+            found.append(
+                f"{file}:{line}: duplicate interrupt line {number}: {name!r} and "
+                f"{other!r} (line {other_line})"
+            )
+        else:
+            first[number] = (name, line)
+    return found
+
+
+def model_facts(model: DesignModel) -> list[Mapping[str, object]]:
+    """Every entity (sorted by key) and relation of `model` as plain mappings."""
+    facts: list[Mapping[str, object]] = [
+        model.entities[key].model_dump(mode="json") for key in sorted(model.entities)
+    ]
+    facts.extend(r.model_dump(mode="json") for r in model.relations)
+    return facts
+
+
+def contains(src: str, dst: str, source: Provenance) -> Relation:
+    return Relation(kind="contains", src=src, dst=dst, source=source)
+
+
+def _display_path(path: Path, root: Path | None) -> str:
+    """`path` relative to `root` (POSIX) when it is under it, else its POSIX form."""
+    if root is not None:
+        try:
+            return path.resolve().relative_to(root.resolve()).as_posix()
+        except ValueError:
+            pass
+    return path.as_posix()
+
+
+def int_or_str(value: object) -> int | str | None:
+    if value is None or isinstance(value, int):
+        return value
+    return str(value)
+
+
+def to_json(value: object) -> JSONValue:
+    """A YAML value as JSON: containers kept, anything else not JSON as a string."""
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    if isinstance(value, list | tuple):
+        return [to_json(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): to_json(v) for k, v in value.items()}
+    return str(value)
+
+
+__all__ = ["QSocContractAdapter"]