"""
Type stubs for {{ soc_name }}
Generated by PeakRDL-pybind11
"""

from typing import Iterator, Protocol, overload

class Master(Protocol):
    """Master interface for register access"""
    
    def read(self, address: int, width: int) -> int:
        """Read a value from the given address"""
        ...
    
    def write(self, address: int, value: int, width: int) -> None:
        """Write a value to the given address"""
        ...

class FieldBase:
    """Base class for register fields"""
    
    @property
    def name(self) -> str: ...
    
    @property
    def offset(self) -> int: ...
    
    @property
    def lsb(self) -> int: ...
    
    @property
    def msb(self) -> int: ...
    
    @property
    def width(self) -> int: ...
    
    @property
    def is_readable(self) -> bool: ...
    
    @property
    def is_writable(self) -> bool: ...
    
    @property
    def mask(self) -> int: ...

class RegisterBase:
    """Base class for registers"""
    
    @property
    def name(self) -> str: ...
    
    @property
    def offset(self) -> int: ...
    
    @property
    def width(self) -> int: ...
    
    def read(self) -> int:
        """Read the full register value"""
        ...
    
    def write(self, value: int) -> None:
        """Write the full register value"""
        ...
    
    def modify(self, value: int, mask: int) -> None:
        """Read-modify-write operation with mask"""
        ...

class NodeBase:
    """Base class for address maps and register files"""
    
    @property
    def name(self) -> str: ...
    
    @property
    def offset(self) -> int: ...

{% for reg in nodes.regs %}
class {{ reg.inst_name }}_t(RegisterBase):
    """Register: {{ reg.inst_name }}
    {% if reg.get_property('desc') %}
    {{ reg.get_property('desc') }}
    {% endif %}"""
    
    def __init__(self, base_offset: int) -> None: ...
    
    {% for field in reg.fields() %}
    class {{ field.inst_name }}_field(FieldBase):
        """Field: {{ field.inst_name }}
        {% if field.get_property('desc') %}
        {{ field.get_property('desc') }}
        {% endif %}"""
        
        def read(self) -> int:
            """Read field value"""
            ...
        
        def write(self, value: int) -> None:
            """Write field value"""
            ...
    
    {{ field.inst_name }}: {{ field.inst_name }}_field
    {% endfor %}

{% endfor %}

{% for mem in nodes.mems %}
{%- set entry_reg = mem.children()|list|first %}
class {{ mem.inst_name }}_t(NodeBase):
    """Memory: {{ mem.inst_name }}
    {% if mem.get_property('desc') %}
    {{ mem.get_property('desc') }}
    {% endif %}
    Entries: {{ mem.get_property('mementries') }}
    Entry width: {{ mem.get_property('memwidth') }} bits
    """
    
    def __init__(self, base_offset: int) -> None: ...
    
    def __len__(self) -> int:
        """Get number of memory entries"""
        ...
    
    @overload
    def __getitem__(self, index: int) -> {{ entry_reg.inst_name }}_t:
        """Access memory entry by index"""
        ...
    
    @overload
    def __getitem__(self, index: slice) -> list[{{ entry_reg.inst_name }}_t]:
        """Access memory entries by slice"""
        ...
    
    def __iter__(self) -> Iterator[{{ entry_reg.inst_name }}_t]:
        """Iterate over memory entries"""
        ...

{% endfor %}

class {{ soc_name }}_t(NodeBase):
    """Top-level SoC register map"""
    
    def __init__(self) -> None: ...
    
    def attach_master(self, master: Master) -> None:
        """Attach a master interface for register access"""
        ...
    
    {% for child in top_node.children() %}
    {% if child.inst_name %}
    {{ child.inst_name }}: {{ child.inst_name }}_t
    {% endif %}
    {% endfor %}

def create() -> {{ soc_name }}_t:
    """Create a new instance of the {{ soc_name }} register map"""
    ...
