addrmap_register.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 '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 field_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 = 2 %}

from typing import Iterator
from typing import Union
from typing import overload
from typing import Literal
from typing import Any
from typing import NoReturn
from typing import Type

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

{% if asyncoutput -%}
from {{ peakrdl_python_lib(depth=lib_depth) }} import AsyncMemory
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 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 AsyncReg
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 ReadableAsyncMemory{% if legacy_block_access %}Legacy{% endif %}, WritableAsyncMemory{% if legacy_block_access %}Legacy{% endif %}
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 %}
{%- else -%}
from {{ peakrdl_python_lib(depth=lib_depth) }} import Memory
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 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 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 ReadableMemory{% if legacy_block_access %}Legacy{% endif %}, WritableMemory{% if legacy_block_access %}Legacy{% endif %}
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 %}
{%- endif %}
from {{ peakrdl_python_lib(depth=lib_depth) }} import FieldSizeProps, FieldMiscProps

{% for enum_needed in dependent_enums %}
from .field_enum import {{enum_needed}}
{%- endfor %}

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

{% for field_cls in dependent_fields %}
from .fields import {{field_cls}}
{%- endfor %}

{%- macro register_class(node) %}
class {{node.python_class_name}}({{node.base_class(asyncoutput)}}):
    """
    Class to represent a register 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,
                 {%- if node.read_write -%}
                    Memory{% if asyncoutput %}Async{% endif -%}ReadWrite{% if legacy_block_access %}Legacy{% endif %}
                 {%- elif node.read_only -%}
                    Readable{% if asyncoutput %}Async{% endif -%}Memory{% if legacy_block_access %}Legacy{% endif %}
                 {%- elif node.write_only -%}
                    Writable{% if asyncoutput %}Async{% endif -%}Memory{% if legacy_block_access %}Legacy{% endif %}
                 {%- endif -%}
                 ]):

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

        # build the field attributes
        {% for child_node in node.fields() %}
        self.__{{child_node.inst_name}}:{{get_fully_qualified_type_name(child_node)}} = {{get_fully_qualified_type_name(child_node)}}(
            parent_register=self,
            size_props=FieldSizeProps(
                width={{child_node.width}},
                lsb={{child_node.lsb}}, msb={{child_node.msb}},
                low={{child_node.low}}, high={{child_node.high}}),
            misc_props=FieldMiscProps(
                default={{get_field_default_value(child_node)}},
                is_volatile={{child_node.is_hw_writable}}),
            logger_handle=logger_handle+'.{{child_node.inst_name}}',
            inst_name='{{child_node.inst_name}}',
            field_type={{node.lookup_field_data_python_class(child_node)}})
        {%- endfor %}

    @property
    def width(self) -> int:
        return {{node.regwidth}}

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

    {% if node.write_only %}
    {# if the register has no readable components, all the fields must be writen as one #}
    {% if asyncoutput %}async {% endif %}def write_fields(self, {%- for child_node in node.fields() -%} {{safe_node_name(child_node)}} : {{node.lookup_field_data_python_class(child_node)}}{%- if not loop.last -%},{%- endif -%}{%- endfor -%}) -> None: # type: ignore[override]
        """
        Do a write to the register, updating all fields
        """
        reg_value = 0
        {%- for child_node in node.fields() %}
        reg_value &= self.{{safe_node_name(child_node)}}.inverse_bitmask
        reg_value |= self.{{safe_node_name(child_node)}}._encode_write_value({{safe_node_name(child_node)}})
        {% endfor %}

        {% if asyncoutput %}await {% endif %}self.write(reg_value)

    {% endif %}

    # build the properties for the fields
    {% for child_node in node.fields() %}
    @property
    def {{safe_node_name(child_node)}}(self) -> {{get_fully_qualified_type_name(child_node)}}:
        """
        Property to access {{child_node.inst_name}} field of the register

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

    {{ systemrdl_python_child_name_map(node.instance) }}

    {{ get_child_by_system_rdl_name(node.instance) }}

    {{ udp_property(node) }}

    {{ universal_properties(node.instance) }}

    {{ field_children_iterator(node) }}

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

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

    @property
    def width(self) -> int:
        return {{node.regwidth}}

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

    @property
    def _element_datatype(self) -> Type[{{node.base_class(asyncoutput)}}]:
        return {{node.python_class_name}}

    {{ universal_properties(node.instance) }}

    {%- endif %}



{%- endmacro %}

# register definitions
{%- for unique_node in unique_registers -%}
{# 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, systemrdlRegNode) %}
    {{ register_class(unique_node)  }}
    {% else %}
    {{ raise_template_error('Encountered unhandled type') }}
    {% endif %}
{% endfor %}

if __name__ == '__main__':
    pass