peakrdl-python 0.7.4__tar.gz → 0.8.0__tar.gz

peakrdl_python-0.8.0/.github/workflows/action.yaml

@@ -0,0 +1,306 @@
+# This is a basic workflow to help you get started with Actions
+
+name: CI
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or pull request events but only for the main branch
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '00 6 1 * *'
+  release:
+    types:
+      - published
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          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
+        run: pylint --rcfile tests/pylint.rc src/peakrdl_python
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+          python -m pip install -U mypy
+      - name: Type Check
+        run: mypy src/peakrdl_python --config-file=tests/.mypy.ini
+
+  unit_tests:
+    needs:
+      - mypy
+      - lint
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ 3.7, 3.8, 3.9, "3.10", "3.11", "3.12" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+
+      - name: Run Unit Tests
+        run: |
+          python -m unittest discover -s tests/unit_tests -t .
+
+  dev_runner:
+    needs:
+      - mypy
+      - lint
+      - unit_tests
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ 3.7, 3.8, 3.9, "3.10", "3.11", "3.12" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[dev]
+          # the generate_and_test script is intended to run directly from source rather than from
+          # the installed package
+          python -m pip uninstall peakrdl-python -y
+          # peakrdl-ipxact is needed for some of the test cases so is imported by the
+          # generate_and_test script
+
+
+          # retrieve the example code from the systemRDL compiler
+          wget -L https://raw.githubusercontent.com/SystemRDL/systemrdl-compiler/main/examples/accelera-generic_example.rdl -O tests/testcases/accelera-generic_example.rdl
+
+      - name: Test Development Runner
+        run: |
+
+          python -m generate_and_test --RDL_source_file tests/testcases/simulator_test.rdl --root_node simulator_test
+          python -m generate_and_test --RDL_source_file tests/testcases/simulator_test.rdl --root_node simulator_test --async
+
+          python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map
+
+  peakrdl_integration:
+    needs:
+      - mypy
+      - lint
+      - unit_tests
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ 3.7, 3.8, 3.9, "3.10", "3.11", "3.12" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[peakrdl]
+
+      - name: Run PeakRDL Case
+        run: |
+
+          peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw/
+          peakrdl python tests/testcases/simple.xml tests/testcases/multifile.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
+          python -m unittest discover -s peakrdl_out/raw_async
+
+          peakrdl python tests/testcases/basic.rdl -o peakrdl_out/no_test/ --skip_test_case_generation
+
+      - name: Check Examples
+        run: |
+
+          # build the libraries for the two cases
+          cd example/tranversing_address_map/
+          peakrdl python chip_with_registers.rdl -o .
+          python -m reseting_registers
+          python -m dumping_register_state_to_json_file
+          python -m writing_register_state_from_json_file
+
+          cd ../..
+
+          cd example/simulating_callbacks
+
+          peakrdl python chip_with_a_GPIO.rdl -o .
+          # this example creates a gui that stays up for ever so needs changing before it can be
+          # in the test suite
+          # python -m flashing_the_LED
+
+          cd ../..
+
+          cd example/optimised_access/
+          peakrdl python optimised_access.rdl -o .
+          python -m demo_optimised_access
+
+          cd ../..
+
+          cd example/array_access/
+          peakrdl python array_access.rdl -o .
+          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 ../..
+
+  integration_tests:
+    needs:
+      - mypy
+      - lint
+      - unit_tests
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9, "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .
+
+        # retrieve the example code from the systemRDL compiler
+        wget -L https://raw.githubusercontent.com/SystemRDL/systemrdl-compiler/main/examples/accelera-generic_example.rdl -O tests/testcases/accelera-generic_example.rdl
+
+    - name: Generate testcases
+      run: |
+
+        # one of the test cases uses IPxact so we need the importer
+        python -m pip install peakrdl-ipxact
+        # the generated code is type checked with mypy so this is needed
+        python -m pip install mypy
+
+        python generate_testcases.py
+        mypy testcase_output --config-file=tests/.mypy.ini
+        # pylint --rcfile tests/pylint.rc testcase_output/autopep8 --disable=duplicate-code,line-too-long,too-many-statements,invalid-name,unused-import,too-many-instance-attributes,too-many-arguments,too-many-lines
+
+        python -m unittest discover -s testcase_output
+
+    - name: Test Autoformating
+      run: |
+        python -m pip install black
+        cp testcase_output autoformatted_testcase_output -r
+        black autoformatted_testcase_output --line-length 120
+        python -m unittest discover -s autoformatted_testcase_output
+
+  #-------------------------------------------------------------------------------
+  build:
+    needs:
+      - integration_tests
+      - dev_runner
+      - peakrdl_integration
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        name: Install Python
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U build
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+          
+
+  #-------------------------------------------------------------------------------
+  deploy:
+    needs:
+      - build
+
+    runs-on: ubuntu-latest
+
+    # Only publish when a GitHub Release is created.
+    if: github.event_name == 'release'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/.gitignore

@@ -57,3 +57,4 @@ __pycache__/
 /example/overridden_names/over_ridden_names/
 /example/simulating_callbacks/mychip/
 /example/tranversing_address_map/chip_with_registers/
+/generate_and_test_output/

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: peakrdl-python
-Version: 0.7.4
+Version: 0.8.0
 Summary: Generate Python Register Access Layer (RAL) from SystemRDL
 Author: Keith Brady
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -704,6 +704,13 @@ 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"
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: peakrdl-ipxact; extra == "dev"
+Provides-Extra: peakrdl
+Requires-Dist: peakrdl; extra == "peakrdl"
 
 ![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)

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/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.4 → peakrdl_python-0.8.0}/docs/generated_package.rst

@@ -9,8 +9,11 @@ will be based on the top level address map name with the package was generated
 
 | ``<root_name>``
 | ├── ``lib``
+| ├── ``sim_lib``
 | ├── ``reg_model``
 | │ └── ``<root_name>.py``
+| ├── ``sim``
+| │ └── ``<root_name>.py``
 | └── ``tests``
 |   └── ``test_<root_name>.py``
 
@@ -57,7 +60,7 @@ access layer package so that it can be used from the console:
         Args:
             addr: Address to write to
             width: Width of the register in bits
-            accesswidth: Minimium access width of the register in bits
+            accesswidth: Minimum access width of the register in bits
 
         Returns:
             value inputted by the used
@@ -69,8 +72,8 @@ access layer package so that it can be used from the console:
 
     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.
+        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
@@ -130,11 +133,10 @@ 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 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,
+does not actually use a device driver. Instead it chip simulator with 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
-the internal state of the simulator accordingly, the LED is then updated based on the state of the
-simulator.
+equivalent to those offered by a hardware device driver), in this case they use the simulator
+provided by PeakRDL Python.
 
 .. literalinclude :: ../example/simulating_callbacks/flashing_the_LED.py
    :language: python
@@ -395,7 +397,7 @@ User Defined Property), attributes can be accessed using the ``get_child_by_syst
 method of any object in the register model. The following example shows both methods to access the
 field from the example above
 
-.. literalinclude :: ../example/overridden_names/over_ridden_names.py
+.. literalinclude :: ../example/overridden_names/demo_over_ridden_names.py
    :language: python
 
 
@@ -414,3 +416,19 @@ to clean up the generated code. This had two issues:
 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.
 
+
+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 feild 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.
+

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/docs/index.rst

@@ -68,13 +68,10 @@ set the state to `1`. The device has 8 GPIO pins controlled from two registers.
 |          |         |            |            |            |            |            |            |            |            | GPIO configured as out |
 +----------+---------+------------+------------+------------+------------+------------+------------+------------+------------+------------------------+
 
-This example uses a simple simulation class to mimic the behaviour of the device offering ``read`` and ``write``
+This example uses the peakrdl python simulator 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)

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/example/array_access/demo_array_access.py

@@ -2,28 +2,16 @@ import json
 from typing import Union
 
 from array_access.reg_model.array_access import array_access_cls
+from array_access.sim.array_access import array_access_simulator_cls
 from array_access.lib.callbacks import NormalCallbackSet
 
-# 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)
-
 if __name__ == '__main__':
 
+    # setup the simple simulator
+    sim = array_access_simulator_cls(0)
+
     # create an instance of the class
-    regmodel = array_access_cls(callbacks=NormalCallbackSet(read_callback=read_addr_space))
+    regmodel = array_access_cls(callbacks=NormalCallbackSet(read_callback=sim.read))
 
     # access a entry in the 1D array
     print(regmodel.reg_array_1D[0].field_a.read())

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/example/enumerated_fields/demo_enumerated_fields.py

@@ -4,29 +4,12 @@ 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
+from enumerated_fields.sim.enumerated_fields import enumerated_fields_simulator_cls as HardwareSimulator
 
 if __name__ == '__main__':
 
     # create an instance of the hardware simulator
-    hw = HardwareSimulator()
+    hw = HardwareSimulator(0)
     # 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))
 

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/example/optimised_access/demo_optimised_access.py

@@ -3,48 +3,18 @@ PeakRDL Python example to show the different methods to access the fields of a r
 """
 from optimised_access.reg_model.optimised_access import optimised_access_cls, \
     optimised_access_gpio_direction_enc_enumcls
+from optimised_access.sim.optimised_access import optimised_access_simulator_cls
 
 from optimised_access.lib import NormalCallbackSet
 
-# 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=NormalCallbackSet(read_callback=read_addr_space,
-                                                           write_callback=write_addr_space))
+    sim = optimised_access_simulator_cls(0)
+    dut = optimised_access_cls(callbacks=NormalCallbackSet(read_callback=sim.read,
+                                                           write_callback=sim.write))
 
     # configure the GPIO 0 and GPIO 1 without affecting the state of the GPIO 2 and GPIO 3
     # configuration.

peakrdl_python-0.8.0/example/optimised_access/demo_optimised_array_access.py

@@ -0,0 +1,42 @@
+"""
+PeakRDL Python example to show the different methods to access the a register array
+"""
+from array import array as Array
+
+from optimised_array_access.reg_model.optimised_array_access import optimised_array_access_cls
+from optimised_array_access.sim.optimised_array_access import optimised_array_access_simulator_cls
+
+from optimised_array_access.lib import NormalCallbackSet
+
+
+
+if __name__ == '__main__':
+
+    # create an instance of the address map with the simulated callback necessary to demonstrate
+    # the example
+    sim = optimised_array_access_simulator_cls(0)
+    dut = optimised_array_access_cls(callbacks=NormalCallbackSet(read_block_callback=sim.read_block,
+                                                                 write_block_callback=sim.write_block,
+                                                                 read_callback=sim.read,
+                                                                 write_callback=sim.write))
+
+    # the following will involve 2 reads and 2 writes (one per feild) for each register (8 in total)
+    for idx in range(len(dut.gpio_register)):
+        dut.gpio_register[idx].gpio_direction.write(dut.gpio_register[idx].gpio_direction.enum_cls.GPIO_OUT)
+        dut.gpio_register[idx].gpio_pullup.write(False)
+        # leave the drive strength untouched
+
+    # the following will involve 1 reads and 1 writes for each register (8 in total)
+    # also note the use of the register array iterator (so you don't need range and indexing)
+    for gpio_register in dut.gpio_register:
+        with gpio_register.single_read_modify_write() as reg:
+            reg.gpio_direction.write(reg.gpio_direction.enum_cls.GPIO_OUT)
+            reg.gpio_pullup.write(False)
+            # leave the drive strength untouched
+
+    # the following will do one block read and one block write for the same thing
+    with dut.gpio_register.single_read_modify_write() as reg_array:
+        for reg in reg_array:
+            reg.gpio_direction.write(reg.gpio_direction.enum_cls.GPIO_OUT)
+            reg.gpio_pullup.write(False)
+            # leave the drive strength untouched

peakrdl_python-0.8.0/example/overridden_names/demo_over_ridden_names.py

@@ -0,0 +1,17 @@
+import json
+from typing import Union
+
+from over_ridden_names.reg_model.over_ridden_names import over_ridden_names_cls
+from over_ridden_names.lib import NormalCallbackSet
+from over_ridden_names.sim_lib.dummy_callbacks import dummy_read
+
+if __name__ == '__main__':
+
+    # create an instance of the class
+    over_ridden_names = over_ridden_names_cls(callbacks=NormalCallbackSet(read_callback=dummy_read))
+
+    # access the field value directly
+    print(over_ridden_names.overridden_reg_a.overridden_field_a.read())
+
+    # access the feild value using the original systemRDL names
+    print(over_ridden_names.get_child_by_system_rdl_name('reg_a').get_child_by_system_rdl_name('field_a').read())

{peakrdl-python-0.7.4 → peakrdl_python-0.8.0}/example/simulating_callbacks/chip_with_a_GPIO.rdl

@@ -18,6 +18,7 @@ addrmap mychip {
             sw=rw;
             hw=r;
             reset={GPIO_direction::dir_in}; };
+
         field GPIO_output_field_type {
             fieldwidth = 1;
             sw=rw;
@@ -27,12 +28,12 @@ addrmap mychip {
             name="GPIO Direction";
             desc="Register to set the direction of each GPIO pin";
             GPIO_direction_field_type PIN_0;
-        } GPIO_dir @ 0x4;
+        } GPIO_dir;
 
         reg {
             name="GPIO Set State";
             desc="Register to set the state of a GPIO Pin";
             GPIO_output_field_type PIN_0;
-        } GPIO_state @ 0x8;
+        } GPIO_state;
     } GPIO;
 };