Introduces the ability to automatically attach simulation models to

robtaylor · robtaylor · commit bee7995bd0a9 · 2025-08-07T09:58:23.000+01:00
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.
diff --git a/chipflow_lib/common/sim/main.cc.jinja b/chipflow_lib/common/sim/main.cc.jinja
@@ -0,0 +1,77 @@
+#undef NDEBUG
+
+#include <cxxrtl/cxxrtl.h>
+#include <cxxrtl/cxxrtl_server.h>
+#include "sim_soc.h"
+{% for include in includes %}
+#include "{{include}}"
+{% endfor %}
+
+#include <fstream>
+#include <filesystem>
+
+using namespace cxxrtl::time_literals;
+using namespace cxxrtl_design;
+
+int main(int argc, char **argv) {
+    p_sim__top top;
+
+    {% for initialiser in initialisers %}
+    {{initialiser}};
+    {% endfor %}
+
+    cxxrtl::agent agent(cxxrtl::spool("spool.bin"), top);
+    if (getenv("DEBUG")) // can also be done when a condition is violated, etc
+        std::cerr << "Waiting for debugger on " << agent.start_debugging() << std::endl;
+
+    open_event_log(BUILD_DIR "/sim/events.json");
+    open_input_commands(PROJECT_ROOT "/design/tests/input.json");
+
+    unsigned timestamp = 0;
+    auto tick = [&]() {
+        {% for interface in interfaces %}
+        {{interface}}.step(timestamp);
+        {% endfor %}
+
+        // FIXME: Currently we tick all clocks together, this need fixing..
+        {% for clock in clocks %}
+        top.{{clock}}.set(false);
+        {% endfor %}
+        agent.step();
+        agent.advance(1_us);
+        ++timestamp;
+
+        {% for clock in clocks %}
+        top.{{clock}}.set(true);
+        {% endfor %}
+        agent.step();
+        agent.advance(1_us);
+        ++timestamp;
+
+        // if (timestamp == 10)
+        //     agent.breakpoint(CXXRTL_LOCATION);
+    };
+
+    {% for data in data_load %}
+    {{data.model_name}}.load_data("{{data.file_name}}", {{data.args | join(', ')}});
+    {% endfor %}
+
+    agent.step();
+    agent.advance(1_us);
+
+    {% for reset in resets %}
+    top.{{reset}}.set(false);
+    {% endfor %}
+
+    tick();
+
+    {% for reset in resets %}
+    top.{{reset}}.set(true);
+    {% endfor %}
+
+    for (int i = 0; i < 3000000; i++)
+        tick();
+
+    close_event_log();
+    return 0;
+}
diff --git a/chipflow_lib/common/sim/models.cc b/chipflow_lib/common/sim/models.cc
@@ -284,16 +284,16 @@ void gpio_model::step(unsigned timestamp) {
         if (action.event == "set") {
             auto bin = std::string(action.payload);
             input_data = 0;
-            for (unsigned i = 0; i < width; i++) {
-                if (bin.at((width - 1) - i) == '1')
+            for (unsigned i = 0; i < pin_count; i++) {
+                if (bin.at((pin_count - 1) - i) == '1')
                     input_data |= (1U << i);
             }
         }
     }
 
     if (o_value != s.o_last || oe_value != s.oe_last) {
         std::string formatted_value;
-        for (int i = width - 1; i >= 0; i--) {
+        for (int i = pin_count - 1; i >= 0; i--) {
             if (oe_value & (1U << unsigned(i)))
                 formatted_value += (o_value & (1U << unsigned(i))) ? '1' : '0';
             else
diff --git a/chipflow_lib/common/sim/models.h b/chipflow_lib/common/sim/models.h
@@ -83,17 +83,21 @@ struct uart_model {
 };
 
 struct gpio_model {
-    static constexpr unsigned width = 8;
     std::string name;
-    gpio_model(const std::string &name, const value<width> &o, const value<width> &oe, value<width> &i) : name(name), o(o), oe(oe), i(i) {};
+    struct parameters {
+        unsigned pin_count;
+    };
+    parameters parameters;
+
+    gpio_model(const std::string &name, parameters, const value<paramters.pin_count> &o, const value<parameters.pin_count> &oe, value<parameters.pin_count> &i) : name(name), parameters(parameters), o(o), oe(oe), i(i) {};
 
     void step(unsigned timestamp);
 
 private:
     uint32_t input_data = 0;
-    const value<width> &o;
-    const value<width> &oe;
-    value<width> &i;
+    const value<pin_count> &o;
+    const value<pin_count> &oe;
+    value<pin_count> &i;
     struct {
         uint32_t o_last = 0;
         uint32_t oe_last = 0;
@@ -103,7 +107,7 @@ struct gpio_model {
 
 struct spi_model {
     std::string name;
-    spi_model(const std::string &name, const value<1> &clk, const value<1> &csn, const value<1> &copi, value<1> &cipo) : 
+    spi_model(const std::string &name, const value<1> &clk, const value<1> &copi, value<1> &cipo, const value<1> &csn) : 
         name(name), clk(clk), csn(csn), copi(copi), cipo(cipo) {
     };
 
@@ -127,7 +131,7 @@ struct spi_model {
 
 struct i2c_model {
     std::string name;
-    i2c_model(const std::string &name, const value<1> &sda_oe, value<1> &sda_i, const value<1> &scl_oe, value<1> &scl_i) : name(name), sda_oe(sda_oe), sda_i(sda_i), scl_oe(scl_oe), scl_i(scl_i) {};
+    i2c_model(const std::string &name, const value<1> &scl_o, const value<1> &scl_oe, value<1> &scl_i, const value<1> &sda_o, const value<1> &sda_oe, value<1> &sda_i)  : name(name), sda_oe(sda_oe), sda_i(sda_i), scl_oe(scl_oe), scl_i(scl_i) {};
 
     void step(unsigned timestamp);
 private:
diff --git a/chipflow_lib/platforms/__init__.py b/chipflow_lib/platforms/__init__.py
@@ -14,11 +14,13 @@
         )
 from ._packages import PACKAGE_DEFINITIONS
 from ._sky130 import Sky130DriveMode
+from ._signatures import JTAGSignature, SPISignature, I2CSignature, UARTSignature, GPIOSignature, QSPIFlashSignature
 
 __all__ = ['IO_ANNOTATION_SCHEMA', 'IOSignature',
            'IOModel', 'IOModelOptions', 'IOTripPoint',
            'OutputIOSignature', 'InputIOSignature', 'BidirIOSignature',
            'SiliconPlatformPort', 'SiliconPlatform',
            'SimPlatform',
+           'JTAGSignature', 'SPISignature', 'I2CSignature', 'UARTSignature', 'GPIOSignature',
            'Sky130DriveMode',
            'PACKAGE_DEFINITIONS']
diff --git a/chipflow_lib/platforms/_annotate.py b/chipflow_lib/platforms/_annotate.py
@@ -0,0 +1,79 @@
+from types import MethodType
+import pydantic
+from amaranth.lib import meta
+from typing import Any, Annotated, NamedTuple, Self, TypeVar
+from typing_extensions import TypedDict, is_typeddict
+_T_TypedDict = TypeVar('_T_TypedDict')
+
+def amaranth_annotate(modeltype: type['_T_TypedDict'], schema_id: str, member='__chipflow_annotation__', decorate_object = False):
+    if not is_typeddict(modeltype):
+        raise TypeError(f'''amaranth_annotate must be passed a TypedDict, not {modeltype}''')
+
+    # interesting pydantic issue gets hit if arbitrary_types_allowed is False
+    if hasattr(modeltype, '__pydantic_config__'):
+        config = getattr(modeltype, '__pydantic_config__')
+        config['arbitrary_types_allowed'] = True
+    else:
+        config = pydantic.ConfigDict()
+        config['arbitrary_types_allowed'] = True
+        setattr(modeltype, '__pydantic_config__', config)
+    PydanticModel = pydantic.TypeAdapter(modeltype)
+
+    def annotation_schema():
+        schema = PydanticModel.json_schema()
+        schema['$schema'] = 'https://json-schema.org/draft/2020-12/schema'
+        schema['$id'] = schema_id
+        return schema
+
+    class Annotation:
+        'Generated annotation class'
+        schema = annotation_schema()
+
+        def __init__(self, parent):
+            self.parent = parent
+
+        def origin(self):
+            return self.parent
+
+        def as_json(self):
+            return PydanticModel.dump_python(getattr(self.parent, member))
+
+    def decorate_class(klass):
+        if hasattr(klass, 'annotations'):
+            old_annotations = klass.annotations
+        else:
+            old_annotations = None
+
+        def annotations(self, obj):
+            if old_annotations:
+                annotations = old_annotations(self, obj)
+            else:
+                annotations = super(klass, obj).annotations(obj)
+            annotation = Annotation(self)
+            return annotations + (annotation,)
+
+        klass.annotations = annotations
+        return klass
+
+    def decorate_obj(obj):
+        if hasattr(obj, 'annotations'):
+            old_annotations = obj.annotations
+        else:
+            old_annotations = None
+
+        def annotations(self = None, origin = None):
+            if old_annotations:
+                annotations = old_annotations(origin)
+            else:
+                annotations = super(obj.__class__, obj).annotations(obj)
+            annotation = Annotation(self)
+            return annotations + (annotation,)
+
+        setattr(obj, 'annotations', MethodType(annotations, obj))
+        return obj
+
+    if decorate_object:
+        return decorate_obj
+    else:
+        return decorate_class
+
diff --git a/chipflow_lib/platforms/_signatures.py b/chipflow_lib/platforms/_signatures.py
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: BSD-2-Clause
+
+import re
+from typing import List, Tuple, Any
+from typing_extensions import Unpack, TypedDict
+
+from amaranth.lib import wiring
+from amaranth.lib.wiring import Out
+
+from .. import ChipFlowError
+from ._utils import InputIOSignature, OutputIOSignature, BidirIOSignature, IOModelOptions, _chipflow_schema_uri, amaranth_annotate
+
+SIM_ANNOTATION_SCHEMA = str(_chipflow_schema_uri("sim-interface", 0))
+
+class SimInterface(TypedDict):
+    uid: str
+    parameters: List[Tuple[str, Any]]
+
+_VALID_UID = re.compile('[a-zA-Z_.]').search
+
+def sim_annotate(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__(),
+                }
+
+        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: {}
+        return klass
+    return decorate
+
+
+@sim_annotate()
+class JTAGSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+        "trst": Out(InputIOSignature(1)),
+        "tck": Out(InputIOSignature(1)),
+        "tms": Out(InputIOSignature(1)),
+        "tdi": Out(InputIOSignature(1)),
+        "tdo": Out(OutputIOSignature(1)),
+    })
+
+
+@sim_annotate()
+class SPISignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+            "sck": Out(OutputIOSignature(1)),
+            "copi": Out(OutputIOSignature(1)),
+            "cipo": Out(InputIOSignature(1)),
+            "csn": Out(OutputIOSignature(1)),
+        })
+
+@sim_annotate()
+class QSPIFlashSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+            "clk": Out(OutputIOSignature(1)),
+            "csn": Out(OutputIOSignature(1)),
+            "d": Out(BidirIOSignature(4, individual_oe=True)),
+        })
+
+@sim_annotate()
+class UARTSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+            "tx": Out(OutputIOSignature(1)),
+            "rx": Out(InputIOSignature(1)),
+        })
+
+@sim_annotate()
+class I2CSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+        "scl": Out(BidirIOSignature(1)),
+        "sda": Out(BidirIOSignature(1))
+    })
+
+@sim_annotate()
+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
+        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
diff --git a/chipflow_lib/platforms/_utils.py b/chipflow_lib/platforms/_utils.py
diff --git a/chipflow_lib/platforms/sim.py b/chipflow_lib/platforms/sim.py

Original file line number	Diff line number	Diff line change
`@@ -284,16 +284,16 @@ void gpio_model::step(unsigned timestamp) {`
`284`	`284`	`if (action.event == "set") {`
`285`	`285`	`auto bin = std::string(action.payload);`
`286`	`286`	`input_data = 0;`
`287`		`- for (unsigned i = 0; i < width; i++) {`
`288`		`- if (bin.at((width - 1) - i) == '1')`
	`287`	`+ for (unsigned i = 0; i < pin_count; i++) {`
	`288`	`+ if (bin.at((pin_count - 1) - i) == '1')`
`289`	`289`	`input_data \|= (1U << i);`
`290`	`290`	`}`
`291`	`291`	`}`
`292`	`292`	`}`
`293`	`293`
`294`	`294`	`if (o_value != s.o_last \|\| oe_value != s.oe_last) {`
`295`	`295`	`std::string formatted_value;`
`296`		`- for (int i = width - 1; i >= 0; i--) {`
	`296`	`+ for (int i = pin_count - 1; i >= 0; i--) {`
`297`	`297`	`if (oe_value & (1U << unsigned(i)))`
`298`	`298`	`formatted_value += (o_value & (1U << unsigned(i))) ? '1' : '0';`
`299`	`299`	`else`