Extract packaging module from platforms/_utils.py

Phase 3 of the refactoring: create a dedicated packaging module with
focused sub-modules for pin definitions, port descriptions, lock files,
and package definitions.

**New Modules Created:**
- chipflow_lib/packaging/pins.py: Pin dataclasses (PowerPins, JTAGPins, BringupPins)
- chipflow_lib/packaging/port_desc.py: Port description models (PortDesc, PortMap)
- chipflow_lib/packaging/lockfile.py: Lock file models (LockFile, Package)
- chipflow_lib/packaging/allocation.py: Pin allocation algorithms
- chipflow_lib/packaging/base.py: Base classes (BasePackageDef, LinearAllocPackageDef)
- chipflow_lib/packaging/standard.py: Standard packages (QuadPackageDef, BareDiePackageDef)
- chipflow_lib/packaging/grid_array.py: Grid array packages (GAPackageDef)
- chipflow_lib/packaging/openframe.py: Openframe package (moved from platforms/)
- chipflow_lib/packaging/utils.py: Utility functions (load_pinlock)
- chipflow_lib/packaging/__init__.py: Public API exports

**Changes:**
- Updated platforms/_utils.py to import from packaging module instead of defining locally
- Removed ~850 lines of duplicate code from platforms/_utils.py
- All tests passing (38 passed, 11 skipped)

**Benefits:**
- Better organization: Related packaging code now grouped together
- Smaller files: Multiple focused ~200-300 line files instead of one 1131-line monster
- Cleaner imports: `from chipflow_lib.packaging import QuadPackageDef`
- Easier maintenance: Clear module boundaries

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

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

Author: robtaylor

KODING.md

@@ -0,0 +1,24 @@
+# ChipFlow Library Coding Standards
+
+## Build/Test/Lint Commands
+
+- Run tests: `pdm run test`
+- Run tests with coverage: `pdm run test-cov`
+- Run tests with HTML coverage report: `pdm run test-cov-html`
+- Run documentation tests: `pdm run test-docs`
+- Run linting: `pdm run lint`
+- Build documentation: `pdm run docs`
+- Run a single test file: `pdm run pytest tests/test_cli.py`
+- Run a single test function: `pdm run pytest tests/test_cli.py::test_command_name`
+
+## Code Style Guidelines
+
+- **Imports:** Follow standard Python import conventions (e.g., `import module`, `from module import name`). Group imports: standard library, third-party, local application.
+- **Formatting:** Use Ruff for automated formatting (`pdm lint`). Always lint before finishing a task. Adhere to PEP 8 guidelines. Max line length is generally 88 characters but Ruff config doesn't enforce this strictly.
+- **Typing:** Use type hints for all function signatures and variables where appropriate. Run type checking if available (currently not configured in `pyproject.toml`).
+- **Naming Conventions:**
+    - Variables and functions: `snake_case`
+    - Classes: `PascalCase`
+    - Constants: `UPPER_SNAKE_CASE`
+- **Error Handling:** Use specific exception types. Avoid catching generic `Exception`. Log errors appropriately.
+- **Documentation:** Write docstrings for all public modules, classes, functions, and methods following Google style docstrings.

\

@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: BSD-2-Clause
+
+import re
+import sys
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+        List, Tuple, Any, Self, Protocol, runtime_checkable,
+        Literal, Union, TypeVar, Generic
+        )
+
+from typing_extensions import Unpack, TypedDict, NotRequired
+
+from amaranth.lib import wiring
+from amaranth.lib.wiring import Out
+
+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))
+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]]
+
+@runtime_checkable
+@dataclass
+class DataclassProtocol(Protocol):
+    pass
+
+
+@dataclass
+class SoftwareBuild:
+    """
+    This holds the information needed for building software and providing the built outcome
+    """
+
+    user_files: list[Path]
+    offset: int
+    filename: Path
+    build_dir: Path
+    type: Literal["SoftwareBuild"] = "SoftwareBuild"
+
+    def __init__(self, user_files: list[Path], *, offset=0):
+        self.build_dir = _ensure_chipflow_root() / 'build' / 'software'
+        self.filename = self.build_dir / 'software.bin'
+        self.user_files = list(user_files)
+        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
+    """
+    component Annotated[
+                wiring.Component,
+                PlainSerializer(lambda x: {
+                    'name': x.__class__.__name__,
+                    'file': sys.modules[x.__module__].__file__, return_type=str),
+              WrapValidator(lambda v, h: h(v.strip('Vv ') if isinstance(v, str) else h(v)))
+          ]
+
+    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
+
+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_data(c: wiring.Component, data: DataclassProtocol):
+    data_dict: Data = {'data':data}
+    setattr(c.signature, '__chipflow_data__', data_dict)
+    amaranth_annotate(Data, DATA_SCHEMA, '__chipflow_data__', decorate_object=True)(c.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'
+
+        include_dirs = []
+        if 'include_dirs' in kwargs:
+            for i in kwargs['include_dirs']:
+                if not Path(i).is_absolute():
+                    include_dirs.append(base_path / i)
+                else:
+                    include_dirs.append(Path(i))
+
+        kwargs['include_dirs'] = include_dirs
+
+        self.__chipflow_driver_model__ = kwargs
+        amaranth_annotate(DriverModel, DRIVER_MODEL_SCHEMA, '__chipflow_driver_model__', decorate_object=True)(self)
+        super().__init__(members=members)
+
+
+