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/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;
+}

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

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:

chipflow_lib/platforms/__init__.py

@@ -14,11 +14,17 @@
         )
 from ._packages import PACKAGE_DEFINITIONS
 from ._sky130 import Sky130DriveMode
+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', 'QSPIFlashSignature',
+           'attach_simulation_data',
            'Sky130DriveMode',
            'PACKAGE_DEFINITIONS']

chipflow_lib/platforms/_annotate.py

@@ -0,0 +1,78 @@
+from types import MethodType
+import pydantic
+from typing import TypeVar
+from typing_extensions import 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
+

chipflow_lib/platforms/_signatures.py

@@ -0,0 +1,131 @@
+# 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
+from ._annotate import amaranth_annotate
+
+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 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):
+            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
+
+
+@simulatable_interface()
+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)),
+    })
+
+
+@simulatable_interface()
+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)),
+        })
+
+@simulatable_interface()
+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)),
+        })
+
+@simulatable_interface()
+class UARTSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+            "tx": Out(OutputIOSignature(1)),
+            "rx": Out(InputIOSignature(1)),
+        })
+
+@simulatable_interface()
+class I2CSignature(wiring.Signature):
+    def __init__(self, **kwargs: Unpack[IOModelOptions]):
+        super().__init__({
+            "scl": Out(BidirIOSignature(1)),
+            "sda": Out(BidirIOSignature(1))
+        })
+        self._options = kwargs
+
+
+@simulatable_interface()
+class GPIOSignature(wiring.Signature):
+
+    def __init__(self, pin_count=1, **kwargs: Unpack[IOModelOptions]):
+        self._pin_count = pin_count
+        self._options = kwargs
+        kwargs['individual_oe'] = True
+        super().__init__({
+            "gpio": Out(BidirIOSignature(pin_count, **kwargs))
+            })
+
+    def __chipflow_parameters__(self):
+        return [('pin_count',self._pin_count)]
+
+
+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)
+