nortl 1.4.0__py3-none-any.whl

nortl/core/constructs/condition.py

@@ -0,0 +1,143 @@
+from types import TracebackType
+
+from nortl.core import Const
+from nortl.core.protocols import EngineProto, Renderable
+from nortl.core.state import State
+
+__all__ = [
+    'Condition',
+    'ElseCondition',
+]
+
+
+class Condition:
+    """Context manager to realize an if-then-else behavior within a noRTL engine."""
+
+    final_state_key: str = 'Condition.start_state'
+
+    def __init__(self, engine: EngineProto, condition: Renderable):
+        """Initializes the Condition context manager.
+
+        The state management is as follows:
+
+        *  If we are realizing the first conditional in a state, we need to create a final-state where the engine should be after executing the conditional code.
+            * This final-state is stored in the metadata of the current state (and will be reused if another conditional is added)
+            * The final-state also has the start state in its meta-data -- if another condition is to be added,
+              it should start from the same initial state as the first conditional.
+            * After the conditional has been executed, the engine is placed in the final state
+        * If we get to realize the second conditional, we recognize that from the metadata of the current state
+            * The start and final state are adapted to resemble the behavior of the first conditional
+
+        The Context manager can be used as follows:
+        ```python
+        from nortl.core import CoreEngine
+        from nortl.utils.context_manager import Condition
+
+        f = CoreEngine('my_engine')
+        in_signal = f.define_input('IN')
+
+        # Example usage:
+        # <= We start at a start_state
+        with Condition(f, in_signal == 1):
+            f.sync()
+            f.do_something()
+            # At the end, the engine goes to an inferred final_state
+
+        with Condition(f, in_signal == 0):
+            #The context manager again starts from the same start_state as before
+            f.sync()
+            f.do_something_else()
+            # At the end, the engine goes to an inferred final_state
+
+        # We proceed execution from the final_state
+
+        # When no further conditions are expected, an f.sync() creates a new state and breaks the chain-of-conditionals.
+
+        ```
+
+        Arguments:
+            engine: The CoreEngine instance.
+            condition: A Renderable signal representing the condition to evaluate.
+        """
+        self.engine = engine
+        self.condition = condition
+
+        if self.engine.current_state.has_metadata(self.final_state_key):
+            self.start_state = self.engine.current_state.get_metadata(self.final_state_key)
+            self.final_state = self.engine.current_state
+            self.engine.current_state = self.start_state
+        else:
+            self.start_state = self.engine.current_state
+            self.final_state = engine.create_state()
+            self.final_state.set_metadata(self.final_state_key, self.start_state)
+
+    def __enter__(self) -> None:
+        """Executes the provided function if the condition is met."""
+        conditional_state = self.engine.create_state()
+        self.engine.jump_if(self.condition, conditional_state)
+        self.engine.current_state = conditional_state
+
+        # TODO consider moving this into the engine itself
+        self.engine.scratch_manager.enter_context()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        jumpconds = [t[0] for t in self.engine.current_state.transitions]
+        if Const(1) not in jumpconds:
+            self.engine.jump_if(Const(1), self.final_state)
+        self.engine.current_state = self.final_state
+
+        self.engine.scratch_manager.exit_context()
+
+
+def get_else_condition(state: State) -> Renderable:
+    conditions = [c for c, _ in state.transitions]
+    ret: Renderable = Const(1)
+
+    for c in conditions:
+        ret = ret & ~c
+
+    return ret
+
+
+class ElseCondition(Condition):
+    """Context manager to realize an else behavior within a noRTL engine.
+
+    Usage example:
+
+        from nortl.core import CoreEngine
+        from nortl.utils.context_manager import Condition, ElseCondition
+
+        f = CoreEngine('my_engine')
+        in_signal = f.define_input('IN')
+
+        with Condition(f, in_signal == 1):
+            f.sync()
+            f.do_something()
+        with Condition(f, possible_second_condition):
+            f.sync()
+            f.do_something()
+
+        with ElseCondition(f):
+            f.do_something_else()
+
+
+    """
+
+    def __init__(self, engine: EngineProto):
+        state = engine.current_state.get_metadata(self.final_state_key)
+        condition = get_else_condition(state)
+        super().__init__(engine, condition)
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        super().__exit__(exc_type, exc_val, exc_tb)
+        self.engine.sync()

nortl/core/constructs/fork_join.py

@@ -0,0 +1,84 @@
+from types import TracebackType
+from typing import List
+
+from nortl.core.constructs import Condition
+from nortl.core.protocols import EngineProto, ThreadProto, WorkerProto
+
+__all__ = [
+    'Fork',
+]
+
+
+class Fork:
+    """Context manager to realize a Fork."""
+
+    def __init__(self, engine: EngineProto, threadname: str):
+        """Initializes the Fork context manager.
+
+        Arguments:
+            engine: The CoreEngine instance.
+            threadname: Name of the new thread, optional
+        """
+        self.engine = engine
+        self.threadname = threadname
+
+        self.checkpoint_worker = self.engine.current_worker
+        self.checkpoint_state = self.engine.current_state
+
+        free_workers: List[WorkerProto] = [w for w in self.engine.workers.values() if not w.working]
+
+        if free_workers == []:
+            self.assigned_worker = self.engine.create_worker()
+        else:
+            self.assigned_worker = free_workers[0]
+
+        self.new_thread = self.assigned_worker.create_thread(self.threadname)
+
+        self.engine.current_worker = self.assigned_worker
+
+    def __enter__(self) -> ThreadProto:
+        """Create a new thread and integrate it into next free worker (or create a new worker)."""
+
+        self.engine.current_state = self.assigned_worker.reset_state
+
+        condition = Condition(self.engine, self.assigned_worker.start & (self.assigned_worker.select == len(self.assigned_worker.threads)))
+
+        with condition:
+            state_within_condition = self.engine.current_state
+            self.engine.set(self.assigned_worker.idle, 0)
+
+        for worker in self.engine.workers.values():
+            if worker is self.checkpoint_worker:
+                spawning_worker = worker
+
+        spawning_thread = spawning_worker.threads[-1]
+        spawning_thread._spawned_threads.append(self.new_thread)
+
+        # Adjust signal accesses
+        self.engine.signal_manager.free_accesses_from_thread(spawning_thread)
+        self.engine.scratch_manager.free_accesses_from_thread(spawning_thread)
+
+        self.engine.current_state = state_within_condition
+
+        self.engine.sync()
+
+        self.new_thread.active = True
+
+        return self.new_thread
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.engine.sync()
+        self.new_thread.finish()
+
+        self.engine.current_worker = self.checkpoint_worker
+        self.engine.current_state = self.checkpoint_state
+
+        # Now the thread has been rendered and so we start the Worker!
+        self.engine.set(self.assigned_worker.start, 1)
+        self.engine.set(self.assigned_worker.select, (len(self.assigned_worker.threads)))
+        self.engine.sync()

nortl/core/constructs/loop.py

@@ -0,0 +1,138 @@
+from types import TracebackType
+
+from nortl.core import Const
+from nortl.core.operations import to_renderable
+from nortl.core.protocols import EngineProto, Renderable, StateProto
+
+__all__ = [
+    'ForLoop',
+    'WhileLoop',
+]
+
+
+class ForLoop:
+    """Context manager to realize a for-loop within a noRTL engine."""
+
+    def __init__(
+        self, engine: EngineProto, start: Renderable | int, stop: Renderable | int, step: Renderable | int = 1, counter_width: int = 16
+    ) -> None:
+        """Initializes the ForLoop context manager.
+
+        Its intention is to emulate the behavior of a for loop in a engine.
+
+        Example:
+        ```python
+        engine = CoreEngine("my_engine")
+        out = engine.define_output("test_output", width=8)
+
+        with ForLoop(engine, 0, 100, 2) as i:
+            # code that should be run multiple times
+            engine.set(out, i)
+        ```
+
+        The context manager cares about the realization of the counter variable and returns it to be used in the loop.
+        This means, multiple (non-colliding) loops may use the same count registers.
+
+        As in other programming languages: Only modify the counter variable within the loop if you really know, what you do.
+        Generally, it is a very bad idea to write to the loop variable.
+
+        Arguments:
+            engine: The CoreEngine instance.
+            start: A signal or int representing the start value of the loop counter
+            stop: A signal or int representing the final value of the loop counter. The value is non-inclusive.
+            step: A signal or int representing the step value of the counter (default: 1)
+            counter_width: Width of the counter variable (default: 16). The counter width must fit the stop value.
+        """
+        self.engine = engine
+        self.start = to_renderable(start)
+        self.stop = to_renderable(stop)
+        self.step = to_renderable(step)
+
+        self.start_state = engine.current_state
+        self.final_state = engine.create_state()
+
+        # TODO Validate start and stop values against counter_width, if possible
+        # FIXME width must be 1 bit wider than the actual counter!
+        self.counter = self.engine.define_scratch(counter_width)
+        self.counter_nxt = self.counter + self.step
+
+    def __enter__(self) -> Renderable:
+        """Executes the provided function if the condition is met."""
+        self.engine.set(self.counter, self.start)
+        self.engine.sync()
+        self.start_state = self.engine.current_state
+
+        other_state = self.engine.create_state()
+
+        self.engine.jump_if(self.counter == self.stop, self.final_state, other_state)
+
+        self.engine.current_state = other_state
+
+        # TODO consider moving this into the engine itself
+        self.engine.scratch_manager.enter_context()
+
+        return self.counter
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.engine.sync()
+        self.engine.set(self.counter, self.counter_nxt)
+        self.engine.jump_if(Const(1), self.start_state)
+
+        # Goto final state
+        self.engine.current_state = self.final_state
+
+        self.engine.scratch_manager.exit_context()
+        self.counter.release()
+
+        self.engine.sync()
+
+
+class WhileLoop:
+    """Context manager to realize a While loop within a noRTL engine."""
+
+    def __init__(self, engine: EngineProto, condition: Renderable) -> None:
+        """Initializes a While construct.
+
+        Arguments:
+            engine: The CoreEngine instance.
+            condition: The condition of the while loop.
+        """
+        self.engine = engine
+        self.condition = to_renderable(condition)
+
+        self.start_state: StateProto
+        self.final_state: StateProto
+
+    def __enter__(self) -> None:
+        self.start_state = self.engine.current_state
+        self.final_state = self.engine.create_state()
+
+        # Add conditional jump to start state
+        self.engine.jump_if(self.condition, self.engine.next_state, self.final_state)
+
+        # Switch to loop content and yield back
+        self.engine.current_state = self.engine.next_state
+
+        # TODO consider moving this into the engine itself
+        self.engine.scratch_manager.enter_context()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if len(self.engine.current_state.transitions) > 0:
+            raise RuntimeError('Last state in a While loop must not have any outgoing transitions!')
+
+        self.engine.jump_if(Const(1), self.start_state)
+
+        # Goto final state
+        self.engine.current_state = self.final_state
+
+        self.engine.scratch_manager.exit_context()