Merge pull request #85 from krcb197/75-context-manager-for-doing-multiple-operations-to-the-same-register

Context Manager and Readback Verify

Author: krcb197

docs/generated_package.rst

@@ -241,8 +241,31 @@ simulator.
 .. literalinclude :: ../example/simulating_callbacks/flashing_the_LED.py
    :language: python
 
+Optimised Access
+----------------
+
+Each time the ``read`` or ``write`` method for a register field is accessed the hardware is read
+and or written (a write to a field will normally require a preceding read). When accessing multiple
+fields in the same register, it may be desirable to use one of the optimised access methods.
+
+Consider the following example of an GPIO block with 4 GPIO pins (configured in a single register):
+
+.. literalinclude :: ../example/optimised_access/optimised_access.rdl
+   :language: systemrdl
+
+In the to configure gpio_0 and gpio_1 whilst leaving the other two unaffected it can be done in two
+methods:
+
+* using the ``write_fields`` method of the register
+* using the register context manager
+
+Both demonstrated in the following code example:
+
+.. literalinclude :: ../example/optimised_access/optimised_access.py
+   :language: python
+
 Walking the Structure
-=====================
+---------------------
 
 The following two example show how to use the generators within the register abstraction layer
 package to traverse the structure.
@@ -261,7 +284,7 @@ a file called ``chip_with_registers.rdl``:
     peakpython chip_with_registers.rdl --outdir chip_with_registers --test
 
 Traversing without Unrolling Loops
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The first example is reading all the readable registers from the register map and writing them
 into a JSON file. To exploit the capabilities of a JSON file the arrays of registers and
@@ -353,7 +376,7 @@ This will create a JSON file as follows:
     }
 
 Traversing without Unrolling Loops
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The second example is setting every register in the address map back to its default values. In
 this case the loops are unrolled to conveniently access all the register without needing to

example/optimised_access/optimised_access.py

@@ -0,0 +1,63 @@
+"""
+PeakRDL Python example to show the different methods to access the fields of a register
+"""
+from optimised_access.reg_model.optimised_access import optimised_access_cls, \
+    optimised_access_gpio_direction_enc_enumcls
+
+from optimised_access.lib import CallbackSet
+
+# dummy functions to demonstrate the class
+def read_addr_space(addr: int, width: int, accesswidth: int) -> int:
+    """
+    Callback to simulate the operation of the package, everytime the read is called, it return
+    an integer value of 0
+
+    Args:
+        addr: Address to write to
+        width: Width of the register in bits
+        accesswidth: Minimum access width of the register in bits
+
+    Returns:
+        value inputted by the used
+    """
+    return int(0)
+
+
+def write_addr_space(addr: int, width: int, accesswidth: int, data: int) -> None:
+    """
+    Callback to simulate the operation of the package, everytime the read is called, it will
+    request the user input the value to be read back.
+
+    Args:
+        addr: Address to write to
+        width: Width of the register in bits
+        accesswidth: Minimum access width of the register in bits
+        data: value to be written to the register
+
+    Returns:
+        None
+    """
+    print(f'0x{data:X} written to 0x{addr:X}')
+
+if __name__ == '__main__':
+
+    # create an instance of the address map with the simulated callback necessary to demonstrate
+    # the example
+    dut = optimised_access_cls(callbacks=CallbackSet(read_callback=read_addr_space,
+                                                        write_callback=write_addr_space))
+
+    # configure the GPIO 0 and GPIO 1 without affecting the state of the GPIO 2 and GPIO 3
+    # configuration.
+
+    # This can be done either using the ``write_fields`` method
+    dut.gpio_register.write_fields(gpio_0_dir=optimised_access_gpio_direction_enc_enumcls.GPIO_OUT,
+                                   gpio_0_pullup=False,
+                                   gpio_0_strength=2,
+                                   gpio_1_dir=optimised_access_gpio_direction_enc_enumcls.GPIO_IN)
+
+    # It can also be done with the context manager
+    with dut.gpio_register.single_read_modify_write() as reg:
+        reg.gpio_0_dir.write(optimised_access_gpio_direction_enc_enumcls.GPIO_OUT)
+        reg.gpio_0_pullup.write(False)
+        reg.gpio_0_strength.write(2)
+        reg.gpio_0_dir.write(optimised_access_gpio_direction_enc_enumcls.GPIO_IN)

example/optimised_access/optimised_access.rdl

@@ -0,0 +1,34 @@
+addrmap optimised_access {
+
+    enum gpio_direction_enc {
+			gpio_in = 0;
+			gpio_out = 1;
+		};
+
+    field gpio_direction { encode = gpio_direction_enc; fieldwidth=1; };
+    field gpio_drive_str { fieldwidth=2; };
+    field gpio_pullup { fieldwidth=1; };
+
+
+    reg {
+        default sw = rw;
+        default hw = r;
+
+        gpio_direction gpio_0_dir;
+        gpio_drive_str gpio_0_strength;
+        gpio_pullup gpio_0_pullup;
+
+        gpio_direction gpio_1_dir;
+        gpio_drive_str gpio_1_strength;
+        gpio_pullup gpio_1_pullup;
+
+        gpio_direction gpio_2_dir;
+        gpio_drive_str gpio_2_strength;
+        gpio_pullup gpio_2_pullup;
+
+        gpio_direction gpio_3_dir;
+        gpio_drive_str gpio_3_strength;
+        gpio_pullup gpio_3_pullup;
+
+    } gpio_register;
+};

src/peakrdl_python/__about__.py

@@ -1,4 +1,4 @@
 """
 Variables that describes the PeakRDL Python Package
 """
-__version__ = "0.3.12"
+__version__ = "0.3.13"

src/peakrdl_python/templates/addrmap.py.jinja

@@ -7,6 +7,8 @@ from typing import Optional
 from typing import Union
 from typing import cast
 from typing import Dict
+from typing import Generator
+from contextlib import contextmanager
 
 from ..lib import AddressMap, RegFile, Memory
 from ..lib  import AddressMapArray, RegFileArray

src/peakrdl_python/templates/addrmap_field.py.jinja

@@ -85,7 +85,7 @@ class {{get_fully_qualified_type_name(node)}}_cls({%- if 'encode' in node.list_p
 
         This returns None:
         - if the field is not reset.
-        - if the register resets to a signal value tht can not be determined
+        - if the register resets to a signal value that can not be determined
         """
         int_default = super().default
 

src/peakrdl_python/templates/addrmap_register.py.jinja

@@ -54,14 +54,17 @@ class {{get_fully_qualified_type_name(node)}}_cls(RegWriteOnly):
         """
         read the register and return a dictionary of the field values
         """
-        reg_value = self.read()
-
-        return_dict = {
-                        {%- for child_node in get_reg_readable_fields(node) %}
-                        '{{child_node.inst_name}}' : self.{{safe_node_name(child_node)}}.decode_read_value(reg_value)
-                        {%- if not loop.last -%} ,  {%- endif -%}
-                        {% endfor %}
-                      }
+        {% if node.has_sw_writable %}
+        with self.single_read_modify_write(skip_write=True) as reg:
+        {% else %}
+        with self.single_read() as reg:
+        {% endif %}
+            return_dict = {
+                            {%- for child_node in get_reg_readable_fields(node) %}
+                            '{{child_node.inst_name}}' : reg.{{safe_node_name(child_node)}}.read()
+                            {%- if not loop.last -%} ,  {%- endif -%}
+                            {% endfor %}
+                          }
 
         return return_dict
 
@@ -74,6 +77,18 @@ class {{get_fully_qualified_type_name(node)}}_cls(RegWriteOnly):
         yield self.{{safe_node_name(child_node)}}
         {% endfor %}
 
+    {# context manager #}
+    {% if node.has_sw_writable %}
+    @contextmanager
+    def single_read_modify_write(self, verify:bool = False, skip_write: bool = False) -> Generator['{{get_fully_qualified_type_name(node)}}_cls', None, None]:
+        """
+        Context Manager to do multiple accesses using a single read/modify write operation
+        """
+        with super().single_read_modify_write(verify=verify, skip_write=skip_write) as reg:
+           yield reg
+    {% endif %}
+
+
     {% endif %}
 
     {% if node.has_sw_writable %}
@@ -92,25 +107,20 @@ class {{get_fully_qualified_type_name(node)}}_cls(RegWriteOnly):
         Do a read-modify-write to the register, updating any field included in
         the arguments
         """
-
         if len(kwargs) == 0:
             raise ValueError('no command args')
 
-        bit_mask = 0
-        reg_value = 0
+        with self.single_read_modify_write() as reg:
         {%- for child_node in get_reg_writable_fields(node) %}
-        if '{{safe_node_name(child_node)}}' in kwargs:
-            reg_value |= self.{{safe_node_name(child_node)}}.encode_write_value(kwargs['{{safe_node_name(child_node)}}'])
-            bit_mask |= self.{{safe_node_name(child_node)}}.bitmask
-            kwargs.pop('{{safe_node_name(child_node)}}')
+            if '{{safe_node_name(child_node)}}' in kwargs:
+                self.{{safe_node_name(child_node)}}.write(kwargs['{{safe_node_name(child_node)}}'])
+                kwargs.pop('{{safe_node_name(child_node)}}')
         {%- endfor %}
-        if len(kwargs) != 0:
-            # left over unhandled arguments
-            raise ValueError('unrecognised arguments in field')
+            if len(kwargs) != 0:
+                # left over unhandled arguments
+                raise ValueError('unrecognised arguments in field')
 
-        inverse_bit_mask = self.max_value ^ bit_mask
 
-        self.write((self.read() & inverse_bit_mask) | reg_value)
 
     {% else %}
     def write_fields(self, {%- for child_node in node.fields() -%} {{safe_node_name(child_node)}} : {%- if 'encode' in child_node.list_properties() %}{{get_fully_qualified_enum_type(child_node.get_property('encode'), top_node.parent)}}_enumcls{% else %}int{% endif %}{%- if not loop.last -%},{%- endif -%}{%- endfor -%}) -> None: # type: ignore[override]