Phase 6 (Part 1): Create new platform module structure

Create new unified platform/ module to replace platforms/ and steps/:
- Created platform/io/ module with signatures, sky130, annotate
- Created platform/silicon.py and silicon_step.py
- Created platform/base.py with StepBase and _wire_up_ports
- Created platform/utils.py with top_components and get_software_builds
- Created platform/__init__.py with public API exports
- Copied sim, software, board modules (imports need updating)

Silicon platform is fully migrated with updated imports. Remaining
modules (sim, software, board) are copied but need import updates.

Next: Update imports in remaining modules and create backward compat shims.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: robtaylor

chipflow_lib/platform/__init__.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+Platform definitions for ChipFlow.
+
+This module provides platform implementations for silicon, simulation,
+and software targets, along with their associated build steps.
+"""
+
+# Silicon platform
+from .silicon import SiliconPlatformPort, SiliconPlatform
+from .silicon_step import SiliconStep, SiliconTop
+
+# Simulation platform (will be added)
+# from .sim import SimPlatform
+# from .sim_step import SimStep
+
+# Software platform (will be added)
+# from .software import SoftwarePlatform
+# from .software_step import SoftwareStep
+
+# Board step (will be added)
+# from .board_step import BoardStep
+
+# IO signatures and utilities
+from .io import (
+    IO_ANNOTATION_SCHEMA, IOSignature, IOModel, IOTripPoint, IOModelOptions,
+    OutputIOSignature, InputIOSignature, BidirIOSignature,
+    JTAGSignature, SPISignature, I2CSignature, UARTSignature, GPIOSignature, QSPIFlashSignature,
+    attach_data, SoftwareDriverSignature, SoftwareBuild,
+    Sky130DriveMode,
+)
+
+# Base classes and utilities
+from .base import StepBase, setup_amaranth_tools
+from .utils import top_components, get_software_builds
+
+__all__ = [
+    # Silicon
+    'SiliconPlatformPort',
+    'SiliconPlatform',
+    'SiliconStep',
+    'SiliconTop',
+    # IO
+    'IO_ANNOTATION_SCHEMA',
+    'IOSignature',
+    'IOModel',
+    'IOModelOptions',
+    'IOTripPoint',
+    'OutputIOSignature',
+    'InputIOSignature',
+    'BidirIOSignature',
+    'JTAGSignature',
+    'SPISignature',
+    'I2CSignature',
+    'UARTSignature',
+    'GPIOSignature',
+    'QSPIFlashSignature',
+    'attach_data',
+    'SoftwareDriverSignature',
+    'SoftwareBuild',
+    'Sky130DriveMode',
+    # Base
+    'StepBase',
+    'setup_amaranth_tools',
+    # Utils
+    'top_components',
+    'get_software_builds',
+]

chipflow_lib/platform/base.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+Base classes and utilities for ChipFlow platform steps.
+"""
+
+import logging
+import os
+
+from abc import ABC
+from amaranth import Module
+
+from .io import IOSignature
+
+logger = logging.getLogger(__name__)
+
+
+def setup_amaranth_tools():
+    """Configure environment for Amaranth/WASM tools."""
+    _amaranth_settings = {
+        "AMARANTH_USE_YOSYS": "system",
+        "YOSYS": "yowasp-yosys",
+        "SBY": "yowasp-sby",
+        "SMTBMC": "yowasp-yosys-smtbmc",
+        "NEXTPNR_ICE40": "yowasp-nextpnr-ice40",
+        "ICEPACK": "yowasp-icepackr",
+        "NEXTPNR_ECP5": "yowasp-nextpnr-ecp5",
+        "ECPBRAM": "yowasp-ecpbram",
+        "ECPMULTI": "yowasp-ecpmulti",
+        "ECPPACK": "yowasp-ecppack",
+        "ECPPLL": "yowasp-ecppll",
+        "ECPUNPACK": "yowasp-ecpunpack",
+        "NEXTPNR-ECP5": "yowasp-nextpnr-ecp5",
+        "YOSYS-WITNESS": "yowasp-yosys-witness",
+    }
+
+    os.environ |= _amaranth_settings
+
+
+class StepBase(ABC):
+    """Base class for ChipFlow build steps."""
+
+    def __init__(self, config={}):
+        ...
+
+    def build_cli_parser(self, parser):
+        "Build the cli parser for this step"
+        ...
+
+    def run_cli(self, args):
+        "Called when this step's is used from `chipflow` command"
+        self.build()
+
+    def build(self, *args):
+        "builds the design"
+        ...
+
+
+def _wire_up_ports(m: Module, top, platform):
+    """
+    Wire up component ports to platform ports based on the pin lock.
+
+    Args:
+        m: Amaranth Module to add connections to
+        top: Dictionary of top-level components
+        platform: Platform instance with _pinlock and _ports
+    """
+    logger.debug("Wiring up ports")
+    logger.debug("-> Adding top components:")
+    for n, t in top.items():
+        logger.debug(f"    > {n}, {t}")
+        setattr(m.submodules, n, t)
+    for component, iface in platform._pinlock.port_map.ports.items():
+        if component.startswith('_'):
+            logger.debug(f"Ignoring special component {component}")
+            continue
+
+        for iface_name, member, in iface.items():
+            for name, port in member.items():
+                logger.debug(f"    > {component}, {iface_name}, {name}: {port}")
+                iface = getattr(top[component], iface_name)
+                wire = (iface if isinstance(iface.signature, IOSignature)
+                        else getattr(iface, name))
+                port = platform._ports[port.port_name]
+                if hasattr(port, 'wire_up'):
+                    port.wire_up(m, wire)
+                else:
+                    inv_mask = sum(inv << bit for bit, inv in enumerate(port.invert))
+                    if hasattr(wire, 'i'):
+                        m.d.comb += wire.i.eq(port.i ^ inv_mask)
+                    if hasattr(wire, 'o'):
+                            m.d.comb += port.o.eq(wire.o ^ inv_mask)
+                    if hasattr(wire, 'oe'):
+                            m.d.comb += port.oe.eq(wire.oe)
+                    if hasattr(wire, 'ie'):
+                            m.d.comb += port.ie.eq(wire.ie)

chipflow_lib/platform/board_step.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-2-Clause
+from . import StepBase, setup_amaranth_tools
+
+class BoardStep(StepBase):
+    """Build the design for a board."""
+
+    def __init__(self, config, platform):
+        self.platform = platform
+        setup_amaranth_tools()
+
+    def build_cli_parser(self, parser):
+        pass
+
+    def run_cli(self, args):
+        self.build()
+
+    def build(self, *args):
+        "Build for the given platform"
+        self.platform.build(*args)

chipflow_lib/platform/io/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+IO signatures and utilities for ChipFlow platforms.
+
+This module provides IO signature definitions, annotations, and
+platform-specific IO utilities.
+"""
+
+# IO signature definitions
+from .iosignature import (
+    IOTripPoint,
+    IOModelOptions,
+    IOModel,
+    IO_ANNOTATION_SCHEMA,
+    IOSignature,
+    InputIOSignature,
+    OutputIOSignature,
+    BidirIOSignature,
+    _chipflow_schema_uri,
+)
+
+# Interface signatures
+from .signatures import (
+    JTAGSignature,
+    SPISignature,
+    I2CSignature,
+    UARTSignature,
+    GPIOSignature,
+    QSPIFlashSignature,
+    attach_data,
+    SoftwareDriverSignature,
+    SoftwareBuild,
+)
+
+# Sky130-specific
+from .sky130 import Sky130DriveMode
+
+# Annotation utilities
+from .annotate import amaranth_annotate, submodule_metadata
+
+__all__ = [
+    # IO Signatures
+    'IOTripPoint',
+    'IOModelOptions',
+    'IOModel',
+    'IO_ANNOTATION_SCHEMA',
+    'IOSignature',
+    'InputIOSignature',
+    'OutputIOSignature',
+    'BidirIOSignature',
+    '_chipflow_schema_uri',
+    # Interface Signatures
+    'JTAGSignature',
+    'SPISignature',
+    'I2CSignature',
+    'UARTSignature',
+    'GPIOSignature',
+    'QSPIFlashSignature',
+    'attach_data',
+    'SoftwareDriverSignature',
+    'SoftwareBuild',
+    # Sky130
+    'Sky130DriveMode',
+    # Annotations
+    'amaranth_annotate',
+    'submodule_metadata',
+]

chipflow_lib/platform/io/annotate.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+Amaranth annotation utilities for ChipFlow.
+"""
+
+from collections.abc import Generator
+from types import MethodType
+from typing import (
+    Tuple, TypeVar,
+)
+from typing_extensions import is_typeddict
+
+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}")
+
+    # interesting pydantic issue gets hit if arbitrary_types_allowed is False
+    if hasattr(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['$id'] = schema_id
+        return schema
+
+    class Annotation(meta.Annotation):
+        "Generated annotation class"
+        schema = annotation_schema()
+
+        def __init__(self, parent):
+            self.parent = parent
+
+        @property
+        def origin(self):  # type: ignore
+            return self.parent
+
+        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, /):  # type: ignore
+            if old_annotations:
+                annotations = old_annotations(self, obj)  # type: ignore
+            else:
+                annotations = super(klass, obj).annotations(obj)
+            annotation = Annotation(self)
+            return annotations + (annotation,)  # type: ignore
+
+
+        klass.annotations = annotations
+        return klass
+
+    def decorate_obj(obj):
+        if hasattr(obj, 'annotations'):
+            old_annotations = obj.annotations
+        else:
+            old_annotations = 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,)  # type: ignore
+
+        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