peakrdl-python 0.9.2__tar.gz → 0.9.3__tar.gz

{peakrdl_python-0.9.2 → peakrdl_python-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: peakrdl-python
-Version: 0.9.2
+Version: 0.9.3
 Summary: Generate Python Register Access Layer (RAL) from SystemRDL
 Author: Keith Brady
 License:                     GNU GENERAL PUBLIC LICENSE

{peakrdl_python-0.9.2 → peakrdl_python-0.9.3}/src/peakrdl_python/__about__.py

@@ -17,4 +17,4 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Variables that describes the peakrdl-python Package
 """
-__version__ = "0.9.2"
+__version__ = "0.9.3"

{peakrdl_python-0.9.2 → peakrdl_python-0.9.3}/src/peakrdl_python/lib/__init__.py

@@ -37,52 +37,52 @@ from .base import AsyncRegFile
 from .base import AsyncAddressMapArray
 from .base import AsyncRegFileArray
 
-from .register import Reg
-from .register import RegArray
-from .register import RegisterWriteVerifyError
+from .register_and_field import Reg
+from .register_and_field import RegArray
+from .register_and_field import RegisterWriteVerifyError
 
-from .register import RegReadOnly
-from .register import RegWriteOnly
-from .register import RegReadWrite
-from .register import WritableRegister
-from .register import ReadableRegister
+from .register_and_field import RegReadOnly
+from .register_and_field import RegWriteOnly
+from .register_and_field import RegReadWrite
+from .register_and_field import WritableRegister
+from .register_and_field import ReadableRegister
 
-from .register import RegReadOnlyArray
-from .register import RegWriteOnlyArray
-from .register import RegReadWriteArray
-from .register import ReadableRegisterArray
-from .register import WriteableRegisterArray
+from .register_and_field import RegReadOnlyArray
+from .register_and_field import RegWriteOnlyArray
+from .register_and_field import RegReadWriteArray
+from .register_and_field import ReadableRegisterArray
+from .register_and_field import WriteableRegisterArray
 
-from .async_register import AsyncReg
-from .async_register import AsyncRegArray
-from .async_register import RegAsyncReadOnly
-from .async_register import RegAsyncWriteOnly
-from .async_register import RegAsyncReadWrite
-from .async_register import ReadableAsyncRegister
-from .async_register import WritableAsyncRegister
-from .async_register import RegAsyncReadOnlyArray
-from .async_register import RegAsyncWriteOnlyArray
-from .async_register import RegAsyncReadWriteArray
-from .async_register import ReadableAsyncRegisterArray
-from .async_register import WriteableAsyncRegisterArray
+from .async_register_and_field import AsyncReg
+from .async_register_and_field import AsyncRegArray
+from .async_register_and_field import RegAsyncReadOnly
+from .async_register_and_field import RegAsyncWriteOnly
+from .async_register_and_field import RegAsyncReadWrite
+from .async_register_and_field import ReadableAsyncRegister
+from .async_register_and_field import WritableAsyncRegister
+from .async_register_and_field import RegAsyncReadOnlyArray
+from .async_register_and_field import RegAsyncWriteOnlyArray
+from .async_register_and_field import RegAsyncReadWriteArray
+from .async_register_and_field import ReadableAsyncRegisterArray
+from .async_register_and_field import WriteableAsyncRegisterArray
 
-from .fields import FieldSizeProps
-from .fields import FieldMiscProps
-from .fields import FieldReadOnly
-from .fields import FieldWriteOnly
-from .fields import FieldReadWrite
-from .fields import Field
-from .fields import FieldEnumReadOnly
-from .fields import FieldEnumWriteOnly
-from .fields import FieldEnumReadWrite
-from .fields import FieldEnum
+from .base_field import FieldSizeProps
+from .base_field import FieldMiscProps
+from .register_and_field import FieldReadOnly
+from .register_and_field import FieldWriteOnly
+from .register_and_field import FieldReadWrite
+from .base_field import Field
+from .register_and_field import FieldEnumReadOnly
+from .register_and_field import FieldEnumWriteOnly
+from .register_and_field import FieldEnumReadWrite
+from .base_field import FieldEnum
 
-from .fields import FieldAsyncReadOnly
-from .fields import FieldAsyncWriteOnly
-from .fields import FieldAsyncReadWrite
-from .fields import FieldEnumAsyncReadOnly
-from .fields import FieldEnumAsyncWriteOnly
-from .fields import FieldEnumAsyncReadWrite
+from .async_register_and_field import FieldAsyncReadOnly
+from .async_register_and_field import FieldAsyncWriteOnly
+from .async_register_and_field import FieldAsyncReadWrite
+from .async_register_and_field import FieldEnumAsyncReadOnly
+from .async_register_and_field import FieldEnumAsyncWriteOnly
+from .async_register_and_field import FieldEnumAsyncReadWrite
 
 from .memory import MemoryReadOnly, MemoryReadOnlyLegacy
 from .memory import MemoryWriteOnly, MemoryWriteOnlyLegacy

{peakrdl_python-0.9.2 → peakrdl_python-0.9.3}/src/peakrdl_python/lib/async_memory.py

@@ -40,10 +40,9 @@ else:
 
 
 if TYPE_CHECKING:
-    from .async_register import AsyncReg, AsyncRegArray
-    from .async_register import ReadableAsyncRegister, WritableAsyncRegister
-    from .async_register import ReadableAsyncRegisterArray, WriteableAsyncRegisterArray
-
+    from .async_register_and_field import AsyncReg, AsyncRegArray
+    from .async_register_and_field import ReadableAsyncRegister, WritableAsyncRegister
+    from .async_register_and_field import ReadableAsyncRegisterArray, WriteableAsyncRegisterArray
 # pylint: disable=duplicate-code
 
 

peakrdl_python-0.9.2/src/peakrdl_python/lib/async_register.py → peakrdl_python-0.9.3/src/peakrdl_python/lib/async_register_and_field.py

@@ -17,10 +17,10 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 This module is intended to distributed as part of automatically generated code by the
 peakrdl-python tool. It provides a set of classes used by the autogenerated code to represent
-registers
+asynchronous registers and fields
 """
 from enum import Enum
-from typing import List, Union, Iterator, TYPE_CHECKING, Tuple, Optional, Dict, TypeVar
+from typing import List, Union, Iterator, Tuple, Optional, Dict, TypeVar, cast
 from typing import AsyncGenerator
 from abc import ABC, abstractmethod
 from contextlib import asynccontextmanager
@@ -28,15 +28,17 @@ from array import array as Array
 import sys
 from warnings import warn
 
-from .utility_functions import get_array_typecode
+from .utility_functions import get_array_typecode, swap_msb_lsb_ordering
 from .base import AsyncAddressMap, AsyncRegFile
-from .register import BaseReg, BaseRegArray, RegisterWriteVerifyError
 from .async_memory import  MemoryAsyncReadOnly, MemoryAsyncWriteOnly, MemoryAsyncReadWrite, \
     AsyncMemory, ReadableAsyncMemory, WritableAsyncMemory
 from .async_memory import  MemoryAsyncReadOnlyLegacy, MemoryAsyncWriteOnlyLegacy, \
     MemoryAsyncReadWriteLegacy
 from .async_memory import ReadableAsyncMemoryLegacy, WritableAsyncMemoryLegacy
 from .callbacks import AsyncCallbackSet, AsyncCallbackSetLegacy
+from .base_register import BaseReg, BaseRegArray, RegisterWriteVerifyError
+from .base_field import FieldEnum, FieldSizeProps, FieldMiscProps, \
+    _FieldReadOnlyFramework, _FieldWriteOnlyFramework
 
 # pylint: disable=duplicate-code
 if sys.version_info >= (3, 11):
@@ -45,9 +47,13 @@ else:
     from typing_extensions import Self
 # pylint: enable=duplicate-code
 
-if TYPE_CHECKING:
-
-    from .fields import FieldAsyncReadOnly, FieldAsyncWriteOnly, FieldAsyncReadWrite
+# pylint: disable=duplicate-code
+if sys.version_info >= (3, 10):
+    # type guarding was introduced in python 3.10
+    from typing import TypeGuard
+else:
+    from typing_extensions import TypeGuard
+# pylint: enable=duplicate-code
 
 # pylint: disable=redefined-slots-in-subclass,too-many-lines
 
@@ -99,7 +105,7 @@ class AsyncReg(BaseReg, ABC):
     @property
     @abstractmethod
     def fields(self) -> \
-            Iterator[Union['FieldAsyncReadOnly','FieldAsyncWriteOnly', 'FieldAsyncReadWrite']]:
+            Iterator[Union['FieldAsyncReadOnly', 'FieldAsyncWriteOnly', 'FieldAsyncReadWrite']]:
         """
         generator that produces has all the fields within the register
         """
@@ -191,11 +197,17 @@ class RegAsyncReadOnly(AsyncReg, ABC):
         raise RuntimeError('This function does not have a useable callback')
 
     @property
-    @abstractmethod
     def readable_fields(self) -> Iterator[Union['FieldAsyncReadOnly', 'FieldAsyncReadWrite']]:
         """
         generator that produces has all the readable fields within the register
         """
+        def is_readable(field: Union['FieldAsyncReadOnly',
+                                     'FieldAsyncWriteOnly',
+                                     'FieldAsyncReadWrite']) -> \
+                TypeGuard[Union['FieldAsyncReadOnly', 'FieldAsyncReadWrite']]:
+            return isinstance(field, (FieldAsyncReadOnly, FieldAsyncReadWrite))
+
+        return filter(is_readable, self.fields)
 
     async def read_fields(self) -> Dict['str', Union[bool, Enum, int]]:
         """
@@ -295,11 +307,17 @@ class RegAsyncWriteOnly(AsyncReg, ABC):
             raise RuntimeError('This function does not have a useable callback')
 
     @property
-    @abstractmethod
     def writable_fields(self) -> Iterator[Union['FieldAsyncWriteOnly', 'FieldAsyncReadWrite']]:
         """
         generator that produces has all the writable fields within the register
         """
+        def is_writable(field: Union['FieldAsyncReadOnly',
+                                     'FieldAsyncWriteOnly',
+                                     'FieldAsyncReadWrite']) -> \
+                TypeGuard[Union['FieldAsyncWriteOnly', 'FieldAsyncReadWrite']]:
+            return isinstance(field, (FieldAsyncWriteOnly, FieldAsyncReadWrite))
+
+        return filter(is_writable, self.fields)
 
     @abstractmethod
     async def write_fields(self, **kwargs) -> None:  # type: ignore[no-untyped-def]
@@ -348,7 +366,7 @@ class RegAsyncReadWrite(RegAsyncReadOnly, RegAsyncWriteOnly, ABC):
 
     @asynccontextmanager
     async def single_read_modify_write(self, verify: bool = False, skip_write: bool = False) -> \
-        AsyncGenerator[Self, None]:
+            AsyncGenerator[Self, None]:
         """
         Context manager to allow multiple field reads/write to be done with a single set of
         field operations
@@ -1035,3 +1053,211 @@ class RegAsyncReadWriteArray(AsyncRegArray, ABC):
 
 ReadableAsyncRegisterArray = Union[RegAsyncReadOnlyArray, RegAsyncReadWriteArray]
 WriteableAsyncRegisterArray = Union[RegAsyncWriteOnlyArray, RegAsyncReadWriteArray]
+
+
+class FieldAsyncReadOnly(_FieldReadOnlyFramework, ABC):
+    """
+    class for an asynchronous read only register field
+
+    Args:
+        parent_register: register within which the field resides
+        size_props: object defining the msb, lsb, high bit, low bit and width
+        logger_handle: name to be used logging messages associate with this
+            object
+
+    """
+    __slots__: List[str] = []
+
+    def __init__(self, *,
+                 parent_register: ReadableAsyncRegister,
+                 size_props: FieldSizeProps,
+                 misc_props: FieldMiscProps,
+                 logger_handle: str,
+                 inst_name: str):
+
+        if not isinstance(parent_register, (RegAsyncReadWrite, RegAsyncReadOnly)):
+            raise TypeError(f'size_props must be of {type(RegAsyncReadWrite)} or '
+                            f'{type(RegAsyncReadOnly)} but got {type(parent_register)}')
+
+        # pylint: disable=duplicate-code
+        super().__init__(logger_handle=logger_handle,
+                         size_props=size_props,
+                         misc_props=misc_props,
+                         parent_register=parent_register,
+                         inst_name=inst_name)
+        # pylint: enable=duplicate-code
+
+    async def read(self) -> int:  # pylint: disable=invalid-overridden-method
+        """
+        Asynchronously reads the register that this field is located in and retries the field
+        value applying the required masking and shifting
+
+        Returns:
+            field value
+
+        """
+        return self.decode_read_value(await self.parent_register.read())
+
+    @property
+    def parent_register(self) -> ReadableAsyncRegister:
+        """
+        parent register the field is placed in
+        """
+
+        # this cast is OK because an explict typing check was done in the __init__
+        return cast(ReadableAsyncRegister, self.parent)
+
+
+class FieldAsyncWriteOnly(_FieldWriteOnlyFramework, ABC):
+    """
+    class for an asynchronous write only register field
+
+    Args:
+        parent_register: register within which the field resides
+        size_props: object defining the msb, lsb, high bit, low bit and width
+        logger_handle: name to be used logging messages associate with this
+            object
+
+    """
+    __slots__: List[str] = []
+
+    def __init__(self, *,
+                 parent_register: WritableAsyncRegister,
+                 size_props: FieldSizeProps,
+                 misc_props: FieldMiscProps,
+                 logger_handle: str,
+                 inst_name: str):
+
+        if not isinstance(parent_register, (RegAsyncReadWrite, RegAsyncWriteOnly)):
+            raise TypeError(f'size_props must be of {type(RegAsyncReadWrite)} or '
+                            f'{type(RegAsyncWriteOnly)} but got {type(parent_register)}')
+
+        # pylint: disable=duplicate-code
+        super().__init__(logger_handle=logger_handle,
+                         size_props=size_props,
+                         misc_props=misc_props,
+                         parent_register=parent_register,
+                         inst_name=inst_name)
+        # pylint: enable=duplicate-code
+
+    async def write(self, value: int) -> None:  # pylint: disable=invalid-overridden-method
+        """
+        The behaviour of this method depends on whether the field is located in
+        a readable register or not:
+
+        If the register is readable, the method will perform an async read-modify-write
+        on the register updating the field with the value provided
+
+        If the register is not writable all other field values will be asynchronously written
+        with zero.
+
+        Args:
+            value: field value to update to
+
+        """
+
+        # This code closely resembles the non-async version but is duplicated for clarity
+        # pylint: disable=duplicate-code
+        self._write_value_checks(value=value)
+
+        if self.msb0:
+            value = swap_msb_lsb_ordering(value=value, width=self.width)
+        # pylint: enable=duplicate-code
+
+        if (self.high == (self.register_data_width - 1)) and (self.low == 0):
+            # special case where the field occupies the whole register,
+            # there a straight write can be performed
+            new_reg_value = value
+        else:
+            # do a read, modify write
+            if isinstance(self.parent_register, RegAsyncReadWrite):
+                reg_value = await self.parent_register.read()
+                masked_reg_value = reg_value & self.inverse_bitmask
+                new_reg_value = masked_reg_value | (value << self.low)
+            elif isinstance(self.parent_register, RegAsyncWriteOnly):
+                new_reg_value = value << self.low
+            else:
+                raise TypeError('Unhandled parent type')
+
+        await self.parent_register.write(new_reg_value)
+
+    @property
+    def parent_register(self) -> WritableAsyncRegister:
+        """
+        parent register the field is placed in
+        """
+
+        # this cast is OK because an explict typing check was done in the __init__
+        return cast(WritableAsyncRegister, self.parent)
+
+
+class FieldAsyncReadWrite(FieldAsyncReadOnly, FieldAsyncWriteOnly, ABC):
+    """
+    class for an asyncronous read/write register field
+
+    Args:
+        parent_register: register within which the field resides
+        size_props: object defining the msb, lsb, high bit, low bit and width
+        logger_handle: name to be used logging messages associate with this
+            object
+
+    """
+    __slots__: List[str] = []
+
+    def __init__(self, *,
+                 parent_register: RegAsyncReadWrite,
+                 size_props: FieldSizeProps,
+                 misc_props: FieldMiscProps,
+                 logger_handle: str,
+                 inst_name: str):
+
+        if not isinstance(parent_register, RegAsyncReadWrite):
+            raise TypeError(f'size_props must be of {type(RegAsyncReadWrite)} '
+                            f'but got {type(parent_register)}')
+
+        # pylint: disable=duplicate-code
+        super().__init__(logger_handle=logger_handle,
+                         size_props=size_props,
+                         misc_props=misc_props,
+                         parent_register=parent_register,
+                         inst_name=inst_name)
+        # pylint: enable=duplicate-code
+
+    @property
+    def parent_register(self) -> RegAsyncReadWrite:
+        """
+        parent register the field is placed in
+        """
+
+        # this cast is OK because an explict typing check was done in the __init__
+        return cast(RegAsyncReadWrite, self.parent)
+
+
+class FieldEnumAsyncReadWrite(FieldAsyncReadWrite, FieldEnum, ABC):
+    """
+    class for an async read/write register field with an enumerated value
+    """
+    __slots__: List[str] = []
+
+    @property
+    def parent_register(self) -> RegAsyncReadWrite:
+        """
+        parent register the field is placed in
+        """
+
+        # this cast is OK because an explict typing check was done in the __init__
+        return cast(RegAsyncReadWrite, self.parent)
+
+
+class FieldEnumAsyncReadOnly(FieldAsyncReadOnly, FieldEnum, ABC):
+    """
+    class for an async read only register field with an enumerated value
+    """
+    __slots__: List[str] = []
+
+
+class FieldEnumAsyncWriteOnly(FieldAsyncWriteOnly, FieldEnum, ABC):
+    """
+    class for an async write only register field with an enumerated value
+    """
+    __slots__: List[str] = []

{peakrdl_python-0.9.2 → peakrdl_python-0.9.3}/src/peakrdl_python/lib/base.py

@@ -43,12 +43,12 @@ else:
 if TYPE_CHECKING:
     from .memory import Memory, MemoryArray
     from .async_memory import AsyncMemory, AsyncMemoryArray
-    from .register import Reg, RegArray
-    from .register import WritableRegister, ReadableRegister
-    from .async_register import AsyncReg, AsyncRegArray
-    from .async_register import ReadableAsyncRegister, WritableAsyncRegister
-    from .register import ReadableRegisterArray, WriteableRegisterArray
-    from .async_register import ReadableAsyncRegisterArray, WriteableAsyncRegisterArray
+    from .register_and_field import Reg, RegArray
+    from .register_and_field import WritableRegister, ReadableRegister
+    from .async_register_and_field import AsyncReg, AsyncRegArray
+    from .async_register_and_field import ReadableAsyncRegister, WritableAsyncRegister
+    from .register_and_field import ReadableRegisterArray, WriteableRegisterArray
+    from .async_register_and_field import ReadableAsyncRegisterArray, WriteableAsyncRegisterArray
 
 UDPStruct = Dict[str, 'UDPType']
 UDPType = Union[str, int, bool, IntEnum, UDPStruct]