Add warning about custom model API stability

Note that the custom simulation model interface is subject to change
in future releases, while built-in models remain stable.

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: robtaylor

chipflow_lib/packaging/base.py

@@ -9,7 +9,7 @@
 
 import abc
 from collections import defaultdict
-from typing import TYPE_CHECKING, Dict, List, Set
+from typing import TYPE_CHECKING, Dict, Generic, List, Set, TypeVar
 
 import pydantic
 from amaranth.lib import wiring, io
@@ -24,8 +24,11 @@
 if TYPE_CHECKING:
     from ..config_models import Config, Process
 
+# Type variable for pin types (int for linear allocation, GAPin for grid arrays, etc.)
+PinType = TypeVar('PinType')
 
-class BasePackageDef(pydantic.BaseModel, abc.ABC):
+
+class BasePackageDef(pydantic.BaseModel, Generic[PinType], abc.ABC):
     """
     Abstract base class for the definition of a package.
 
@@ -45,6 +48,7 @@ def model_post_init(self, __context):
         """Initialize internal tracking structures"""
         self._interfaces: Dict[str, dict] = {}
         self._components: Dict[str, wiring.Component] = {}
+        self._ordered_pins = None  # Subclasses should set this
         return super().model_post_init(__context)
 
     def register_component(self, name: str, component: wiring.Component) -> None:
@@ -130,14 +134,17 @@ def _allocate_bringup(self, config: 'Config') -> Component:
 
         return {'bringup_pins': d}
 
-    @abc.abstractmethod
     def allocate_pins(self, config: 'Config', process: 'Process', lockfile: LockFile | None) -> LockFile:
         """
         Allocate package pins to the registered components.
 
         Pins should be allocated in the most usable way for users
         of the packaged IC.
 
+        This default implementation uses _linear_allocate_components with
+        self._allocate for the allocation strategy. Subclasses can override
+        if they need completely different allocation logic.
+
         Args:
             config: ChipFlow configuration
             process: Semiconductor process
@@ -149,6 +156,35 @@ def allocate_pins(self, config: 'Config', process: 'Process', lockfile: LockFile
         Raises:
             UnableToAllocate: If the ports cannot be allocated
         """
+        assert self._ordered_pins is not None, "Subclass must set self._ordered_pins in model_post_init"
+        portmap = _linear_allocate_components(
+            self._interfaces,
+            lockfile,
+            self._allocate,
+            set(self._ordered_pins)
+        )
+        bringup_pins = self._allocate_bringup(config)
+        portmap.ports['_core'] = bringup_pins
+        package = self._get_package()
+        return LockFile(package=package, process=process, metadata=self._interfaces, port_map=portmap)
+
+    @abc.abstractmethod
+    def _allocate(self, available: Set[PinType], width: int) -> List[PinType]:
+        """
+        Allocate pins from available set.
+
+        Subclasses must implement this to define their allocation strategy.
+
+        Args:
+            available: Set of available pins (type depends on package)
+            width: Number of pins needed
+
+        Returns:
+            List of allocated pins
+
+        Raises:
+            UnableToAllocate: If allocation fails
+        """
         ...
 
     @property
@@ -173,7 +209,7 @@ def _sortpins(self, pins: Pins) -> PinList:
         return sorted(list(pins))
 
 
-class LinearAllocPackageDef(BasePackageDef):
+class LinearAllocPackageDef(BasePackageDef[int]):
     """
     Base class for package types with linear pin/pad allocation.
 
@@ -186,24 +222,6 @@ class LinearAllocPackageDef(BasePackageDef):
     Not directly serializable - use concrete subclasses.
     """
 
-    def __init__(self, **kwargs):
-        self._ordered_pins = None
-        super().__init__(**kwargs)
-
-    def allocate_pins(self, config: 'Config', process: 'Process', lockfile: LockFile | None) -> LockFile:
-        """Allocate pins linearly from the ordered pin list"""
-        assert self._ordered_pins
-        portmap = _linear_allocate_components(
-            self._interfaces,
-            lockfile,
-            self._allocate,
-            set(self._ordered_pins)
-        )
-        bringup_pins = self._allocate_bringup(config)
-        portmap.ports['_core'] = bringup_pins
-        package = self._get_package()
-        return LockFile(package=package, process=process, metadata=self._interfaces, port_map=portmap)
-
     def _allocate(self, available: Set[int], width: int) -> List[int]:
         """
         Allocate pins from available set.

chipflow_lib/packaging/grid_array.py

@@ -9,15 +9,10 @@
 import logging
 from enum import StrEnum, auto
 from math import ceil, floor
-from typing import Dict, List, Literal, NamedTuple, Optional, Set, Tuple, TYPE_CHECKING
+from typing import Dict, List, Literal, NamedTuple, Optional, Set, Tuple
 
 from .base import BasePackageDef
 from .pins import PowerPins, JTAGPins, BringupPins
-from .lockfile import LockFile
-from .allocation import _linear_allocate_components
-
-if TYPE_CHECKING:
-    from ..config_models import Config, Process
 
 logger = logging.getLogger(__name__)
 
@@ -41,7 +36,7 @@ class GALayout(StrEnum):
     ISLAND = auto()  # Perimeter + center island
 
 
-class GAPackageDef(BasePackageDef):
+class GAPackageDef(BasePackageDef[GAPin]):
     """
     Definition of a grid array package.
 
@@ -187,19 +182,6 @@ def sort_by_quadrant(pins: Set[GAPin]) -> List[GAPin]:
 
         return super().model_post_init(__context)
 
-    def allocate_pins(self, config: 'Config', process: 'Process', lockfile: LockFile | None) -> LockFile:
-        """Allocate pins from the grid array"""
-        portmap = _linear_allocate_components(
-            self._interfaces,
-            lockfile,
-            self._allocate,
-            set(self._ordered_pins)
-        )
-        bringup_pins = self._allocate_bringup(config)
-        portmap.ports['_core'] = bringup_pins
-        package = self._get_package()
-        return LockFile(package=package, process=process, metadata=self._interfaces, port_map=portmap)
-
     def _allocate(self, available: Set[GAPin], width: int) -> List[GAPin]:
         """Allocate pins from available grid array pins"""
         from .allocation import _find_contiguous_sequence

docs/simulation-guide.rst

@@ -372,6 +372,9 @@ Adding Custom Models
 
 ChipFlow's built-in simulation models cover common peripherals (UART, SPI, I2C, GPIO, QSPI Flash). For custom peripherals, you'll need to write C++ models that interact with the CXXRTL-generated design.
 
+.. warning::
+   The custom simulation model interface is subject to change. Model APIs may be updated in future ChipFlow releases. Built-in models (UART, SPI, etc.) are stable, but custom model registration and integration mechanisms may evolve.
+
 **Learning Resources:**
 
 1. **Study existing models**: The best way to learn is to examine ChipFlow's built-in implementations: