peakrdl-busdecoder 0.2.0__py3-none-any.whl

peakrdl_busdecoder/cpuif/fanout_gen.py

@@ -0,0 +1,50 @@
+from collections import deque
+from typing import TYPE_CHECKING
+
+from systemrdl.node import AddressableNode
+from systemrdl.walker import WalkerAction
+
+from ..body import Body, ForLoopBody
+from ..design_state import DesignState
+from ..listener import BusDecoderListener
+
+if TYPE_CHECKING:
+    from .base_cpuif import BaseCpuif
+
+
+class FanoutGenerator(BusDecoderListener):
+    def __init__(self, ds: DesignState, cpuif: "BaseCpuif") -> None:
+        super().__init__(ds)
+        self._cpuif = cpuif
+
+        self._stack: deque[Body] = deque()
+        self._stack.append(Body())
+
+    def enter_AddressableComponent(self, node: AddressableNode) -> WalkerAction | None:
+        action = super().enter_AddressableComponent(node)
+
+        if node.array_dimensions:
+            for i, dim in enumerate(node.array_dimensions):
+                fb = ForLoopBody(
+                    "genvar",
+                    f"gi{i}",
+                    dim,
+                )
+                self._stack.append(fb)
+
+        self._stack[-1] += self._cpuif.fanout(node)
+
+        return action
+
+    def exit_AddressableComponent(self, node: AddressableNode) -> None:
+        if node.array_dimensions:
+            for _ in node.array_dimensions:
+                b = self._stack.pop()
+                if not b:
+                    continue
+                self._stack[-1] += b
+
+        super().exit_AddressableComponent(node)
+
+    def __str__(self) -> str:
+        return "\n".join(map(str, self._stack))

peakrdl_busdecoder/cpuif/interface.py

@@ -0,0 +1,190 @@
+"""Interface abstraction for handling flat and non-flat signal declarations."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from systemrdl.node import AddressableNode
+
+if TYPE_CHECKING:
+    from .base_cpuif import BaseCpuif
+
+
+class Interface(ABC):
+    """Abstract base class for interface signal handling."""
+
+    def __init__(self, cpuif: "BaseCpuif") -> None:
+        self.cpuif = cpuif
+
+    @property
+    @abstractmethod
+    def is_interface(self) -> bool:
+        """Whether this uses SystemVerilog interfaces."""
+        ...
+
+    @abstractmethod
+    def get_port_declaration(self, slave_name: str, master_prefix: str) -> str:
+        """
+        Generate port declarations for the interface.
+
+        Args:
+            slave_name: Name of the slave interface/signal prefix
+            master_prefix: Prefix for master interfaces/signals
+
+        Returns:
+            Port declarations as a string
+        """
+        ...
+
+    @abstractmethod
+    def signal(
+        self,
+        signal: str,
+        node: AddressableNode | None = None,
+        indexer: str | int | None = None,
+    ) -> str:
+        """
+        Generate signal reference.
+
+        Args:
+            signal: Signal name
+            node: Optional addressable node for master signals
+            indexer: Optional indexer for arrays.
+                     For SVInterface: str like "i" or "gi" for loop indices
+                     For FlatInterface: str or int for array subscript
+
+        Returns:
+            Signal reference as a string
+        """
+        ...
+
+
+class SVInterface(Interface):
+    """SystemVerilog interface-based signal handling."""
+
+    @property
+    def is_interface(self) -> bool:
+        return True
+
+    def get_port_declaration(self, slave_name: str, master_prefix: str) -> str:
+        """Generate SystemVerilog interface port declarations."""
+        slave_ports: list[str] = [f"{self.get_interface_type()}.slave {slave_name}"]
+        master_ports: list[str] = []
+
+        for child in self.cpuif.addressable_children:
+            base = f"{self.get_interface_type()}.master {master_prefix}{child.inst_name}"
+
+            # When unrolled, current_idx is set - append it to the name
+            if child.current_idx is not None:
+                base = f"{base}_{'_'.join(map(str, child.current_idx))}"
+
+            # Only add array dimensions if this should be treated as an array
+            if self.cpuif.check_is_array(child):
+                assert child.array_dimensions is not None
+                base = f"{base} {''.join(f'[{dim}]' for dim in child.array_dimensions)}"
+
+            master_ports.append(base)
+
+        return ",\n".join(slave_ports + master_ports)
+
+    def signal(
+        self,
+        signal: str,
+        node: AddressableNode | None = None,
+        indexer: str | int | None = None,
+    ) -> str:
+        """Generate SystemVerilog interface signal reference."""
+        from ..utils import get_indexed_path
+
+        # SVInterface only supports string indexers (loop variable names like "i", "gi")
+        if indexer is not None and not isinstance(indexer, str):
+            raise TypeError(f"SVInterface.signal() requires string indexer, got {type(indexer).__name__}")
+
+        if node is None or indexer is None:
+            # Node is none, so this is a slave signal
+            slave_name = self.get_slave_name()
+            return f"{slave_name}.{signal}"
+
+        # Master signal
+        master_prefix = self.get_master_prefix()
+        return f"{master_prefix}{get_indexed_path(node.parent, node, indexer, skip_kw_filter=True)}.{signal}"
+
+    @abstractmethod
+    def get_interface_type(self) -> str:
+        """Get the SystemVerilog interface type name."""
+        ...
+
+    @abstractmethod
+    def get_slave_name(self) -> str:
+        """Get the slave interface instance name."""
+        ...
+
+    @abstractmethod
+    def get_master_prefix(self) -> str:
+        """Get the master interface name prefix."""
+        ...
+
+
+class FlatInterface(Interface):
+    """Flat signal-based interface handling."""
+
+    @property
+    def is_interface(self) -> bool:
+        return False
+
+    def get_port_declaration(self, slave_name: str, master_prefix: str) -> str:
+        """Generate flat port declarations."""
+        slave_ports = self._get_slave_port_declarations(slave_name)
+        master_ports: list[str] = []
+
+        for child in self.cpuif.addressable_children:
+            master_ports.extend(self._get_master_port_declarations(child, master_prefix))
+
+        return ",\n".join(slave_ports + master_ports)
+
+    def signal(
+        self,
+        signal: str,
+        node: AddressableNode | None = None,
+        indexer: str | int | None = None,
+    ) -> str:
+        """Generate flat signal reference."""
+        if node is None:
+            # Node is none, so this is a slave signal
+            slave_prefix = self.get_slave_prefix()
+            return f"{slave_prefix}{signal}"
+
+        # Master signal
+        master_prefix = self.get_master_prefix()
+        base = f"{master_prefix}{node.inst_name}"
+
+        if not self.cpuif.check_is_array(node):
+            # Not an array or an unrolled element
+            if node.current_idx is not None:
+                # This is a specific instance of an unrolled array
+                return f"{base}_{signal}_{'_'.join(map(str, node.current_idx))}"
+            return f"{base}_{signal}"
+
+        # Is an array
+        if indexer is not None:
+            return f"{base}_{signal}[{indexer}]"
+        return f"{base}_{signal}[N_{node.inst_name.upper()}S]"
+
+    @abstractmethod
+    def _get_slave_port_declarations(self, slave_prefix: str) -> list[str]:
+        """Get slave port declarations."""
+        ...
+
+    @abstractmethod
+    def _get_master_port_declarations(self, child: AddressableNode, master_prefix: str) -> list[str]:
+        """Get master port declarations for a child node."""
+        ...
+
+    @abstractmethod
+    def get_slave_prefix(self) -> str:
+        """Get the slave signal name prefix."""
+        ...
+
+    @abstractmethod
+    def get_master_prefix(self) -> str:
+        """Get the master signal name prefix."""
+        ...

peakrdl_busdecoder/decode_logic_gen.py

@@ -0,0 +1,152 @@
+from collections import deque
+from enum import Enum
+from typing import cast
+
+from systemrdl.node import AddressableNode
+from systemrdl.walker import WalkerAction
+
+from .body import Body, ForLoopBody, IfBody
+from .design_state import DesignState
+from .listener import BusDecoderListener
+from .sv_int import SVInt
+from .utils import get_indexed_path
+
+
+class DecodeLogicFlavor(Enum):
+    READ = "rd"
+    WRITE = "wr"
+
+    @property
+    def cpuif_address(self) -> str:
+        return f"cpuif_{self.value}_addr"
+
+    @property
+    def cpuif_select(self) -> str:
+        return f"cpuif_{self.value}_sel"
+
+
+class DecodeLogicGenerator(BusDecoderListener):
+    def __init__(
+        self,
+        ds: DesignState,
+        flavor: DecodeLogicFlavor,
+    ) -> None:
+        super().__init__(ds)
+        self._flavor = flavor
+
+        self._decode_stack: deque[Body] = deque()  # Tracks decoder body
+        self._cond_stack: deque[str] = deque()  # Tracks conditions nested for loops
+
+        # Initial Stack Conditions
+        self._decode_stack.append(IfBody())
+
+    def cpuif_addr_predicate(self, node: AddressableNode, total_size: bool = True) -> list[str]:
+        # Generate address bounds
+        addr_width = self._ds.addr_width
+        l_bound = SVInt(
+            node.raw_absolute_address,
+            addr_width,
+        )
+        if total_size:
+            u_bound = l_bound + SVInt(node.total_size, addr_width)
+        else:
+            u_bound = l_bound + SVInt(node.size, addr_width)
+
+        array_stack = list(self._array_stride_stack)
+        if total_size and node.array_dimensions:
+            array_stack = array_stack[: -len(node.array_dimensions)]
+
+        # Handle arrayed components
+        l_bound_comp = [str(l_bound)]
+        u_bound_comp = [str(u_bound)]
+        for i, stride in enumerate(array_stack):
+            l_bound_comp.append(f"({addr_width}'(i{i})*{SVInt(stride, addr_width)})")
+            u_bound_comp.append(f"({addr_width}'(i{i})*{SVInt(stride, addr_width)})")
+
+        lower_expr = f"{self._flavor.cpuif_address} >= ({'+'.join(l_bound_comp)})"
+        upper_expr = f"{self._flavor.cpuif_address} < ({'+'.join(u_bound_comp)})"
+
+        predicates: list[str] = []
+        # Avoid generating a redundant >= 0 comparison, which triggers Verilator warnings.
+        if not (l_bound.value == 0 and len(l_bound_comp) == 1):
+            predicates.append(lower_expr)
+        predicates.append(upper_expr)
+
+        return predicates
+
+    def cpuif_prot_predicate(self, node: AddressableNode) -> list[str]:
+        if self._flavor == DecodeLogicFlavor.READ:
+            # Can we have PROT on read? (axi full?)
+            return []
+
+        # TODO: Implement
+        return []
+
+    def enter_AddressableComponent(self, node: AddressableNode) -> WalkerAction | None:
+        action = super().enter_AddressableComponent(node)
+
+        conditions: list[str] = []
+        conditions.extend(self.cpuif_addr_predicate(node))
+        conditions.extend(self.cpuif_prot_predicate(node))
+        condition = " && ".join(f"({c})" for c in conditions)
+
+        # Generate condition string and manage stack
+        if node.array_dimensions:
+            # arrayed component with new if-body
+            self._cond_stack.append(condition)
+            for i, dim in enumerate(
+                node.array_dimensions,
+            ):
+                fb = ForLoopBody(
+                    "int",
+                    f"i{i}",
+                    dim,
+                )
+                self._decode_stack.append(fb)
+
+            self._decode_stack.append(IfBody())
+        elif isinstance(self._decode_stack[-1], IfBody):
+            # non-arrayed component with if-body
+            ifb = cast(IfBody, self._decode_stack[-1])
+            with ifb.cm(condition) as b:
+                b += f"{self._flavor.cpuif_select}.{get_indexed_path(self._ds.top_node, node)} = 1'b1;"
+        else:
+            raise RuntimeError("Invalid decode stack state")
+
+        return action
+
+    def exit_AddressableComponent(self, node: AddressableNode) -> None:
+        if not node.array_dimensions:
+            return
+
+        ifb = self._decode_stack.pop()
+        if not ifb and isinstance(ifb, IfBody):
+            conditions: list[str] = []
+            conditions.extend(self.cpuif_addr_predicate(node, total_size=False))
+            condition = " && ".join(f"({c})" for c in conditions)
+
+            with ifb.cm(condition) as b:
+                b += f"{self._flavor.cpuif_select}.{get_indexed_path(self._ds.top_node, node)} = 1'b1;"
+        self._decode_stack[-1] += ifb
+
+        for _ in node.array_dimensions:
+            b = self._decode_stack.pop()
+            if not b:
+                continue
+
+            if isinstance(self._decode_stack[-1], IfBody):
+                ifb = cast(IfBody, self._decode_stack[-1])
+                with ifb.cm(self._cond_stack.pop()) as parent_b:
+                    parent_b += b
+            else:
+                self._decode_stack[-1] += b
+
+        super().exit_AddressableComponent(node)
+
+    def __str__(self) -> str:
+        body = self._decode_stack[-1]
+        if isinstance(body, IfBody):
+            with body.cm(...) as b:
+                b += f"{self._flavor.cpuif_select}.cpuif_err = 1'b1;"
+
+        return str(body)

peakrdl_busdecoder/design_scanner.py

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING
+
+from systemrdl.node import AddressableNode, AddrmapNode, Node, RegNode
+from systemrdl.walker import RDLListener, RDLWalker, WalkerAction
+
+if TYPE_CHECKING:
+    from .design_state import DesignState
+
+
+class DesignScanner(RDLListener):
+    """
+    Scans through the register model and validates that any unsupported features
+    are not present.
+
+    Also collects any information that is required prior to the start of the export process.
+    """
+
+    def __init__(self, ds: "DesignState") -> None:
+        self.ds = ds
+        self.msg = self.top_node.env.msg
+
+    @property
+    def top_node(self) -> AddrmapNode:
+        return self.ds.top_node
+
+    def do_scan(self) -> None:
+        RDLWalker().walk(self.top_node, self)
+        if self.msg.had_error:
+            self.msg.fatal("Unable to export due to previous errors")
+
+    def enter_Component(self, node: Node) -> WalkerAction:
+        if node.external and (node != self.top_node):
+            # Do not inspect external components. None of my business
+            return WalkerAction.SkipDescendants
+
+        # Collect any signals that are referenced by a property
+        for prop_name in node.list_properties():
+            _ = node.get_property(prop_name)
+
+        return WalkerAction.Continue
+
+    def enter_AddressableComponent(self, node: AddressableNode) -> None:
+        if node.external and node != self.top_node:
+            self.ds.has_external_addressable = True
+            if not isinstance(node, RegNode):
+                self.ds.has_external_block = True

peakrdl_busdecoder/design_state.py

@@ -0,0 +1,74 @@
+from typing import TypedDict
+
+from systemrdl.node import AddrmapNode
+from systemrdl.rdltypes.user_enum import UserEnum
+
+from .design_scanner import DesignScanner
+from .identifier_filter import kw_filter as kwf
+from .utils import clog2
+
+
+class DesignStateKwargs(TypedDict, total=False):
+    reuse_hwif_typedefs: bool
+    module_name: str
+    package_name: str
+    address_width: int
+    cpuif_unroll: bool
+    max_decode_depth: int
+
+
+class DesignState:
+    """
+    Dumping ground for all sorts of variables that are relevant to a particular
+    design.
+    """
+
+    def __init__(self, top_node: AddrmapNode, kwargs: DesignStateKwargs) -> None:
+        self.top_node = top_node
+        msg = top_node.env.msg
+
+        # ------------------------
+        # Extract compiler args
+        # ------------------------
+        self.reuse_hwif_typedefs: bool = kwargs.pop("reuse_hwif_typedefs", True)
+        self.module_name: str = kwargs.pop("module_name", None) or kwf(self.top_node.inst_name)
+        self.package_name: str = kwargs.pop("package_name", None) or f"{self.module_name}_pkg"
+        user_addr_width: int | None = kwargs.pop("address_width", None)
+
+        self.cpuif_unroll: bool = kwargs.pop("cpuif_unroll", False)
+        self.max_decode_depth: int = kwargs.pop("max_decode_depth", 1)
+
+        # ------------------------
+        # Info about the design
+        # ------------------------
+        self.cpuif_data_width = 0
+
+        # Track any referenced enums
+        self.user_enums: list[type[UserEnum]] = []
+
+        self.has_external_addressable = False
+        self.has_external_block = False
+
+        # Scan the design to fill in above variables
+        DesignScanner(self).do_scan()
+
+        if self.cpuif_data_width == 0:
+            # Scanner did not find any registers in the design being exported,
+            # so the width is not known.
+            # Assume 32-bits
+            msg.warning(
+                "Addrmap being exported only contains external components. Unable to infer the CPUIF bus width. Assuming 32-bits.",
+                self.top_node.inst.def_src_ref,
+            )
+            self.cpuif_data_width = 32
+
+        # ------------------------
+        # Min address width encloses the total size AND at least 1 useful address bit
+        self.addr_width = max(clog2(self.top_node.size), clog2(self.cpuif_data_width // 8) + 1)
+
+        if user_addr_width is None:
+            return
+
+        if user_addr_width < self.addr_width:
+            msg.fatal(f"User-specified address width shall be greater than or equal to {self.addr_width}.")
+        self.addr_width = user_addr_width

peakrdl_busdecoder/exporter.py

@@ -0,0 +1,142 @@
+import os
+from datetime import datetime
+from importlib.metadata import version
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypedDict
+
+import jinja2 as jj
+from systemrdl.node import AddrmapNode, RootNode
+from systemrdl.walker import RDLSteerableWalker
+from typing_extensions import Unpack
+
+from .cpuif import BaseCpuif
+from .cpuif.apb4 import APB4Cpuif
+from .decode_logic_gen import DecodeLogicFlavor, DecodeLogicGenerator
+from .design_state import DesignState
+from .identifier_filter import kw_filter as kwf
+from .listener import BusDecoderListener
+from .struct_gen import StructGenerator
+from .sv_int import SVInt
+from .utils import clog2
+from .validate_design import DesignValidator
+
+
+class ExporterKwargs(TypedDict, total=False):
+    cpuif_cls: type[BaseCpuif]
+    module_name: str
+    package_name: str
+    address_width: int
+    cpuif_unroll: bool
+    reuse_hwif_typedefs: bool
+    max_decode_depth: int
+
+
+if TYPE_CHECKING:
+    pass
+
+
+class BusDecoderExporter:
+    cpuif: BaseCpuif
+    ds: DesignState
+
+    def __init__(self, **kwargs: Unpack[ExporterKwargs]) -> None:
+        # Check for stray kwargs
+        if kwargs:
+            raise TypeError(f"got an unexpected keyword argument '{next(iter(kwargs.keys()))}'")
+
+        fs_loader = jj.FileSystemLoader(Path(__file__).parent)
+        c_loader = jj.ChoiceLoader(
+            [
+                fs_loader,
+                jj.PrefixLoader(
+                    {"base": fs_loader},
+                    delimiter=":",
+                ),
+            ]
+        )
+
+        self.jj_env = jj.Environment(
+            loader=c_loader,
+            undefined=jj.StrictUndefined,
+        )
+        self.jj_env.filters["kwf"] = kwf  # type: ignore
+        self.jj_env.filters["walk"] = self.walk  # type: ignore
+        self.jj_env.filters["clog2"] = clog2  # type: ignore
+
+    def export(self, node: RootNode | AddrmapNode, output_dir: str, **kwargs: Unpack[ExporterKwargs]) -> None:
+        """
+        Parameters
+        ----------
+        node: AddrmapNode
+            Top-level SystemRDL node to export.
+        output_dir: str
+            Path to the output directory where generated SystemVerilog will be written.
+            Output includes two files: a module definition and package definition.
+        cpuif_cls: :class:`peakrdl_busdecoder.cpuif.CpuifBase`
+            Specify the class type that implements the CPU interface of your choice.
+            Defaults to AMBA APB4.
+        module_name: str
+            Override the SystemVerilog module name. By default, the module name
+            is the top-level node's name.
+        package_name: str
+            Override the SystemVerilog package name. By default, the package name
+            is the top-level node's name with a "_pkg" suffix.
+        address_width: int
+            Override the CPU interface's address width. By default, address width
+            is sized to the contents of the busdecoder.
+        cpuif_unroll: bool
+            Unroll arrayed addressable nodes into separate instances in the CPU
+            interface. By default, arrayed nodes are kept as arrays.
+        max_decode_depth: int
+            Maximum depth for address decoder to descend into nested addressable
+            components. By default, the decoder descends 1 level deep.
+        """
+        # If it is the root node, skip to top addrmap
+        if isinstance(node, RootNode):
+            top_node = node.top
+        else:
+            top_node = node
+
+        self.ds = DesignState(top_node, kwargs)
+
+        cpuif_cls: type[BaseCpuif] = kwargs.pop("cpuif_cls", None) or APB4Cpuif
+
+        # Check for stray kwargs
+        if kwargs:
+            raise TypeError(f"got an unexpected keyword argument '{next(iter(kwargs.keys()))}'")
+
+        # Construct exporter components
+        self.cpuif = cpuif_cls(self)
+
+        # Validate that there are no unsupported constructs
+        DesignValidator(self).do_validate()
+
+        # Build Jinja template context
+        context = {  # type: ignore
+            "current_date": datetime.now().strftime("%Y-%m-%d"),
+            "version": version("peakrdl-busdecoder"),
+            "cpuif": self.cpuif,
+            "cpuif_decode": DecodeLogicGenerator,
+            "cpuif_select": StructGenerator,
+            "cpuif_decode_flavor": DecodeLogicFlavor,
+            "ds": self.ds,
+            "SVInt": SVInt,
+        }
+
+        # Write out design
+        os.makedirs(output_dir, exist_ok=True)
+        package_file_path = os.path.join(output_dir, self.ds.package_name + ".sv")
+        template = self.jj_env.get_template("package_tmpl.sv")
+        stream = template.stream(context)
+        stream.dump(package_file_path)
+
+        module_file_path = os.path.join(output_dir, self.ds.module_name + ".sv")
+        template = self.jj_env.get_template("module_tmpl.sv")
+        stream = template.stream(context)
+        stream.dump(module_file_path)
+
+    def walk(self, listener_cls: type[BusDecoderListener], **kwargs: dict[str, Any]) -> str:
+        walker = RDLSteerableWalker()
+        listener = listener_cls(self.ds, **kwargs)
+        walker.walk(self.ds.top_node, listener, skip_top=True)
+        return str(listener)