Complete package pin interface implementation

robtaylor · robtaylor · commit cf2bc9237383 · 2025-03-18T13:23:06.000Z
diff --git a/chipflow_lib/pin_lock.py b/chipflow_lib/pin_lock.py
@@ -91,14 +91,27 @@ def lock_pins() -> None:
     package_type = PACKAGE_DEFINITIONS[package_name]
 
     package = Package(package_type=package_type)
+    
+    # Initialize standard pins from package type
+    package.initialize_from_package_type()
+    
+    # Process user-defined pads and power pins
     for d in ("pads", "power"):
+        if d not in config["chipflow"]["silicon"]:
+            continue
+            
         logger.debug(f"Checking [chipflow.silicon.{d}]:")
         _map = {}
         for k, v in config["chipflow"]["silicon"][d].items():
-            pin = str(v['loc'])
-            used_pins.add(pin)
+            # Handle both old-style (loc) and new-style (name/voltage) configurations
+            pin = str(v['loc']) if 'loc' in v else None
+            
+            # Mark the pin as used if it has a location
+            if pin:
+                used_pins.add(pin)
+                
             port = oldlock.package.check_pad(k, v) if oldlock else None
-            if port and port.pins != [pin]:
+            if port and pin and port.pins != [pin]:
                 raise ChipFlowError(
                     f"chipflow.toml conflicts with pins.lock: "
                     f"{k} had pin {port.pins}, now {[pin]}."
diff --git a/chipflow_lib/platforms/utils.py b/chipflow_lib/platforms/utils.py
@@ -278,7 +278,7 @@ def jtag(self) -> Dict[JTAGWireName, Pin]:
 
     @property
     @abc.abstractmethod
-    def heartbeat(self) -> Dict(int, Pin):
+    def heartbeat(self) -> Dict[int, Pin]:
         """
         Numbered set of heartbeat pins for the package
         """
@@ -298,7 +298,7 @@ class _BareDiePackageDef(_BasePackageDef):
     """
 
     # Used by pydantic to differentate when deserialising
-    type: Literal["_QuadPackageDef"] = "_QuadPackageDef"
+    type: Literal["_BareDiePackageDef"] = "_BareDiePackageDef"
 
     width: int
     height: int
@@ -320,6 +320,55 @@ def allocate(self, available: PinSet, width: int) -> PinList:
         logger.debug(f"_BareDiePackageDef.returned {ret}")
         assert len(ret) == width
         return ret
+        
+    @property
+    def power(self) -> Dict[PowerType, Pin]:
+        """
+        The set of power pins for the package
+        """
+        # Default implementation - to be customized for specific package types
+        return {
+            PowerType.POWER: (_Side.N, 0),  # North side, pin 0
+            PowerType.GROUND: (_Side.S, 0)  # South side, pin 0
+        }
+    
+    @property
+    def resets(self) -> Dict[int, Pin]:
+        """
+        Numbered set of reset pins for the package
+        """
+        # Default implementation with one reset pin
+        return {0: (_Side.N, 1)}  # North side, pin 1
+    
+    @property
+    def clocks(self) -> Dict[int, Pin]:
+        """
+        Numbered set of clock pins for the package
+        """
+        # Default implementation with one clock pin
+        return {0: (_Side.N, 2)}  # North side, pin 2
+    
+    @property
+    def jtag(self) -> Dict[JTAGWireName, Pin]:
+        """
+        Map of JTAG pins for the package
+        """
+        # Default JTAG pin allocations
+        return {
+            JTAGWireName.TRST: (_Side.W, 0),  # West side, pin 0
+            JTAGWireName.TCK: (_Side.W, 1),   # West side, pin 1
+            JTAGWireName.TMS: (_Side.W, 2),   # West side, pin 2
+            JTAGWireName.TDI: (_Side.W, 3),   # West side, pin 3
+            JTAGWireName.TDO: (_Side.W, 4)    # West side, pin 4
+        }
+    
+    @property
+    def heartbeat(self) -> Dict[int, Pin]:
+        """
+        Numbered set of heartbeat pins for the package
+        """
+        # Default implementation with one heartbeat pin
+        return {0: (_Side.S, 1)}  # South side, pin 1
 
 
 class _QuadPackageDef(_BasePackageDef):
@@ -355,6 +404,62 @@ def allocate(self, available: Set[str], width: int) -> List[str]:
 
     def sortpins(self, pins: Union[List[str], Set[str]]) -> List[str]:
         return sorted(list(pins), key=int)
+        
+    @property
+    def power(self) -> Dict[PowerType, Pin]:
+        """
+        The set of power pins for the package
+        """
+        # Default implementation for a PGA package
+        # Use pin numbers for the corners of the package
+        total_pins = self.width * 2 + self.height * 2
+        return {
+            PowerType.POWER: str(1),  # First pin
+            PowerType.GROUND: str(total_pins // 2)  # Middle pin
+        }
+    
+    @property
+    def resets(self) -> Dict[int, Pin]:
+        """
+        Numbered set of reset pins for the package
+        """
+        # Default implementation with one reset pin
+        # Use a pin near the beginning of the package
+        return {0: str(2)}  # Second pin
+    
+    @property
+    def clocks(self) -> Dict[int, Pin]:
+        """
+        Numbered set of clock pins for the package
+        """
+        # Default implementation with one clock pin
+        # Use a pin near the beginning of the package
+        return {0: str(3)}  # Third pin
+    
+    @property
+    def jtag(self) -> Dict[JTAGWireName, Pin]:
+        """
+        Map of JTAG pins for the package
+        """
+        # Default JTAG pin allocations
+        # Use consecutive pins in the middle of the package
+        mid_pin = (self.width * 2 + self.height * 2) // 4
+        return {
+            JTAGWireName.TRST: str(mid_pin),
+            JTAGWireName.TCK: str(mid_pin + 1),
+            JTAGWireName.TMS: str(mid_pin + 2),
+            JTAGWireName.TDI: str(mid_pin + 3),
+            JTAGWireName.TDO: str(mid_pin + 4)
+        }
+    
+    @property
+    def heartbeat(self) -> Dict[int, Pin]:
+        """
+        Numbered set of heartbeat pins for the package
+        """
+        # Default implementation with one heartbeat pin
+        # Use the last pin in the package
+        return {0: str(self.width * 2 + self.height * 2 - 1)}
 
 
 # Add any new package types to both PACKAGE_DEFINITIONS and the PackageDef union
@@ -363,7 +468,7 @@ def sortpins(self, pins: Union[List[str], Set[str]]) -> List[str]:
     "cf20": _BareDiePackageDef(name="cf20", width=7, height=3)
 }
 
-PackageDef = Union[_QuadPackageDef, _BasePackageDef]
+PackageDef = Union[_QuadPackageDef, _BareDiePackageDef, _BasePackageDef]
 
 
 class Port(pydantic.BaseModel):
@@ -382,13 +487,15 @@ class Package(pydantic.BaseModel):
     power: Dict[str, Port] = {}
     clocks: Dict[str, Port] = {}
     resets: Dict[str, Port] = {}
+    jtag: Dict[str, Port] = {}
+    heartbeat: Dict[str, Port] = {}
 
     def check_pad(self, name: str, defn: dict):
         match defn:
             case {"type": "clock"}:
                 return self.clocks[name] if name in self.clocks else None
             case {"type": "reset"}:
-                return self.resets[name] if name in self.clocks else None
+                return self.resets[name] if name in self.resets else None
             case {"type": "power"}:
                 return self.power[name] if name in self.power else None
             case {"type": "ground"}:
@@ -406,8 +513,44 @@ def add_pad(self, name: str, defn: dict):
                 self.power[name] = Port(type="power", pins=[loc])
             case {"type": "ground", "loc": loc}:
                 self.power[name] = Port(type="ground", pins=[loc])
+            case {"type": "power", "name": name, "voltage": voltage}:
+                # Support for new power pin format
+                # First, get the default pin from the package type
+                power_pin = self.package_type.power[PowerType.POWER]
+                self.power[name] = Port(type="power", pins=[str(power_pin)], options={"voltage": voltage})
+            case {"type": "ground", "name": name}:
+                # Support for new ground pin format
+                ground_pin = self.package_type.power[PowerType.GROUND]
+                self.power[name] = Port(type="ground", pins=[str(ground_pin)])
             case _:
                 pass
+                
+    def initialize_from_package_type(self):
+        """Initialize standard pins from package type definitions"""
+        # Set up clocks
+        for clock_id, pin in self.package_type.clocks.items():
+            name = f"clock_{clock_id}"
+            if name not in self.clocks:
+                self.clocks[name] = Port(type="clock", pins=[str(pin)], direction=io.Direction.Input)
+        
+        # Set up resets
+        for reset_id, pin in self.package_type.resets.items():
+            name = f"reset_{reset_id}"
+            if name not in self.resets:
+                self.resets[name] = Port(type="reset", pins=[str(pin)], direction=io.Direction.Input)
+                
+        # Set up heartbeat pins
+        for hb_id, pin in self.package_type.heartbeat.items():
+            name = f"heartbeat_{hb_id}"
+            if name not in self.heartbeat:
+                self.heartbeat[name] = Port(type="heartbeat", pins=[str(pin)], direction=io.Direction.Output)
+                
+        # Set up JTAG pins
+        for jtag_name, pin in self.package_type.jtag.items():
+            name = f"jtag_{jtag_name.value}"
+            direction = io.Direction.Output if jtag_name == JTAGWireName.TDO else io.Direction.Input
+            if name not in self.jtag:
+                self.jtag[name] = Port(type="jtag", pins=[str(pin)], direction=direction)
 
 
 _Interface = Dict[str, Dict[str, Port]]
diff --git a/docs/package_pins.md b/docs/package_pins.md
@@ -0,0 +1,103 @@
+# Package Pin Interface in ChipFlow
+
+This document describes the package pin interface in ChipFlow, introduced to provide a more structured and consistent way to specify pin configurations for chip packages.
+
+## Overview
+
+The package pin interface provides definitions for various types of pins in a chip package:
+
+- Power and ground pins
+- Clock pins 
+- Reset pins
+- JTAG pins
+- Heartbeat pins
+
+Each package type (PGA, bare die, etc.) defines its own implementation of these pin types, with appropriate pin numbering and allocation strategies.
+
+## Configuration in TOML Files
+
+### Legacy Format (still supported)
+```toml
+[chipflow.silicon.power]
+vdd = { type = "power", loc = "1" }
+gnd = { type = "ground", loc = "2" }
+
+[chipflow.silicon.pads]
+reset = { type = "reset", loc = "3" }
+clock = { type = "clock", loc = "4" }
+```
+
+### New Format
+```toml
+[chipflow.silicon.power]
+vdd = { type = "power", name = "vdd", voltage = "1.8V" }
+gnd = { type = "ground", name = "gnd" }
+```
+
+In the new format, the package definition provides default locations for standard pins like power, ground, clocks, and resets. You only need to specify the name and properties.
+
+## Using the Package Pin Interface in Code
+
+### Getting Default Pins
+
+```python
+from chipflow_lib.platforms.utils import PACKAGE_DEFINITIONS, PowerType, JTAGWireName
+
+# Get a package definition
+package_def = PACKAGE_DEFINITIONS["pga144"]
+
+# Get power pins
+power_pins = package_def.power
+vdd_pin = power_pins[PowerType.POWER]  # Get the default power pin
+gnd_pin = power_pins[PowerType.GROUND]  # Get the default ground pin
+
+# Get clock pins
+clock_pins = package_def.clocks
+default_clock = clock_pins[0]  # Get the first clock pin
+
+# Get JTAG pins
+jtag_pins = package_def.jtag
+tck_pin = jtag_pins[JTAGWireName.TCK]  # Get the TCK pin
+tms_pin = jtag_pins[JTAGWireName.TMS]  # Get the TMS pin
+```
+
+### Creating a Package with Default Pins
+
+```python
+from chipflow_lib.platforms.utils import Package, PACKAGE_DEFINITIONS
+
+# Create a package with a specific package definition
+package = Package(package_type=PACKAGE_DEFINITIONS["pga144"])
+
+# Initialize default pins from the package definition
+package.initialize_from_package_type()
+```
+
+## Extending for New Package Types
+
+To create a new package type, you need to:
+
+1. Subclass `_BasePackageDef` and implement all the required properties and methods
+2. Add your new package type to the `PackageDef` union and `PACKAGE_DEFINITIONS` dictionary
+
+Example:
+
+```python
+class MyNewPackageDef(_BasePackageDef):
+    type: Literal["MyNewPackageDef"] = "MyNewPackageDef"
+    # ... implement all required methods ...
+
+# Add to the union
+PackageDef = Union[_QuadPackageDef, _BareDiePackageDef, MyNewPackageDef, _BasePackageDef]
+
+# Add to the dictionary of available packages
+PACKAGE_DEFINITIONS["my_new_package"] = MyNewPackageDef(name="my_new_package", ...)
+```
+
+## Running Tests
+
+Tests for the package pin interface can be run using:
+
+```bash
+pdm run pytest tests/test_package_pins.py
+```
diff --git a/tests/test_package_pins.py b/tests/test_package_pins.py
