Move HDL reading logic and fix

Author: KelvinChung2000

FABulous/fabric_definition/Yosys_obj.py

@@ -1,14 +1,32 @@
-from dataclasses import dataclass, field
 import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Literal
 
+from loguru import logger
+
+from FABulous.FABulous_CLI.helper import check_if_application_exists
 
+"""Type alias for Yosys bit vectors containing integers or logic values."""
 BitVector = list[int | Literal["0", "1", "x", "z"]]
 
 
 @dataclass
 class YosysPortDetails:
+    """
+    Represents port details in a Yosys module.
+
+    Attributes:
+        direction: Port direction - "input", "output", or "inout"
+        bits: Bit vector representing the port's signals
+        offset: Bit offset for multi-bit ports (default: 0)
+        upto: Upper bound for bit ranges (default: 0)
+        signed: Whether the port is signed (0=unsigned, 1=signed, default: 0)
+    """
+
     direction: Literal["input", "output", "inout"]
     bits: BitVector
     offset: int = 0
@@ -18,19 +36,45 @@ class YosysPortDetails:
 
 @dataclass
 class YosysCellDetails:
+    """
+    Represents a cell instance in a Yosys module.
+
+    Cells are instantiated components like logic gates, flip-flops, or user-defined modules.
+
+    Attributes:
+        hide_name: Whether to hide the cell name in output (1=hide, 0=show)
+        type: Cell type/primitive name (e.g., "AND", "DFF", custom module name)
+        parameters: Cell parameters as string key-value pairs
+        attributes: Cell attributes including metadata and synthesis directives
+        connections: Port connections mapping port names to bit vectors
+        port_directions: Direction of each port ("input", "output", "inout")
+        model: Associated model name (optional, default: "")
+    """
+
     hide_name: Literal[1, 0]
     type: str
     parameters: dict[str, str]
     attributes: dict[str, str | int]
     connections: dict[str, BitVector]
-    port_directions: dict[str, Literal["input", "output", "inout"]] = field(
-        default_factory=dict
-    )
+    port_directions: dict[str, Literal["input", "output", "inout"]] = field(default_factory=dict)
     model: str = ""
 
 
 @dataclass
 class YosysMemoryDetails:
+    """
+    Represents memory block details in a Yosys module.
+
+    Memory blocks are inferred or explicitly instantiated memory elements.
+
+    Attributes:
+        hide_name: Whether to hide the memory name in output (1=hide, 0=show)
+        attributes: Memory attributes and metadata
+        width: Data width in bits
+        start_offset: Starting address offset
+        size: Memory size (number of addressable locations)
+    """
+
     hide_name: Literal[1, 0]
     attributes: dict[str, str]
     width: int
@@ -40,6 +84,20 @@ class YosysMemoryDetails:
 
 @dataclass
 class YosysNetDetails:
+    """
+    Represents net/wire details in a Yosys module.
+
+    Nets are the connections between cells and ports in the design.
+
+    Attributes:
+        hide_name: Whether to hide the net name in output (1=hide, 0=show)
+        bits: Bit vector representing the net's signals
+        attributes: Net attributes including unused bit information
+        offset: Bit offset for multi-bit nets (default: 0)
+        upto: Upper bound for bit ranges (default: 0)
+        signed: Whether the net is signed (0=unsigned, 1=signed, default: 0)
+    """
+
     hide_name: Literal[1, 0]
     bits: BitVector
     attributes: dict[str, str]
@@ -50,16 +108,41 @@ class YosysNetDetails:
 
 @dataclass
 class YosysModule:
+    """
+    Represents a module in a Yosys design.
+
+    A module contains the structural description of a digital circuit including
+    its interface (ports), internal components (cells), memory blocks, and
+    interconnections (nets).
+
+    Attributes:
+        attributes: Module attributes and metadata (e.g., "top" for top module)
+        parameter_default_values: Default values for module parameters
+        ports: Dictionary mapping port names to YosysPortDetails
+        cells: Dictionary mapping cell names to YosysCellDetails
+        memories: Dictionary mapping memory names to YosysMemoryDetails
+        netnames: Dictionary mapping net names to YosysNetDetails
+    """
+
     attributes: dict[str, str | int]
     parameter_default_values: dict[str, str | int]
     ports: dict[str, YosysPortDetails]
     cells: dict[str, YosysCellDetails]
     memories: dict[str, YosysMemoryDetails]
     netnames: dict[str, YosysNetDetails]
 
-    def __init__(
-        self, *, attributes, parameter_default_values, ports, cells, memories, netnames
-    ):
+    def __init__(self, *, attributes, parameter_default_values, ports, cells, memories, netnames):
+        """
+        Initialize a YosysModule from parsed JSON data.
+
+        Args:
+            attributes: Module attributes dictionary
+            parameter_default_values: Parameter defaults dictionary
+            ports: Ports dictionary (will be converted to YosysPortDetails objects)
+            cells: Cells dictionary (will be converted to YosysCellDetails objects)
+            memories: Memories dictionary (will be converted to YosysMemoryDetails objects)
+            netnames: Netnames dictionary (will be converted to YosysNetDetails objects)
+        """
         self.attributes = attributes
         self.parameter_default_values = parameter_default_values
         self.ports = {k: YosysPortDetails(**v) for k, v in ports.items()}
@@ -70,14 +153,63 @@ def __init__(
 
 @dataclass
 class YosysJson:
+    """
+    Root object representing a complete Yosys JSON file.
+
+    This class provides the main interface for loading and analyzing Yosys JSON
+    netlists. It contains all modules in the design and provides utility methods
+    for common netlist analysis tasks.
+
+    Attributes:
+        srcPath: Path to the source JSON file
+        creator: Tool that created the JSON (usually "Yosys")
+        modules: Dictionary mapping module names to YosysModule objects
+        models: Dictionary of behavioral models (implementation-specific)
+    """
+
     srcPath: Path
     creator: str
     modules: dict[str, YosysModule]
     models: dict
 
     def __init__(self, path: Path):
+        """
+        Load and parse a HDL file to a Yosys JSON object.
+
+        Args:
+            path: Path to a HDL file
+
+        Raises:
+            FileNotFoundError: If the JSON file doesn't exist
+            json.JSONDecodeError: If the file contains invalid JSON
+        """
+
         self.srcPath = path
-        with open(path, "r") as f:
+        yosys = check_if_application_exists(os.getenv("FAB_YOSYS_PATH", "yosys"))
+
+        json_file = self.srcPath.with_suffix(".json")
+
+        if self.srcPath.suffix in [".v", ".sv"]:
+            runCmd = [
+                yosys,
+                "-q",
+                f"-p read_verilog -sv {self.srcPath}; proc -noopt; write_json -compat-int {json_file}",
+            ]
+        elif self.srcPath.suffix in [".vhd", ".vhdl"]:
+            runCmd = [
+                yosys,
+                "-m",
+                "ghdl-q",
+                f"-p ghdl {self.srcPath}; proc -noopt; write_json -compat-int {json_file}",
+            ]
+        else:
+            raise ValueError(f"Unsupported HDL file type: {self.srcPath.suffix}")
+        try:
+            subprocess.run(runCmd, check=True)
+        except subprocess.CalledProcessError as e:
+            logger.opt(exception=subprocess.CalledProcessError(1, runCmd)).error(f"Failed to run yosys command: {e}")
+
+        with open(json_file, "r") as f:
             o = json.load(f)
         self.creator = o.get("creator", "")  # Use .get() for safety
         # Provide default empty dicts for potentially missing keys in module data
@@ -95,37 +227,85 @@ def __init__(self, path: Path):
         self.models = o.get("models", {})  # Use .get() for safety
 
     def getTopModule(self) -> YosysModule:
+        """
+        Find and return the top-level module in the design.
+
+        The top module is identified by having a "top" attribute.
+
+        Returns:
+            YosysModule: The top-level module
+
+        Raises:
+            ValueError: If no top module is found in the design
+        """
         for module in self.modules.values():
             if "top" in module.attributes:
                 return module
         raise ValueError("No top module found in Yosys JSON")
 
     def isTopModuleNet(self, net: int) -> bool:
+        """
+        Check if a net ID corresponds to a top-level module port.
+
+        Args:
+            net: Net ID to check
+
+        Returns:
+            bool: True if the net is connected to a top module port, False otherwise
+        """
         for module in self.modules.values():
             for pDetail in module.ports.values():
                 if net in pDetail.bits:
                     return True
         return False
 
     def isNetUsed(self, net: int) -> bool:
+        """
+        Determine if a net is actually used in the design.
+
+        This method checks the "unused_bits" attribute to determine if a specific
+        net bit is marked as unused by Yosys optimization.
+
+        Args:
+            net: Net ID to check
+
+        Returns:
+            bool: True if the net is used, False if it's marked as unused
+        """
         for module in self.modules.values():
             for net_name, net_details in module.netnames.items():
                 if net in net_details.bits and "unused_bits" in net_details.attributes:
                     if r := re.search(r"\w+\[(\d+)\]", net_name):
-                        if int(r.group(1)) in [
-                            int(i)
-                            for i in net_details.attributes["unused_bits"].split(" ")
-                        ]:
+                        if int(r.group(1)) in [int(i) for i in net_details.attributes["unused_bits"].split(" ")]:
                             return False
 
                     else:
                         if "0 " in net_details.attributes["unused_bits"]:
                             return False
         return True
 
-    def getNetPortSrcSinks(
-        self, net: int
-    ) -> tuple[tuple[str, str], list[tuple[str, str]]]:
+    def getNetPortSrcSinks(self, net: int) -> tuple[tuple[str, str], list[tuple[str, str]]]:
+        """
+        Find the source and sink connections for a given net.
+
+        This method analyzes the netlist to determine what drives a net (source)
+        and what it connects to (sinks).
+
+        Args:
+            net: Net ID to analyze
+
+        Returns:
+            tuple: A tuple containing:
+                - Source: (cell_name, port_name) tuple for the driving cell/port
+                - Sinks: List of (cell_name, port_name) tuples for driven cells/ports
+
+        Raises:
+            ValueError: If net is not found or has multiple drivers
+
+        Note:
+            If no driver is found, the source will be ("", "z") indicating
+            a high-impedance or undriven net.
+        """
         src: list[tuple[str, str]] = []
         sinks: list[tuple[str, str]] = []
         for module in self.modules.values():
@@ -138,9 +318,7 @@ def getNetPortSrcSinks(
                             sinks.append((cell_name, conn_name))
 
         if len(sinks) == 0:
-            raise ValueError(
-                f"Net {net} not found in Yosys JSON or is a top module port output"
-            )
+            raise ValueError(f"Net {net} not found in Yosys JSON or is a top module port output")
 
         if len(src) == 0:
             src.append(("", "z"))

FABulous/fabric_generator/file_parser.py

@@ -138,7 +138,9 @@ def parseFabricCSV(fileName: str) -> Fabric:
         if i[0].startswith("Tile"):
             if "GENERATE" in i:
                 # import here to avoid circular import
-
+                from FABulous.fabric_generator.fabric_automation import (
+                    generateCustomTileConfig,
+                )
                 # we generate the tile right before we parse everything
                 i[1] = str(generate_custom_tile_config(filePath.joinpath(i[1])))
 
@@ -1020,17 +1022,7 @@ def parseBelFile(
 
     if filetype == "verilog":
         # Runs yosys on verilog file, creates netlist, saves to json in same directory.
-        json_file = filename.with_suffix(".json")
-        runCmd = [
-            "yosys",
-            f"-qpread_verilog -sv {filename}; proc -noopt; write_json -compat-int {json_file}",
-        ]
-        try:
-            subprocess.run(runCmd, check=True)
-        except subprocess.CalledProcessError as e:
-            logger.error(f"Failed to run yosys command: {e}")
-            raise ValueError
-        hdlData = YosysJson(json_file)
+        hdlData = YosysJson(filename)
 
         modules: dict[str, YosysModule] = hdlData.modules
         filtered_ports = {}