addrmap.py.jinja

{#
peakrdl-python is a tool to generate Python Register Access Layer (RAL) from SystemRDL
Copyright (C) 2021 - 2025

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
#}

{% include "header.py.jinja" with context %}

{% from 'reg_definitions.py.jinja' import register_class_attributes with context %}
{% from 'addrmap_udp_property.py.jinja' import udp_property with context %}
{% from 'addrmap_universal_property.py.jinja' import universal_properties with context %}
{% from 'addrmap_system_rdl_name_mapping.py.jinja' import get_child_by_system_rdl_name with context %}
{% from 'addrmap_system_rdl_name_mapping.py.jinja' import systemrdl_python_child_name_map with context %}
{% from 'child_definitions.py.jinja' import node_children_iterator with context %}
{% from 'template_ultilities.py.jinja' import peakrdl_python_lib with context %}
{# the following defining the number relative steps up to the lib and sim_lib packages from the current file #}
{% set lib_depth = 1 %}
{% from 'template_ultilities.py.jinja' import peakrld_version_check with context %}

from typing import Iterator
from typing import Optional
from typing import Union
from typing import Type
from typing import overload
from typing import Literal
from typing import Any
from typing import NoReturn
import warnings
{% if legacy_block_access %}from array import array as Array{% endif %}


from {{ peakrdl_python_lib(depth=lib_depth) }} import Node, NodeArray, Base
from {{ peakrdl_python_lib(depth=lib_depth) }} import UDPStruct

from {{ peakrdl_python_lib(depth=lib_depth) }}  import AddressMapArray, RegFileArray
{% if asyncoutput -%}
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncMemory, AsyncMemoryArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncAddressMap
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncRegFile
from {{ peakrdl_python_lib(depth=lib_depth) }}  import AsyncAddressMapArray
from {{ peakrdl_python_lib(depth=lib_depth) }}  import AsyncRegFileArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import MemoryAsyncReadOnly{% if legacy_block_access %}Legacy{% endif %}, MemoryAsyncWriteOnly{% if legacy_block_access %}Legacy{% endif %}, MemoryAsyncReadWrite{% if legacy_block_access %}Legacy{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import MemoryAsyncReadOnlyArray, MemoryAsyncWriteOnlyArray, MemoryAsyncReadWriteArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncReg, AsyncRegArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import RegAsyncReadOnly, RegAsyncWriteOnly, RegAsyncReadWrite
from {{ peakrdl_python_lib(depth=lib_depth) }} import RegAsyncReadOnlyArray, RegAsyncWriteOnlyArray, RegAsyncReadWriteArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import FieldAsyncReadOnly, FieldAsyncWriteOnly, FieldAsyncReadWrite, Field
{% if uses_enum %}from {{ peakrdl_python_lib(depth=lib_depth) }} import FieldEnumAsyncReadOnly, FieldEnumAsyncWriteOnly, FieldEnumAsyncReadWrite{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableAsyncRegister, WritableAsyncRegister
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableAsyncMemory{% if legacy_block_access %}Legacy{% endif %}, WritableAsyncMemory{% if legacy_block_access %}Legacy{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableAsyncRegisterArray, WriteableAsyncRegisterArray
{%- else -%}
from {{ peakrdl_python_lib(depth=lib_depth) }} import Memory, MemoryArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import AddressMap
from {{ peakrdl_python_lib(depth=lib_depth) }} import RegFile
from {{ peakrdl_python_lib(depth=lib_depth) }}  import AddressMapArray
from {{ peakrdl_python_lib(depth=lib_depth) }}  import RegFileArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import MemoryReadOnly{% if legacy_block_access %}Legacy{% endif %}, MemoryWriteOnly{% if legacy_block_access %}Legacy{% endif %}, MemoryReadWrite{% if legacy_block_access %}Legacy{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import MemoryReadOnlyArray, MemoryWriteOnlyArray, MemoryReadWriteArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import Reg, RegArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import RegReadOnly, RegWriteOnly, RegReadWrite
from {{ peakrdl_python_lib(depth=lib_depth) }} import RegReadOnlyArray, RegWriteOnlyArray, RegReadWriteArray
from {{ peakrdl_python_lib(depth=lib_depth) }} import FieldReadOnly, FieldWriteOnly, FieldReadWrite, Field
{% if uses_enum %}from {{ peakrdl_python_lib(depth=lib_depth) }} import FieldEnumReadOnly, FieldEnumWriteOnly, FieldEnumReadWrite{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableRegister, WritableRegister
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableMemory{% if legacy_block_access %}Legacy{% endif %}, WritableMemory{% if legacy_block_access %}Legacy{% endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import ReadableRegisterArray, WriteableRegisterArray
{%- endif %}


{% if asyncoutput %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncCallbackSet, AsyncCallbackSetLegacy
{% else %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import NormalCallbackSet, NormalCallbackSetLegacy
{% endif %}

{{ peakrld_version_check() }}

{% for property_enum in unique_property_enums %}
from .{{top_node.inst_name}}_property_enums import {{property_enum.type_name}}_property_enumcls
{% endfor %}

{%- for node in dependent_registers -%}
from ._registers import {{node.python_class_name}}{% if node.instance.is_array %}_array{% endif %}
{% endfor %}

{%- for node in dependent_memories -%}
from ._memories import {{node.python_class_name}}{% if node.instance.is_array %}_array{% endif %}
{% endfor %}



{%- macro regfile_or_addr_instance(node) %}
    {%- if not hide_node_func(node) %}
    {%- if isinstance(node, systemrdlRegNode) %}
        {{ register_class_attributes(node) }}
    {%- elif isinstance(node, systemrdlMemNode) %}
        {%- if node.is_array %}
    self.__{{node.inst_name}}:{{get_fully_qualified_type_name(node)}}_array = {{get_fully_qualified_type_name(node)}}_array(address=self.address+{{node.raw_address_offset}},
                                                                                  stride={{node.array_stride}},
                                                                                  dimensions=tuple({{node.array_dimensions}}),
                                                                                  logger_handle=logger_handle+'.{{node.inst_name}}',
                                                                                  inst_name='{{node.inst_name}}', parent=self)
        {%- else %}
    self.__{{node.inst_name}}:{{get_fully_qualified_type_name(node)}} = {{get_fully_qualified_type_name(node)}}(
                                                                 address=self.address+{{node.address_offset}},
                                                                 logger_handle=logger_handle+'.{{node.inst_name}}',
                                                                                   inst_name='{{node.inst_name}}', parent=self)
        {%- endif %}
    {%- elif isinstance(node, systemrdlRegfileNode) or isinstance(node, systemrdlAddrmapNode) %}
        {%- if node.is_array %}
    self.__{{node.inst_name}}:{{get_fully_qualified_type_name(node)}}_array = {{get_fully_qualified_type_name(node)}}_array(address=self.address+{{node.raw_address_offset}},
                                                                                  stride={{node.array_stride}},
                                                                                  dimensions=tuple({{node.array_dimensions}}),
                                                                                  logger_handle=logger_handle+'.{{node.inst_name}}',
                                                                                  inst_name='{{node.inst_name}}', parent=self)
        {%- else -%}
    self.__{{node.inst_name}}:{{get_fully_qualified_type_name(node)}} = {{get_fully_qualified_type_name(node)}}(
                                                                            address=self.address+{{node.address_offset}},
                                                                            logger_handle=logger_handle+'.{{node.inst_name}}',
                                                                            inst_name='{{node.inst_name}}',
                                                                            parent=self)
        {%- endif %}
    {%- endif %}
    {%- endif %}
{%- endmacro %}

{%- macro regfile_class(node) %}
class {{node.python_class_name}}({% if asyncoutput %}Async{% endif %}RegFile):
    """
    Class to represent a register file in the register model

    {{get_table_block(node.instance) | indent}}
    """

    __slots__ : list[str] = [{%- for child_node in node.children(unroll=False) -%}'__{{child_node.inst_name}}'{% if not loop.last %}, {% endif %}{%- endfor %}]

    def __init__(self,
                 address: int,
                 logger_handle:str,
                 inst_name:str,
                 parent:Union[{% if asyncoutput %}Async{% endif %}AddressMap,{% if asyncoutput %}Async{% endif %}RegFile]):

        super().__init__(address=address,
                         logger_handle=logger_handle,
                         inst_name=inst_name,
                         parent=parent)

        # instance of objects within the class
        {% for child_node in node.children(unroll=False) -%}
            {{ regfile_or_addr_instance(child_node) | indent }}
        {% endfor %}

    @property
    def size(self) -> int:
        return {{node.instance.size}}

    # properties for Register and RegisterFiles
    {%- for child_node in node.children(unroll=False) %}
        {%- if isinstance(child_node, (systemrdlRegNode, systemrdlRegfileNode)) %}
    @property
    def {{safe_node_name(child_node)}}(self) -> '{% if child_node.is_array -%}{{get_fully_qualified_type_name(child_node)}}_array{% else %}{{get_fully_qualified_type_name(child_node)}}{%- endif -%}':
        """
        Property to access {{child_node.inst_name}} {% if child_node.is_array -%}array{% endif %}

        {{get_table_block(child_node) | indent(8)}}
        """
        return self.__{{child_node.inst_name}}
        {%- endif %}
    {% endfor %}

    {{ systemrdl_python_child_name_map(node.instance) }}

    {{ get_child_by_system_rdl_name(node.instance) }}

    {{ udp_property(node) }}

    {{ universal_properties(node.instance) }}

    {{ node_children_iterator(node) }}

     {%- if node.instance.is_array %}
class {{node.python_class_name}}_array({% if asyncoutput %}Async{% endif %}RegFileArray):
    """
    Class to represent a regfile array in the register model

    {{get_table_block(node.instance) | indent}}
    """
    __slots__: list[str] = []

    @property
    def _element_datatype(self) -> Type[{% if asyncoutput %}Async{% endif %}RegFile]:
        return {{node.python_class_name}}
    {%- endif %}
{%- endmacro %}

{%- macro addrmap_class(node) %}
class {{node.python_class_name}}({% if asyncoutput %}Async{% endif %}AddressMap):
    """
    Class to represent a address map in the register model

    {{get_table_block(node.instance) | indent}}
    """

    __slots__ : list[str] = [{%- for child_node in node.children(unroll=False) -%}{%- if isinstance(child_node, systemrdlRegNode) or isinstance(child_node, systemrdlRegfileNode) or isinstance(child_node, systemrdlAddrmapNode) or isinstance(child_node, systemrdlMemNode) -%}'__{{child_node.inst_name}}'{% if not loop.last %}, {% endif %}{% endif %}{%- endfor %}]

    def __init__(self, *,
                 address:int {%- if node.instance == top_node -%}={{top_node.absolute_address}}{%- endif -%},
                 logger_handle:str {%- if node.instance == top_node -%}='reg_model.{{top_node.get_path()}}'{%- endif -%},
                 inst_name:str{%- if node.instance == top_node -%}='{{node.instance.inst_name}}'{%- endif -%},
                 callbacks: Optional[Union[{% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSet, {% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSetLegacy]]=None,
                 parent:Optional[{% if asyncoutput %}Async{% endif %}AddressMap]=None):

        if callbacks is not None:
            if not isinstance(callbacks, ({% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSet, {% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSetLegacy)):
                raise TypeError(f'callbacks should be {% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSet, {% if asyncoutput %}Async{% else %}Normal{% endif %}CallbackSetLegacy got {type(callbacks)}')

        super().__init__(callbacks=callbacks,
                         address=address,
                         logger_handle=logger_handle,
                         inst_name=inst_name,
                         parent=parent)

        {% for child_node in node.children(unroll=False) -%}
            {{ regfile_or_addr_instance(child_node) | indent }}
        {% endfor %}

    @property
    def size(self) -> int:
        return {{node.instance.size}}

        {%- for child_node in node.children(unroll=False) -%}
            {%- if isinstance(child_node, (systemrdlRegNode, systemrdlRegfileNode, systemrdlAddrmapNode, systemrdlMemNode)) %}
    @property
    def {{safe_node_name(child_node)}}(self) -> '{% if child_node.is_array -%}{{get_fully_qualified_type_name(child_node)}}_array{% else %}{{get_fully_qualified_type_name(child_node)}}{%- endif -%}':
        """
        Property to access {{child_node.inst_name}} {% if child_node.is_array -%}array{% endif %}

        {{get_table_block(child_node) | indent(8)}}
        """
        return self.__{{child_node.inst_name}}
            {%- endif %}
        {% endfor %}

    {{ systemrdl_python_child_name_map(node.instance) }}

    {{ get_child_by_system_rdl_name(node.instance) }}

    {{ udp_property(node) }}

    {{ universal_properties(node.instance) }}

    {{ node_children_iterator(node) }}

    {%- if node.instance.is_array %}
class {{node.python_class_name}}_array({% if asyncoutput %}Async{% endif %}AddressMapArray):
    """
    Class to represent a addrmap array in the register model

    {{get_table_block(node.instance) | indent}}
    """
    __slots__: list[str] = []

    @property
    def _element_datatype(self) -> Type[{% if asyncoutput %}Async{% endif %}AddressMap]:
        return {{node.python_class_name}}
    {%- endif %}
{%- endmacro %}

# addrmap, regfile, memor and register definitions
{%- for unique_node in unique_components -%}
{# the get_dependent_component already strips out hidden items so there is no need to check here
   for hidden items #}
    {% if isinstance(unique_node.instance, systemrdlRegfileNode) %}
    {{ regfile_class(unique_node) }}
    {% elif isinstance(unique_node.instance, systemrdlAddrmapNode) %}
    {{ addrmap_class(unique_node) }}
    {% else %}
    {{ raise_template_error('Encountered unhandled type') }}
    {% endif %}
{% endfor %}

{{top_node.inst_name}}_cls = {{get_fully_qualified_type_name(top_node)}}

if __name__ == '__main__':
    # dummy functions to demonstrate the class
    {% if asyncoutput %}async {% endif %}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 int(input('value to read from address:0x%X'%addr))

    {% if asyncoutput %}async {% endif %}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
        """
        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))

    # create an instance of the class
    {{top_node.inst_name}} = {{top_node.inst_name}}_cls(callbacks = {% if asyncoutput %}AsyncCallbackSet{% else %}NormalCallbackSet{% endif %}{% if legacy_block_access %}Legacy{% endif %}(read_callback=read_addr_space,
                                                                                                     write_callback=write_addr_space))