Introduces the ability to automatically attach simulation models to

ports.

This allows port signatures to be annotated as to the kind and behaviour
of that port (e.g. its SPI, its I2C..) to allow the automatic assembling
of a simulation model for the IC design.

Author: robtaylor

chipflow_lib/platforms/__init__.py

@@ -14,13 +14,17 @@
         )
 from ._packages import PACKAGE_DEFINITIONS
 from ._sky130 import Sky130DriveMode
-from ._signatures import JTAGSignature, SPISignature, I2CSignature, UARTSignature, GPIOSignature, QSPIFlashSignature
+from ._signatures import (
+        JTAGSignature, SPISignature, I2CSignature, UARTSignature, GPIOSignature, QSPIFlashSignature,
+        attach_simulation_data
+        )
 
 __all__ = ['IO_ANNOTATION_SCHEMA', 'IOSignature',
            'IOModel', 'IOModelOptions', 'IOTripPoint',
            'OutputIOSignature', 'InputIOSignature', 'BidirIOSignature',
            'SiliconPlatformPort', 'SiliconPlatform',
            'SimPlatform',
-           'JTAGSignature', 'SPISignature', 'I2CSignature', 'UARTSignature', 'GPIOSignature',
+           'JTAGSignature', 'SPISignature', 'I2CSignature', 'UARTSignature', 'GPIOSignature', 'QSPIFlashSignature',
+           'attach_simulation_data',
            'Sky130DriveMode',
            'PACKAGE_DEFINITIONS']

chipflow_lib/platforms/_signatures.py

@@ -8,46 +8,60 @@
 from amaranth.lib.wiring import Out
 
 from .. import ChipFlowError
-from ._utils import InputIOSignature, OutputIOSignature, BidirIOSignature, IOModelOptions, _chipflow_schema_uri, amaranth_annotate
+from ._utils import InputIOSignature, OutputIOSignature, BidirIOSignature, IOModelOptions, _chipflow_schema_uri
+from ._annotate import amaranth_annotate
 
-SIM_ANNOTATION_SCHEMA = str(_chipflow_schema_uri("sim-interface", 0))
+SIM_ANNOTATION_SCHEMA = str(_chipflow_schema_uri("simulatable-interface", 0))
+SIM_DATA_SCHEMA = str(_chipflow_schema_uri("simulatable-data", 0))
 
 class SimInterface(TypedDict):
     uid: str
     parameters: List[Tuple[str, Any]]
 
+class SimData(TypedDict):
+    file_name: str
+    offset: int
+
 _VALID_UID = re.compile('[a-zA-Z_.]').search
 
+def _unpack_dict(d: dict) -> str:
+    params = [ f"{k}={repr(v)}" for k,v in d.items()]
+    return ', '.join(params)
+
 """
 Attributes:
     __chipflow_parameters__: list of tuples (name, value).
         It is expected that a model that takes parameters is implmemted as a template, with the parameters in the order
         given.
 """
-def sim_annotate(base="com.chipflow.chipflow_lib"):
+def simulatable_interface(base="com.chipflow.chipflow_lib"):
     def decorate(klass):
         assert _VALID_UID(base)
         dec = amaranth_annotate(SimInterface, SIM_ANNOTATION_SCHEMA)
         klass = dec(klass)
 
         def new_init(self,*args, **kwargs):
-            print("called new_init")
             original_init(self, *args, **kwargs)
             self.__chipflow_annotation__ = {
                 "uid": klass.__chipflow_uid__,
                 "parameters": self.__chipflow_parameters__(),
                 }
 
+        def repr(self) -> str:
+            return f"{klass.__name__}({_unpack_dict(self.__chipflow_parameters__())}, {_unpack_dict(self._options)})"
+
         original_init = klass.__init__
         klass.__init__ = new_init
         klass.__chipflow_uid__ = f"{base}.{klass.__name__}"
         if not hasattr(klass, '__chipflow_parameters__'):
             klass.__chipflow_parameters__ = lambda self: []
+        if not klass.__repr__:
+            klass.__repr__ = repr
         return klass
     return decorate
 
 
-@sim_annotate()
+@simulatable_interface()
 class JTAGSignature(wiring.Signature):
     def __init__(self, **kwargs: Unpack[IOModelOptions]):
         super().__init__({
@@ -59,7 +73,7 @@ def __init__(self, **kwargs: Unpack[IOModelOptions]):
     })
 
 
-@sim_annotate()
+@simulatable_interface()
 class SPISignature(wiring.Signature):
     def __init__(self, **kwargs: Unpack[IOModelOptions]):
         super().__init__({
@@ -69,7 +83,7 @@ def __init__(self, **kwargs: Unpack[IOModelOptions]):
             "csn": Out(OutputIOSignature(1)),
         })
 
-@sim_annotate()
+@simulatable_interface()
 class QSPIFlashSignature(wiring.Signature):
     def __init__(self, **kwargs: Unpack[IOModelOptions]):
         super().__init__({
@@ -78,51 +92,40 @@ def __init__(self, **kwargs: Unpack[IOModelOptions]):
             "d": Out(BidirIOSignature(4, individual_oe=True)),
         })
 
-@sim_annotate()
+@simulatable_interface()
 class UARTSignature(wiring.Signature):
     def __init__(self, **kwargs: Unpack[IOModelOptions]):
         super().__init__({
             "tx": Out(OutputIOSignature(1)),
             "rx": Out(InputIOSignature(1)),
         })
 
-@sim_annotate()
+@simulatable_interface()
 class I2CSignature(wiring.Signature):
     def __init__(self, **kwargs: Unpack[IOModelOptions]):
         super().__init__({
-        "scl": Out(BidirIOSignature(1)),
-        "sda": Out(BidirIOSignature(1))
-    })
+            "scl": Out(BidirIOSignature(1)),
+            "sda": Out(BidirIOSignature(1))
+        })
+        self._options = kwargs
+
 
-@sim_annotate()
+@simulatable_interface()
 class GPIOSignature(wiring.Signature):
 
     def __init__(self, pin_count=1, **kwargs: Unpack[IOModelOptions]):
-        if pin_count > 32:
-            raise ValueError(f"Pin pin_count must be lesser than or equal to 32, not {pin_count}")
         self._pin_count = pin_count
+        self._options = kwargs
         kwargs['individual_oe'] = True
         super().__init__({
             "gpio": Out(BidirIOSignature(pin_count, **kwargs))
             })
 
     def __chipflow_parameters__(self):
-        print("called GPIOSignature.__chipflow_parameters__")
         return [('pin_count',self._pin_count)]
 
-    def __repr__(self) -> str:
-        return f"GPIOSignature(pin_count={self._pin_count}, {dict(self.members.items())})"
-
-
-class SimulationCanLoadData:
-    """
-    Inherit from this in your object's Signature if you want a simulation model
-    to be able to load data from your object
-    """
-    @classmethod
-    def __init_submodule__(cls, /, *args, **kwargs):
-        if wiring.Signature not in cls.mro():
-            raise ChipFlowError("SimulationCanLoadData can only be used with ``wiring.Signature`` classes")
-        original_annotations = getattr(cls, 'annotations')
-        #def annotations(self, obj, /):
-        #cls.annotate
+
+def attach_simulation_data(c: wiring.Component, **kwargs: Unpack[SimData]):
+    setattr(c.signature, '__chipflow_simulation_data__', kwargs)
+    amaranth_annotate(SimData, SIM_DATA_SCHEMA, '__chipflow_simulation_data__', decorate_object=True)(c.signature)
+

chipflow_lib/platforms/_utils.py

@@ -31,6 +31,7 @@
 
 from .. import ChipFlowError, _ensure_chipflow_root, _get_cls_by_reference
 from .._appresponse import AppResponseModel, OmitIfNone
+from ._annotate import amaranth_annotate
 from ._sky130 import Sky130DriveMode
 
 if TYPE_CHECKING:
@@ -83,7 +84,6 @@ class IOTripPoint(StrEnum):
 IO_ANNOTATION_SCHEMA = str(_chipflow_schema_uri("pin-annotation", 0))
 
 
-@pydantic.with_config(ConfigDict(arbitrary_types_allowed=True))  # type: ignore[reportCallIssue]
 class IOModelOptions(TypedDict):
     """
     Options for an IO pad/pin.
@@ -130,45 +130,8 @@ class IOModel(IOModelOptions):
     width: int
     direction: Annotated[io.Direction, PlainSerializer(lambda x: x.value)]
 
-def amaranth_annotate(modeltype: Type[TypedDict], schema_id: str):
-    PydanticModel = TypeAdapter(modeltype)
-
-    def annotation_schema():
-        class Model(pydantic.BaseModel):
-            data_td: modeltype
-
-        schema = PydanticModel.json_schema()
-        schema['$schema'] = "https://json-schema.org/draft/2020-12/schema"
-        schema['$id'] = schema_id
-        return schema
-
-    class Annotation(meta.Annotation):
-        "Generated annotation class"
-        schema = annotation_schema()
-
-        def __init__(self, model: modeltype):
-            self.__chipflow_annotation__ = model
-
-        @property
-        def origin(self):  # type: ignore
-            return self.__chipflow_annotation__
-
-        def as_json(self):  # type: ignore
-            return PydanticModel.dump_python(self.__chipflow_annotation__)
-
-    def decorator(klass):
-        def annotations(self, *args):  # type: ignore
-            annotations = super(klass, self).annotations(*args)  # type: ignore
-            annotation = Annotation(self.__chipflow_annotation__)
-            return annotations + (annotation,)  # type: ignore
-
-
-        klass.annotations = annotations
-        return klass
-    return decorator
-
 
-@amaranth_annotate(IOModel, IO_ANNOTATION_SCHEMA)
+@amaranth_annotate(IOModel, IO_ANNOTATION_SCHEMA, '_model')
 class IOSignature(wiring.Signature):
     """An :py:obj:`Amaranth Signature <amaranth.lib.wiring.Signature>` used to decorate wires that would usually be brought out onto a port on the package.
     This class is generally not directly used.  Instead, you would typically utilize the more specific
@@ -212,34 +175,34 @@ def __init__(self, **kwargs: Unpack[IOModel]):
         if 'clock_domain' not in model:
             model['clock_domain'] = 'sync'
 
-        self.__chipflow_annotation__ = model
+        self._model = model
         super().__init__(sig)
 
     @property
     def direction(self) -> io.Direction:
         "The direction of the IO port"
-        return self.__chipflow_annotation__['direction']
+        return self._model['direction']
 
     @property
     def width(self) -> int:
         "The width of the IO port, in wires"
-        return self.__chipflow_annotation__['width']
+        return self._model['width']
 
     @property
     def invert(self) -> Iterable[bool]:
         "A tuple as wide as the IO port, with a bool for the polarity inversion for each wire"
-        assert type(self.__chipflow_annotation__['invert']) is tuple
-        return self.__chipflow_annotation__['invert']
+        assert type(self._model['invert']) is tuple
+        return self._model['invert']
 
     @property
     def options(self) -> IOModelOptions:
         """
         Options set on the io port at construction
         """
-        return self.__chipflow_annotation__
+        return self._model
 
     def __repr__(self):
-        return f"IOSignature({','.join('{0}={1!r}'.format(k,v) for k,v in self.__chipflow_annotation__.items())})"
+        return f"IOSignature({','.join('{0}={1!r}'.format(k,v) for k,v in self._model.items())})"
 
 
 def OutputIOSignature(width: int, **kwargs: Unpack[IOModelOptions]):
@@ -640,6 +603,7 @@ def register_component(self, name: str, component: wiring.Component) -> None:
             component: Amaranth `wiring.Component` to allocate
 
         """
+        print(f"registering {component}")
         self._components[name] = component
         self._interfaces[name] = component.metadata.as_json()
 

chipflow_lib/platforms/sim.py

@@ -23,7 +23,7 @@
 from .. import ChipFlowError, _ensure_chipflow_root
 from ._signatures import (
         I2CSignature, GPIOSignature, UARTSignature, SPISignature, QSPIFlashSignature,
-        SIM_ANNOTATION_SCHEMA, SimInterface
+        SIM_ANNOTATION_SCHEMA, SIM_DATA_SCHEMA, SimInterface
         )
 from ._utils import load_pinlock, Interface
 
@@ -143,6 +143,7 @@ def find_builder(builders: List[BasicCxxBuilder], sim_interface: SimInterface):
     logger.warn(f"Unable to find builder for '{uid}'")
     return None
 
+
 _COMMON_BUILDER = BasicCxxBuilder(
     models=[
         SimModel('spi_model', SPISignature),
@@ -164,17 +165,18 @@ def __init__(self, config):
         self.sim_boxes = dict()
         self._ports: Dict[str, io.SimulationPort] = {}
         self._config = config
-        self._builders: List[BasicCxxBuilder] = [ _COMMON_BUILDER ]
-        self._top_sim = {}
         self._clocks = {}
         self._resets = {}
+        self._builders: List[BasicCxxBuilder] = [ _COMMON_BUILDER ]
+        self._top_sim = {}
+        self._sim_data = {}
 
     def add_file(self, filename, content):
         if not isinstance(content, (str, bytes)):
             content = content.read()
         self.extra_files[filename] = content
 
-    def build(self, e):
+    def build(self, e, top):
         Path(self.build_dir).mkdir(parents=True, exist_ok=True)
 
         ports = []
@@ -186,7 +188,7 @@ def build(self, e):
             if port.direction is io.Direction.Bidir:
                 ports.append((f"io${port_name}$oe", port.oe, PortDirection.Output))
 
-        print("elaborating design")
+        print("Generating RTLIL from design")
         output = rtlil.convert(e, name="sim_top", ports=ports, platform=self)
 
         top_rtlil = Path(self.build_dir) / "sim_soc.il"
@@ -211,19 +213,39 @@ def build(self, e):
             print("write_cxxrtl -header sim_soc.cc", file=yosys_file)
         main = Path(self.build_dir) / "main.cc"
 
+        metadata = {}
+        for key in top.keys():
+            metadata[key] = getattr(e.submodules, key).metadata.as_json()
+        for component, iface in metadata.items():
+            for interface, interface_desc in iface['interface']['members'].items():
+                annotations = interface_desc['annotations']
+
+                if SIM_DATA_SCHEMA in annotations:
+                    self._sim_data[interface] = annotations[SIM_DATA_SCHEMA]
+
+        data_load = []
+        for i,d in self._sim_data.items():
+            args = [f"0x{d['offset']:X}U"]
+            p = Path(d['file_name'])
+            if not p.is_absolute():
+                p = _ensure_chipflow_root() / p
+            data_load.append({'model_name': i, 'file_name': p, 'args': args})
+
+
         env = Environment(
             loader=PackageLoader("chipflow_lib", "common/sim"),
             autoescape=select_autoescape()
         )
         template = env.get_template("main.cc.jinja")
+
         with main.open("w") as main_file:
             print(template.render(
                     includes = [hpp for b in self._builders if b.hpp_files for hpp in b.hpp_files ],
                     initialisers = [exp for exp in self._top_sim.values()],
                     interfaces = [exp for exp in self._top_sim.keys()],
                     clocks = [cxxrtlmangle(f"io${clk}$i") for clk in self._clocks.keys()],
                     resets = [cxxrtlmangle(f"io${rst}$i") for rst in self._resets.keys()],
-                    data_load = [{'model_name': 'flash', 'file_name':_ensure_chipflow_root() / 'build'/ 'software'/'software.bin', 'args':[ '0x00100000U' ]}]
+                    data_load = data_load
                 ),
                 file=main_file)
 
@@ -239,9 +261,12 @@ def instantiate_ports(self, m: Module):
                     logger.debug(f"Instantiating port {port_desc.port_name}: {port_desc}")
                     invert = port_desc.invert if port_desc.invert else False
                     self._ports[port_desc.port_name] = io.SimulationPort(port_desc.direction, port_desc.width, invert=invert, name=port_desc.port_name)
-                if not component.startswith('_') \
-                and pinlock.metadata[component]['interface']['members'][interface]['annotations']:
-                    sim_interface = pinlock.metadata[component]['interface']['members'][interface]['annotations'][SIM_ANNOTATION_SCHEMA]
+                if component.startswith('_'):
+                    continue
+                annotations = pinlock.metadata[component]['interface']['members'][interface]['annotations']
+
+                if SIM_ANNOTATION_SCHEMA in annotations:
+                    sim_interface = annotations[SIM_ANNOTATION_SCHEMA]
                     builder = find_builder(self._builders, sim_interface)
                     if builder:
                         self._top_sim[interface] = builder.instantiate_model(interface, sim_interface, interface_desc, self._ports)

chipflow_lib/software/soft_gen.py

@@ -11,7 +11,7 @@ def __init__(self, *, rom_start, rom_size, ram_start, ram_size):
         self.defines = []
         self.periphs = []
         self.extra_init = []
-        print("initialed SoftwareGenerator")
+        print("initialised SoftwareGenerator")
 
     def generate(self, out_dir):
         Path(out_dir).mkdir(parents=True, exist_ok=True)