Merge pull request #237 from krcb197/234-optimised-test_int_field_read_and_write

234 optimised `test_int_field_read_and_write`

Author: krcb197

src/peakrdl_python/__about__.py

@@ -17,4 +17,4 @@
 
 Variables that describes the peakrdl-python Package
 """
-__version__ = "2.1.0"
+__version__ = "3.0.0rc1"

src/peakrdl_python/_deploy_package.py

@@ -154,8 +154,10 @@ class GeneratedPackage(PythonPackage):
     Args:
         include_tests (bool): include the tests package
     """
+    # pylint:disable=too-many-instance-attributes
     template_lib_package = PythonPackage(Path(__file__).parent / 'lib')
     template_sim_lib_package = PythonPackage(Path(__file__).parent / 'sim_lib')
+    template_lib_test_package = PythonPackage(Path(__file__).parent / 'lib_test')
 
     def __init__(self, path: str, package_name: str, include_tests: bool, include_libraries: bool):
         super().__init__(Path(path) / package_name)
@@ -169,6 +171,9 @@ def __init__(self, path: str, package_name: str, include_tests: bool, include_li
         self.reg_model = _GeneratedRegModelPackage(self.child_path('reg_model'))
 
         if include_tests:
+            if include_libraries:
+                self.lib_test = self.child_ref_package('lib_test',
+                                                       self.template_lib_test_package)
             self.tests = self.child_package('tests')
 
         if include_libraries:
@@ -200,4 +205,6 @@ def create_empty_package(self, cleanup: bool) -> None:
         if self._include_libraries:
             self.lib.create_empty_package(cleanup=cleanup)
             self.sim_lib.create_empty_package(cleanup=cleanup)
+            if self._include_tests:
+                self.lib_test.create_empty_package(cleanup=cleanup)
         self.sim.create_empty_package(cleanup=cleanup)

src/peakrdl_python/lib_test/__init__.py

@@ -0,0 +1,24 @@
+"""
+peakrdl-python is a tool to generate Python Register Access Layer (RAL) from SystemRDL
+Copyright (C) 2021 - 2025
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+This package is intended to distributed as part of automatically generated code by the PeakRDL
+Python tool. It provides a set of base test classes to reduce the size of the auto generated code
+"""
+from .base_reg_test_class import LibTestBase
+from .async_reg_base_test_class import AsyncLibTestBase
+
+from .utilities import reverse_bits

src/peakrdl_python/lib_test/async_reg_base_test_class.py

@@ -0,0 +1,185 @@
+"""
+peakrdl-python is a tool to generate Python Register Access Layer (RAL) from SystemRDL
+Copyright (C) 2021 - 2025
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+This package is intended to distributed as part of automatically generated code by the PeakRDL
+Python tool. It provide the base class for the autogenerated tests
+"""
+# this module is very similar to the non-async version, a lot of code has been put into common
+# methods but it did not make sense to do everything as it would destroy readability
+# pylint:disable=duplicate-code
+
+import unittest
+from abc import ABC
+from typing import Union
+import random
+from unittest.mock import patch
+from itertools import product
+
+from ..lib import FieldAsyncReadOnly, FieldAsyncWriteOnly, FieldAsyncReadWrite
+from ..sim_lib.dummy_callbacks import async_dummy_read
+from ..sim_lib.dummy_callbacks import async_dummy_write
+
+
+from .utilities import reverse_bits, expected_reg_write_data
+
+class AsyncLibTestBase(unittest.IsolatedAsyncioTestCase, ABC):
+    """
+    Base Test class for the autogenerated register test when in async mode
+    """
+
+    # The following may look odd by a second layer of indirection is required to effectively patch
+    # the read and write within tests
+
+    # pylint:disable=missing-function-docstring
+
+    async def outer_read_callback(self, addr: int, width: int, accesswidth: int) -> int:
+        return await self.read_callback(addr=addr,
+                                        width=width,
+                                        accesswidth=accesswidth)
+
+    async def read_callback(self, addr: int, width: int, accesswidth: int) -> int:
+        return await  async_dummy_read(addr=addr,
+                                       width=width,
+                                       accesswidth=accesswidth)
+
+    async def outer_write_callback(self, addr: int,
+                                   width: int, accesswidth: int,
+                                   data: int) -> None:
+        return await self.write_callback(addr=addr,
+                                         width=width,
+                                         accesswidth=accesswidth,
+                                         data=data)
+
+    async def write_callback(self, addr: int, width: int, accesswidth: int, data: int) -> None:
+        return await  async_dummy_write(addr=addr,
+                                        width=width,
+                                        accesswidth=accesswidth,
+                                        data=data)
+
+    # pylint:enable=missing-function-docstring
+
+
+    async def _single_int_field_read_and_write_test(
+            self,
+            fut: Union[FieldAsyncReadOnly, FieldAsyncWriteOnly, FieldAsyncReadWrite],
+            is_sw_readable: bool,
+            is_sw_writable: bool) -> None:
+
+        # the lsb, msb, high, low, bitmask, inv_bitmask and max_value are all checked as part of
+        # `test_field_properties` so do no need to checked here. Similarly, the properties of
+        # parent register are checked as part of `test_register_properties`
+
+        if is_sw_readable:
+            if not isinstance(fut, (FieldAsyncReadOnly, FieldAsyncReadWrite)):
+                raise TypeError('Test can not proceed as the fut is not a readable field')
+            await self.__single_field_read_test(fut=fut)
+
+        if is_sw_writable:
+            if not isinstance(fut, (FieldAsyncWriteOnly, FieldAsyncReadWrite)):
+                raise TypeError('Test can not proceed as the fut is not a writable field')
+            await self.__single_field_write_test(fut=fut)
+
+    async def __single_field_read_test(
+            self,
+            fut: Union[FieldAsyncReadOnly, FieldAsyncReadWrite]) -> None:
+
+        with patch.object(self,'write_callback') as write_callback_mock, \
+            patch.object(self,'read_callback', return_value=0) as read_callback_mock:
+
+            # read back - zero, this is achieved by setting the register to inverse bitmask
+            read_callback_mock.return_value = fut.inverse_bitmask
+            self.assertEqual(await fut.read(),0)
+            read_callback_mock.assert_called_once_with(
+                addr=fut.parent_register.address,
+                width=fut.parent_register.width,
+                accesswidth=fut.parent_register.accesswidth)
+
+            # read back - max_value, this is achieved by setting the register to bitmask
+            read_callback_mock.reset_mock()
+            read_callback_mock.return_value = fut.bitmask
+            self.assertEqual(await fut.read(), fut.max_value)
+            read_callback_mock.assert_called_once_with(
+                addr=fut.parent_register.address,
+                width=fut.parent_register.width,
+                accesswidth=fut.parent_register.accesswidth)
+
+            # read back - random value
+            read_callback_mock.reset_mock()
+            random_value = random.randrange(0, fut.parent_register.max_value + 1)
+            read_callback_mock.return_value = random_value
+            random_field_value = (random_value & fut.bitmask) >> fut.low
+            if fut.msb == fut.high:
+                self.assertEqual(await fut.read(), random_field_value)
+            else:
+                self.assertEqual(await fut.read(),
+                                 reverse_bits(value=random_field_value, number_bits=fut.width))
+            read_callback_mock.assert_called_once_with(
+                addr=fut.parent_register.address,
+                width=fut.parent_register.width,
+                accesswidth=fut.parent_register.accesswidth)
+
+            # at the end of the read tests the write should not have been called
+            read_callback_mock.reset_mock()
+            write_callback_mock.assert_not_called()
+
+    async def __single_field_write_test(
+            self,
+            fut: Union[FieldAsyncWriteOnly, FieldAsyncReadWrite]) -> None:
+
+        with patch.object(self, 'write_callback') as write_callback_mock, \
+                patch.object(self, 'read_callback', return_value=0) as read_callback_mock:
+
+            # pylint:disable-next=protected-access
+            readable_reg = fut.parent_register._is_readable
+
+
+
+            random_reg_value = random.randrange(0, fut.parent_register.max_value + 1)
+            random_field_value = random.randrange(0, fut.max_value + 1)
+            for reg_base_value, field_value in product(
+                    [0, fut.parent_register.max_value, random_reg_value],
+                    [0, fut.max_value, random_field_value]):
+                read_callback_mock.reset_mock()
+                write_callback_mock.reset_mock()
+                read_callback_mock.return_value = reg_base_value
+
+                await fut.write(field_value)
+
+                if (fut.width < fut.parent_register.width) and readable_reg:
+                    read_callback_mock.assert_called_once_with(
+                        addr=fut.parent_register.address,
+                        width=fut.parent_register.width,
+                        accesswidth=fut.parent_register.accesswidth)
+                else:
+                    read_callback_mock.assert_not_called()
+
+                write_callback_mock.assert_called_once_with(
+                    addr=fut.parent_register.address,
+                    width=fut.parent_register.width,
+                    accesswidth=fut.parent_register.accesswidth,
+                    data=expected_reg_write_data(fut=fut,
+                                                 reg_base_value=reg_base_value,
+                                                 readable_reg=readable_reg,
+                                                 field_value=field_value))
+
+
+                # check invalid write values bounce
+                with self.assertRaises(ValueError):
+                    await fut.write(fut.max_value + 1)
+
+                with self.assertRaises(ValueError):
+                    await fut.write(-1)