nortl 1.4.0__py3-none-any.whl

nortl/renderer/verilog_utils/process.py

@@ -0,0 +1,226 @@
+from collections import deque
+from typing import Deque, Dict, List, Literal, Optional, Tuple, Union
+
+from .utils import VerilogRenderable, to_verilog_renderable
+
+
+class VerilogAssignment:
+    def __init__(self, tgt: Union[str, VerilogRenderable], src: Union[str, VerilogRenderable]) -> None:
+        self.tgt = to_verilog_renderable(tgt)
+        self.src = to_verilog_renderable(src)
+        self.operator = '<='
+
+    def render(self) -> str:
+        return f'{self.tgt} {self.operator} {self.src};'
+
+
+class VerilogBlock:
+    def __init__(self) -> None:
+        self.items: Deque[VerilogRenderable] = deque([])
+
+    def render(self) -> str:
+        content: List[str] = ['begin']
+        content.append(self.render_items())
+        content.append('end')
+
+        return '\n'.join(content)
+
+    def render_items(self) -> str:
+        content: List[str] = []
+        content.extend(item.render() for item in self.items)
+        return '\n'.join(content)
+
+    def add(self, item: VerilogRenderable) -> None:
+        self.items.append(item)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+
+class VerilogCase:
+    def __init__(self, tgt_signal: str) -> None:
+        self.tgt_signal = tgt_signal
+        self.cases: Dict[str, VerilogBlock] = {}
+        self.compress_output = True
+
+    def add_case(self, value: str, block: Optional[VerilogBlock] = None) -> None:
+        if block is None:
+            self.cases[value] = VerilogBlock()
+        else:
+            self.cases[value] = block
+
+    def add_item(self, case: str, item: VerilogRenderable) -> None:
+        if case not in self.cases:
+            self.add_case(case)
+
+        self.cases[case].add(item)
+
+    def compress_cases(self) -> Dict[str, str]:
+        new_cases: Dict[str, str] = {}
+
+        for case, block in self.cases.items():
+            if len(block) != 0:
+                old_case = ''
+                new_block = block.render()
+
+                for existing_case, existing_block in new_cases.items():
+                    if existing_block == new_block:
+                        old_case = existing_case
+
+                if old_case == '':
+                    new_cases[case] = new_block
+                else:
+                    del new_cases[old_case]
+                    new_cases[f'{case}, {old_case}'] = new_block
+
+        return new_cases
+
+    def render(self) -> str:
+        content: List[str] = []
+
+        if all(len(block) == 0 for block in self.cases.values()):
+            return ''
+
+        content.append(f'case ({self.tgt_signal})')
+
+        if self.compress_output:
+            for case, block in self.compress_cases().items():
+                content.append(f'{case}: {block}')
+        else:
+            for case, vblock in self.cases.items():
+                if len(vblock) != 0:
+                    content.append(f'{case}: {vblock.render()}')
+
+        content.append('endcase')
+
+        return '\n'.join(content)
+
+
+class VerilogIf:
+    def __init__(self, condition: Union[VerilogRenderable, str]) -> None:
+        self.condition: VerilogRenderable = to_verilog_renderable(condition)
+        self.true_branch = VerilogBlock()
+        self.false_branch = VerilogBlock()
+
+    def render(self) -> str:
+        if self.condition.render() == '1':
+            return self.true_branch.render_items()
+
+        content = [f'if ({self.condition})']
+        content.append(self.true_branch.render())
+
+        if len(self.false_branch) > 0:
+            content.append('else ')
+            content.append(self.false_branch.render())
+
+        return '\n'.join(content)
+
+
+class VerilogProcess:
+    def __init__(self) -> None:
+        self.sensitivity: List[Tuple[Literal['posedge', 'negedge'], VerilogRenderable]] = []
+        self.content = VerilogBlock()
+        self.render_sensitivity = True
+        self.block_label = 'always'
+
+    def _add(self, item: VerilogRenderable) -> None:
+        self.content.add(item)
+
+    def add_sensitivity(self, edge: Literal['posedge', 'negedge'], signal: VerilogRenderable) -> None:
+        self.sensitivity.append((edge, signal))
+
+    def render(self) -> str:
+        content = []
+
+        line = f'{self.block_label}'
+
+        if self.render_sensitivity:
+            if self.sensitivity == []:
+                line = f'{line} @(*)'
+            else:
+                sens_lst = []
+                for edge, signal in self.sensitivity:
+                    sens_lst.append(f'{edge} {signal}')
+                line = f'{line} @({" or ".join(sens_lst)})'
+
+        content.append(line)
+
+        content.append(self.content.render())
+
+        return '\n'.join(content)
+
+
+class AlwaysFF(VerilogProcess):
+    def __init__(self, clk: Union[VerilogRenderable, str], reset: Union[VerilogRenderable, str]) -> None:
+        super().__init__()
+        self.clk = clk
+        self.reset = reset
+
+        self.behavior = VerilogIf(to_verilog_renderable(reset))
+        self._add(self.behavior)
+
+        self.block_label = 'always_ff'
+
+    def add_reset(self, item: VerilogRenderable) -> None:
+        self.behavior.true_branch.add(item)
+
+    def add(self, item: VerilogRenderable) -> None:
+        self.behavior.false_branch.add(item)
+
+    def render(self) -> str:
+        self.add_sensitivity('posedge', to_verilog_renderable(self.clk))
+        self.add_sensitivity('posedge', to_verilog_renderable(self.reset))
+
+        return super().render()
+
+
+class AlwaysComb(VerilogProcess):
+    def __init__(self) -> None:
+        super().__init__()
+        self.block_label = 'always_comb'
+        self.render_sensitivity = False
+
+    def add(self, item: VerilogRenderable) -> None:
+        self._add(item)
+
+
+class AlwaysLatch(VerilogProcess):
+    def __init__(self, latch_en: VerilogRenderable) -> None:
+        super().__init__()
+
+        self.behavior = VerilogIf(latch_en)
+        self._add(self.behavior)
+
+        self.block_label = 'always_latch'
+        self.render_sensitivity = False
+
+    def add(self, item: VerilogRenderable) -> None:
+        self.behavior.true_branch.add(item)
+
+
+class VerilogPrint:
+    def __init__(self, line: str, *args: str) -> None:
+        self.line = line
+        self.args = args
+
+    def render(self) -> str:
+        line = f'$display("{self.line}", {",".join(self.args)});'
+        return line
+
+
+class VerilogPrintf:
+    def __init__(self, fname: str, line: str, *args: str) -> None:
+        self.fname = fname
+        self.line = line
+        self.args = args
+
+    def render(self) -> str:
+        ret = []
+        ret.append('begin')
+        ret.append('int fd;')
+        ret.append(f'fd = $fopen({self.fname}, "w+");')
+        ret.append(f'$fdisplay("{self.line}", {",".join(self.args)});')
+        ret.append('$fclose(fd);')
+        ret.append('end')
+
+        return '\n'.join(ret)

nortl/renderer/verilog_utils/structural.py

@@ -0,0 +1,146 @@
+from typing import Dict, List, Optional, Union
+
+from .formatter import VerilogFormatter
+from .utils import VerilogRenderable
+
+
+class VerilogDeclaration:
+    def __init__(
+        self,
+        verilog_type: str,
+        name: Union[str, List[str]],
+        width: Union[int, str, VerilogRenderable] = 0,
+        connections: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, str]] = None,
+        members: Optional[Union[List[str], Dict[str, int]]] = None,
+    ):
+        self.verilog_type = verilog_type
+        self.name = name
+        self.connections = connections
+        self.params = params
+        self.members = members
+        self.width = width
+
+    def add_member(self, name: str, value: Optional[Union[int]] = None) -> None:
+        if self.members is None:
+            if value is not None:
+                self.members = {}
+            else:
+                self.members = []
+
+        if isinstance(self.members, list):
+            if value is not None:
+                raise RuntimeError('Cannot add an encoded member to an enum without all items to be encoded!')
+            self.members.append(name)
+        else:
+            if value is None:
+                raise RuntimeError('Cannot add an un-encoded member to an enum where all items are encoded!')
+            self.members[name] = value
+
+    def add_parameter(self, name: str, value: Union[str, int]) -> None:
+        if self.params is None:
+            self.params = {}
+
+        if isinstance(value, int):
+            self.params[name] = str(value)
+        else:
+            self.params[name] = value
+
+    def add_connection(self, src: str, tgt: str) -> None:
+        if self.connections is None:
+            self.connections = {}
+
+        self.connections[src] = tgt
+
+    def render(self) -> str:  # noqa: C901
+        content: List[str] = []
+        connection_lst = []
+        param_lst = []
+
+        if self.connections is not None:
+            connection_lst = [f'.{x}({y})' for x, y in self.connections.items()]
+        if self.params is not None:
+            param_lst = [f'.{x}({y})' for x, y in self.params.items()]
+
+        name_str = ''
+
+        content.append(self.verilog_type)
+
+        if isinstance(self.name, list):
+            name_str = ', '.join(self.name)
+        else:
+            name_str = self.name
+
+        if isinstance(self.width, int):
+            if self.width > 1:
+                content.append(f'[{self.width - 1}:0]')
+        else:
+            content.append(f'[{self.width}-1:0]')
+
+        if self.verilog_type.startswith('enum'):
+            if self.members is None:
+                raise RuntimeError(f'Tried to create enum {name_str} without any values. Something is wrong here.')
+
+            if isinstance(self.members, List):
+                item_str = ', '.join(self.members)
+            else:
+                item_str = ', '.join([f'{item} = {value}' for item, value in self.members.items()])
+
+            content.append(f'{{{item_str}}}')
+
+        if self.params is not None:
+            content.append(f'#({", ".join(param_lst)})')
+
+        content.append(name_str)
+
+        if not any(t in self.verilog_type for t in ['wire', 'logic', 'reg']) and not self.verilog_type.startswith(
+            'enum'
+        ):  # other net types are out of scope for now
+            content.append(f'({", ".join(connection_lst)})')
+
+        return ' '.join(content)
+
+
+class VerilogModule:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.ports: List[VerilogDeclaration] = []
+        self.parameters: Dict[str, Optional[Union[int, str]]] = {}
+        self.signals: List[VerilogDeclaration] = []
+        self.instances: List[VerilogDeclaration] = []
+        self.functionals: List[VerilogRenderable] = []
+
+    def render(self) -> str:
+        content = []
+        line = f'module {self.name} '
+
+        if len(self.parameters) != 0:
+            params = []
+            for p, val in self.parameters.items():
+                if val is None:
+                    params.append(f'parameter {p}')
+                else:
+                    params.append(f'parameter {p} = {val}')
+
+            line = f'{line} #(\n{",\n".join(params)}) '
+
+        ports = [p.render() for p in self.ports]
+
+        line = f'{line} ({",\n".join(ports)});'
+
+        content.append(line)
+
+        content.extend([item.render() + ';' for item in self.signals + self.instances])
+        content.extend([item.render() for item in self.functionals])
+
+        content.append('endmodule')
+
+        code = '\n'.join(content)
+
+        return VerilogFormatter(code).format()
+
+    def get_instance(self, name: str) -> VerilogDeclaration:
+        for item in self.instances:
+            if item.name == name:
+                return item
+        raise RuntimeError(f'Could not find an instance named {name}.')

nortl/renderer/verilog_utils/utils.py

@@ -0,0 +1,23 @@
+from typing import Protocol, Union
+
+from nortl.core.operations import RawText
+
+
+class VerilogRenderable(Protocol):
+    """Protocol for Verilog Renderable.
+
+    Compared to the [nortl.core.Renderable][nortl.core.operations.Renderable], it doesn't require the [OperationTrait Mixin][nortl.core.operations.OperationTrait] and `target` argument for `render()`.
+    """
+
+    def render(self) -> str: ...
+
+
+def to_verilog_renderable(value: Union[str, VerilogRenderable]) -> VerilogRenderable:
+    """Convert value to Verilog Renderable.
+
+    Compared to [nortl.core.to_renderable][nortl.core.operations.to_renderable], this also supports strings.
+    """
+    if isinstance(value, str):
+        return RawText(value)
+    else:
+        return value

nortl/utils/parse_utils.py

@@ -0,0 +1,37 @@
+from typing import Optional, Tuple
+
+__all__ = [
+    'parse_int',
+]
+
+
+def parse_int(string: str) -> Tuple[int, Optional[int]]:
+    """Parses an integer from a string.
+
+    For numbers in binary, octal or hexadecimal representation, it infers the width.
+
+    Arguments:
+        string: Integer value as a string.
+
+    Returns:
+        Tuple of the value and inferred width.
+    """
+
+    try:
+        # Parse binary, octal or hexadecimal number
+        if string.startswith('0b'):
+            value = int(string, 2)
+            width = len(string.split('0b', maxsplit=1)[1])
+        elif string.startswith('0o'):
+            value = int(string, 8)
+            width = len(string.split('0o', maxsplit=1)[1]) * 3
+        elif string.startswith('0x'):
+            value = int(string, 16)
+            width = len(string.split('0x', maxsplit=1)[1]) * 4
+        else:
+            value = int(string)
+            width = None
+    except ValueError:
+        raise ValueError(f"Unable to create Const from '{string}', failed to convert it to integer.")
+
+    return value, width

nortl/utils/templates/testbench.sv

@@ -0,0 +1,41 @@
+module testbench();
+
+logic CLK, RST;
+
+initial begin
+    CLK = 0;
+    while(1)
+    begin
+        #(10);
+        CLK = ~CLK;
+    end
+end
+
+logic finish, passed, timeout;
+
+my_engine DUT(
+    .RST_ASYNC_I(RST),
+    .CLK_I(CLK),
+    .timeout(timeout),
+    .passed(passed),
+    .finish(finish)
+);
+
+initial begin
+    RST = 1;
+    #(100);
+    RST = 0;
+
+    @(posedge finish);
+
+    // variable dump section
+
+    $display("timeout=%d;\n", timeout);
+    $display("errors=%d;\n", DUT.error_ctr);
+    $display("passed=%d;\n", passed);
+
+    $finish();
+end
+
+
+endmodule

nortl/utils/test_wrapper.py

@@ -0,0 +1,218 @@
+import re
+import subprocess
+from abc import ABC, abstractmethod
+from inspect import currentframe, getframeinfo
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import FrameType
+
+import pytest
+
+from nortl.core import CoreEngine
+from nortl.core.constructs import Condition, ElseCondition, Fork
+from nortl.core.modifiers import UnregisteredRead
+from nortl.core.operations import to_renderable
+from nortl.core.protocols import Renderable
+from nortl.renderer.verilog_renderer import VerilogRenderer
+
+
+class NoRTLTestBase(ABC):
+    """Base class for noRTL tests with Verilog simulation.
+
+    Subclasses must implement:
+        - build_engine(): Create and configure the engine to be tested
+        - generate_testbench(): Generate the Verilog testbench file
+
+    The simulation is automatically run before each test method.
+    Test methods can access:
+        - self.engine: The engine instance
+        - self.simulation_result: The subprocess result from simulation
+        - self.simulation_output: Parsed simulation output (string)
+    """
+
+    @abstractmethod
+    def init_sequence(self) -> CoreEngine:
+        """This function must initialize the engine that is to be tested. In the most trivial case, this means, that an instance of CoreEngine is created.
+
+        Returns:
+            CoreEngine: Initialized engine
+        """
+        pass
+
+    def verify_final_state(self, engine: CoreEngine) -> None:
+        """This state-sequence is called after the dut and testbench threads have ended. It can be used to verify the final state of the dut."""
+        pass
+
+    def the_testbench(self, engine: CoreEngine) -> None:
+        """The state sequence that is run in parallel to the engine-under-Test. This may use the self.assert* functions to verify the behavior.
+
+        Arguments:
+            engine (CoreEngine): engine instance
+        """
+        pass
+
+    @abstractmethod
+    def dut(self, engine: CoreEngine) -> None:
+        """The dut function is the state sequence that is to be tested. It is executed in parallel to the testbench.
+
+        A call to self.assert* is not forbidden but not advised to create a good seperation between dut and test code.
+        """
+        pass
+
+    def get_test_engine(self) -> CoreEngine:
+        self.engine = self.init_sequence()
+
+        self.finish_flag = self.engine.define_output('finish', 1, 0)
+        self.state_flag = self.engine.define_output('passed', 1, 0)
+        self.error_ctr = self.engine.define_local('error_ctr', 16, 0)
+        self.timeout = self.engine.define_output('timeout', 1, 0)
+        ctr = self.engine.define_local('timeout_ctr', 16, 0)
+
+        self.engine.sync()
+
+        # FIXME: Introduce Timeout-timer
+        with Fork(self.engine, 'DUT') as t_dut:
+            self.dut(self.engine)
+        with Fork(self.engine, 'testbench') as t_tb:
+            self.the_testbench(self.engine)
+        with Fork(self.engine, 'timeout') as t_timeout:
+            self.engine.sync()
+            self.engine.set(ctr, ctr + 1)
+            with Condition(self.engine, ctr == 0xFFFF):
+                self.engine.set(self.timeout, 1)
+                t_timeout.finish()
+
+        self.engine.sync()
+
+        self.engine.wait_for((t_dut.finished & t_tb.finished) | t_timeout.finished)
+
+        with Condition(self.engine, t_timeout.finished):
+            t_dut.cancel()
+            t_tb.cancel()
+            if not hasattr(self, 'expect_timeout'):
+                self.assertTrue(0)  # Show that we had a timeout
+            else:
+                self.assertTrue(self.expect_timeout)
+        with ElseCondition(self.engine):
+            t_timeout.cancel()
+
+        self.verify_final_state(self.engine)
+
+        self.engine.sync()
+
+        self.finish_simulation()
+
+        return self.engine
+
+    def increment_error_ctr(self) -> None:
+        self.engine.sync()
+
+        with Condition(self.engine, self.error_ctr != 0xFFFF):
+            self.engine.set(self.error_ctr, self.error_ctr + 1)
+        with ElseCondition(self.engine):
+            pass
+
+        self.engine.sync()
+
+    def finish_simulation(self) -> None:
+        self.engine.sync()
+
+        with Condition(self.engine, self.error_ctr == 0):
+            self.engine.set(self.state_flag, 1)
+        with ElseCondition(self.engine):
+            self.engine.set(self.state_flag, 0)
+
+        self.engine.set(self.finish_flag, 1)
+        self.engine.sync()
+
+    def print_line(self, frame: FrameType) -> None:
+        fi = getframeinfo(frame)
+        if fi.code_context is None:
+            return
+        code_context = fi.code_context[0]
+        code_context = re.sub('#.*', '', code_context)
+        code_context = code_context.lstrip().rstrip()
+        self.engine.print(f'Assertion \\"{code_context}\\" failed at {fi.filename}:{frame.f_lineno}')
+
+    def assertTrue(self, condition: Renderable | int) -> None:  # noqa: N802
+        with Condition(self.engine, UnregisteredRead(~to_renderable(condition))):
+            frame = currentframe()
+            if frame is not None:
+                frame = frame.f_back
+                if frame is not None:
+                    self.print_line(frame)
+            self.increment_error_ctr()
+            self.finish_simulation()
+        with ElseCondition(self.engine):
+            pass
+        self.engine.sync()
+
+    def assertEqual(self, value1: Renderable | int, value2: Renderable | int) -> None:  # noqa: N802
+        with Condition(self.engine, UnregisteredRead(to_renderable(value1) != to_renderable(value2))):
+            frame = currentframe()
+            if frame is not None:
+                frame = frame.f_back
+                if frame is not None:
+                    self.print_line(frame)
+
+            self.engine.print('Left-hand side: 0x%h', to_renderable(value1))
+            self.engine.print('Right-hand side: 0x%h', to_renderable(value2))
+            self.increment_error_ctr()
+            self.finish_simulation()
+        with ElseCondition(self.engine):
+            pass
+        self.engine.sync()
+
+    def test_compile_and_run(self) -> None:
+        """Automatically executed fixture.
+
+        Process:
+        1. Builds the engine
+        2. Generates and compiles Verilog
+        3. Runs the simulation
+        4. Makes results available to test methods
+
+        """
+        # Create engine from derived class
+        self.engine = self.get_test_engine()
+
+        with TemporaryDirectory() as tempdir_str:
+            tmp_path = Path(tempdir_str)
+
+            # Generate Verilog files
+            self.verilog_file: Path = tmp_path / 'engine.sv'
+            self.testbench_file: Path = Path(__file__).parent / 'templates' / 'testbench.sv'
+
+            renderer = VerilogRenderer(self.engine)
+            with open(self.verilog_file, 'w') as fptr:
+                fptr.write(renderer.render())
+
+            # Compile with Icarus Verilog
+            self.compiled_file: Path = tmp_path / 'engine.vvp'
+            compile_result = subprocess.run(
+                ['iverilog', '-g2005-sv', '-o', str(self.compiled_file), str(self.verilog_file), str(self.testbench_file)],
+                capture_output=True,
+                text=True,
+            )
+
+            if compile_result.returncode != 0:
+                pytest.fail(f'Verilog compilation failed:\n{compile_result.stderr}')
+
+            # Run simulation automatically
+            self._run_simulation()
+            self.simulation_output: str = self.simulation_result.stdout
+
+            res = re.findall(r'passed=\s*\d+', self.simulation_output)[0]
+            print(self.simulation_output)
+
+            pass_state = int(res.split('=')[1]) == 1
+            print(pass_state)
+
+            if not pass_state:
+                pytest.fail('Verilog simulation discovered errors')
+
+    def _run_simulation(self) -> None:
+        """Internal method to execute the simulation."""
+        cmd = ['vvp', str(self.compiled_file)]
+
+        self.simulation_result = subprocess.run(cmd, capture_output=True, text=True)