305 enhancement to avoid read on read write registers

README.md

@@ -139,4 +139,14 @@ some legacy features from the early versions were removed in release 4.0.0, the
   This had some restrictions, so a new methodology based on the `list` type was introduced in version 0.9.
   The old array based behaviour was removed in this version
 
+This release also improved the features for write-only register:
+- field write operations no longer have a hard-code base value of `0` in the register, the base register value is configurable via the `write_initial_state` property
+- the `write_fields` methods also uses the `write_initial_state` property to allow other bits in the register to be set if needed, rather than a hardcoded `0`
+- A new `single_write` context manager can be used to set multiple field values in a single write with a configurable initial register state
+
+The read/write register class has similar feature:
+- A new `single_write` context manager that does not use a read before the write to set multiple field values in a single write with a configurable initial register state
+- A new `write_all_fields_without_read` method tht will write all the writable fields with the `write_initial_state` property to allow other bits in the register to be set if needed
+
+
 

docs/generated_package/callbacks.rst

@@ -0,0 +1,113 @@
+Callbacks
+*********
+
+The Register Access Layer will typically interfaced to a driver that
+allows accesses the chip.
+
+.. tip:: The simulator generated with the register model can be used as an alternative to
+         a hardware connection
+
+In order to operate the register access layer typically requires the following:
+
+- A callback for a single register write, this not required if there is no writable register in
+  the register access layer
+- A callback for a single register read, this not required if there is no writable register in
+  the register access layer
+
+In addition the register access layer can make use of block operations where a block of the
+address space is read in a single transaction. Not all drivers support these
+
+The examples of these two methods are included within the generated register
+access layer package so that it can be used from the console:
+
+.. code-block:: python
+
+    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 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
+
+        Returns:
+            value inputted by the used
+        """
+        assert isinstance(addr, int)
+        assert isinstance(width, int)
+        assert isinstance(accesswidth, int)
+        return input('value to read from address:0x%X' % addr)
+
+    def write_addr_space(addr: int, width: int, accesswidth: int, data: int) -> None:
+        """
+        Callback to simulate the operation of the package, everytime the write is called, it will
+        print out the result.
+
+        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
+        """
+        assert isinstance(addr, int)
+        assert isinstance(width, int)
+        assert isinstance(accesswidth, int)
+        assert isinstance(data, int)
+        print('write data:0x%X to address:0x%X' % (data, addr))
+
+In a real system these call backs will be connected to a driver.
+
+In addition there is also an option to use ``async`` callbacks if the package is built
+``asyncoutput`` set to True.
+
+Callback Set
+============
+
+The callbacks are passed into the register access layer using either:
+
+* ``NormalCallbackSet`` for standard python function callbacks
+* ``AsyncCallbackSet`` for async python function callbacks, these are called from the library using
+  ``await``
+
+Legacy Block Callback and Block Access
+======================================
+
+.. versionchanged:: 0.9.0
+
+   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.
+
+   .. warning::
+      The developers apologise for making a breaking change, however, not being able to fully the
+      systemRDL specification was determined to be a major limitation that needed to be addressed.
+
+      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.
+
+   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``
+
+.. versionchanged:: 3.0.0
+
+    The ``legacy_block_access`` will now default to ``False``
+
+.. versionchanged:: 4.0.0
+
+    The ``legacy_block_access`` was removed, the ``NormalCallbackSetLegacy`` and ``AsyncCallbackSetLegacy`` are no longer supported

docs/generated_package/output_structure.rst

@@ -0,0 +1,123 @@
+Output Structure
+****************
+
+PeakRDL Python generates a python Register Access Layer (RAL) from a System RDL design. The
+generated python code is contained in a package, structured as shown below. The ``root_name``
+will be based on the top level address map name with the package was generated
+
+| ``<root_name>``
+| ├── ``lib``
+| ├── ``lib_test``
+| ├── ``sim_lib``
+| ├── ``reg_model``
+| │ └── ``<root_name>.py``
+| ├── ``sim``
+| │ └── ``<root_name>.py``
+| └── ``tests``
+|   └── ``test_<root_name>.py``
+
+In the folder structure above:
+
+- ``<root_name>.py`` - This is the register access layer code for the design
+- ``test_<root_name>.py`` - This is a set of autogenerated unittests to verify the register access layer (The unit test generation can be skipped, see ``skip_test_case_generation``)
+- ``lib`` - This is a package of base classes used by the register access layer (The copy of this can be skipped, see :ref:`skipping-lib-copy`)
+- ``lib_test`` - This is a package of base classes autogenerated unit tests (The copy of this can be skipped, see :ref:`skipping-lib-copy`)
+- ``sim_lib`` - This is a package of base classes used by the register access layer simulator (The copy of this can be skipped, see :ref:`skipping-lib-copy`)
+
+.. versionchanged:: 2.0.0
+
+    The ``reg_model`` was changed in version 2.0.0 to split it out into multiple modules rather
+    than building the whole register model in a single python module. This helps avoid
+    excessively large files which helps speed up the generation and loading time.
+
+.. versionchanged:: 3.0.0
+
+    The auto-generated unit tests were changed in version 3.0.0 to split to make use
+    of a test library, which significantly reduced the size of the generated code.
+
+Top Level Classes
+=================
+
+.. versionchanged:: 2.0.0
+
+    A new class aliases were added to the ``reg_model`` and ``sim`` packages to allow the register
+    model and simulator to be imported more easily. See the example below using ``RegModel`` and
+    ``Simulator``.
+
+Class Names
+===========
+
+.. versionchanged:: 2.0.0
+
+    In order to reduce duplication within the generated model a hashing algortihm is applied to the
+    nodes in the design to determine which nodes are unique. This hash is appended to the name
+    of all the python classes in the register model
+
+.. versionadded:: 2.1.0
+
+    There are two possible algorithms for the hashing, this is selectable by the user:
+
+    * The builtin python ``hash`` function, this is fast but is a salted hash so changes hashes export to
+      export
+    * Use the ``SHA256`` hash from the python ``hashlib`` standard library, this may slow down the export
+      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
+
+    .. tip::
+
+        Use the default builtin ``hash`` option unless you need to use the alternative
+
+Unit Tests
+==========
+
+In addition to the Register Model a set od unit tests are made that test that the register model has been
+built correctly
+
+Running the Unit Tests
+----------------------
+
+There are many ways to run Python Unit tests. A good place to start is the ``unittest`` module
+included in the Python standard installation.
+
+
+Simulator
+=========
+
+PeakRDL Python also generates an simulator, this can be used to test and develop using the
+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 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.
+
+.. warning:: The PeakRDL Python simulator is not intended to replace an RTL simulation of the
+             design. It does not simulate the hardware, it is intended as a simple tool for
+             development and testing of the python wrappers or code that uses them.
+
+.. _skipping-lib-copy:
+
+Skipping the Library Copy
+=========================
+
+In some cases it may be desirable to skip the copy of the library from the generated pacakge.
+This may be useful in development of PeakRDL-python. It can also be used to avoid distributing
+licensed code.
+
+.. warning:: If the libraries are not distributed with the package, it is very important to
+             ensure users download the matching version of the PeakRDL-python package to use it
+
+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
+post-generation. Previous versions of peakrdl-python included the option to run an autoformatter
+to clean up the generated code. This had two issues:
+
+* It created maintenance issues when the autoformatter changed
+* The choice of autoformatter is an individual one, rather than force an autoformatter on people
+  it is better to let people choose their own.
+
+peakrdl-python uses the Black `Black <https://pypi.org/project/black/L>`_ in the CI tests to check
+that the generated code is compatible with an autoformatter.