nortl 1.4.0__py3-none-any.whl

nortl/__init__.py

@@ -0,0 +1,85 @@
+"""noRTL Code Generation Engine."""
+
+from typing import Union
+
+from nortl import verilog_library
+from nortl.components import Channel, ElasticChannel, Timer
+from nortl.core import All, Any, Concat, Const, CoreEngine, IfThenElse, Var, Volatile
+from nortl.core.constructs import Condition, ElseCondition, Fork, ForLoop, WhileLoop
+from nortl.core.protocols import ParameterProto, Renderable
+
+__all__ = [
+    'All',
+    'Any',
+    'Concat',
+    'Const',
+    'CoreEngine',
+    'Engine',
+    'IfThenElse',
+    'Var',
+    'Volatile',
+]
+
+
+class ComponentsMixin(CoreEngine):
+    """Mixin class providing noRTL Components.
+
+    This allows easier access to the components, without needing to import them.
+    """
+
+    def create_channel(self, width: int, name: str = 'channel') -> Channel:
+        """Create a channel."""
+        return Channel(self, width, name=name)
+
+    def create_elastic_channel(self, width: int, name: str = 'channel') -> ElasticChannel:
+        """Create an elastic channel."""
+        return ElasticChannel(self, width, name=name)
+
+    def create_timer(self, width: Union[int, ParameterProto] = 16, instance_name_prefix: str = 'I_TIMER', clock_gating: bool = False) -> Timer:
+        """Create a timer."""
+        return Timer(self, width=width, instance_name_prefix=instance_name_prefix, clock_gating=clock_gating)
+
+
+class ConstructsMixin(CoreEngine):
+    """Mixin class providing noRTL Constructs.
+
+    This allows easier access to the flow control constructs, without needing to import them.
+    """
+
+    def condition(self, condition: Renderable) -> Condition:
+        """Adds a Condition."""
+        return Condition(self, condition)
+
+    def else_condition(self) -> ElseCondition:
+        """Adds a Else Condition."""
+        return ElseCondition(self)
+
+    def fork(self, threadname: str) -> Fork:
+        """Adds a Fork."""
+        return Fork(self, threadname)
+
+    def for_loop(
+        self, start: Union[Renderable, int], stop: Union[Renderable, int], step: Union[Renderable, int] = Const(1), counter_width: int = 16
+    ) -> ForLoop:
+        """Adds a For loop."""
+        return ForLoop(self, start, stop, step=step, counter_width=counter_width)
+
+    def while_loop(self, condition: Renderable) -> WhileLoop:
+        """Adds a While loop."""
+        return WhileLoop(self, condition)
+
+
+class Engine(ComponentsMixin, ConstructsMixin, CoreEngine):
+    """noRTL Engine."""
+
+    def __init__(self, module_name: str, reset_state_name: str = 'IDLE') -> None:
+        """Initialize a new noRTL Engine.
+
+        Arguments:
+            module_name: Name of the resulting SystemVerilog module.
+            reset_state_name: Default name for the reset state.
+        """
+        super().__init__(module_name, reset_state_name)
+
+        for module in verilog_library.get_modules():
+            self.add_module(module)

nortl/components/__init__.py

@@ -0,0 +1,8 @@
+from .channel import Channel, ElasticChannel
+from .timer import Timer
+
+__all__ = [
+    'Channel',
+    'ElasticChannel',
+    'Timer',
+]

nortl/components/channel.py

@@ -0,0 +1,132 @@
+import math
+from typing import List, Sequence
+
+from nortl.core import Concat, Const, IfThenElse, Volatile
+from nortl.core.operations import to_renderable
+from nortl.core.protocols import EngineProto, Renderable, ScratchSignalProto, SignalProto
+
+# FIXME: Create Abstract base class for Channel
+
+
+class Channel:
+    """A simple Channel with a ready/valid handshake to send data from one thread to another.
+
+    The send and rec functions realize a blocking transfer. This channel cannot be used for a elastic pipeline!
+    """
+
+    def __init__(self, engine: EngineProto, width: int, name: str = 'channel') -> None:
+        self.engine = engine
+        self.width = width
+
+        # FIXME validate if this channel already exists!
+        # Maybe turn into named entity
+
+        # All our signals cross the thread boundaries, so we have non-id rw access
+        self.ready = Volatile(self.engine.define_local(f'channel_{name}_ready', 1, 0), 'identical_rw')
+        self.valid = Volatile(self.engine.define_local(f'channel_{name}_valid', 1, 0), 'identical_rw')
+        self.data = Volatile(self.engine.define_local(f'channel_{name}_data', width, 0), 'identical_rw')
+
+    def send(self, data: Renderable | int) -> None:
+        """Sends the data over the channel to the target. The execution is blocked until the data has been received."""
+        tx_data = to_renderable(data)
+        self.engine.set(self.data, tx_data)
+        self.engine.set(self.valid, 1)
+        self.engine.wait_for(self.ready == 1)
+        self.engine.set(self.valid, 0)
+        self.engine.set(self.data, 0)
+        self.engine.sync()
+
+    def receive(self) -> ScratchSignalProto:
+        """Fetches a data item from the channel. The execution is blocked until the data has been received."""
+        target = self.engine.define_scratch(self.width)
+        self.engine.set(self.ready, 1)
+        self.engine.wait_for(self.valid == 1)
+        self.engine.set(target, self.data)
+        self.engine.set(self.ready, 0)
+        self.engine.sync()
+        return target
+
+
+class ElasticChannel:
+    """A Channel with a FIFO for rate matching."""
+
+    def __init__(self, engine: EngineProto, width: int, name: str = 'channel', depth: int = 16) -> None:
+        ptr_width = math.ceil(math.log2(depth))
+
+        if not ptr_width.is_integer():
+            # FIXME this does not work
+            raise ValueError('The depth of a FIFO in an ElasticChannel must be 2**N!')
+
+        self.name = name
+
+        self.engine = engine
+        self.width = width
+        self.depth = depth
+
+        self.read_ptr = Volatile(self.engine.define_local(f'channel_{name}_readctr', ptr_width, 0))
+        self.write_ptr = Volatile(self.engine.define_local(f'channel_{name}_writectr', ptr_width, 0))
+
+        self.level = ((Concat('0b0', self.write_ptr) + self.depth) - self.read_ptr) % self.depth
+
+        # Create data store
+        self.data: List[Volatile[SignalProto]] = []
+        for i in range(depth):
+            data_item = Volatile(self.engine.define_local(f'channel_{name}_data_{i}', width, 0))
+            self.data.append(data_item)
+
+    def send(self, data: Renderable | int) -> None:
+        """Sends the data over the channel to the target. The execution is blocked until the data has been sent."""
+        if isinstance(data, int):
+            tx_data: Renderable = Const(data, self.width)
+        else:
+            tx_data = to_renderable(data)
+
+        self.engine.wait_for(self.level < (self.depth - 2))
+
+        for i in range(self.depth):
+            self.engine.set(self.data[i], IfThenElse(self.write_ptr == i, tx_data, self.data[i]))
+
+        self.engine.set(self.write_ptr, self.write_ptr + 1)
+        self.engine.sync()
+
+    def send_multiple(self, data_lst: List[Renderable | int]) -> None:
+        """Sends several data items over the channel to the target. The execution is blocked until the data has been sent.
+
+        Note that the list order is MSB first!
+        """
+
+        if (length := len(data_lst)) > self.depth - 2:
+            raise RuntimeError('send_multiple expects the item list to be smaller than (Channel.depth - 2)!')
+
+        tx_data: Sequence[Renderable] = tuple(Const(item, self.width) if isinstance(item, int) else to_renderable(item) for item in data_lst)
+
+        self.engine.wait_for(self.level < (self.depth - 1 - length))
+
+        tmp_data: List[Renderable] = [i for i in self.data]
+
+        for j, item in enumerate(tx_data[::-1]):
+            for i in range(self.depth):
+                tmp_data[i] = IfThenElse(((self.write_ptr + j) % self.depth) == (i), item, tmp_data[i])
+
+        for i in range(self.depth):
+            self.engine.set(self.data[i], tmp_data[i])
+
+        self.engine.sync()
+        self.engine.set(self.write_ptr, self.write_ptr + length)
+
+        self.engine.sync()
+
+    def receive(self) -> ScratchSignalProto:
+        """Fetches a data item from the channel. The execution is blocked until the data has been received."""
+        target = self.engine.define_scratch(self.width)
+        self.engine.wait_for(self.level != 0)
+
+        res: Renderable = Const(0, self.width)
+
+        for i in range(self.depth):
+            res = IfThenElse(self.read_ptr == i, self.data[i], res)
+
+        self.engine.set(target, res)
+        self.engine.set(self.read_ptr, self.read_ptr + 1)
+        self.engine.sync()
+        return target

nortl/components/timer.py

@@ -0,0 +1,73 @@
+from typing import Union
+
+from nortl.core.protocols import EngineProto, ParameterProto, Renderable
+
+
+class Timer:
+    """This class represents a timer in the engine. It provides functions for operating the timer conveniently.
+
+    It depends on the availability of a verilog module `nortl_count_down_timer`
+    """
+
+    def __init__(
+        self, engine: EngineProto, width: Union[int, ParameterProto] = 16, instance_name_prefix: str = 'I_TIMER', clock_gating: bool = False
+    ) -> None:
+        """Initializes a timer object in the engine.
+
+        This function instantiates a (count-down) timer module in the engine and holds the signals for the delay, reload and finish / zero.
+
+        Arguments:
+            engine (CoreEngine): Target engine object
+            width (int): width of the counter register
+            instance_name_prefix (str): Prefix for the instance name used in verilog. This also prefixes the names of the connected signals
+            clock_gating (bool): If true, the unit is connected to the gated clock. If clock gating is disable, this setting is ignored.
+        """
+        self.engine = engine
+
+        timer_idx = 0
+        while (instance_name := f'{instance_name_prefix}_{timer_idx}') in engine.module_instances:
+            timer_idx = timer_idx + 1
+
+        self.instance_name = instance_name
+
+        self.timer_module = self.engine.create_module_instance('nortl_count_down_timer', self.instance_name, clock_gating)
+
+        self.engine.override_module_parameter(self.instance_name, 'DATA_WIDTH', width)
+
+        self.delay = self.engine.define_local(f'{self.instance_name}_delay', reset_value=0, width=width)  # Todo: Could be an async signal
+        self.reload = self.engine.define_local(f'{self.instance_name}_reload', reset_value=0)  # Todo: Could be an async signal
+        self.zero = self.engine.define_local(f'{self.instance_name}_zero')  # Todo: Could be an async signal
+
+        self.engine.connect_module_port(self.instance_name, 'DELAY', self.delay)
+        self.engine.connect_module_port(self.instance_name, 'RELOAD', self.reload)
+        self.engine.connect_module_port(self.instance_name, 'ZERO', self.zero)
+
+    def wait_delay(self, delay: Union[Renderable, int, bool]) -> None:
+        """Wait for a given delay without returning control to the engine. This can be seen as blocking delay.
+
+        Arguments:
+            delay (Renderable): Delay to wait for (in cycles)
+        """
+        self.start_delay(delay)
+        self.engine.wait_for(self.finished)
+
+    def start_delay(self, delay: Union[Renderable, int, bool]) -> None:
+        """Start the timer with a given delay. This acts as a non-blocking delay and therefore returns control after starting the timer.
+
+        Arguments:
+            delay (Renderable): Delay to wait for (in cycles)
+        """
+        self.engine.set(self.delay, delay)
+        self.engine.set(self.reload, 1)
+        self.engine.sync()
+        self.engine.set(self.reload, 0)
+        self.engine.sync()
+
+    @property
+    def finished(self) -> Renderable:
+        """Returns the signal (Renderable) that signals, if the timer has finished, i.e. the counter register is zero.
+
+        Returns:
+            Renderable: Zero-Flag of the counter
+        """
+        return self.zero

nortl/core/__init__.py

@@ -0,0 +1,40 @@
+from .engine import CoreEngine
+from .exceptions import (
+    ConflictingAssignmentError,
+    ExclusiveReadError,
+    ExclusiveWriteError,
+    ForbiddenAssignmentError,
+    NonIdenticalRWError,
+    OwnershipError,
+    TransitionLockError,
+    TransitionRestrictionError,
+    UnfinishedForwardDeclarationError,
+    WriteViolationError,
+)
+from .modifiers import Volatile
+from .operations import All, Any, Concat, Const, IfThenElse, Var
+from .parameter import Parameter
+from .signal import Signal
+
+__all__ = [
+    'All',
+    'Any',
+    'Concat',
+    'ConflictingAssignmentError',
+    'Const',
+    'CoreEngine',
+    'ExclusiveReadError',
+    'ExclusiveWriteError',
+    'ForbiddenAssignmentError',
+    'IfThenElse',
+    'NonIdenticalRWError',
+    'OwnershipError',
+    'Parameter',
+    'Signal',
+    'TransitionLockError',
+    'TransitionRestrictionError',
+    'UnfinishedForwardDeclarationError',
+    'Var',
+    'Volatile',
+    'WriteViolationError',
+]

nortl/core/checker.py

@@ -0,0 +1,135 @@
+from logging import getLogger
+from typing import Callable, ClassVar, Dict, List, Literal, Protocol, Set, Type
+from warnings import warn
+
+from .exceptions import ExclusiveReadError, ExclusiveWriteError, NonIdenticalRWError
+from .protocols import ACCESS_CHECKS, SIGNAL_ACCESS_CHECKS, StaticAccessProto
+
+__all__ = [
+    'StaticAccessChecker',
+    'set_severity_level',
+]
+
+logger = getLogger(__name__)
+
+
+T_SEVERITY_LEVEL = Literal['raise', 'warn', 'log', 'suppress']
+
+
+def set_severity_level(level: T_SEVERITY_LEVEL) -> None:
+    """Set severity level for noRTL access checks."""
+    BaseChecker.severity = level
+
+
+class AccessControlledSignal(Protocol):
+    """Minimal protocol for access controlled signals.
+
+    This supports both real signals and Volatile modifiers.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def read_accesses(self) -> Set[StaticAccessProto]: ...
+
+    @property
+    def write_accesses(self) -> Set[StaticAccessProto]: ...
+
+
+class BaseChecker:
+    """Baseclass for checkers."""
+
+    severity: ClassVar[T_SEVERITY_LEVEL] = 'raise'
+
+    @staticmethod
+    def throw(exception_type: Type[Exception], msg: str) -> None:
+        """Throw exception."""
+        match BaseChecker.severity:
+            case 'raise':
+                raise exception_type(msg)
+            case 'warn':
+                warn(msg, stacklevel=2)
+            case 'log':
+                logger.error(f'[{exception_type.__name__}] {msg}', stacklevel=2, stack_info=True)
+
+
+class StaticAccessChecker(BaseChecker):
+    """Static access checker for signals."""
+
+    # FIXME: Adapt traceback of the checks to show position in the actual user-code where the exception happened
+
+    def __init__(self, signal: AccessControlledSignal) -> None:
+        self.signal = signal
+        self.enabled_checks: List[SIGNAL_ACCESS_CHECKS] = ['exclusive_read', 'exclusive_write', 'identical_rw']
+        self._cached_reading_thread_names: Set[str] = set()
+        self._cached_writing_thread_names: Set[str] = set()
+
+        self.check_mapping: Dict[ACCESS_CHECKS, Callable[[], None]] = {
+            'exclusive_read': self.check_exclusive_read,
+            'exclusive_write': self.check_exclusive_write,
+            'identical_rw': self.check_identical_rw,
+        }
+
+    @property
+    def reading_thread_names(self) -> Set[str]:
+        if len(self._cached_reading_thread_names) != 0:
+            return self._cached_reading_thread_names
+
+        threadnames: Set[str] = set()
+        for access in self.signal.read_accesses:
+            if access.active and access.thread.running:
+                threadnames.add(f'{access.thread.worker.name}.{access.thread.name}')
+
+        self._cached_reading_thread_names = threadnames
+
+        return threadnames
+
+    @property
+    def writing_thread_names(self) -> Set[str]:
+        if len(self._cached_writing_thread_names) != 0:
+            return self._cached_writing_thread_names
+
+        threadnames: Set[str] = set()
+        for access in self.signal.write_accesses:
+            if access.active and access.thread.running:
+                threadnames.add(f'{access.thread.worker.name}.{access.thread.name}')
+
+        self._cached_writing_thread_names = threadnames
+
+        return threadnames
+
+    def disable_check(self, check: SIGNAL_ACCESS_CHECKS) -> None:
+        self.enabled_checks.remove(check)
+
+    def check(self, ignore: Set[ACCESS_CHECKS] = set()) -> None:
+        """This function executes all checks and raises errors, if needed."""
+
+        # Clear out caches
+        self._cached_reading_thread_names = set()
+        self._cached_writing_thread_names = set()
+
+        # Actual Check
+        for check in self.enabled_checks:
+            if check not in ignore:
+                self.check_mapping[check]()
+
+    def check_exclusive_read(self) -> None:
+        if len(self.reading_thread_names) > 1:
+            self.throw(
+                ExclusiveReadError, f'Signal {self.signal} has been read by more than one thread! Reading Threads: {self.reading_thread_names}'
+            )
+
+    def check_exclusive_write(self) -> None:
+        if len(self.writing_thread_names) > 1:
+            self.throw(
+                ExclusiveWriteError, f'Signal {self.signal} has been written by more than one thread! Writing Threads: {self.writing_thread_names}'
+            )
+
+    def check_identical_rw(self) -> None:
+        if len(self.writing_thread_names) == 0 or len(self.reading_thread_names) == 0:
+            pass
+        elif self.writing_thread_names != self.reading_thread_names:
+            self.throw(
+                NonIdenticalRWError, f'Signal {self.signal} has been written by {self.writing_thread_names} and read by {self.reading_thread_names}.'
+            )

nortl/core/common/__init__.py

@@ -0,0 +1,4 @@
+from .access import StaticAccess
+from .naming_helper import NamedEntity
+
+__all__ = ['NamedEntity', 'StaticAccess']

nortl/core/common/access.py

@@ -0,0 +1,25 @@
+from nortl.core.protocols import ThreadProto
+
+from .debug import DebugEntity
+
+
+class StaticAccess(DebugEntity):
+    """Model for an access to a signal.
+
+    This class is used as a container to hold references to the thread that caused the access and information about what caused the access where in the code.
+    The signal object can then hold a list (or deque) of accesses for executing checks for e.g. two parallel-running threads accessing the register.
+
+    Note that this does not include checks like access counters that verify,
+    that the number of reads is equal to the number of writes so that no data gets lost.
+    This structure is only used for detecting concurrent accesses at assemble-time of the noRTL engine (where the code assembles the internal noRTL engine model).
+    Realizing access counters is a task to be performed at other levels of abstraction, e.g. in the rendered Verilog code where also formal properties
+    can be included for verification in simulation.
+    """
+
+    def __init__(self, thread: ThreadProto) -> None:
+        super().__init__()
+        self.thread = thread
+        self.active = True
+
+    def disable(self) -> None:
+        self.active = False

nortl/core/common/debug.py

@@ -0,0 +1,6 @@
+import inspect
+
+
+class DebugEntity:
+    def __init__(self) -> None:
+        self.debug_stack = inspect.trace()

nortl/core/common/naming_helper.py

@@ -0,0 +1,33 @@
+from typing import Any, Dict
+
+from .debug import DebugEntity
+
+
+class NamedEntity(DebugEntity):
+    """Model a named something in Verilog and implement the feature to add metadata.
+
+    This class will (in future) ensure that there are no naming collisions since all names of verilog objects will be stored here.
+    To add traceability, this class inherits from DebugEntity that stores the current execution trace.
+    """
+
+    def __init__(self, name: str) -> None:
+        super().__init__()
+        self._metadata: Dict[str, Any] = {}
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """Just return name."""
+        return self._name
+
+    def get_metadata(self, key: str, default: Any = None) -> Any:
+        """Get metadata item."""
+        return self._metadata.get(key, default)
+
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set metadata item."""
+        self._metadata[key] = value
+
+    def has_metadata(self, key: str) -> bool:
+        """Test if a certain key is present in metadata."""
+        return key in self._metadata

nortl/core/constructs/__init__.py

@@ -0,0 +1,13 @@
+"""This module will contain helpers for writing sub-engines and wrapping existing functions outside of the core."""
+
+from .condition import Condition, ElseCondition
+from .fork_join import Fork
+from .loop import ForLoop, WhileLoop
+
+__all__ = [
+    'Condition',
+    'ElseCondition',
+    'ForLoop',
+    'Fork',
+    'WhileLoop',
+]