nortl 1.4.0__py3-none-any.whl

nortl/core/state.py

@@ -0,0 +1,201 @@
+"""Describes engine states as Python object."""
+
+from typing import Dict, List, Optional, Sequence, Set, Tuple
+
+from typing_extensions import Self
+
+from nortl.core.exceptions import ConflictingAssignmentError, ForbiddenAssignmentError, TransitionLockError, TransitionRestrictionError
+
+from .common import NamedEntity
+from .protocols import AssignmentTarget, EngineProto, Renderable, StateProto, WorkerProto
+
+__all__ = [
+    'State',
+]
+
+
+class State(NamedEntity):
+    """Representation of an engine state.
+
+    An engine state is characterized by a set of assignments to signals and a set of
+    conditions, when to enter which next state (transitions).
+
+    Each state belongs to a worker. Transitions can only be created betwen states of the same worker.
+    """
+
+    def __init__(self, worker: WorkerProto, name: str, allow_assignments: bool = True):
+        """Initialize a state.
+
+        Arguments:
+            worker: Engine worker.
+            name: State name.
+            allow_assignments: If the state allows assignments. This is used for internal purposes.
+        """
+        super().__init__('')
+        self._worker = worker
+
+        # Use setter for validation
+        self.name = name
+
+        self._allow_assignments = allow_assignments
+
+        self._assignments: List[Tuple[AssignmentTarget, Renderable]] = []
+        self._assigned_signal_names: Set[str] = set()
+
+        # Transition <Condition>, <next value of state variable>
+        self._transitions: List[Tuple[Renderable, Self]] = []
+        self._restricted_state: Optional[State] = None
+        self._transitions_locked = False
+
+        # Store for debug prints. These will not be rendered to synthesizeable constructs
+        self._prints: List[Tuple[str, Tuple[Renderable, ...]]] = []
+        self._printfs: Dict[str, List[Tuple[str, Tuple[Renderable, ...]]]] = {}
+
+    @property
+    def engine(self) -> EngineProto:
+        """Engine that this state belongs to."""
+        return self.worker.engine
+
+    @property
+    def worker(self) -> WorkerProto:
+        """Engine worker that this state belongs to."""
+        return self._worker
+
+    @property
+    def name(self) -> str:
+        """State name.
+
+        If the worker for this state is not the main worker, the name of the state must be prefixed with the name of the current worker.
+        The prefix is automatically added, if missing.
+        """
+        return self._name
+
+    @name.setter
+    def name(self, name: str) -> None:
+        """State name.
+
+        If the worker for this state is not the main worker, the name of the state must be prefixed with the name of the current worker.
+        The prefix is automatically added, if missing.
+        """
+
+        # Prefix the worker name if missing. The prefix is omitted for the main worker.
+        name = self.worker.create_scoped_name(name)
+
+        if name == self.name:
+            return
+
+        if name in self.worker.state_names:
+            raise KeyError(f'State {name} already exists.')
+
+        # Update set of state names in worker
+        if self.name != '':
+            self.worker.state_names.discard(self.name)
+        self.worker.state_names.add(name)
+
+        self._name = name
+
+    # Assignment Management
+    @property
+    def allow_assignments(self) -> bool:
+        """If this state allows assignments."""
+        return self._allow_assignments
+
+    @property
+    def assignments(self) -> Sequence[Tuple[AssignmentTarget, Renderable]]:
+        """Sequence of assignments for this state."""
+        return self._assignments
+
+    def add_assignment(self, signal: AssignmentTarget, value: Renderable) -> None:
+        """Add assignment to this state."""
+        if not self.allow_assignments:
+            raise ForbiddenAssignmentError(f'State {self.name} does not allow assignments.')
+
+        # Check if signal is already assigned
+        if (old_assignment := self.get_assignment(signal)) is not None:
+            other_signal, old_value = old_assignment
+
+            overlap = signal.overlaps_with(other_signal)
+
+            if overlap == 'partial':
+                raise ConflictingAssignmentError(
+                    f'State {self.name} already has an assignment to signal {signal.name} that partially overlaps with the new assignment.\n'
+                    f'Previous assignment was {other_signal} = {old_value}, new assignment is {signal} = {value}.'
+                    '\nRefusing to overwrite the signal.'
+                )
+
+            # Check equality of the signals by rendering them. This could cause false-negatives, but is the easiest way.
+            if overlap is True and value.render() != old_value.render():
+                raise ConflictingAssignmentError(
+                    f'State {self.name} already has an assignment to signal {signal.name}.\n'
+                    f'Previous value was {old_value}, new value would be {value}. Refusing to overwrite the signal.'
+                )
+
+        self._assignments.append((signal, value))
+        self._assigned_signal_names.add(signal.name)
+
+    def get_assignment(self, signal: AssignmentTarget) -> Optional[Tuple[AssignmentTarget, Renderable]]:
+        """Get current assignment for a signal.
+
+        Arguments:
+            signal: The signal to search for.
+
+        Returns:
+            The current assignment for this signal or None, if it is not assigned.
+        """
+        # Use a set of the assigned signal names for quick check. In case of a match, search for the signal.
+        if signal.name in self._assigned_signal_names:
+            for other_signal, value in self.assignments:
+                # Check by signal name, will also find slices of the same signal
+                if signal.name == other_signal.name:
+                    return other_signal, value
+        return None
+
+    # Transition Management
+    @property
+    def transitions(self) -> Sequence[Tuple[Renderable, Self]]:
+        """List of transitions to other states."""
+        return tuple(self._transitions)
+
+    def _add_transition(self, condition: Renderable, state: StateProto) -> None:
+        """Add transition to other state."""
+        if self._transitions_locked:
+            raise TransitionLockError('The transitions for this state have been locked. You cannot add any other transitions.')
+        elif self._restricted_state is not None and state is not self._restricted_state:
+            raise TransitionRestrictionError(
+                f'This state was restricted to transitions to state {self._restricted_state.name}. Unable to add other transitions.'
+            )
+        self._transitions.append((condition, state))  # type: ignore[arg-type]
+
+    def _restrict_transition(self, state: StateProto) -> None:
+        """Restrict transitions to only allow one other state."""
+        if self._restricted_state is not None and state is not self._restricted_state:
+            raise TransitionRestrictionError(
+                f'This state was alreay restricted to transitions to state {self._restricted_state.name}. Unable to restrict for another state.'
+            )
+        self._restricted_state = state  # type: ignore[assignment]
+
+    def _lock_transitions(self) -> None:
+        """Lock the current transitions and prevent any others from being added."""
+        self._transitions_locked = True
+
+    # Misc.
+    def render(self, target: Optional[str] = None) -> str:
+        """Returns the state name for Verilog.
+
+        This function will later contain the logic to transform any string to a correct verilog name.
+        """
+        return self._name
+
+    def __format__(self, format_spec: str) -> str:
+        return self.render()
+
+    def print(self, line: str, *args: Renderable) -> None:
+        """Adds a line to the print list that will be processed during simulation."""
+        self._prints.append((line, args))
+
+    def printf(self, fname: str, line: str, *args: Renderable) -> None:
+        """Store an item that will be output to a file during simulation."""
+        if fname in self._printfs:
+            self._printfs[fname].append((line, args))
+        else:
+            self._printfs[fname] = [(line, args)]

nortl/renderer/__init__.py

@@ -0,0 +1,5 @@
+from .mermaid_renderer import MermaidRenderer
+from .networkx_renderer import NetworkXRenderer
+from .verilog_renderer import VerilogRenderer
+
+__all__ = ['MermaidRenderer', 'NetworkXRenderer', 'VerilogRenderer']

nortl/renderer/mermaid_renderer.py

@@ -0,0 +1,38 @@
+from typing import List, Tuple
+
+from nortl.core.protocols import EngineProto, StateProto
+
+
+class MermaidRenderer:
+    """This class contains the methods to render a nortl to a mermaid state diagram.
+
+    Note that only states and transitions are shown. For transitions, the conditions are omitted.
+    It's purpose is to support illustration only!
+    """
+
+    # FIXME: Include Fork/Joins
+
+    def __init__(self, engine: EngineProto):
+        self.engine = engine
+
+        self.transitions: List[Tuple[str, str]] = []
+        self.indent_level = 0
+
+    def _add_transition(self, s1: StateProto, s2: StateProto) -> None:
+        self.transitions.append((s1.name, s2.name))
+
+    def render(self) -> str:
+        for states in self.engine.states.values():
+            for state in states:
+                for _, next_state in state.transitions:
+                    self._add_transition(state, next_state)
+
+        # Generate the mermaid code
+        ret = '---\n'
+        ret += f'title {self.engine.module_name}\n'
+        ret += '---\n'
+        ret += 'stateDiagram-v2\n'
+        for s1, s2 in self.transitions:
+            ret += f'    {s1} --> {s2}\n'
+
+        return ret

nortl/renderer/networkx_renderer.py

@@ -0,0 +1,29 @@
+from typing import List, Tuple
+
+import networkx as nx
+
+from nortl.core import CoreEngine
+
+
+class NetworkXRenderer:
+    """This class contains the methods to render a nortl to verilog code.
+
+    It only represents states and their transitions without representing the conditions.
+    """
+
+    def __init__(self, engine: CoreEngine):
+        self.engine = engine
+
+        self.transitions: List[Tuple[str, str]] = []
+        self.indent_level = 0
+
+    def render(self) -> nx.Graph:  # type: ignore
+        """Render the engine to a networkx graph."""
+        g = nx.DiGraph()  # type: ignore
+        for states in self.engine.states.values():
+            for state in states:
+                g.add_node(state.name)
+                for _, next_state in state.transitions:
+                    g.add_edge(state.name, next_state.name)
+
+        return g

nortl/renderer/verilog_renderer.py

@@ -0,0 +1,325 @@
+from typing import List
+
+from nortl.core.protocols import EngineProto
+
+from .verilog_utils.process import AlwaysComb, AlwaysFF, VerilogAssignment, VerilogCase, VerilogIf, VerilogPrint, VerilogPrintf
+from .verilog_utils.structural import VerilogDeclaration, VerilogModule
+
+# FIXME: Make empty blocks being not rendered at all.
+# FIXME: Remove if(1) statements
+
+
+class VerilogRenderer:
+    """This class transforms the engine data into a verilog code.
+
+    To simplify matters, the verilog_utils folder contains code for rendering individual blocks.
+    """
+
+    def __init__(self, engine: EngineProto, include_modules: bool = True, clock_gating: bool = False):
+        """Initializes the VerilogRenderer with the engine data and rendering options.
+
+        Args:
+            engine: The CoreEngine object representing the finite state machine.
+            include_modules: A boolean indicating whether to include module instantiations in the generated Verilog code. Defaults to True.
+            clock_gating: A boolean indicating whether to enable clock gating logic in the generated Verilog code. Defaults to False.
+        """
+        self.engine = engine
+        self.verilog_module = VerilogModule(self.engine.module_name)
+
+        self.codelst: List[str] = []
+
+        self.include_modules = include_modules
+        self.clock_gating = clock_gating
+
+        self.clk_request_signals: List[str] = []
+
+    def clear(self) -> None:
+        """Clears the internal code list and resets the Verilog module for a new rendering cycle."""
+        self.codelst = []
+        self.verilog_module = VerilogModule(self.engine.module_name)
+
+    def render(self) -> str:
+        """Renders the engine into Verilog code.
+
+        This method orchestrates the creation of the Verilog module, signals, instances, and logic blocks.
+
+        Returns:
+            A string containing the complete Verilog code.
+        """
+        self.clear()
+
+        self.create_interface()
+        self.create_state_enum()
+        self.create_instances()
+        self.create_next_state_logic()
+        self.create_output_function()
+        self.create_prints()
+        self.create_combinationals()
+        self.create_state_transition()
+
+        if self.clock_gating:
+            self.create_clock_gates()
+
+        ret: List[str] = []
+        if self.include_modules:
+            ret.extend(m.hdl_code for m in self.engine.modules.values())
+
+        ret.append(self.verilog_module.render())
+
+        return '\n'.join(ret)
+
+    def create_clock_gates(self) -> None:
+        """Creates the clock gating logic, including gated clock signals and enables.
+
+        This method adds the necessary signals and connections for implementing clock gating,
+        which can reduce power consumption by disabling the clock signal to inactive parts of the engine.
+        """
+        # Create gated clock signals and clock enables
+        self.verilog_module.signals.append(VerilogDeclaration('logic', 'GCLK'))
+        self.verilog_module.signals.append(VerilogDeclaration('logic', 'GCLK_enable'))
+        self.verilog_module.signals.append(VerilogDeclaration('logic', 'GCLK_enable_latched'))
+
+        clk_requests: List[str] = []
+
+        # Get clock requests from instances
+        for name, instance in self.engine.module_instances.items():
+            if instance.module.clk_request_port is not None:
+                signalname = f'clk_request_{name}'
+                self.verilog_module.signals.append(VerilogDeclaration('logic', signalname))
+                clk_requests.append(signalname)
+            if not instance.module._ignore_clk_rst_connection and instance._clock_gating:
+                verilog_inst = self.verilog_module.get_instance(name)
+                verilog_inst.add_connection('CLK_I', 'GCLK')
+
+        self.create_clock_enable(clk_requests)
+
+        # Change Clock signal of Always_ff blocks
+        for blk in self.verilog_module.functionals:
+            if isinstance(blk, AlwaysFF):
+                blk.clk = 'GCLK'
+
+        # Instantiate Clock Gate
+        clock_gate = VerilogDeclaration('nortl_clock_gate', 'I_CLOCK_GATE')
+        clock_gate.add_connection('CLK_I', 'CLK_I')
+        clock_gate.add_connection('EN', 'GCLK_enable')
+        clock_gate.add_connection('GCLK_O', 'GCLK')
+
+        self.verilog_module.instances.append(clock_gate)
+
+    def create_clock_enable(self, clk_requests: List[str]) -> None:
+        """Creates the clock enable signal based on state and clock requests.
+
+        This method generates the logic for controlling the clock enable signal, which is used to
+        disable the clock signal to inactive parts of the engine, reducing power consumption.
+        """
+        # Create clock enable by states
+        clk_en_proc = AlwaysComb()
+        clk_en_proc.add(VerilogAssignment('GCLK_enable', "1'b1"))
+
+        for worker in self.engine.workers.values():
+            state_variable = worker.create_scoped_name('state_nxt')
+            cases = VerilogCase(state_variable)
+
+            for state in worker.states:
+                if state.has_metadata('Clock_gating'):  # FIXME: Add Metadata to docs
+                    cases.add_case(state.name)
+                    cases.add_item(state.name, VerilogAssignment('GCLK_enable', "1'b0"))
+
+                    for condition, _ in state.transitions:
+                        block = VerilogIf(condition)
+                        block.true_branch.add(VerilogAssignment('GCLK_enable', "1'b1"))
+                        cases.add_item(state.name, block)
+
+                    for signal, val in state.assignments:
+                        block = VerilogIf(signal != val)
+                        block.true_branch.add(VerilogAssignment('GCLK_enable', "1'b1"))
+                        cases.add_item(state.name, block)
+
+            clk_en_proc.add(cases)
+
+        for req in clk_requests:
+            block = VerilogIf(req)
+            block.true_branch.add(VerilogAssignment('GCLK_enable', "1'b1"))
+            clk_en_proc.add(block)
+
+        self.verilog_module.functionals.append(clk_en_proc)
+
+    def create_interface(self) -> None:
+        """Creates the Verilog module interface, including parameters, signals, and ports.
+
+        This method defines the input and output signals of the Verilog module, as well as any
+        parameters that can be used to customize its behavior.
+        """
+        # Parameters
+        for param in self.engine.parameters.values():
+            if param.width is not None:
+                self.verilog_module.parameters[f'[{param.width - 1}:0] {param.name}'] = param.default_value
+            else:
+                self.verilog_module.parameters[param.name] = param.default_value
+
+        # Signals and Ports
+        self.verilog_module.ports.append(VerilogDeclaration('input logic', 'CLK_I'))
+        self.verilog_module.ports.append(VerilogDeclaration('input logic', 'RST_ASYNC_I'))
+
+        for name, signal in self.engine.signals.items():
+            if signal.type == 'local':
+                verilog_signal = VerilogDeclaration(signal.data_type, name, width=signal.width)
+                self.verilog_module.signals.append(verilog_signal)
+            else:
+                if signal.data_type in ['reg', 'wire', 'logic']:
+                    verilog_signal = VerilogDeclaration(f'{signal.type} {signal.data_type}', name, signal.width)
+                else:
+                    verilog_signal = VerilogDeclaration(signal.data_type, name, width=signal.width)
+                self.verilog_module.ports.append(verilog_signal)
+
+    def create_state_enum(self) -> None:
+        """Creates the Verilog state enumeration.
+
+        This method defines the enumeration type for the engine states, which is used to represent
+        the current state of the engine in the Verilog code.
+        """
+        for worker in self.engine.workers.values():
+            state_variable = worker.create_scoped_name('state')
+            state_nxt_variable = worker.create_scoped_name('state_nxt')
+            state_var = VerilogDeclaration('enum', [state_variable, state_nxt_variable])
+            for state in worker.states:
+                state_var.add_member(state.name)
+            self.verilog_module.signals.append(state_var)
+
+    def create_instances(self) -> None:
+        """Creates the Verilog module instances.
+
+        This method instantiates the submodules of the engine, connecting their ports to the
+        appropriate signals in the top-level module.
+        """
+        for instance in self.engine.module_instances.values():
+            decl = VerilogDeclaration(instance.module.name, instance.name)
+
+            # Parameters
+            for name, value in instance.module.parameters.items():
+                if name in instance.parameter_overrides:
+                    decl.add_parameter(name, instance.parameter_overrides[name].render())
+                else:
+                    decl.add_parameter(name, value)
+
+            # Connections
+            if not instance.module._ignore_clk_rst_connection:
+                decl.add_connection('CLK_I', 'CLK_I')
+                decl.add_connection('RST_ASYNC_I', 'RST_ASYNC_I')
+
+            for port_name, signal in instance.port_connections.items():
+                decl.add_connection(port_name, signal.render())
+
+            self.verilog_module.instances.append(decl)
+
+    def create_next_state_logic(self) -> None:
+        """Creates the Verilog next state logic.
+
+        This method generates the logic for determining the next state of the engine, based on the
+        current state and the input signals.
+        """
+        next_state_func = AlwaysComb()
+
+        for worker in self.engine.workers.values():
+            state_variable = worker.create_scoped_name('state')
+            state_nxt_variable = worker.create_scoped_name('state_nxt')
+
+            next_state_func.add(VerilogAssignment(state_nxt_variable, state_variable))
+
+            cases = VerilogCase(state_variable)
+
+            for state in worker.states:
+                cases.add_case(state.name)
+
+                for condition, next_state in state.transitions:
+                    item = VerilogIf(condition)
+                    item.true_branch.add(VerilogAssignment(state_nxt_variable, next_state))
+                    cases.add_item(state.name, item)
+
+            next_state_func.add(cases)
+
+        self.verilog_module.functionals.append(next_state_func)
+
+    def create_output_function(self) -> None:
+        """Creates the Verilog output function.
+
+        This method generates the logic for updating the output signals of the engine, based on the
+        current state and the input signals.
+        """
+        output_func = AlwaysFF('CLK_I', 'RST_ASYNC_I')
+
+        for signal, reset_val in self.engine.main_worker.reset_state.assignments:
+            output_func.add_reset(VerilogAssignment(signal, reset_val))
+
+        for signal in self.engine.signals.values():
+            if signal.pulsing:
+                output_func.add(VerilogAssignment(signal, '0'))
+
+        for worker in self.engine.workers.values():
+            state_nxt_variable = worker.create_scoped_name('state_nxt')
+            cases = VerilogCase(state_nxt_variable)
+
+            for state in worker.states:
+                if len(state.assignments) > 0:
+                    cases.add_case(state.name)
+
+                    for signal, val in state.assignments:
+                        cases.add_item(state.name, VerilogAssignment(signal, val))
+
+            output_func.add(cases)
+
+        self.verilog_module.functionals.append(output_func)
+
+    def create_prints(self) -> None:
+        """Creates the print statements that have been put into each state."""
+        output_func = AlwaysFF('CLK_I', 'RST_ASYNC_I')
+
+        for worker in self.engine.workers.values():
+            state_nxt_variable = worker.create_scoped_name('state_nxt')
+            cases = VerilogCase(state_nxt_variable)
+
+            for state in worker.states:
+                cases.add_case(state.name)
+
+                for fname, item in state._printfs.items():
+                    for line, val in item:
+                        cases.add_item(state.name, VerilogPrintf(fname, line, *[v.render() for v in val]))
+
+                for line, val in state._prints:
+                    cases.add_item(state.name, VerilogPrint(line, *[v.render() for v in val]))
+
+            output_func.add(cases)
+
+        self.verilog_module.functionals.append(output_func)
+
+    def create_combinationals(self) -> None:
+        """Creates the Verilog combinational logic.
+
+        This method generates the combinational logic for the engine, based on the input signals.
+        """
+        combinationals = AlwaysComb()
+
+        for signal, value in self.engine.combinationals:
+            combinationals.add(VerilogAssignment(signal, value))
+
+        self.verilog_module.functionals.append(combinationals)
+
+    def create_state_transition(self) -> None:
+        """Creates the Verilog state transition logic.
+
+        This method generates the logic for transitioning the engine from one state to another.
+        """
+        state_transition = AlwaysFF('CLK_I', 'RST_ASYNC_I')
+        for worker in self.engine.workers.values():
+            state_variable = worker.create_scoped_name('state')
+            state_nxt_variable = worker.create_scoped_name('state_nxt')
+
+            state_transition.add_reset(VerilogAssignment(state_variable, worker.reset_state.name))
+
+            block = VerilogIf(f'{worker.sync_reset}')
+            block.true_branch.add(VerilogAssignment(state_variable, worker.reset_state.name))
+            block.false_branch.add(VerilogAssignment(state_variable, state_nxt_variable))
+
+            state_transition.add(block)
+
+        self.verilog_module.functionals.append(state_transition)

nortl/renderer/verilog_utils/__init__.py

@@ -0,0 +1,6 @@
+from .structural import VerilogDeclaration, VerilogModule
+
+__all__ = [
+    'VerilogDeclaration',
+    'VerilogModule',
+]

nortl/renderer/verilog_utils/formatter.py

@@ -0,0 +1,29 @@
+class VerilogFormatter:
+    def __init__(self, code: str) -> None:
+        self.code_lst = code.split('\n')
+        self.indent_level = 0
+
+    def format(self) -> str:
+        self.code_lst = [self._indent(line) for line in self.code_lst]
+        self.code_lst = [self._newlines(line) for line in self.code_lst]
+        return '\n'.join(self.code_lst)
+
+    def _indent(self, line: str) -> str:
+        reasons_for_indent = ['begin', 'case']
+        reasons_for_dedent = ['end', 'endcase']
+
+        if any([x in line.split() for x in reasons_for_dedent]):
+            self.indent_level -= 1
+
+        ret = '   ' * self.indent_level + line
+
+        if any([x in line.split() for x in reasons_for_indent]):
+            self.indent_level += 1
+
+        return ret
+
+    def _newlines(self, line: str) -> str:
+        reasons_for_newline = ['module', 'always']
+        if any(line.strip().startswith(reason) for reason in reasons_for_newline):
+            return f'\n{line}'
+        return line