Complete rework of software generation support

This completely reworks software support for a much simpler model for
the user.

 * User needs add only one line to their design to generate software
   and one line to associate that software with their rom/flash storage

 * Drivers now live with their IPs. The driver information is
   communicated via the signature of the component

Author: robtaylor

chipflow_lib/_doit.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 *-*
+# SPDX-License-Identifier: BSD-2-Clause
+
+from typing import List, Tuple, Callable, TypeVar, Generic
+from typing_extensions import TypedDict, NotRequired
+
+T=TypeVar('T')
+class TaskParams(TypedDict, Generic[T]):
+    name: str
+    default: T
+    short: NotRequired[str]
+    long: NotRequired[str]
+    type: NotRequired[Callable[[T], str]]
+    choices: NotRequired[List[Tuple[str, str]]]
+    help: NotRequired[str]
+    inverse: NotRequired[str]
+
+

chipflow_lib/cli.py

@@ -25,6 +25,7 @@ class UnexpectedError(ChipFlowError):
 DEFAULT_STEPS = {
     "silicon": "chipflow_lib.steps.silicon:SiliconStep",
     "sim": "chipflow_lib.steps.sim:SimStep",
+    "software": "chipflow_lib.steps.software:SoftwareStep"
 }
 
 

chipflow_lib/platforms/__init__.py

@@ -8,6 +8,7 @@
 
 from .silicon import SiliconPlatformPort, SiliconPlatform
 from .sim import SimPlatform
+from ._software import SoftwarePlatform
 from ._utils import (
         IO_ANNOTATION_SCHEMA, IOSignature, IOModel, IOTripPoint, IOModelOptions,
         OutputIOSignature, InputIOSignature, BidirIOSignature,
@@ -16,15 +17,15 @@
 from ._sky130 import Sky130DriveMode
 from ._signatures import (
         JTAGSignature, SPISignature, I2CSignature, UARTSignature, GPIOSignature, QSPIFlashSignature,
-        attach_simulation_data
+        attach_data, DriverSignature, SoftwareBuild
         )
 
 __all__ = ['IO_ANNOTATION_SCHEMA', 'IOSignature',
            'IOModel', 'IOModelOptions', 'IOTripPoint',
            'OutputIOSignature', 'InputIOSignature', 'BidirIOSignature',
            'SiliconPlatformPort', 'SiliconPlatform',
-           'SimPlatform',
+           'SimPlatform', 'SoftwarePlatform',
            'JTAGSignature', 'SPISignature', 'I2CSignature', 'UARTSignature', 'GPIOSignature', 'QSPIFlashSignature',
-           'attach_simulation_data',
+           'attach_data', 'DriverSignature', 'SoftwareBuild',
            'Sky130DriveMode',
            'PACKAGE_DEFINITIONS']

chipflow_lib/platforms/_annotate.py

@@ -1,55 +1,70 @@
+
+from collections.abc import Generator
 from types import MethodType
-import pydantic
-from typing import TypeVar
+from typing import (
+    Tuple, 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):
+import pydantic
+from amaranth import Fragment
+from amaranth.lib import meta, wiring
+
+
+_T_TypedDict = TypeVar('_T_TypedDict')
+def amaranth_annotate(modeltype: type[_T_TypedDict], schema_id: str, member: str = '__chipflow_annotation__', decorate_object = False):
+    # a bit of nastyness as can't set TypedDict as a bound yet
     if not is_typeddict(modeltype):
-        raise TypeError(f'''amaranth_annotate must be passed a TypedDict, not {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: pydantic.ConfigDict = 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['$schema'] = "https://json-schema.org/draft/2020-12/schema"
         schema['$id'] = schema_id
         return schema
 
-    class Annotation:
-        'Generated annotation class'
+    class Annotation(meta.Annotation):
+        "Generated annotation class"
         schema = annotation_schema()
 
         def __init__(self, parent):
             self.parent = parent
 
-        def origin(self):
+        @property
+        def origin(self):  # type: ignore
             return self.parent
 
-        def as_json(self):
-            return PydanticModel.dump_python(getattr(self.parent, member))
+        def as_json(self):  # type: ignore
+            # TODO: this is slow, but atm necessary as dump_python doesn't do the appropriate
+            # transformation of things like PosixPath. Figure out why, maybe log issue/PR with
+            # pydantic
+            # return json.loads(PydanticModel.dump_json(getattr(self.parent, member)))
+            return PydanticModel.dump_python(getattr(self.parent, member), mode='json')
 
     def decorate_class(klass):
         if hasattr(klass, 'annotations'):
             old_annotations = klass.annotations
         else:
             old_annotations = None
-
-        def annotations(self, obj):
+        def annotations(self, obj, /):  # type: ignore
             if old_annotations:
-                annotations = old_annotations(self, obj)
+                annotations = old_annotations(self, obj)  # type: ignore
             else:
                 annotations = super(klass, obj).annotations(obj)
             annotation = Annotation(self)
-            return annotations + (annotation,)
+            return annotations + (annotation,)  # type: ignore
+
 
         klass.annotations = annotations
         return klass
@@ -60,19 +75,46 @@ def decorate_obj(obj):
         else:
             old_annotations = None
 
-        def annotations(self = None, origin = None):
+        def annotations(self, origin , /):  # type: ignore
             if old_annotations:
                 annotations = old_annotations(origin)
             else:
                 annotations = super(obj.__class__, obj).annotations(obj)
             annotation = Annotation(self)
-            return annotations + (annotation,)
+            return annotations + (annotation,)  # type: ignore
 
-        setattr(obj, 'annotations', MethodType(annotations, obj))
+        setattr(obj, 'annotations',  MethodType(annotations, obj))
         return obj
 
     if decorate_object:
         return decorate_obj
     else:
         return decorate_class
 
+
+def submodule_metadata(fragment: Fragment, component_name: str, recursive=False) -> Generator[Tuple[wiring.Component, str| tuple, dict]]:
+    """
+    Generator that finds `component_name` in `fragment` and
+    then yields the ``wiring.Component``s of that component's submodule, along with their names and metadata
+
+    Can only be run once for a given component (or its children)
+
+    If recursive = True, then name is a tuple of the heirarchy of names
+    otherwise, name is the string name of the first level component
+    """
+
+    subfrag = fragment.find_subfragment(component_name)
+    design = subfrag.prepare()
+    for k,v in design.elaboratables.items():
+        full_name:tuple = design.fragments[design.elaboratables[k]].name
+        if len(full_name) > 1:  # ignore the top component
+            if recursive:
+                name = full_name[1:]
+            else:
+                if len(full_name) != 2:
+                    continue
+                name = full_name[1]
+            if isinstance(k, wiring.Component):
+                metadata = k.metadata.as_json()['interface']
+                yield k, name, metadata
+

chipflow_lib/platforms/_internal.py

@@ -1,12 +1,15 @@
 from .silicon import *
 from .sim import *
+from ._software import SoftwarePlatform
 from ._utils import *
 from ._packages import *
+
 __all__ = ['IO_ANNOTATION_SCHEMA', 'IOSignature', 'IOModel',
            'OutputIOSignature', 'InputIOSignature', 'BidirIOSignature',
            'load_pinlock', "PACKAGE_DEFINITIONS", 'top_components', 'LockFile',
            'Package', 'PortMap', 'PortDesc', 'Process',
            'GAPackageDef', 'QuadPackageDef', 'BareDiePackageDef', 'BasePackageDef',
            'BringupPins', 'JTAGPins', 'PowerPins',
            'SiliconPlatformPort', 'SiliconPlatform',
-           'SimPlatform']
+           'SoftwarePlatform', 'SimPlatform',
+           ]

chipflow_lib/platforms/_signatures.py

@@ -1,25 +1,103 @@
 # SPDX-License-Identifier: BSD-2-Clause
 
 import re
-from typing import List, Tuple, Any
-from typing_extensions import Unpack, TypedDict
+import sys
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+        List, Tuple, Any, Protocol, runtime_checkable,
+        Literal, TypeVar, Generic, Annotated
+        )
+
+from typing_extensions import Unpack, TypedDict, NotRequired
 
 from amaranth.lib import wiring
 from amaranth.lib.wiring import Out
+from pydantic import PlainSerializer, WithJsonSchema, WrapValidator
 
+from .. import _ensure_chipflow_root
 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))
+DATA_SCHEMA = str(_chipflow_schema_uri("simulatable-data", 0))
+DRIVER_MODEL_SCHEMA = str(_chipflow_schema_uri("driver-model", 0))
 
 class SimInterface(TypedDict):
     uid: str
     parameters: List[Tuple[str, Any]]
 
-class SimData(TypedDict):
-    file_name: str
+@runtime_checkable
+@dataclass
+class DataclassProtocol(Protocol):
+    pass
+
+
+@dataclass
+class SoftwareBuild:
+    """
+    This holds the information needed for building software and providing the built outcome
+    """
+
+    sources: list[Path]
+    includes: list[Path]
+    include_dirs: list[Path]
     offset: int
+    filename: Path
+    build_dir: Path
+    type: Literal["SoftwareBuild"] = "SoftwareBuild"
+
+    def __init__(self, *, sources: list[Path], includes: list[Path] = [], include_dirs = [], offset=0):
+        self.build_dir = _ensure_chipflow_root() / 'build' / 'software'
+        self.filename = self.build_dir / 'software.bin'
+        self.sources= list(sources)
+        self.includes = list(includes)
+        self.include_dirs = list(include_dirs)
+        self.offset = offset
+
+
+_T_DataClass = TypeVar('_T_DataClass', bound=DataclassProtocol)
+class Data(TypedDict, Generic[_T_DataClass]):
+    data: _T_DataClass
+
+
+class DriverModel(TypedDict):
+    """
+    Options for `DriverSignature`
+
+    Attributes:
+        component: The `wiring.Component` that this is the signature for.
+        regs_struct: The name of the C struct that represents the registers of this component
+        h_files: Header files for the driver
+        c_files: C files for the driver
+        regs_bus: The bus of this `Component` which contains its control registers
+        include_dirs: any extra include directories needed by the driver
+    """
+    # we just extrat the info we need, don't actually serialise a `wiring.Component`...
+    component: Annotated[
+                wiring.Component,
+                PlainSerializer(lambda x: {
+                    'name': x.__class__.__name__,
+                    'file': sys.modules[x.__module__].__file__
+                    }, return_type=dict),
+                WithJsonSchema({
+                    'type': 'object',
+                    'properties': {
+                        'name': { 'type': 'string' },
+                        'file': { 'type': 'string' },
+                        }
+                    }),
+                WrapValidator(lambda v, h: v)  # Don't care about it actually..
+          ] | dict
+
+    regs_struct: str
+    h_files: NotRequired[list[Path]]
+    c_files: NotRequired[list[Path]]
+    include_dirs: NotRequired[list[Path]]
+    regs_bus: NotRequired[str]
+    _base_path: NotRequired[Path]  # gets filled by the decorator to the base directory where the Component was defined
+
 
 _VALID_UID = re.compile('[a-zA-Z_.]').search
 
@@ -124,7 +202,31 @@ 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)
+def attach_data(external_interface: wiring.PureInterface, component: wiring.Component, data: DataclassProtocol):
+    data_dict: Data = {'data':data}
+    setattr(component.signature, '__chipflow_data__', data_dict)
+    amaranth_annotate(Data, DATA_SCHEMA, '__chipflow_data__', decorate_object=True)(component.signature)
+    setattr(external_interface.signature, '__chipflow_data__', data_dict)
+    amaranth_annotate(Data, DATA_SCHEMA, '__chipflow_data__', decorate_object=True)(external_interface.signature)
+
+
+class DriverSignature(wiring.Signature):
+
+    def __init__(self, members, **kwargs: Unpack[DriverModel]):
+        definition_file = sys.modules[kwargs['component'].__module__].__file__
+        assert definition_file
+        base_path = Path(definition_file).parent.absolute()
+        kwargs['_base_path'] = base_path
+        if 'regs_bus' not in kwargs:
+            kwargs['regs_bus'] = 'bus'
+
+        # execute any generators here
+        for k in ('c_files', 'h_files', 'includedirs'):
+            if k in kwargs:
+                kwargs[k] = list(kwargs[k])  #type: ignore
+
+        self.__chipflow_driver_model__ = kwargs
+        amaranth_annotate(DriverModel, DRIVER_MODEL_SCHEMA, '__chipflow_driver_model__', decorate_object=True)(self)
+        super().__init__(members=members)
+