Merge pull request #143 from krcb197/105-user-defined-properties-in-python-wrappers

105 user defined properties in python wrappers

Author: krcb197

.github/workflows/action.yaml

@@ -37,10 +37,12 @@ jobs:
           python -m pip install .
           python -m pip install -U pylint
 
-      - name: Run Lint
-        #run: pylint --rcfile tests/pylint.rc src/peakrdl_python tests/unit_tests
+      - name: Run Main code Lint
         run: pylint --rcfile tests/pylint.rc src/peakrdl_python
 
+      - name: Run unit tests Lint
+        run: pylint --rcfile tests/pylint.rc src/peakrdl_python tests/unit_tests
+
   mypy:
     runs-on: ubuntu-latest
     steps:
@@ -126,6 +128,12 @@ jobs:
 
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map
 
+          python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_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
+          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
+          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
+
   peakrdl_integration:
     needs:
       - mypy
@@ -158,6 +166,7 @@ jobs:
           peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw/show_hidden/ --show_hidden
           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
           python -m unittest discover -s peakrdl_out/raw
 
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw_async/ --async

docs/generated_package.rst

@@ -383,6 +383,29 @@ worry if they are in an array or not.
 .. literalinclude :: ../example/tranversing_address_map/reseting_registers.py
    :language: python
 
+Exposing User Defined Properties
+--------------------------------
+
+SystemRDL allows properties to be added to any component (Field, Memory, Register, Register File,
+Address Map), so called *User Defined Properties (UDP)*.
+
+Consider the following systemRDL example with a user defined property: ``component_usage``
+
+.. literalinclude :: ../example/user_defined_properties/user_defined_properties.rdl
+   :language: systemrdl
+
+User Defined Properties are not automatically included they must be specified, as shown:
+
+.. code-block:: bash
+
+   peakrdl python chip_with_registers.rdl -o chip_with_registers
+
+The user defined properties are stored in a ``udp`` property of all component in the generated
+register access and can be accessed as follows:
+
+.. literalinclude :: ../example/user_defined_properties/demo_user_defined_properties.py
+   :language: python
+
 Python Safe Names
 =================
 

example/user_defined_properties/demo_user_defined_properties.py

@@ -0,0 +1,16 @@
+from user_defined_property.reg_model.user_defined_property import user_defined_property_cls
+from user_defined_property.sim_lib.dummy_callbacks import dummy_read, dummy_write
+from user_defined_property.lib.callbacks import NormalCallbackSet
+
+if __name__ == '__main__':
+
+    # create an instance of the class
+    regmodel = user_defined_property_cls(callbacks=NormalCallbackSet(read_callback=dummy_read,
+                                                                     write_callback=dummy_write))
+
+    # loop through the the fields in the register access model and print out the value of the
+    # component_usage property
+    for field in regmodel.control_register.readable_fields:
+        field_usage = field.udp['component_usage']
+        print(f"Control register field:{field.inst_name} has recommend usage {field_usage.name}")
+

example/user_defined_properties/user_defined_properties.rdl

@@ -0,0 +1,17 @@
+enum component_type {
+			test_function = 0 { name = "test the design"; };
+			device_configuration = 1 { name = "configuring_the_device"; };
+			normal_use = 2 { desc="normal device usage"; };
+		};
+
+property component_usage { type = component_type; component = addrmap | regfile | reg | field | mem; };
+
+addrmap user_defined_property {
+
+    reg  {
+        field { fieldwidth=4; component_usage=component_type::test_function;  } data_loop_back;
+        field { fieldwidth=1; component_usage=component_type::device_configuration; } power_control;
+        field { fieldwidth=1; component_usage=component_type::normal_use;  } led_control;
+    } control_register;
+
+};

generate_and_test.py

@@ -83,6 +83,9 @@
                                dest='legacy_block_access',
                                help='peakrdl python has two methods to hold blocks of data, the '
                                     'legacy mode based on Array or the new mode using lists')
+CommandLineParser.add_argument('--udp', dest='udp', nargs='*',
+                               type=str, help='any user defined properties to include in the '
+                                              'reg_model')
 
 
 def build_logging_cong(logfilepath:str):
@@ -168,7 +171,8 @@ def build_logging_cong(logfilepath:str):
                     asyncoutput=CommandLineArgs.asyncoutput,
                     delete_existing_package_content=not CommandLineArgs.suppress_cleanup,
                     skip_library_copy=not CommandLineArgs.copy_libraries,
-                    legacy_block_access=CommandLineArgs.legacy_block_access)
+                    legacy_block_access=CommandLineArgs.legacy_block_access,
+                    user_defined_properties_to_include=CommandLineArgs.udp)
     print(f'generation time {time.time() - start_time}s')
 
     if not CommandLineArgs.export_only:

src/peakrdl_python/__about__.py

@@ -17,4 +17,4 @@
 
 Variables that describes the peakrdl-python Package
 """
-__version__ = "0.9.0.rc3"
+__version__ = "0.9.0-rc4"

src/peakrdl_python/__peakrdl__.py

@@ -77,6 +77,8 @@ def add_exporter_arguments(self, arg_group: 'argparse._ActionsContainer') -> Non
                                help='show addrmap, regfile, memory, register and fields that '
                                     'have been given the python_hide user defined property and '
                                     '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')
 
     def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> None:
         """
@@ -100,5 +102,6 @@ def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> N
             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
+            show_hidden=options.show_hidden,
+            user_defined_properties_to_include=options.udp
         )

src/peakrdl_python/exporter.py

@@ -20,7 +20,7 @@
 import os
 from pathlib import Path
 from shutil import copy
-from typing import List, NoReturn, Iterable, Tuple, Dict, Any
+from typing import List, NoReturn, Iterable, Tuple, Dict, Any, Optional
 
 import jinja2 as jj
 from systemrdl import RDLWalker # type: ignore
@@ -29,15 +29,16 @@
 from systemrdl.node import FieldNode, MemNode, AddressableNode # type: ignore
 from systemrdl.node import SignalNode # type: ignore
 from systemrdl.rdltypes import OnReadType, OnWriteType, PropertyReference  # type: ignore
-from systemrdl.rdltypes.user_enum import UserEnumMeta  # type: ignore
+from systemrdl.rdltypes.user_enum import UserEnum, UserEnumMeta  # type: ignore
+from systemrdl.rdltypes.user_struct import UserStruct  # type: ignore
 
 from .systemrdl_node_utility_functions import get_reg_readable_fields, get_reg_writable_fields, \
     get_table_block, get_dependent_component, \
     get_field_bitmask_hex_string, get_field_inv_bitmask_hex_string, \
     get_field_max_value_hex_string, get_reg_max_value_hex_string, get_fully_qualified_type_name, \
     uses_enum, uses_memory, \
     get_memory_max_entry_value_hex_string, get_memory_width_bytes, \
-    get_field_default_value, get_enum_values
+    get_field_default_value, get_enum_values, get_properties_to_include, get_reg_fields
 
 from .lib import get_array_typecode
 
@@ -291,7 +292,8 @@ def __export_reg_model(self,  # pylint: disable=too-many-arguments
                            skip_lib_copy: bool,
                            asyncoutput: bool,
                            legacy_block_access: bool,
-                           show_hidden: bool) -> None:
+                           show_hidden: bool,
+                           udp_to_include: Optional[List[str]]) -> None:
 
         context = {
             'print': print,
@@ -304,11 +306,14 @@ def __export_reg_model(self,  # pylint: disable=too-many-arguments
             'systemrdlMemNode': MemNode,
             'systemrdlAddressableNode': AddressableNode,
             'systemrdlSignalNode': SignalNode,
+            'systemrdlUserEnum': UserEnum,
+            'systemrdlUserStruct': UserStruct,
             'asyncoutput': asyncoutput,
             'OnWriteType': OnWriteType,
             'OnReadType': OnReadType,
             'PropertyReference': PropertyReference,
             'isinstance': isinstance,
+            'str': str,
             'uses_enum' : uses_enum(top_block),
             'uses_memory' : uses_memory(top_block),
             'get_fully_qualified_type_name': self._lookup_type_name,
@@ -323,6 +328,7 @@ def __export_reg_model(self,  # pylint: disable=too-many-arguments
             'get_table_block': get_table_block,
             'get_reg_writable_fields': get_reg_writable_fields,
             'get_reg_readable_fields': get_reg_readable_fields,
+            'get_reg_fields' : get_reg_fields,
             'get_memory_max_entry_value_hex_string': get_memory_max_entry_value_hex_string,
             'get_memory_width_bytes': get_memory_width_bytes,
             'get_field_default_value': get_field_default_value,
@@ -332,7 +338,12 @@ def __export_reg_model(self,  # pylint: disable=too-many-arguments
             'skip_lib_copy': skip_lib_copy,
             'version': __version__,
             'legacy_block_access': legacy_block_access,
-            'show_hidden': show_hidden
+            'show_hidden': show_hidden,
+            'udp_to_include': udp_to_include,
+            'get_properties_to_include': get_properties_to_include,
+            'dependent_property_enum':
+                self._get_dependent_property_enum(node=top_block,
+                                                  udp_to_include=udp_to_include)
         }
         if legacy_block_access is True:
             context['get_array_typecode'] = get_array_typecode
@@ -437,7 +448,8 @@ def __export_tests(self,  # pylint: disable=too-many-arguments
                        skip_lib_copy: bool,
                        asyncoutput: bool,
                        legacy_block_access: bool,
-                       show_hidden: bool) -> None:
+                       show_hidden: bool,
+                       udp_to_include: Optional[List[str]]) -> None:
         """
 
         Args:
@@ -492,7 +504,11 @@ def is_reg_array(item: RegNode) -> bool:
                 'systemrdlMemNode': MemNode,
                 'systemrdlRegfileNode': RegfileNode,
                 'systemrdlAddrmapNode': AddrmapNode,
+                'systemrdlUserEnum': UserEnum,
+                'systemrdlUserStruct': UserStruct,
                 'isinstance': isinstance,
+                'type': type,
+                'str': str,
                 'get_python_path_segments': get_python_path_segments,
                 'safe_node_name': safe_node_name,
                 'uses_memory': (len(owned_elements.memories) > 0),
@@ -512,7 +528,12 @@ def is_reg_array(item: RegNode) -> bool:
                 'version': __version__,
                 'get_array_typecode': get_array_typecode,
                 'legacy_block_access': legacy_block_access,
-                'show_hidden': show_hidden
+                'show_hidden': show_hidden,
+                'udp_to_include': udp_to_include,
+                'get_properties_to_include': get_properties_to_include,
+                'dependent_property_enum':
+                    self._get_dependent_property_enum(node=top_block,
+                                                      udp_to_include=udp_to_include)
             }
 
 
@@ -532,7 +553,8 @@ def export(self, node: Node, path: str,  # pylint: disable=too-many-arguments
                delete_existing_package_content: bool = True,
                skip_library_copy: bool = False,
                legacy_block_access: bool = True,
-               show_hidden: bool = False) -> List[str]:
+               show_hidden: bool = False,
+               user_defined_properties_to_include: Optional[List[str]] = None) -> List[str]:
         """
         Generated Python Code and Testbench
 
@@ -560,6 +582,9 @@ def export(self, node: Node, path: str,  # pylint: disable=too-many-arguments
                                  set to true will not be included in the generated python code.
                                  This behaviour can be overridden by setting this property to
                                  true.
+            user_defined_properties_to_include : A list of strings of the names of user-defined
+                                                 properties to include. Set to None for nothing
+                                                 to appear.
 
         Returns:
             List[str] : modules that have been exported:
@@ -584,11 +609,28 @@ def export(self, node: Node, path: str,  # pylint: disable=too-many-arguments
                            include_libraries=not skip_library_copy)
         package.create_empty_package(cleanup=delete_existing_package_content)
 
+        if user_defined_properties_to_include is not None:
+            # the list of user defined properties may not include the names used by peakrdl python
+            # for control behaviours
+            if not isinstance(user_defined_properties_to_include, list):
+                raise TypeError(f'The user_defined_properties_to_include must be a list, got '
+                                f'{type(user_defined_properties_to_include)}')
+            for entry in user_defined_properties_to_include:
+                if not isinstance(entry, str):
+                    raise TypeError('The entries in the user_defined_properties_to_include must '
+                                    f'be a str, got {type(entry)}')
+            reserved_names = ['python_hide', 'python_name']
+            for reserved_name in reserved_names:
+                if reserved_name in user_defined_properties_to_include:
+                    raise RuntimeError('It is not permitted to expose a property name used to'
+                                       ' build the peakrdl-python wrappers: '+reserved_name)
+
         self._build_node_type_table(top_block, show_hidden)
 
         self.__export_reg_model(top_block=top_block, package=package, asyncoutput=asyncoutput,
                                 skip_lib_copy=skip_library_copy,
-                                legacy_block_access=legacy_block_access, show_hidden=show_hidden)
+                                legacy_block_access=legacy_block_access, show_hidden=show_hidden,
+                                udp_to_include=user_defined_properties_to_include)
 
         self.__export_simulator(top_block=top_block, package=package, asyncoutput=asyncoutput,
                                 skip_lib_copy=skip_library_copy,
@@ -608,7 +650,8 @@ def export(self, node: Node, path: str,  # pylint: disable=too-many-arguments
             self.__export_tests(top_block=top_block, package=package, asyncoutput=asyncoutput,
                                 skip_lib_copy=skip_library_copy,
                                 legacy_block_access=legacy_block_access,
-                                show_hidden=show_hidden)
+                                show_hidden=show_hidden,
+                                udp_to_include=user_defined_properties_to_include)
 
         return top_block.inst_name
 
@@ -719,3 +762,43 @@ def _get_dependent_enum(self, node: AddressableNode, show_hidden: bool) -> \
                     if fully_qualified_enum_name not in enum_needed:
                         enum_needed.append(fully_qualified_enum_name)
                         yield field_enum, child_node
+
+    def _get_dependent_property_enum(self, node: AddressableNode,
+                                     udp_to_include: Optional[List[str]]) -> \
+            List[UserEnumMeta]:
+        """
+        iterable of enums which is used by a descendant of the input node,
+        this list is de-duplicated
+        """
+        if udp_to_include is None:
+            return []
+
+        enum_needed = []
+
+        def update_enum_list(node_to_process: AddressableNode) -> None:
+
+            def walk_property_struct_node(value: Any) -> None:
+                if isinstance(value, UserEnum) and type(value) not in enum_needed:
+                    enum_needed.append(type(value))
+
+                if isinstance(value, UserStruct):
+                    for sub_value in value.members.values():
+                        walk_property_struct_node(sub_value)
+
+            node_properties = get_properties_to_include(node=node_to_process,
+                                                        udp_to_include=udp_to_include)
+            for node_property_name in node_properties:
+                node_property = node_to_process.get_property(node_property_name)
+                if isinstance(node_property, UserEnum) and type(node_property) not in enum_needed:
+                    enum_needed.append(type(node_property))
+
+                if isinstance(node_property, UserStruct):
+                    for sub_value in node_property.members.values():
+                        walk_property_struct_node(sub_value)
+
+        update_enum_list(node_to_process=node)
+
+        for child_node in node.descendants():
+            update_enum_list(node_to_process=child_node)
+
+        return enum_needed

src/peakrdl_python/lib/__init__.py

@@ -108,3 +108,4 @@
 from .utility_functions import get_array_typecode
 from .utility_functions import UnsupportedWidthError
 from .base import Node
+from .base import UDPStruct

src/peakrdl_python/lib/async_register.py

@@ -96,6 +96,14 @@ def _callbacks(self) -> Union[AsyncCallbackSet, AsyncCallbackSetLegacy]:
 
         raise TypeError(f'unhandled parent callback type: {type(self.parent._callbacks)}')
 
+    @property
+    @abstractmethod
+    def fields(self) -> \
+            Iterator[Union['FieldAsyncReadOnly','FieldAsyncWriteOnly', 'FieldAsyncReadWrite']]:
+        """
+        generator that produces has all the fields within the register
+        """
+
 
 class RegAsyncReadOnly(AsyncReg, ABC):
     """