peakrdl-python 0.9.0rc4__tar.gz → 0.9.1__tar.gz

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/.github/workflows/action.yaml

@@ -10,7 +10,6 @@ on:
   pull_request:
     branches:
     - main
-    - 0.9.0
   schedule:
     - cron: '00 6 1 * *'
   release:
@@ -40,6 +39,10 @@ jobs:
       - name: Run Main code Lint
         run: pylint --rcfile tests/pylint.rc src/peakrdl_python
 
+      - name: Install dependencies for unit tests
+        run: |
+          python -m pip install .[unit_test] -U
+
       - name: Run unit tests Lint
         run: pylint --rcfile tests/pylint.rc src/peakrdl_python tests/unit_tests
 
@@ -81,7 +84,9 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .
+          # the unit tests need the development version of installer as tomllib may be needed
+          # for older versions of python
+          python -m pip install .[unit_test]
 
       - name: Run Unit Tests
         run: |
@@ -134,6 +139,8 @@ jobs:
           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
           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
 
+          python -m generate_and_test --RDL_source_file tests/testcases/reserved_elements.rdl --root_node reserved_elements --hide_regex "(?:[\w_\[\]]+\.)+RSVD"
+
   peakrdl_integration:
     needs:
       - mypy
@@ -167,6 +174,7 @@ jobs:
           peakrdl python tests/testcases/simple.xml tests/testcases/multifile.rdl -o peakrdl_out/raw
           peakrdl python tests/testcases/extended_memories.rdl -o peakrdl_out/raw/
           peakrdl python tests/testcases/user_defined_properties.rdl -o peakrdl_out/raw/ --udp bool_property_to_include
+          peakrdl python tests/testcases/reserved_elements.rdl -o peakrdl_out/raw/ --hide_regex "(?:[\w_\[\]]+\.)+RSVD"
           python -m unittest discover -s peakrdl_out/raw
 
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw_async/ --async
@@ -178,6 +186,15 @@ jobs:
 
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/no_test/ --skip_test_case_generation
 
+          # test a TOMl file that passes in overridden templates
+          peakrdl python tests/testcases/basic.rdl -o peakrdl_out/simple_user_template/ --peakrdl-cfg tests/alternative_templates_toml/peakrdl.toml
+          python tests/alternative_templates_toml/header_check.py --generated_package_location peakrdl_out/simple_user_template/ --top_name basic
+          peakrdl python tests/testcases/basic.rdl -o peakrdl_out/dynamic_user_template/ --peakrdl-cfg tests/alternative_templates_dynamic_toml/peakrdl.toml
+          python tests/alternative_templates_dynamic_toml/header_check.py --generated_package_location peakrdl_out/dynamic_user_template/ --top_name basic
+
+
+
+
       - name: Check Examples
         run: |
 

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: peakrdl-python
-Version: 0.9.0rc4
+Version: 0.9.1
 Summary: Generate Python Register Access Layer (RAL) from SystemRDL
 Author: Keith Brady
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -700,7 +700,7 @@ Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: systemrdl-compiler>=1.24.0
+Requires-Dist: systemrdl-compiler>=1.25.0
 Requires-Dist: jinja2
 Requires-Dist: asynctest; python_version < "3.8"
 Requires-Dist: typing-extensions; python_version < "3.11"
@@ -711,6 +711,9 @@ Requires-Dist: coverage; extra == "dev"
 Requires-Dist: peakrdl-ipxact; extra == "dev"
 Provides-Extra: peakrdl
 Requires-Dist: peakrdl; extra == "peakrdl"
+Provides-Extra: unit-test
+Requires-Dist: peakrdl; extra == "unit-test"
+Requires-Dist: tomli; python_version < "3.11" and extra == "unit-test"
 
 ![CI](https://github.com/krcb197/PeakRDL-python/actions/workflows/action.yaml/badge.svg)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/peakrdl-python.svg)](https://pypi.org/project/peakrdl-python)

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/docs/api.rst

@@ -18,13 +18,15 @@ Example
 The following example shows the compiling an SystemRDL file and then generating
 the python register access layer using PeakRDL Python.
 
+
+
 .. code-block:: python
 
-    from systemrdl import RDLCompiler
+    from peakrdl_python import compiler_with_udp_registers
     from peakrdl_python.exporter import PythonExporter
 
     # compile the systemRDL
-    rdlc = RDLCompiler()
+    rdlc = compiler_with_udp_registers()
     rdlc.compile_file('basic.rdl')
     spec = rdlc.elaborate(top_def_name='basic').top
 
@@ -36,6 +38,25 @@ the python register access layer using PeakRDL Python.
 PythonExporter
 ==============
 
+The main exported class used to build the python register access layer:
+
 .. autoclass:: peakrdl_python.exporter.PythonExporter
     :members:
-    :special-members: __init__
+    :special-members: __init__
+
+Compiler Extensions
+-------------------
+
+PeakRDL Python uses two User Defined Properties to help the generation, there are definitions of
+these available to register with a the Compiler
+
+.. autoclass:: peakrdl_python.PythonHideUDP
+    :members:
+
+
+.. autoclass:: peakrdl_python.PythonInstNameUDP
+    :members:
+
+The compiler factory function will generate an instance of the compiler with these registered
+
+.. autofunction:: peakrdl_python.compiler_with_udp_registers

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/docs/generated_package.rst

@@ -467,7 +467,7 @@ included to reserve space or test functions.
 User Defined Property
 ---------------------
 
-PeakRDL Python supports a User Defined Propery (UDP): ``python_hide`` that can be used to hide
+PeakRDL Python supports a User Defined Property (UDP): ``python_hide`` that can be used to hide
 items that should not appear in the generated python wrappers.
 
 In the following example, python wrapper generated would have the registers:
@@ -508,8 +508,18 @@ However the ``hidden_reg`` would not be included in the python wrappers
 The ``python_hide`` property can be overridden with the ``show_hidden`` argument to the peakrdl
 command line tool or the ``export`` method.
 
-Autoformating
-=============
+Regular Expression
+------------------
+
+PeakRDL Python supports hiding elements of the based on a regular expression.
+
+.. note:: The expression uses the python re.match, for example to hide all fields, registers,
+          regfiles, address maps or memories  with the name ``RSVD``, the regular expression
+          must match on the full name e.g. ``(?:[\w_\[\]]+\.)+RSVD``
+
+
+Autoformatting
+==============
 
 The generated code is not perfect it often has lots of spare black lines, over time this will
 improve but the quickest way to resolve these issue is to include an autoformatter

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/generate_and_test.py

@@ -35,14 +35,13 @@ from unittest import TestLoader
 from unittest import TestSuite
 from unittest import TextTestRunner
 
-from coverage import Coverage
+#from coverage import Coverage
 
-from systemrdl import RDLCompiler
-
-from peakrdl_ipxact import IPXACTImporter
+#from peakrdl_ipxact import IPXACTImporter
 
 sys.path.append('src')
 from peakrdl_python import PythonExporter
+from peakrdl_python import compiler_with_udp_registers
 
 CommandLineParser = argparse.ArgumentParser(description='Test the framework')
 CommandLineParser.add_argument('--RDL_source_file', dest='root_RDL_file',
@@ -86,6 +85,13 @@ CommandLineParser.add_argument('--legacy_block_access', action='store_true',
 CommandLineParser.add_argument('--udp', dest='udp', nargs='*',
                                type=str, help='any user defined properties to include in the '
                                               'reg_model')
+CommandLineParser.add_argument('--hide_regex', dest='hide_regex', type=str,
+                               help='A regex that will cause any matching fully qualified node to '
+                                    'be hidden')
+CommandLineParser.add_argument('--full_inst_file', dest='full_inst_file',
+                               type=pathlib.Path, required=False,
+                               help='export a text file with a list of the all qualified instance'
+                                    'names in the systemRDL')
 
 
 def build_logging_cong(logfilepath:str):
@@ -143,7 +149,7 @@ if __name__ == '__main__':
     logfile_path = build_logging_cong(CommandLineArgs.output_path / f'{__file__}.log')
     logging.config.dictConfig(logfile_path)
 
-    rdlc = RDLCompiler()
+    rdlc = compiler_with_udp_registers()
 
     if CommandLineArgs.ipxact is not None:
 
@@ -165,6 +171,12 @@ if __name__ == '__main__':
         node_list.append(node)
         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:
+        with CommandLineArgs.full_inst_file.open('w', encoding='utf-8') as fid:
+            for child in spec.descendants(unroll=True):
+                fid.write('.'.join(child.get_path_segments()) + '\n')
+
     exporter = PythonExporter()
     start_time = time.time()
     exporter.export(node=spec, path=str(CommandLineArgs.output_path / 'generate_and_test_output'),
@@ -172,7 +184,8 @@ if __name__ == '__main__':
                     delete_existing_package_content=not CommandLineArgs.suppress_cleanup,
                     skip_library_copy=not CommandLineArgs.copy_libraries,
                     legacy_block_access=CommandLineArgs.legacy_block_access,
-                    user_defined_properties_to_include=CommandLineArgs.udp)
+                    user_defined_properties_to_include=CommandLineArgs.udp,
+                    hidden_inst_name_regex=CommandLineArgs.hide_regex)
     print(f'generation time {time.time() - start_time}s')
 
     if not CommandLineArgs.export_only:

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/pyproject.toml

@@ -7,7 +7,7 @@ name = "peakrdl-python"
 dynamic = ["version"]
 requires-python = ">=3.7"
 dependencies = [
-    "systemrdl-compiler>=1.24.0",
+    "systemrdl-compiler>=1.25.0",
     "jinja2",
     "asynctest;python_version<'3.8'",
     "typing-extensions;python_version<'3.11'"
@@ -62,4 +62,10 @@ dev = [
     "coverage",
     "peakrdl-ipxact"
 ]
-peakrdl = ["peakrdl"]
+peakrdl = [
+    "peakrdl"
+]
+unit_test = [
+    "peakrdl",
+    "tomli;python_version<'3.11'"
+]

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/src/peakrdl_python/__about__.py

@@ -17,4 +17,4 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Variables that describes the peakrdl-python Package
 """
-__version__ = "0.9.0-rc4"
+__version__ = "0.9.1"

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/src/peakrdl_python/__init__.py

@@ -17,3 +17,6 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 """
 from .exporter import PythonExporter
+
+from .compiler_udp import PythonHideUDP, PythonInstNameUDP
+from .compiler_udp import compiler_with_udp_registers

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/src/peakrdl_python/__peakrdl__.py

@@ -28,6 +28,7 @@ from peakrdl.config import schema  # type: ignore[import]
 #pylint: enable=no-name-in-module,import-error
 
 from .exporter import PythonExporter
+from .compiler_udp import PythonHideUDP, PythonInstNameUDP
 
 if TYPE_CHECKING:
     import argparse
@@ -38,11 +39,14 @@ class Exporter(ExporterSubcommandPlugin):
     """
     PeakRDL export class, see PeakRDL for more details
     """
-    short_desc = "Generater Python Wrappers"
+    short_desc = "Generate Python Wrappers"
     long_desc = "Generate Python Wrappers for the Register Model"
+    udp_definitions = [PythonHideUDP, PythonInstNameUDP]
+    generates_output_file = True
 
     cfg_schema = {
         "user_template_dir": schema.DirectoryPath(),
+        "user_template_context": { "*" : schema.AnyType() }
     }
 
     def add_exporter_arguments(self, arg_group: 'argparse._ActionsContainer') -> None:
@@ -79,6 +83,9 @@ class Exporter(ExporterSubcommandPlugin):
                                     'would be removed from the build python by default')
         arg_group.add_argument('--udp', dest='udp', nargs='*', type=str,
                                help='any user defined properties to include in the reg_model')
+        arg_group.add_argument('--hide_regex', dest='hide_regex', type=str,
+                               help='A regex that will cause any matching fully qualified node to '
+                                    'be hidden')
 
     def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> None:
         """
@@ -92,16 +99,23 @@ class Exporter(ExporterSubcommandPlugin):
 
         """
         templates = self.cfg['user_template_dir']
-        peakrdl_exporter = \
-            PythonExporter(user_template_dir=templates)  # type: ignore[no-untyped-call]
+        user_template_context = self.cfg['user_template_context']
+        if user_template_context is None:
+            peakrdl_exporter = \
+                PythonExporter(user_template_dir=templates)  # type: ignore[no-untyped-call]
+        else:
+            peakrdl_exporter = \
+                PythonExporter(user_template_dir=templates, # type: ignore[no-untyped-call]
+                               user_template_context=user_template_context)
 
         peakrdl_exporter.export(
-            top_node,
-            options.output,
-            options.is_async,
+            node=top_node,
+            path=options.output,
+            asyncoutput=options.is_async,
             skip_test_case_generation=options.skip_test_case_generation,
             delete_existing_package_content=not options.suppress_cleanup,
             legacy_block_access=options.legacy_block_access,
             show_hidden=options.show_hidden,
-            user_defined_properties_to_include=options.udp
+            user_defined_properties_to_include=options.udp,
+            hidden_inst_name_regex=options.hide_regex
         )

{peakrdl_python-0.9.0rc4 → peakrdl_python-0.9.1}/src/peakrdl_python/_node_walkers.py

@@ -22,19 +22,21 @@ from typing import Optional, List, Union, Iterator
 from systemrdl import RDLListener, WalkerAction # type: ignore
 from systemrdl.node import RegNode, MemNode, FieldNode, AddrmapNode, RegfileNode # type: ignore
 
+from .systemrdl_node_utility_functions import HideNodeCallback
+
 
 class AddressMaps(RDLListener):
     """
     class intended to be used as part of the walker/listener protocol to find all the descendant
     address maps
     """
-    def __init__(self, show_hidden: bool) -> None:
+    def __init__(self, hide_node_callback: HideNodeCallback) -> None:
         super().__init__()
         self.__address_maps: List[AddrmapNode] = []
-        self.__show_hidden = show_hidden
+        self.__hide_node_callback = hide_node_callback
 
     def enter_Addrmap(self, node: AddrmapNode) -> Optional[WalkerAction]:
-        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+        if self.__hide_node_callback(node):
             return WalkerAction.SkipDescendants
 
         self.__address_maps.append(node)
@@ -50,7 +52,7 @@ class OwnedbyAddressMap(RDLListener):
     class intended to be used as part of the walker/listener protocol to find all the items owned
     by an address map but not the descendents of any address map
     """
-    def __init__(self, show_hidden: bool) -> None:
+    def __init__(self, hide_node_callback: HideNodeCallback) -> None:
         super().__init__()
 
         self.registers: List[RegNode] = []
@@ -63,10 +65,10 @@ class OwnedbyAddressMap(RDLListener):
         self._hidden_memories: List[RegNode] = []
         self._hidden_addr_maps: List[AddrmapNode] = []
         self._hidden_reg_files: List[RegfileNode] = []
-        self.__show_hidden = show_hidden
+        self.__hide_node_callback = hide_node_callback
 
     def enter_Reg(self, node: RegNode) -> Optional[WalkerAction]:
-        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+        if self.__hide_node_callback(node):
             self._hidden_registers.append(node)
             return WalkerAction.SkipDescendants
 
@@ -74,7 +76,7 @@ class OwnedbyAddressMap(RDLListener):
         return WalkerAction.Continue
 
     def enter_Mem(self, node: MemNode) -> Optional[WalkerAction]:
-        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+        if self.__hide_node_callback(node):
             self._hidden_memories.append(node)
             return WalkerAction.SkipDescendants
 
@@ -82,7 +84,7 @@ class OwnedbyAddressMap(RDLListener):
         return WalkerAction.Continue
 
     def enter_Field(self, node: FieldNode) -> Optional[WalkerAction]:
-        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+        if self.__hide_node_callback(node):
             self._hidden_fields.append(node)
             return WalkerAction.SkipDescendants
 
@@ -90,14 +92,14 @@ class OwnedbyAddressMap(RDLListener):
         return WalkerAction.Continue
 
     def enter_Addrmap(self, node: AddrmapNode) -> Optional[WalkerAction]:
-        if not node.get_property('python_hide', default=False) or self.__show_hidden:
+        if not self.__hide_node_callback(node):
             self.addr_maps.append(node)
         else:
             self._hidden_addr_maps.append(node)
         return WalkerAction.SkipDescendants
 
     def enter_Regfile(self, node: RegfileNode) -> Optional[WalkerAction]:
-        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+        if self.__hide_node_callback(node):
             self._hidden_reg_files.append(node)
             return WalkerAction.SkipDescendants
 

peakrdl_python-0.9.1/src/peakrdl_python/compiler_udp.py

@@ -0,0 +1,99 @@
+"""
+peakrdl-python is a tool to generate Python Register Access Layer (RAL) from SystemRDL
+Copyright (C) 2021 - 2023
+
+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/>.
+
+Defined the compiler classes that are used
+"""
+from typing import Any
+from systemrdl import RDLCompiler  # type: ignore
+from systemrdl.udp import UDPDefinition  # type: ignore
+from systemrdl.component import Field, Reg, Regfile, Mem, Addrmap # type: ignore
+from systemrdl.node import FieldNode, RegNode, RegfileNode, MemNode, AddrmapNode  # type: ignore
+from systemrdl.node import Node  # type: ignore
+
+from .safe_name_utility import is_safe_field_name, is_safe_memory_name, is_safe_addrmap_name, \
+    is_safe_regfile_name, is_safe_register_name
+
+
+def compiler_with_udp_registers(**kwargs: Any) -> RDLCompiler:
+    """
+    Factory function to create an instance of the systemRDL compiler with the UDP registrations
+    """
+    rdlc = RDLCompiler(**kwargs)
+    rdlc.register_udp(PythonHideUDP)
+    rdlc.register_udp(PythonInstNameUDP)
+
+    return rdlc
+
+
+class PythonInstNameUDP(UDPDefinition):
+    """
+    Definition of the class for the ``python_inst_name`` systemRDL property used by peakrdl-python
+    """
+    name = "python_inst_name"
+    valid_components = {Field, Reg, Regfile, Mem, Addrmap}
+    valid_type = str
+
+    def validate(self, node: Node, value: str) -> None:
+        if isinstance(node, FieldNode):
+            if not is_safe_field_name(node, value):
+                self.msg.error(
+                    f"{value} is not a safe node name for a field as it clashes with a python "
+                    f"keyword or attribute of a peakrdl-python field",
+                    self.get_src_ref(node)
+                )
+        elif isinstance(node, RegNode):
+            if not is_safe_register_name(node, value):
+                self.msg.error(
+                    f"{value} is not a safe node name for a register as it clashes with a python "
+                    f"keyword or attribute of a peakrdl-python register",
+                    self.get_src_ref(node)
+                )
+        elif isinstance(node, RegfileNode):
+            if not is_safe_regfile_name(node, value):
+                self.msg.error(
+                    f"{value} is not a safe node name for a regfile as it clashes with a python "
+                    f"keyword or attribute of a peakrdl-python regfile",
+                    self.get_src_ref(node)
+                )
+        elif isinstance(node, AddrmapNode):
+            if not is_safe_addrmap_name(node, value):
+                self.msg.error(
+                    f"{value} is not a safe node name for a addrmap as it clashes with a python "
+                    f"keyword or attribute of a peakrdl-python addrmap",
+                    self.get_src_ref(node)
+                )
+        elif isinstance(node, MemNode):
+            if not is_safe_memory_name(node, value):
+                self.msg.error(
+                    f"{value} is not a safe node name for a Memory as it clashes with a python "
+                    f"keyword or attribute of a peakrdl-python memory",
+                    self.get_src_ref(node)
+                )
+        else:
+            self.msg.error(
+                f"unhandled type for property {type(node)}",
+                self.get_src_ref(node)
+            )
+
+
+class PythonHideUDP(UDPDefinition):
+    """
+    Definition of the class for the ``python_hide`` systemRDL property used by peakrdl-python
+    """
+    name = "python_hide"
+    valid_components = {Field, Reg, Regfile, Mem, Addrmap}
+    valid_type = bool