Merge pull request #142 from krcb197/104-hidden-and-reserved-items

104 hidden items

Author: krcb197

.github/workflows/action.yaml

@@ -8,7 +8,9 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
+    branches:
+    - main
+    - 0.9.0
   schedule:
     - cron: '00 6 1 * *'
   release:
@@ -152,10 +154,15 @@ jobs:
         run: |
 
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw/
+          peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw/
+          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/
           python -m unittest discover -s peakrdl_out/raw
+
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw_async/ --async
+          peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw_async/ --async
+          peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw_async/show_hidden/ --show_hidden --async
           python -m unittest discover -s peakrdl_out/raw_async
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw_legacy/ --legacy_block_access
           python -m unittest discover -s peakrdl_out/raw_legacy

docs/generated_package.rst

@@ -109,7 +109,7 @@ Legacy Block Callback and Block Access
 
 .. versionchanged:: 0.9.0
 
-   Previous versions of peakrdl python used the python ``array.array`` for efficiently moving blocks
+   Previous versions of PeakRDL Python used the python ``array.array`` for efficiently moving blocks
    of data. This was changed in version 0.9.0 in order to accommodate memories which were larger
    than 64 bit wide which could not be supported as the array type only support entries of up to
    64 bit.
@@ -120,19 +120,20 @@ Legacy Block Callback and Block Access
 
       It could have left this as a future compatibility mode before making a breaking change but
       that would just delay the pain it was felt to be better to get as many users onto the new
-      API as soon as possible whilst peakrdl-python is in beta.
+      API as soon as possible whilst PeakRDL Python is in beta.
 
    If you really want to just keep on with the array based interface and make only minimal changes
    to existing code, there are two simple steps:
+
    1. The northbound interfaces that are provided by the generated package expect lists of integers
       rather than array. The old interfaces can be retained by using the ``legacy_block_access``
       build option.
    2. The southbound interfaces into the callbacks again need to use lists for the
       ``read_block_callback`` and ``write_block_callback`` methods. If you want to continue to use
       the old scheme use the following callback classes which are part of the callbacks:
       * ``NormalCallbackSetLegacy`` for standard python function callbacks
-      * ``AsyncCallbackSetLegacy`` for async python function callbacks, these are called from the
-        library using ``await``
+      * ``AsyncCallbackSetLegacy`` for async python function callbacks, these are called from the library using ``await``
+
 
 Using the Register Access Layer
 ===============================
@@ -200,7 +201,9 @@ The following example shows the usage of the enumeration
 Array Access
 ------------
 
-SystemRDL supports multi-dimensional arrays, the following example shows an definition with an 1D and 3D array with various methods to access individual elements of the array and use of the iterators to walk through elements in loops
+SystemRDL supports multi-dimensional arrays, the following example shows an definition with an 1D
+and 3D array with various methods to access individual elements of the array and use of the
+iterators to walk through elements in loops
 
 .. literalinclude :: ../example/array_access/array_access.rdl
    :language: systemrdl
@@ -386,7 +389,9 @@ Python Safe Names
 The systemRDL structure is converted to a python class structure, there are two concerns:
 
 * if any systemRDL node name is a python keyname
-* if any systemRDL node name clashes with part of the peakrdl_standard types, for example all register nodes have an ``address`` property that would clash with a field of that register called ``address``
+* if any systemRDL node name clashes with part of the peakrdl_standard types, for example all
+  register nodes have an ``address`` property that would clash with a field of that register
+  called ``address``
 
 consider the following example:
 
@@ -430,6 +435,55 @@ field from the example above
 .. literalinclude :: ../example/overridden_names/demo_over_ridden_names.py
    :language: python
 
+Hidden Elements
+===============
+
+Commonly some parts of the register map want to be hidden from some users, for example register
+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
+items that should not appear in the generated python wrappers.
+
+In the following example, python wrapper generated would have the registers:
+
+* ``explictly_visible_reg``
+* ``implicitly_visible_reg``
+
+However the ``hidden_reg`` would not be included in the python wrappers
+
+.. code-block:: systemrdl
+
+   property python_hide { type = boolean; component = addrmap | regfile | reg | field | mem; };
+
+   addrmap my_addr_map {
+
+       reg {
+           default sw = rw;
+           default hw = r;
+           python_hide = true;
+           field { fieldwidth=1; } field_a;
+       } hidden_reg;
+
+      reg {
+           default sw = rw;
+           default hw = r;
+           python_hide = false;
+           field { fieldwidth=1; } field_a;
+       } explictly_visible_reg;
+
+      reg {
+           default sw = rw;
+           default hw = r;
+           field { fieldwidth=1; } field_a;
+       } implicitly_visible_reg;
+
+   };
+
+The ``python_hide`` property can be overridden with the ``show_hidden`` argument to the peakrdl
+command line tool or the ``export`` method.
 
 Autoformating
 =============
@@ -454,7 +508,7 @@ PeakRDL Python also generates an simulator, this can be used to test and develop
 generated package. The simulator is used in a the examples shown earlier in this section. The
 simulator has the option to attach a callback to the read and write operations of either a
 register or field. In addition there is a ``value`` property that allows access to the register
-or feild content, this allows the contents to be accessed or updated without activating the
+or field content, this allows the contents to be accessed or updated without activating the
 callbacks, this is intended to allow the simulator to be extended with behaviour that is not
 fully described by the systemRDL.
 

docs/index.rst

@@ -38,7 +38,7 @@ At some point another software component called a Hardware Abstraction Layer (HA
 get produced that abstracts the device function providing functions to do more useful things.
 The RAL could be used as part of a HAL.
 
-.. note:: The Hardware Abstraction Layer (HAL) provides abstact functionality and allows
+.. note:: The Hardware Abstraction Layer (HAL) provides abstract functionality and allows
           people to use the device without needing a full knowledge of how it works.
 
 What does it do
@@ -91,7 +91,7 @@ manipulations
 .. warning:: A Register Access Layer (RAL) is not for everyone. Some engineers like to see the
              address of each register and the content of a register as a hex word. You may be quite
              happy with this, if that is you please stop, the overhead of an extra
-             layer, its opaque nature and inefficency will annoy you.
+             layer, its opaque nature and inefficiency will annoy you.
 
 In order to move on the systemRDL code for the registers needs to exist
 
@@ -111,7 +111,7 @@ Once built, a set of test cases can be run on the code to confirm its integrity,
 
    python -m unittest discover -s gpio\tests -t .
 
-Using the RAL allows for much simipler to understand code that does the function that was intended
+Using the RAL allows for much simpler to understand code that does the function that was intended
 
 .. literalinclude :: ../example/why_ral/with_ral.py
    :language: python

src/peakrdl_python/__about__.py

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

src/peakrdl_python/__peakrdl__.py

@@ -64,14 +64,19 @@ def add_exporter_arguments(self, arg_group: 'argparse._ActionsContainer') -> Non
                                     'files found in the directory where the package will be'
                                     ' generated. This is normally useful if the user is '
                                     'generating over the top of an existing package and prevents '
-                                    'problems when the strucutre of the register map changes. '
+                                    'problems when the structure of the register map changes. '
                                     'However, if additional python files are added by the user '
                                     '(not recommended) this cleanup will need to be suppressed '
                                     'and managed by the user')
         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')
+        arg_group.add_argument('--show_hidden', action='store_true',
+                               dest='show_hidden',
+                               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')
 
     def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> None:
         """
@@ -94,5 +99,6 @@ def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> N
             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
+            legacy_block_access=options.legacy_block_access,
+            show_hidden=options.show_hidden
         )

src/peakrdl_python/_node_walkers.py

@@ -28,49 +28,79 @@ 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) -> None:
+    def __init__(self, show_hidden: bool) -> None:
         super().__init__()
         self.__address_maps: List[AddrmapNode] = []
+        self.__show_hidden = show_hidden
 
     def enter_Addrmap(self, node: AddrmapNode) -> Optional[WalkerAction]:
+        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+            return WalkerAction.SkipDescendants
+
         self.__address_maps.append(node)
         return WalkerAction.Continue
 
     def __iter__(self) -> Iterator[AddrmapNode]:
         return self.__address_maps.__iter__()
 
 
+# pylint: disable=too-many-instance-attributes
 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) -> None:
+    def __init__(self, show_hidden: bool) -> None:
         super().__init__()
 
         self.registers: List[RegNode] = []
         self.fields: List[RegNode] = []
         self.memories: List[RegNode] = []
         self.addr_maps: List[AddrmapNode] = []
         self.reg_files: List[RegfileNode] = []
+        self._hidden_registers: List[RegNode] = []
+        self._hidden_fields: List[RegNode] = []
+        self._hidden_memories: List[RegNode] = []
+        self._hidden_addr_maps: List[AddrmapNode] = []
+        self._hidden_reg_files: List[RegfileNode] = []
+        self.__show_hidden = show_hidden
 
     def enter_Reg(self, node: RegNode) -> Optional[WalkerAction]:
+        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+            self._hidden_registers.append(node)
+            return WalkerAction.SkipDescendants
+
         self.registers.append(node)
         return WalkerAction.Continue
 
     def enter_Mem(self, node: MemNode) -> Optional[WalkerAction]:
+        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+            self._hidden_memories.append(node)
+            return WalkerAction.SkipDescendants
+
         self.memories.append(node)
         return WalkerAction.Continue
 
     def enter_Field(self, node: FieldNode) -> Optional[WalkerAction]:
+        if node.get_property('python_hide', default=False) and not self.__show_hidden:
+            self._hidden_fields.append(node)
+            return WalkerAction.SkipDescendants
+
         self.fields.append(node)
         return WalkerAction.Continue
 
     def enter_Addrmap(self, node: AddrmapNode) -> Optional[WalkerAction]:
-        self.addr_maps.append(node)
+        if not node.get_property('python_hide', default=False) or self.__show_hidden:
+            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:
+            self._hidden_reg_files.append(node)
+            return WalkerAction.SkipDescendants
+
         self.reg_files.append(node)
         return WalkerAction.Continue
 
@@ -89,6 +119,29 @@ def nodes(self) -> List[Union[RegNode, MemNode, FieldNode, AddrmapNode, RegfileN
         """
         return self.addr_maps + self.reg_files + self.memories + self.registers + self.fields
 
+    @property
+    def hidden_nodes(self) -> List[Union[RegNode, MemNode, FieldNode, AddrmapNode, RegfileNode]]:
+        """
+        All the 1st tier nodes owned by the address map which are hidden, including:
+        - address maps
+        - register files
+        - registers
+        - memories
+        - fields
+
+        Returns: list of nodes
+
+        """
+        return self._hidden_addr_maps + self._hidden_reg_files + self._hidden_memories + \
+               self._hidden_registers + self._hidden_fields
+
+    @property
+    def has_hidden_nodes(self) -> bool:
+        """
+        If there are 1st tier hidden nodes in the address map
+        """
+        return len(self.hidden_nodes) > 0
+
     @property
     def addressable_nodes(self) -> List[Union[RegNode, MemNode, AddrmapNode, RegfileNode]]:
         """
@@ -102,3 +155,4 @@ def addressable_nodes(self) -> List[Union[RegNode, MemNode, AddrmapNode, Regfile
 
         """
         return self.addr_maps + self.reg_files + self.memories + self.registers
+# pylint: enable=too-many-instance-attributes