nortl 1.4.0__py3-none-any.whl

nortl/core/exceptions.py

@@ -0,0 +1,139 @@
+"""This module defines exception types for noRTL."""
+
+from typing import TypeVar
+
+from nortl.core.protocols import AssignmentTarget, Renderable
+
+__all__ = [
+    'AccessAfterReleaseError',
+    'ConflictingAssignmentError',
+    'ExclusiveReadError',
+    'ExclusiveWriteError',
+    'ForbiddenAssignmentError',
+    'NonIdenticalRWError',
+    'OwnershipError',
+    'TransitionLockError',
+    'TransitionRestrictionError',
+    'UnfinishedForwardDeclarationError',
+    'WriteViolationError',
+    'read_access',
+    'write_access',
+]
+
+
+T_Read = TypeVar('T_Read', bound=Renderable)
+T_Write = TypeVar('T_Write', bound=AssignmentTarget)
+
+
+# Access Violation Errors
+class AccessViolationError(RuntimeError):
+    """Base class for errors caused by invalid read or write access to signals or operation results."""
+
+
+class ExclusiveReadError(AccessViolationError):
+    """This error occurs when a signal is read by more than one thread.
+
+    This error can be suppressed by disabling or ignoring the 'exclusive_read' check for a signal.
+
+    To permanently disable the check, use `signal.acess_checker.disable_check('exclusive_read')`.
+
+    To ignore the check during a read or write access, wrap the signal in a [Volatile][nortl.core.modifiers.Volatile] modifier with
+    `Volatile(signal, 'exclusive_read')`.
+    """
+
+
+class ExclusiveWriteError(AccessViolationError):
+    """This error occurs when a signal is written by more than one thread.
+
+    This error can be suppressed by disabling or ignoring the 'exclusive_write' check for a signal.
+
+    To permanently disable the check, use `signal.acess_checker.disable_check(''exclusive_write)`.
+
+    To ignore the check during a read or write access, wrap the signal in a [Volatile][nortl.core.modifiers.Volatile] modifier with
+    `Volatile(signal, 'exclusive_write')`.
+    """
+
+
+class NonIdenticalRWError(AccessViolationError):
+    """This error occurs when a signal is read and written by different threads.
+
+    This error can be suppressed by disabling or ignoring the 'identical_rw' check for a signal.
+
+    To permanently disable the check, use `signal.acess_checker.disable_checkidentical_rw('')`.
+
+    To ignore the check during a read or write access, wrap the signal in a [Volatile][nortl.core.modifiers.Volatile] modifier with
+    `Volatile(signal, 'identical_rw')`.
+    """
+
+
+class AccessAfterReleaseError(AccessViolationError):
+    """This error occurs when a scratch signal is accessed after being released."""
+
+
+class WriteViolationError(AccessViolationError):
+    """This error occurs when an input signal is written."""
+
+
+def read_access(object: T_Read) -> T_Read:
+    """Perform read access to renderable.
+
+    This helper function hides the traceback caused during recursive read access.
+    """
+    try:
+        object.read_access()
+    except AccessViolationError as e:
+        raise e.with_traceback(None)
+    return object
+
+
+def write_access(object: T_Write) -> T_Write:
+    """Perform write access to signal.
+
+    This helper function hides the traceback caused during recursive write access.
+    """
+    try:
+        object.write_access()
+    except AccessViolationError as e:
+        raise e.with_traceback(None)
+    return object
+
+
+# Transition Errors
+class TransitionError(RuntimeError):
+    """Base class for errors related to invalid transitions."""
+
+
+class TransitionLockError(TransitionError):
+    """This error occurs when attempting to add new transitions to a state that has been locked or would need to be locked but cannot."""
+
+
+class TransitionRestrictionError(TransitionError):
+    """This error occurs when attempting to add new transitions to a state that has been restricted to transition to a specific other state."""
+
+
+# Assignment Errors
+class AssignmentError(RuntimeError):
+    """Base class for errors related to invalid assignments."""
+
+
+class ForbiddenAssignmentError(AssignmentError):
+    """This error occurs when attempting to add assignments to a state that does not allow it."""
+
+
+class ConflictingAssignmentError(AssignmentError):
+    """This error occurs when attempting to add multiple conflicting assignments to the same signal in one state."""
+
+
+# Misc. Errors
+class OwnershipError(RuntimeError):
+    """This error occurs when noRTL instances, that don't belong to the same noRTL Engine are mixed up.
+
+    This can occur when noRTL is used in an interactive context, e.g. a Jupyter notebook.
+    """
+
+
+class UnfinishedForwardDeclarationError(RuntimeError):
+    """This error occurs when the worker has a forward-declared state, but the user attempts to switch the current state to a different state.
+
+    This error is meant to prevent dead-ends in the state graph.
+    """

nortl/core/manager/__init__.py

@@ -0,0 +1,6 @@
+"""This folder holds objects that are instantiated by the CoreEngine to 'manage' certain other objects such as signals."""
+
+from .scratch_manager import ScratchManager
+from .signal_manager import SignalManager
+
+__all__ = ['ScratchManager', 'SignalManager']

nortl/core/manager/scratch_manager.py

@@ -0,0 +1,128 @@
+from collections import deque
+from typing import Deque, List, Optional
+
+from more_itertools import run_length
+
+from nortl.core.operations import Var
+from nortl.core.protocols import EngineProto, ScratchSignalProto, SignalProto, ThreadProto
+from nortl.core.signal import ScratchSignal
+
+
+class ScratchManager:
+    def __init__(self, engine: EngineProto) -> None:
+        self.engine = engine
+
+        self._scratchpad_width: Optional[Var] = None
+        self._scratchpad: Optional[SignalProto] = None
+
+        self.scratch_signals: Deque[ScratchSignalProto] = deque([])
+
+    @property
+    def scratchpad_width(self) -> int:
+        """Width of scratch pad signal."""
+        if self._scratchpad_width is None:
+            self._create_scratch_pad()
+        return self._scratchpad_width.value  # type: ignore[union-attr]
+
+    @scratchpad_width.setter
+    def scratchpad_width(self, value: int) -> None:
+        """Width of scratch pad signal."""
+        if self._scratchpad_width is None:
+            self._create_scratch_pad()
+        if value < self.scratchpad_width:
+            raise ValueError('Scratch pad width must not be decreased.')
+        self._scratchpad_width.update(value)  # type: ignore[union-attr]
+
+    @property
+    def scratchpad(self) -> SignalProto:
+        """Scratch pad."""
+        if self._scratchpad is None:
+            self._create_scratch_pad()
+        return self._scratchpad  # type: ignore[return-value]
+
+    def _create_scratch_pad(self) -> None:
+        """Create scratchpad signal."""
+        self._scratchpad_width = Var(0)
+        self._scratchpad = self.engine.define_local('SCRATCH_SIGNAL', width=self._scratchpad_width, reset_value=0)
+
+    def create(self, width: int) -> ScratchSignal:
+        position = self.alloc(width)
+
+        if position is None:
+            raise ValueError('Scratch map full!')
+
+        new_scratch_signal = self.scratchpad[position + width - 1 : position].as_scratch_signal()
+        self.scratch_signals.append(new_scratch_signal)
+        return new_scratch_signal  # type: ignore[return-value]
+
+    @property
+    def scratch_map(self) -> List[bool]:
+        """Returns a list that shows the state of the currently allocated scratchpad.
+
+        The returned List comprises each bit on the scratchpad as a bool. True-values show, that the bit is currently in use.
+        This function is the base for the allocation algorithm that needs to find an appropriate slice of the scratchpad that
+        can be used for the next scratch register.
+
+        This function could be realized in a more incremental way in a future version.
+        """
+
+        smap = self.scratchpad_width * [False]
+
+        for elem in self.scratch_signals:
+            if not elem.released:
+                if isinstance(elem.index, slice):
+                    bits = list(elem.index.indices(self.scratchpad_width))
+
+                    if bits[1] < bits[0]:
+                        bits[0], bits[1] = bits[1], bits[0]
+
+                    # Include last bit in range
+                    bits[1] += 1
+
+                    for idx in range(*bits):
+                        smap[idx] = True
+                else:
+                    smap[elem.index] = True
+
+        return smap
+
+    def alloc(self, width: int) -> Optional[int]:
+        """Looks for a portion of the scratchpad, where N bits can be used.
+
+        The function returns the first bit's position.
+        """
+
+        mmap_encoded = run_length.encode(self.scratch_map)
+
+        position = 0
+        for used, length in mmap_encoded:
+            if not used and length >= width:
+                return position
+            position = position + length
+
+        # We did not find a position until now, so we extend the scratch pad by enough bits to fit the new signal in.
+        self.scratchpad_width += width
+
+        return self.alloc(width)
+
+    def enter_context(self) -> None:
+        """Triggers the enter_context function of all managed scratch signals."""
+        for scratch_signal in self.scratch_signals:
+            scratch_signal.enter_context()
+
+    def exit_context(self) -> None:
+        """Triggers the exit_context function of all managed scratch signals."""
+        for scratch_signal in self.scratch_signals:
+            scratch_signal.exit_context()
+
+    def force_release_signals_by_thread(self, thread: ThreadProto) -> None:
+        """Releases all signals of the current thread. This is triggered by the Thread class after the thread has safely ended."""
+        for scratch_signal in self.scratch_signals:
+            if scratch_signal.owner == thread:
+                scratch_signal.release(force=True)
+
+        self.free_accesses_from_thread(thread)
+
+    def free_accesses_from_thread(self, thread: ThreadProto) -> None:
+        for scratch_signal in self.scratch_signals:
+            scratch_signal.free_access_from_thread(thread)

nortl/core/manager/signal_manager.py

@@ -0,0 +1,71 @@
+from typing import Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from nortl.core.protocols import SIGNAL_TYPES, EngineProto, ParameterProto, Renderable, ThreadProto
+from nortl.core.signal import Signal
+
+
+class SignalManager:
+    def __init__(self, engine: EngineProto) -> None:
+        self.engine = engine
+        self._signals: Dict[str, Signal] = {}
+        self._combinationals: List[Tuple[Signal, Renderable]] = []
+
+    @property
+    def signals(self) -> Mapping[str, Signal]:
+        """Signals."""
+        return self._signals
+
+    @property
+    def combinationals(self) -> Sequence[Tuple[Signal, Renderable]]:
+        """Sequence of combinational signal assignments."""
+        return self._combinationals
+
+    def get_signal(self, name: str) -> Signal:
+        return self.signals[name]
+
+    def create_signal(
+        self,
+        type: SIGNAL_TYPES,
+        name: str,
+        width: Union[int, ParameterProto, Renderable] = 1,
+        data_type: str = 'logic',
+        is_synchronized: bool = False,
+        pulsing: bool = False,
+        assignment: Optional[Renderable] = None,
+    ) -> Signal:
+        """Create a signal.
+
+        Arguments:
+            type: Type of the signal.
+            name: Name of the signal.
+            width: Width of the signal in bits.
+            data_type: Data type of the signal.
+            is_synchronized: Indicates, if the signal is synchronous to the used clock domain
+            pulsing: If true, the signal automatically resets to zero if not set in the current state
+            assignment: Source expression for combinational assignment.
+
+        Returns:
+            The created signal.
+
+        Raises:
+            KeyError: If the signal name already exists.
+        """
+
+        if name in self.signals:
+            raise KeyError(f'Signal name {name} already exists.')
+        if name in self.engine.parameters:
+            raise KeyError(f'Signal name {name} collides with existing parameter name.')
+        signal = Signal(
+            self.engine, type, name, width=width, data_type=data_type, is_synchronized=is_synchronized, pulsing=pulsing, assignment=assignment
+        )
+        self._signals[name] = signal
+
+        # TODO width of assignment source is not respected, would be better to automatically pick it up?
+        # Maybe replace default of width with None?
+        if assignment is not None:
+            self._combinationals.append((signal, assignment))
+        return signal
+
+    def free_accesses_from_thread(self, thread: ThreadProto) -> None:
+        for signal in self.signals.values():
+            signal.free_access_from_thread(thread)

nortl/core/modifiers.py

@@ -0,0 +1,136 @@
+"""Modifiers can be applied to Renderables."""
+
+from typing import Generic, Literal, Optional, Set, TypeVar, Union
+
+from nortl.core.operations import OperationTrait
+from nortl.core.protocols import ACCESS_CHECKS, SIGNAL_ACCESS_CHECKS, AnySignal, AssignmentTarget, EngineProto, Renderable
+
+__all__ = [
+    'UnregisteredRead',
+    'Volatile',
+]
+T_Content = TypeVar('T_Content', bound=Renderable)
+T_Signal = TypeVar('T_Signal', bound=AnySignal)
+
+
+# Modifiers
+class BaseModifier(Generic[T_Content], OperationTrait):
+    """Baseclass for Modifiers."""
+
+    def __init__(self, content: T_Content) -> None:
+        """Initialize an alias.
+
+        Arguments:
+            content: An operation result.
+        """
+        self._content = content
+        super().__init__()
+
+    @property
+    def content(self) -> T_Content:
+        """Content of the alias."""
+        return self._content
+
+    # Implement OperationTrait
+    @property
+    def is_primitive(self) -> bool:
+        """Indicates if this object is a Verilog primitive."""
+        return self.content.is_primitive
+
+    @property
+    def operand_width(self) -> Optional[int]:
+        """Indicates the width when used as an operand, equal to the width of the alias operation.
+
+        A width of None means that the width is not fixed during execution of noRTL.
+        """
+        return self.content.operand_width
+
+    def render(self, target: Optional[str] = None) -> str:
+        """Render operation to target language.
+
+        Arguments:
+            target: Target language.
+        """
+        return self.content.render(target=target)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.render()
+
+    # TODO Modifier must only be valid within current construct
+
+
+class UnregisteredRead(Generic[T_Content], BaseModifier[T_Content]):
+    """Modifier for signals or operations, that hides them from read accesses.
+
+    Any read access to signals inside a UnregisteredRead modifier is not registered.
+    Note that this does not permanently disable the access checks, when acessing the signals normally.
+
+    !!! danger
+        This modifier is meant for internal purposes. For example, it is used in the noRTL test wrapper for assertions.
+        It must not be used in production code!
+    """
+
+    def read_access(self, ignore: Set[ACCESS_CHECKS] = set()) -> None:
+        """Register read access from the current thread, state and construct depth.
+
+        Does nothing for UnregisteredRead.
+        """
+
+
+class Volatile(Generic[T_Signal], BaseModifier[T_Signal]):
+    """Modifier for signals, allowing them to be shared between threads.
+
+    Wrapping a noRTL signal will temporarily ignore the following checks by default:
+
+    - Exclusive Read Check ([ExclusiveReadError][nortl.core.exceptions.ExclusiveReadError]): The modified object can be read from multiple threads.
+    - Non-Identical Read/Write Check ([NonIdenticalRWError][nortl.core.exceptions.NonIdenticalRWError]): The modified object can be read/written from different threads.
+
+    It's possible to select other checks to ignore, by listing their names, e.g.:
+
+    ```python
+    # Ignore a set of checks
+    unsafe_signal = Volatile(signal, 'identical_rw', 'exclusive_write')
+
+    # Ignore a single check
+    unsafe_signal = Volatile(signal, 'identical_rw')
+    ```
+
+    Note that this does not permanently disable the access checks. The read or write access to the signal is still registered.
+    If the same signal is used in other places, it may still cause access violations exceptions.
+    """
+
+    def __init__(self, content: T_Signal, *ignore: SIGNAL_ACCESS_CHECKS) -> None:
+        super().__init__(content)
+        if len(ignore) > 0:
+            self._ignore: Set[SIGNAL_ACCESS_CHECKS] = set(ignore)
+        else:
+            self._ignore = {'exclusive_read', 'identical_rw'}
+
+    @property
+    def ignore(self) -> Set[SIGNAL_ACCESS_CHECKS]:
+        """Set of ignored access checks."""
+        return self._ignore
+
+    # Implement OperationTrait
+    def read_access(self, ignore: Set[ACCESS_CHECKS] = set()) -> None:
+        """Register read access from the current thread, state and construct depth."""
+        self.content.read_access(ignore=ignore | self.ignore)
+
+    # Implement AssignmentTarget
+    @property
+    def name(self) -> str:
+        """Just return name."""
+        return self.content.name
+
+    @property
+    def engine(self) -> EngineProto:
+        """NoRTL engine that the signal belongs to."""
+        return self.content.engine
+
+    def write_access(self, ignore: Set[ACCESS_CHECKS] = set()) -> None:
+        """Register write access from the current thread."""
+        self.content.write_access(ignore=ignore | self.ignore)
+
+    def overlaps_with(self, other: AssignmentTarget) -> Union[bool, Literal['partial']]:
+        """Check if signal overlaps with other signal or signal slice."""
+        return self.content.overlaps_with(other)

nortl/core/module.py

@@ -0,0 +1,181 @@
+from typing import Dict, Final, List, Optional, Union
+
+from .operations import Const
+from .protocols import ModuleProto, ParameterProto, PermanentSignal, Renderable
+
+
+class Module:
+    """Representation of a Verilog module."""
+
+    def __init__(self, name: str, hdl_code: str = '') -> None:
+        """Initialize a new Verilog module.
+
+        Arguments:
+            name: Name of the module.
+            hdl_code: Verilog/VHDL code of the module that should be included in the output.
+        """
+        self._name: str = name
+        self._port_names: List[str] = []
+        self._parameters: Dict[str, int] = {}
+        self._hdl_code: str = hdl_code
+
+        # The following variable is used by the verilog renderer and masks out the connections of clk and reset
+        # Should be handled with care! Therefore this will not be exposed
+        self._ignore_clk_rst_connection: bool = False
+
+        # This variable is used for synthesizing the clock network in the final module.
+        # The verilog renderer will ignore this signal, if it is set to 'None', otherwise, it will
+        # create and connect a signal and wire it up to the enable of the clock gate of the top module.
+        self._clk_request_port: Union[None, str] = None
+
+    @property
+    def name(self) -> str:
+        """Module name."""
+        return self._name
+
+    @property
+    def ports(self) -> List[str]:
+        """List of ports for this module."""
+        return self._port_names
+
+    @property
+    def parameters(self) -> Dict[str, int]:
+        """Dictionary of parameter names and their values."""
+        return self._parameters
+
+    @property
+    def hdl_code(self) -> str:
+        """HDL Code of the module."""
+        return self._hdl_code
+
+    def add_port(self, port_name: str) -> None:
+        """Add a new port to the module.
+
+        Arguments:
+            port_name (str): The signal representing the port.
+        """
+        self._port_names.append(port_name)
+
+    def has_port(self, port_name: str) -> bool:
+        """Test, if a given port (identivfied by name) is in this module.
+
+        Arguments:
+            port_name (str): Port name to be checked
+
+        Returns:
+            bool: True, if port is in module
+        """
+        return port_name in self._port_names
+
+    def add_parameter(self, name: str, value: int) -> None:
+        """Add a new parameter to the module.
+
+        Arguments:
+            name: Name of the parameter.
+            value: Value of the parameter.
+        """
+        self._parameters[name] = value
+
+    def set_clk_request(self, port_name: str) -> None:
+        """Set the clock request port for the rendering process.
+
+        Arguments:
+           port_name (str): The name of the clock request port.
+
+        Note that this method should be called after all ports have been added.
+        """
+        if port_name in self._port_names:
+            self._clk_request_port = port_name
+        else:
+            raise ValueError(f'Port {port_name} not found in module ports.')
+
+    @property
+    def clk_request_port(self) -> Optional[str]:
+        """Get the clock request port for the rendering process.
+
+        Returns:
+           Optional[str]: The name of the clock request port or None if not set.
+        """
+        return self._clk_request_port
+
+
+class ModuleInstance:
+    """Representation of an instance of a Verilog module."""
+
+    is_primitive: Final = False
+
+    def __init__(self, module: ModuleProto, name: str, clock_gating: bool = False) -> None:
+        """Initialize a new instance of a Verilog module.
+
+        Arguments:
+            module: The module to be instantiated.
+            name: Name of the instance.
+            clock_gating: If the clock is gated if the current state demands it (and clock gating is enabled in renderer)
+        """
+        self._module = module
+        self._name = name
+        self._port_connections: Dict[str, PermanentSignal] = {}  # Use signal name as key
+        self._parameter_overrides: Dict[str, Union[Const, ParameterProto, Renderable]] = {}
+        self._clock_gating = clock_gating
+
+        if self._module.clk_request_port is not None:
+            self._clock_gating = True
+
+    @property
+    def module(self) -> ModuleProto:
+        """The module being instantiated."""
+        return self._module
+
+    @property
+    def name(self) -> str:
+        """Name of the instance."""
+        return self._name
+
+    @property
+    def port_connections(self) -> Dict[str, PermanentSignal]:
+        """Connections between the ports and signals."""
+        return self._port_connections
+
+    @property
+    def parameter_overrides(self) -> Dict[str, Union[Const, ParameterProto, Renderable]]:
+        """Dictionary of overridden parameter names and their values."""
+        return self._parameter_overrides
+
+    def connect_port(self, port_name: str, signal: PermanentSignal) -> None:
+        """Connect a port of the instance to a signal.
+
+        Arguments:
+            port_name: The port being connected.
+            signal: The signal it is being connected to.
+        """
+        if port_name not in self.module.ports:
+            raise ValueError(f'Port {port_name} does not exist in module {self.module.name}')
+
+        self._port_connections[port_name] = signal  # Use signal name as key
+
+    def get_connected_signal(self, port_name: str) -> PermanentSignal:
+        """Returns the signal that is connected to the given port.
+
+        Arguments:
+            port_name (str): The port where the connected signal should be acquired
+        """
+
+        if port_name not in self.module.ports:
+            raise ValueError(f'Port {port_name} does not exist in module {self.module.name}')
+
+        return self._port_connections[port_name]
+
+    def override_parameter(self, name: str, value: Union[int, ParameterProto, Renderable]) -> None:
+        """Override a parameter of the instance.
+
+        Arguments:
+            name: Name of the parameter to be overridden.
+            value: New value for the parameter.
+        """
+        if name not in self.module.parameters:
+            raise ValueError(f'Parameter {name} does not exist in module {self.module.name}')
+
+        if isinstance(value, int):
+            self._parameter_overrides[name] = Const(value)
+        else:
+            self._parameter_overrides[name] = value