Merge pull request #253 from krcb197/release/3.0.0

Release/3.0.0

Author: krcb197

.github/workflows/action.yaml

@@ -134,26 +134,42 @@ jobs:
         run: |
 
           python -m generate_and_test --RDL_source_file tests/testcases/simulator_test.rdl --root_node simulator_test
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/simulator_test.rdl --root_node simulator_test --async
+          sleep 10
 
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_block_access
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_enum_type
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --copy_libraries
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --hashing_mode PYTHONHASH
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --hashing_mode SHA256
+          sleep 10
 
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include str_property_to_include
+          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include str_property_to_include struct_property_to_include double_layer_struct_property_to_include
+          sleep 10
           
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp_regex "bool_property_to_include|enum_property_to_include|int_property_to_include|str_property_to_include|struct_property_to_include|double_layer_struct_property_to_include"
+          sleep 10
 
           python -m generate_and_test --RDL_source_file tests/testcases/reserved_elements.rdl --root_node reserved_elements --hide_regex "(?:[\w_\[\]]+\.)+RSVD"
+          sleep 10
           
           python -m generate_and_test --RDL_source_file tests/testcases/name_desc_all_levels.rdl --root_node name_desc_all_levels --skip_systemrdl_name_and_desc_properties
+          sleep 10
 
   peakrdl_integration:
     needs:
@@ -323,7 +339,6 @@ jobs:
       matrix:
         python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14"]
         lib_copy: [true, false]
-        hashing_mode: ["PYTHONHASH", "SHA256"]
 
     steps:
     - uses: actions/checkout@v4
@@ -349,12 +364,12 @@ jobs:
     - name: Generate testcases (lib_copy true)
       if: matrix.lib_copy == true
       run: |
-        python generate_testcases.py --copy_libraries --output testcase_output --hashing_mode ${{ matrix.hashing_mode }}
+        python generate_testcases.py --copy_libraries --output testcase_output
 
     - name: Generate testcases (lib_copy false)
       if: matrix.lib_copy == false
       run: |
-        python generate_testcases.py --output testcase_output --hashing_mode ${{ matrix.hashing_mode }}
+        python generate_testcases.py --output testcase_output
 
     - name: Static checks
       run: |
@@ -410,10 +425,47 @@ jobs:
         mypy autoformatted_output
         python -m unittest discover -s autoformatted_output
 
+  pathological:
+
+    needs:
+      - integration_tests
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[peakrdl]
+          python -m pip install mypy
+
+      - name: Prepare System RDL
+        run: |
+          mkdir ./pathological_test
+          python -m tests.pathological_register_maps.pathological_rdl_builder ./pathological_test/deep.rdl deep
+
+      - name: build_package
+        run: |
+          peakrdl python ./pathological_test/deep.rdl -o ./pathological_test/ --skip_library_copy
+
+      - name: type check generated code
+        run: |
+           mypy ./pathological_test/deep/
+
+      - name: Run unit tests
+        run: python -m unittest discover -s ./pathological_test/
+
   #-------------------------------------------------------------------------------
   build:
     needs:
       - autoformating
+      - pathological
 
     name: Build source distribution
     runs-on: ubuntu-latest

README.md

@@ -75,9 +75,9 @@ assumes that peakrdl has been installed.
 To make use of the RAL with real hardware or a different simulation, the callbacks will need to be 
 connected to the appropriate access function in order to perform an address space reads and writes 
 
-# Upgrading from previous versions (some important changes)
+# Some important changes
 
-## Upgrading from pre 0.9.0
+## 0.9.0
 
 In order to address a major limitation of peakrdl-python that prevented it from implementing the
 full systemRDL specification, a breaking API change was needed for handling blocks:
@@ -88,15 +88,15 @@ Users are encouraged to upgrade in order to avoid this limitation. However, ther
 to support users with existing designs, see: _Legacy Block Callback and Block Access_ in the 
 documentation
 
-## Upgrading from pre 1.2.0
+## 1.2.0
 
 Version 1.2 introduced a new way to define the enumerations for the field encoding. This allows 
 metadata from the systemRDL to propagate through to the generated code. This may break advanced 
 usage of the python enumerations. User are encouraged to use the new feature, however, if there 
 are problems with the old enumeration types (based on `IntEnum`) can be used, see 
 _Legacy Enumeration Types_ in the documentation
 
-## Upgrading from pre 2.0.0
+## 2.0.0
 
 Version 2.0.0 introduced a significant change to the process for building the register model python
 code. This change was intended to reduce the size of the generated code by only generating 
@@ -114,4 +114,20 @@ changing each time it was regenerated, version 2.1.0 introduces a option to eith
   of large register models but will be consistent, therefore is useful if the resultant code is being
   checked into a version control system (such as GIT) and the differences are being reviewed
 
+## 3.0.0
+
+Version 3.0.0 has included a significant refactoring of the generated test cases, moving functions out
+of the templates (generated code) in favour of an enhanced test library. On some cases, this 
+reduced the size of the test case generated code by 90%, significantly improved the time to generate
+the code and also improved the time to run the tests by a 30% reduction.
+
+In preparation for the removal of some legacy features from the early versions in release 4.0.0, 
+the following options were changed:
+- Version 1.2 introduced a new custom enumeration type (rather than using `IntEnum`) in order to allow
+  the content to `name` and `desc` systemRDL properties in be accessible. Until version 3.0.0 the new
+  type was not the default, it now is. The old enumeration types can still be used by setting `legacy_enum_type`.
+- The first versions of PeakRDL Python used the built-in `Array` type for accessing blocks of data efficiently.
+  This had some restrictions, so the a new methodology based on the `list` type was introduced in version 0.9.
+  The old array based behaviour is no longer the default but can be turned on using the `legacy_block_access`
+
 

docs/conf.py

@@ -45,7 +45,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
+
+html_theme_options = {
+    "repository_url": "https://github.com/krcb197/PeakRDL-python",
+    "path_to_docs": "docs",
+    "use_download_button": False,
+    "use_source_button": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/generated_package.rst

@@ -174,6 +174,10 @@ Legacy Block Callback and Block Access
       * ``NormalCallbackSetLegacy`` for standard python function callbacks
       * ``AsyncCallbackSetLegacy`` for async python function callbacks, these are called from the library using ``await``
 
+.. versionchanged:: 3.0.0
+
+    The ``legacy_block_access`` will now default to ``False``
+
 Legacy Enumeration Types
 ------------------------
 
@@ -187,6 +191,10 @@ Legacy Enumeration Types
    There was a small risk this may impact some users code, in the case of advanced usage of the
    enumeration. The old behaviour can be brought back using the ``legacy_enum_type`` build option.
 
+.. versionchanged:: 3.0.0
+
+    The ``legacy_enum_type`` will now default to ``False``
+
 
 Using the Register Access Layer
 ===============================

docs/requirements.txt

@@ -1,3 +1,3 @@
 pygments-systemrdl
 peakrdl-python
-sphinx_rtd_theme
+sphinx-book-theme

generate_and_test.py

@@ -36,7 +36,7 @@
 
 #from coverage import Coverage
 
-#from peakrdl_ipxact import IPXACTImporter
+from peakrdl_ipxact import IPXACTImporter
 
 sys.path.append('src')
 from peakrdl_python import PythonExporter
@@ -46,6 +46,8 @@
 CommandLineParser = argparse.ArgumentParser(description='Test the framework')
 CommandLineParser.add_argument('--RDL_source_file', dest='root_RDL_file',
                                type=pathlib.Path, required=True)
+CommandLineParser.add_argument('--RDL_additional_file', dest='additional_file_RDL_file',
+                               type=pathlib.Path)
 CommandLineParser.add_argument('--root_node', dest='root_node',
                                type=str, required=True)
 CommandLineParser.add_argument('--output', dest='output_path',
@@ -195,13 +197,15 @@ def build_logging_cong(logfilepath:str):
         else:
             raise(RuntimeError('not a list'))
 
+    if CommandLineArgs.additional_file_RDL_file is not None:
+        rdlc.compile_file(CommandLineArgs.additional_file_RDL_file)
     rdlc.compile_file(CommandLineArgs.root_RDL_file)
     spec = rdlc.elaborate(top_def_name=CommandLineArgs.root_node).top
 
     node_list = []
     for node in spec.descendants(unroll=True):
         node_list.append(node)
-        print(node.inst_name)
+        # print(node.inst_name)
 
     # write out text file of all the nodes names, this can be used to debug regex issues
     if CommandLineArgs.full_inst_file is not None:

generate_testcases.py

@@ -49,16 +49,6 @@
                                     'and debugging as multiple copies of the libraries can cause'
                                     'confusion. Therefore by default this script does not copy '
                                     'them over.')
-CommandLineParser.add_argument('--hashing_mode',
-                               dest='hashing_mode',
-                               type=str,
-                               choices=[item.name for item in NodeHashingMethod],
-                               default='PYTHONHASH',
-                               help='The method used to generate the hash of the node, in order to '
-                                    'deduplicate the register model. Set this to `SHA256` if '
-                                    'the python names need to stay consistent one export to the '
-                                    'next. However, this mode is slower')
-
 
 def compile_rdl(infile: str,
                 incl_search_paths: Optional[List[str]] = None,
@@ -158,19 +148,22 @@ def generate(root: Node, outdir: str,
         options = {
             'asyncoutput': [True, False],
             'legacy': [True, False],
-            'skip_systemrdl_name_and_desc_in_docstring': [True, False]
+            'skip_systemrdl_name_and_desc_in_docstring': [True, False],
+            'hashing': list(NodeHashingMethod)
         }
 
-        for asyncoutput, legacy, skip_name_and_desc_in_docstring in product(
+        for asyncoutput, legacy, skip_name_and_desc_in_docstring, hashing_method in product(
                 options['asyncoutput'], options['legacy'],
-                options['skip_systemrdl_name_and_desc_in_docstring'] ):
+                options['skip_systemrdl_name_and_desc_in_docstring'],
+                options['hashing']):
 
             # test cases that use the extended widths an not be tested in the non-legacy modes
             if (testcase_name in ['extended_memories', 'extended_sizes_registers_array']) and \
                     (legacy is True):
                 continue
 
-            folder_parts = 'raw'
+            folder_parts = 'raw_'
+            folder_parts += hashing_method.name
             if asyncoutput:
                 folder_parts += '_async'
             if legacy:
@@ -184,7 +177,7 @@ def generate(root: Node, outdir: str,
                          legacy_enum_type=legacy,
                          copy_library=CommandLineArgs.copy_libraries,
                          skip_systemrdl_name_and_desc_in_docstring=skip_name_and_desc_in_docstring,
-                         hashing_mode=NodeHashingMethod[CommandLineArgs.hashing_mode])
+                         hashing_mode=hashing_method)
 
             module_fqfn = output_path / folder_parts / '__init__.py'
             with open(module_fqfn, 'w', encoding='utf-8') as fid:

pyproject.toml

@@ -63,7 +63,11 @@ dev = [
     "mypy",
     "pylint",
     "coverage",
-    "peakrdl"
+    "peakrdl",
+    # needed for the documentation build
+    "sphinx-book-theme",
+    "pygments-systemrdl"
+
 ]
 peakrdl = [
     "peakrdl"

src/peakrdl_python/__about__.py

@@ -3,8 +3,8 @@
 Copyright (C) 2021 - 2025
 
 This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as 
-published by the Free Software Foundation, either version 3 of 
+it under the terms of the GNU Lesser 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,
@@ -17,4 +17,4 @@
 
 Variables that describes the peakrdl-python Package
 """
-__version__ = "2.3.0"
+__version__ = "3.0.0"

src/peakrdl_python/__peakrdl__.py

@@ -80,7 +80,8 @@ def add_exporter_arguments(self, arg_group: 'argparse._ActionsContainer') -> Non
         arg_group.add_argument('--legacy_block_access', action='store_true',
                                dest='legacy_block_access',
                                help='peakrdl python has two methods to hold blocks of data, the '
-                                    'legacy mode based on array.array or the new mode using lists')
+                                    'legacy mode based on array.array or the new mode using '
+                                    'lists. This option will be removed in version 4.0')
         arg_group.add_argument('--show_hidden', action='store_true',
                                dest='show_hidden',
                                help='show addrmap, regfile, memory, register and fields that '
@@ -100,7 +101,8 @@ def add_exporter_arguments(self, arg_group: 'argparse._ActionsContainer') -> Non
                                dest='legacy_enum_type',
                                help='peakrdl python has two ways to define field encoding as '
                                      'enums new method and an old method based on IntEnum. '
-                                     'Setting this to true will restore the old behaviour')
+                                     'Setting this to true will restore the old behaviour.'
+                                     ' This option will be removed in version 4.0')
         arg_group.add_argument('--skip_systemrdl_name_and_desc_properties', action='store_true',
                                dest='skip_systemrdl_name_and_desc_properties',
                                help='peakrdl python includes the system RDL name and desc '