peakrdl-python 0.7.3__tar.gz → 0.7.5__tar.gz

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/.github/workflows/action.yaml

@@ -36,6 +36,7 @@ jobs:
           python -m pip install -U pylint
 
       - name: Run Lint
+        #run: pylint --rcfile tests/pylint.rc src/peakrdl_python tests/unit_tests
         run: pylint --rcfile tests/pylint.rc src/peakrdl_python
 
   mypy:
@@ -59,6 +60,7 @@ jobs:
     needs:
       - mypy
       - lint
+
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -77,10 +79,9 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install .
 
-
     - name: Run Unit Tests
       run: |
-        python -m unittest discover -s tests/unit_tests
+        python -m unittest discover -s tests/unit_tests -t .
 
     - name: Generate testcases
       run: |
@@ -150,6 +151,21 @@ jobs:
         python -m demo_array_access
 
         cd ../..
+
+        cd example/enumerated_fields/
+        peakrdl python enumerated_fields.rdl -o .
+        python -m demo_enumerated_fields
+
+
+        cd ../..
+
+        cd example/why_ral/
+        peakrdl python gpio.rdl -o .
+        python -m without_ral
+        python -m with_ral
+        python -m with_hal
+
+        cd ../..
   #-------------------------------------------------------------------------------
   build:
     needs:

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: peakrdl-python
-Version: 0.7.3
-Summary: Generate python wrapper for a register model compiled SystemRDL input
+Version: 0.7.5
+Summary: Generate Python Register Access Layer (RAL) from SystemRDL
 Author: Keith Brady
 License:                     GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
@@ -682,7 +682,7 @@ Project-URL: Source, https://github.com/krcb197/PeakRDL-python
 Project-URL: Tracker, https://github.com/krcb197/PeakRDL-python/issues
 Project-URL: Documentation, https://peakrdl-python.readthedocs.io/
 Project-URL: Changelog, https://github.com/krcb197/PeakRDL-python/releases
-Keywords: SystmRDL,PeakRDL,CSR,compiler,tool,registers,generator,Python
+Keywords: SystemRDL,PeakRDL,CSR,compiler,tool,registers,generator,Python
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -703,16 +703,17 @@ License-File: LICENSE
 Requires-Dist: systemrdl-compiler>=1.24.0
 Requires-Dist: jinja2
 Requires-Dist: asynctest; python_version < "3.8"
+Requires-Dist: typing-extensions; python_version < "3.11"
 
 ![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)
 [![Documentation Status](https://readthedocs.org/projects/peakrdl-python/badge/?version=latest)](https://peakrdl-python.readthedocs.io/en/latest/?badge=latest)
 [![Downloads](https://static.pepy.tech/badge/peakrdl-python)](https://pepy.tech/project/peakrdl-python)
 
-# PeakRDL-python
-Generate Python wrapper for a register model compiled SystemRDL input
+# peakrdl-python
+Generate Python Register Access Layer (RAL) from SystemRDL
 
 ## Documentation
-See the [PeakRDL Python Documentation](https://peakrdl-python.readthedocs.io/) for more details
+See the [peakrdl-python Documentation](https://peakrdl-python.readthedocs.io/) for more details
 
 

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/README.md

@@ -3,10 +3,10 @@
 [![Documentation Status](https://readthedocs.org/projects/peakrdl-python/badge/?version=latest)](https://peakrdl-python.readthedocs.io/en/latest/?badge=latest)
 [![Downloads](https://static.pepy.tech/badge/peakrdl-python)](https://pepy.tech/project/peakrdl-python)
 
-# PeakRDL-python
-Generate Python wrapper for a register model compiled SystemRDL input
+# peakrdl-python
+Generate Python Register Access Layer (RAL) from SystemRDL
 
 ## Documentation
-See the [PeakRDL Python Documentation](https://peakrdl-python.readthedocs.io/) for more details
+See the [peakrdl-python Documentation](https://peakrdl-python.readthedocs.io/) for more details
 
 

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/docs/api.rst

@@ -16,7 +16,7 @@ Example
 =======
 
 The following example shows the compiling an SystemRDL file and then generating
-the python register abstraction layer using PeakRDL Python.
+the python register access layer using PeakRDL Python.
 
 .. code-block:: python
 
@@ -28,7 +28,7 @@ the python register abstraction layer using PeakRDL Python.
     rdlc.compile_file('basic.rdl')
     spec = rdlc.elaborate(top_def_name='basic').top
 
-    # generate the python package register abstraction layer
+    # generate the python package register access layer
     exporter = PythonExporter()
     exporter.export(node=spec, path='generated_code')
 

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/docs/api_components.rst

@@ -65,7 +65,7 @@ Memories
     :inherited-members:
 
 Registers
-^^^^^^^^^
+=========
 
 .. autoclass:: peakrdl_python.lib.register.RegReadOnly
     :members:
@@ -93,6 +93,7 @@ Registers
 
 Register Fields
 ^^^^^^^^^^^^^^^
+A register will always have fields within it
 
 .. autoclass:: peakrdl_python.lib.fields.FieldReadOnly
     :members:
@@ -116,4 +117,4 @@ Register Fields
 
 .. autoclass:: peakrdl_python.lib.fields.FieldEnumReadWrite
     :members:
-    :inherited-members:
+    :inherited-members:

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/docs/command_line.rst

@@ -4,7 +4,7 @@ Command Line Interface
 PeakRDL Python can either be run from within another Python script or using the
 command line program via the PeakRDL suite
 
-In order to use the PeakRDL Suite it must be installed:
+In order to use the PeakRDL Suite it must be installed first, see :ref:`peakrdl_installation`.
 
 .. code-block:: bash
 

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/docs/customisation.rst

@@ -46,7 +46,7 @@ The path to the folder of alternative templates must be ``PythonExporter`` is in
     rdlc.compile_file('basic.rdl')
     spec = rdlc.elaborate(top_def_name='basic').top
 
-    # generate the python package register abstraction layer
+    # generate the python package register access layer
     exporter = PythonExporter(user_template_dir='my_company_headers')
     exporter.export(node=spec, path='generated_code')
 

peakrdl_python-0.7.5/docs/design_decisions.rst

@@ -0,0 +1,23 @@
+Design Decisions
+****************
+
+A collection of notes to explain some of the design decisions to potential developers and
+advanced users
+
+'Pure' Python
+=============
+
+The peakrdl-python RAL was designed to have very limited dependencies on other packages once
+deployed, this includes the peakrdl-python packages itself, so the library classes are copied
+into the generated package.
+
+It does need a few packages inorder to build it:
+
+* systemrdl-compiler
+* jinja2
+
+Integer Data Types
+===================
+
+All the APIs present memory, register and field entries as python integers. This abstracts, the
+complexity of byte ordering and reversed registers.

peakrdl_python-0.7.5/docs/design_tools.rst

@@ -0,0 +1,11 @@
+Design Tools
+************
+
+In order to assist developers peakrdl-python can be run from a script. This means the
+peakrdl-python package does not need to be installed and uninstalled during development.
+
+See ``generate_and_test.py``
+
+.. code-block:: bash
+
+    python -m generate_and_test --RDL_source_file "tests\testcases\basic.rdl" --root_node "basic"

{peakrdl-python-0.7.3 → peakrdl_python-0.7.5}/docs/generated_package.rst

@@ -3,9 +3,9 @@ Generated Package
 
 Output Structure
 ================
-PeakRDL Python generates a python packages from a System RDL design, structured
-as shown below. The ``root_name`` will be based on the top level address map name
-with the package was generated
+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``
@@ -16,11 +16,9 @@ with the package was generated
 
 In the folder structure above:
 
-- ``<root_name>.py`` - This is the register abstraction layer code for the design
-- ``lib`` - This is a package of base classes used by the register abstraction layer
-- ``test_<root_name>.py`` - This is a set of autogenerated unittests to verify the register abstraction layer
-
-
+- ``<root_name>.py`` - This is the register access layer code for the design
+- ``lib`` - This is a package of base classes used by the register access layer
+- ``test_<root_name>.py`` - This is a set of autogenerated unittests to verify the register access layer
 
 
 Running the Unit Tests
@@ -32,18 +30,18 @@ included in the Python standard installation.
 Callbacks
 =========
 
-The Register Abstraction Layer will typically interfaced to a driver that
+The Register Access Layer will typically interfaced to a driver that
 allows accesses the chip. However, it can also be interfaced to a simulation
 of the device.
 
-In order to operate the register abstraction layer typically requires the following:
+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 abstraction layer
+  the register access layer
 - A callback for a single register read, this not required if there is no writable register in
-  the register abstraction layer
+  the register access layer
 
-In addition the register abstraction layer can make use of block operations where a block of the
+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
@@ -97,16 +95,16 @@ In addition there is also an option to use ``async`` callbacks if the package is
 Callback Set
 ------------
 
-The callbacks are passed into the register abstraction layer using either:
+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``
 
-Using the Register Abstraction Layer
-====================================
+Using the Register Access Layer
+===============================
 
-The register abstraction layer package is intended to integrated into another
+The register access layer package is intended to integrated into another
 piece of code. That code could be a simple test script for blinking an LED on a
 GPIO or it could be a more complex application with a GUI.
 
@@ -131,7 +129,7 @@ a file called ``chip_with_a_GPIO.rdl``:
 
 .. tip:: It is always good practice to run the unittests on the generated code.
 
-Once the register abstraction layer has been generated and it can be used. The following example
+Once the register access layer has been generated and it can be used. The following example
 does not actually use a device driver. Instead it chip simulator with a a Tkinter GUI,
 incorporating a RED circle to represent the LED. The chip simulator has read and write methods (
 equivalent to those offered by a device driver), these look at the address of the write and update
@@ -141,9 +139,56 @@ simulator.
 .. literalinclude :: ../example/simulating_callbacks/flashing_the_LED.py
    :language: python
 
+Enumerated Fields
+-----------------
+
+Enumerations are a good practice to implicitly encode that have special meanings which can not be
+easily understood from the field name. The SystemRDL enumerations are implemented using python
+
+.. literalinclude :: ../example/enumerated_fields/enumerated_fields.rdl
+   :language: systemrdl
+
+This systemRDL code can be built using the command line tool as follows (assuming it is stored in
+a file called ``enumerated_fields.rdl``):
+
+.. code-block:: bash
+
+    peakrdl python enumerated_fields.rdl -o .
+
+The following example shows the usage of the enumeration
+
+.. note::
+   In order to set the value of an enumerated field, using the ``write()`` method. The correct
+   enumerated class is needed. This can be retrieved from the field itself with the ``enum_cls``
+   property
+
+.. literalinclude :: ../example/enumerated_fields/demo_enumerated_fields.py
+   :language: python
+
+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
+
+.. literalinclude :: ../example/array_access/array_access.rdl
+   :language: systemrdl
+
+This systemRDL code can be built using the command line tool as follows (assuming it is stored in
+a file called ``array_access.rdl``):
+
+.. code-block:: bash
+
+    peakrdl python array_access.rdl -o .
+
+.. literalinclude :: ../example/array_access/demo_array_access.py
+   :language: python
+
 Optimised Access
 ----------------
 
+Working with individual registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 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.
@@ -164,10 +209,27 @@ Both demonstrated in the following code example:
 .. literalinclude :: ../example/optimised_access/demo_optimised_access.py
    :language: python
 
+Working with registers arrays
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In many systems it is more efficient to read and write in block operations rather than using
+individual register access.
+
+Consider the following example of an GPIO block with 8 GPIO pins (configured in a 8 registers):
+
+.. literalinclude :: ../example/optimised_access/optimised_array_access.rdl
+   :language: systemrdl
+
+In order to configure all the GPIOs a range of operations are shown with the use of the context
+managers to make more efficient operations
+
+.. literalinclude :: ../example/optimised_access/demo_optimised_array_access.py
+   :language: python
+
 Walking the Structure
 ---------------------
 
-The following two example show how to use the generators within the register abstraction layer
+The following two example show how to use the generators within the register access layer
 package to traverse the structure.
 
 Both examples use the following register set which has a number of features to demonstrate the
@@ -177,7 +239,7 @@ structures
    :language: systemrdl
 
 This systemRDL code can be built using the command line tool as follows (assuming it is stored in
-a file called ``chip_with_registers.rdl``:
+a file called ``chip_with_registers.rdl``):
 
 .. code-block:: bash
 
@@ -286,25 +348,6 @@ worry if they are in an array or not.
 .. literalinclude :: ../example/tranversing_address_map/reseting_registers.py
    :language: python
 
-
-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
-
-.. literalinclude :: ../example/array_access/array_access.rdl
-   :language: systemrdl
-
-This systemRDL code can be built using the command line tool as follows (assuming it is stored in
-a file called ``array_access.rdl``:
-
-.. code-block:: bash
-
-    peakrdl python array_access.rdl -o .
-
-.. literalinclude :: ../example/array_access/demo_array_access.py
-   :language: python
-
 Python Safe Names
 =================
 

peakrdl_python-0.7.5/docs/index.rst

@@ -0,0 +1,167 @@
+PeakRDL Python
+##############
+
+Introduction
+============
+
+PeakRDL Python is a python package which can be used to generate a register
+access layer python package from a SystemRDL definition.
+
+SystemRDL and control & status register (CSR) generator toolchain
+=================================================================
+
+SystemRDL, more accurately `SystemRDL 2.0 <https://www.accellera.org/images/downloads/standards/systemrdl/SystemRDL_2.0_Jan2018.pdf>`_
+is a description language that describes the registers in a device, for example an FPGA or
+Integrated Circuit (IC). Using this technology allows other parts of the design flow to be
+automatically generated, avoiding mistakes with inconsistencies and speeding up the design flow.
+
+The suite of tools needed for this flow are called a control & status register (CSR) generator.
+
+.. note:: This documentation does not attempt to explain all the good reasons for wanted a
+          CSR generator, other people have done a far better job.
+
+PeakRDl Python is intended to be part of CSR generator flow.
+
+What is a Register Access Layer (RAL)
+=====================================
+
+A Register Access Layer is a software component to make writing scripts and software to control
+a device with hardware registers easier.
+
+Hardware Abstraction Layer (HAL) versus Register Access Layer (RAL)
+*******************************************************************
+
+.. note:: The Register Access Layer (RAL) is aimed at people who understand the registers in the
+           device.
+
+At some point another software component called a Hardware Abstraction Layer (HAL) will often
+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
+          people to use the device without needing a full knowledge of how it works.
+
+What does it do
+***************
+
+The use of a RAL is best shown with an example
+
+Imagine a script to carry out a simple task on a IC, configure an GPIO Pin as an output and
+set the state to `1`. The device has 8 GPIO pins controlled from two registers.
+
++----------+---------+-------------------------------------------------------------------------------------------------------+------------------------+
+| Register | Address |                      Bit                                                                              | Function               |
+|          |         +------------+------------+------------+------------+------------+------------+------------+------------+                        |
+|          |         |  7         |  6         |  5         |  4         |  3         |  2         |  1         |  0         |                        |
++==========+=========+============+============+============+============+============+============+============+============+========================+
+| DIR      | 0x100   | GPIO_7_DIR | GPIO_6_DIR | GPIO_5_DIR | GPIO_4_DIR | GPIO_3_DIR | GPIO_2_DIR | GPIO_1_DIR | GPIO_0_DIR | Sets direction of GPIO |
+|          |         |            |            |            |            |            |            |            |            |   +-------+---------+  |
+|          |         |            |            |            |            |            |            |            |            |   | Value | Meaning |  |
+|          |         |            |            |            |            |            |            |            |            |   +=======+=========+  |
+|          |         |            |            |            |            |            |            |            |            |   | 0     | In      |  |
+|          |         |            |            |            |            |            |            |            |            |   +-------+---------+  |
+|          |         |            |            |            |            |            |            |            |            |   | 1     | Out     |  |
+|          |         |            |            |            |            |            |            |            |            |   +-------+---------+  |
+|          |         |            |            |            |            |            |            |            |            |                        |
++----------+---------+------------+------------+------------+------------+------------+------------+------------+------------+------------------------+
+| DATA_OUT | 0x104   | GPIO_7_OUT | GPIO_6_OUT | GPIO_5_OUT | GPIO_4_OUT | GPIO_3_OUT | GPIO_2_OUT | GPIO_1_OUT | GPIO_0_OUT | Sets the state of a    |
+|          |         |            |            |            |            |            |            |            |            | GPIO configured as out |
++----------+---------+------------+------------+------------+------------+------------+------------+------------+------------+------------------------+
+
+This example uses a simple simulation class to mimic the behaviour of the device offering ``read`` and ``write``
+methods to offer register read and write access to the device. In the real work this would likely go
+via a device driver or JTAG emulator, if the software is running off chip (i.e. a PC).
+
+.. literalinclude :: ../example/why_ral/hardware_sim.py
+   :language: python
+
+To configure pin 0 and set its state you would need to do the following steps:
+
+1. Read the DIR register (to make sure you preserve the states of other pins)
+2. Take the read value of the DIR register, force bit 0 to `1` then write it back
+3. Read the DATA_OUT register (to make sure you preserve the states of other pins)
+4. Take the read value of the DATA_OUT register, force bit 0 to `1` then write it back
+
+If you had a simple environment that only had register read / write function, the code would be
+as follows:
+
+.. literalinclude :: ../example/why_ral/without_ral.py
+   :language: python
+
+This code requires addresses to be hard coded, remembering to do read/modify/writes and bit
+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.
+
+In order to move on the systemRDL code for the registers needs to exist
+
+.. literalinclude :: ../example/why_ral/gpio.rdl
+   :language: systemrdl
+
+In order to build the code (assuming you have everything installed), use the following
+
+.. code-block:: bash
+
+   peakrdl python gpio.rdl -o .
+
+Once built, a set of test cases can be run on the code to confirm its integrity, this is using the
+``unittest`` framework that comes with python
+
+.. code-block:: bash
+
+   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
+
+.. literalinclude :: ../example/why_ral/with_ral.py
+   :language: python
+
+The final part of this example shows a Hardware Abstraction Layer (HAL), in this case the GPIO pins
+are abstracted to look like an array and the direction is automatically configured when the user
+attempts to set the output state.
+
+.. literalinclude :: ../example/why_ral/with_hal.py
+   :language: python
+
+
+.. toctree::
+   :hidden:
+   :caption: Overview
+
+   self
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: usage
+
+   installation
+   generated_package
+   api_components
+   api
+   command_line
+   customisation
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: developer notes
+
+   design_decisions
+   design_tools
+
+.. toctree::
+   :hidden:
+   :caption: other
+
+   genindex
+
+
+
+
+
+
+

peakrdl_python-0.7.5/docs/installation.rst

@@ -0,0 +1,31 @@
+Installation
+************
+
+Dependencies
+============
+
+peakrdl-python runs in any modern version of python 3. This needs to be installed first
+
+Installing the Package
+======================
+
+Install from `PyPi`_ using pip
+
+.. code-block:: bash
+
+   python3 -m pip install peakrdl-python
+
+.. _PyPi: https://pypi.org/project/peakrdl-python
+
+.. note:: peakrdl-python uses the systemrdl-compiler. If your source files use
+          the embedded Perl preprocess refer to the installation instruction for
+          `systemrdl-compiler <https://pypi.org/project/systemrdl-compiler/>`_
+
+.. _peakrdl_installation:
+
+peakrdl
+=======
+
+`PeakRDL <https://pypi.org/project/peakrdl/>`_ is not a required dependency of PeakRDL Python,
+therefore, it is not automatically installed. However, if you want to use the command line method
+of invoking peakrdl-python

peakrdl_python-0.7.5/example/enumerated_fields/demo_enumerated_fields.py

@@ -0,0 +1,39 @@
+"""
+A demonstration of using enumeration
+"""
+from enumerated_fields.lib import NormalCallbackSet
+
+from enumerated_fields.reg_model.enumerated_fields import enumerated_fields_cls as GPIO
+
+class HardwareSimulator:
+    def __init__(self):
+        # use a python dictionary to simulate the hardware
+        self._address_space = {0x00: 0, 0x04: 0}
+
+    def read(self, addr: int, width: int = 32, accesswidth: int = 32) -> int:
+        """
+        function to simulate a device read
+        """
+        return self._address_space[addr]
+
+
+    def write(self, addr: int, data: int, width: int=32, accesswidth: int=32) -> None:
+        """
+        function to simulate a device read
+        """
+        self._address_space[addr] = data
+
+if __name__ == '__main__':
+
+    # create an instance of the hardware simulator
+    hw = HardwareSimulator()
+    # create an instance of the RAL with the callbacks directed at the hardware simulator
+    gpio = GPIO(callbacks=NormalCallbackSet(read_callback=hw.read, write_callback=hw.write))
+
+    # get the field values
+    for field in gpio.gpio_strength.readable_fields:
+        print(f'{field.inst_name} has strength {field.read().name} [0x{field.read().value}]')
+
+    # set the field values by retrieving the enum class from the class itself
+    CurrentEnum = gpio.gpio_strength.gpio_0.enum_cls
+    gpio.gpio_strength.gpio_0.write(CurrentEnum.STRENGTH_12MA)