corel_mmio 8.0.0__tar.gz

corel_mmio-8.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Deutsches Elektronen-Synchrotron DESY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

corel_mmio-8.0.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: corel_mmio
+Version: 8.0.0
+Summary: Common Memory-Mapped IO operations and in-memory representations.
+Author-email: Jason Watson <jason.watson@desy.de>
+License-Expression: MIT
+Project-URL: repository, https://gitlab.desy.de/corel/corel-mmio
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions~=4.12
+Provides-Extra: dev
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: pre-commit~=4.1; extra == "dev"
+Requires-Dist: mypy~=1.15; extra == "dev"
+Requires-Dist: pytest~=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio~=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: coverage>=7.4.0; extra == "dev"
+Dynamic: license-file
+
+# <img align="right" src="misc/logo.png" height="200"></a>
+
+# corel-mmio
+
+[![pipeline status](https://gitlab.desy.de/corel/corel-mmio/badges/main/pipeline.svg)](https://gitlab.desy.de/corel/corel-mmio) [![coverage report](https://gitlab.desy.de/corel/corel-mmio/badges/main/coverage.svg)](https://gitlab.desy.de/corel/corel-mmio)
+
+Common Memory-Mapped Input/Output (MMIO) operations and in-memory
+representations, to aid in the development of packages which communicate with
+hardware containing a memory-mapped address space.
+
+This package is part of the [corel](https://gitlab.desy.de/corel) project ecosystem,
+which is a collection of Python packages for the cooperative development of
+software and firmware for  memory mapped FPGAs, microcontrollers and other hardware.
+
+* Supported Python versions: 3.10+
+* Supported platforms: Linux, OSX
+* Source: <https://gitlab.desy.de/corel/corel-mmio>
+* Pypi: <https://pypi.org/project/corel-mmio>
+* Documentation: TODO
+* License: [MIT](LICENSE)
+
+
+## Features
+
+* Unification of the interfaces involved in the interaction between software
+  and Memory-Mapped Input/Output (MMIO) hardware.
+* Object-oriented description of a memory map address space, providing
+  register address access and validation and supporting multiple layers of
+  submaps.
+* Convenient asynchronous read/write methods attached to the memory-mapped
+  registers via an abstract "interface" class defined through the structural
+  subtyping of Python `Protocol`.
+* Supports the development of hardware drivers which can be reused in different
+  bench setups, where the underlying protocol (message format or communication
+  protocol) changes, but the memory map of the device (and therefore the
+  device operation) is common.
+
+
+## Acknowledgements
+
+Concepts in corel-mmio have been inspired by the
+[hdl_registers](https://hdl-registers.com/) package. However, corel-mmio
+deliberately avoids a dependency on hdl_registers, so that it may be used in
+software architectures which strive to minimise dependencies.
+
+
+## Installation
+
+This package is installable via pip from PyPI:
+```
+pip install corel-mmio
+```
+
+This package is installable via pip directly from this repository
+(via https or ssh), e.g.:
+```
+pip install 'git+https://gitlab.desy.de/corel/corel-mmio.git'
+```
+For developers, follow the usual `git clone` procedure and see the
+[Makefile](Makefile) for development commands.

corel_mmio-8.0.0/README.md

@@ -0,0 +1,60 @@
+# <img align="right" src="misc/logo.png" height="200"></a>
+
+# corel-mmio
+
+[![pipeline status](https://gitlab.desy.de/corel/corel-mmio/badges/main/pipeline.svg)](https://gitlab.desy.de/corel/corel-mmio) [![coverage report](https://gitlab.desy.de/corel/corel-mmio/badges/main/coverage.svg)](https://gitlab.desy.de/corel/corel-mmio)
+
+Common Memory-Mapped Input/Output (MMIO) operations and in-memory
+representations, to aid in the development of packages which communicate with
+hardware containing a memory-mapped address space.
+
+This package is part of the [corel](https://gitlab.desy.de/corel) project ecosystem,
+which is a collection of Python packages for the cooperative development of
+software and firmware for  memory mapped FPGAs, microcontrollers and other hardware.
+
+* Supported Python versions: 3.10+
+* Supported platforms: Linux, OSX
+* Source: <https://gitlab.desy.de/corel/corel-mmio>
+* Pypi: <https://pypi.org/project/corel-mmio>
+* Documentation: TODO
+* License: [MIT](LICENSE)
+
+
+## Features
+
+* Unification of the interfaces involved in the interaction between software
+  and Memory-Mapped Input/Output (MMIO) hardware.
+* Object-oriented description of a memory map address space, providing
+  register address access and validation and supporting multiple layers of
+  submaps.
+* Convenient asynchronous read/write methods attached to the memory-mapped
+  registers via an abstract "interface" class defined through the structural
+  subtyping of Python `Protocol`.
+* Supports the development of hardware drivers which can be reused in different
+  bench setups, where the underlying protocol (message format or communication
+  protocol) changes, but the memory map of the device (and therefore the
+  device operation) is common.
+
+
+## Acknowledgements
+
+Concepts in corel-mmio have been inspired by the
+[hdl_registers](https://hdl-registers.com/) package. However, corel-mmio
+deliberately avoids a dependency on hdl_registers, so that it may be used in
+software architectures which strive to minimise dependencies.
+
+
+## Installation
+
+This package is installable via pip from PyPI:
+```
+pip install corel-mmio
+```
+
+This package is installable via pip directly from this repository
+(via https or ssh), e.g.:
+```
+pip install 'git+https://gitlab.desy.de/corel/corel-mmio.git'
+```
+For developers, follow the usual `git clone` procedure and see the
+[Makefile](Makefile) for development commands.

corel_mmio-8.0.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = [
+    "setuptools>=77",
+    "setuptools_scm[toml]>=8",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "corel_mmio"
+version = "8.0.0"
+description = "Common Memory-Mapped IO operations and in-memory representations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name =  "Jason Watson", email = "jason.watson@desy.de"},
+]
+dependencies = [
+    "typing-extensions~=4.12",  # TODO: replace for Python 3.12
+]
+
+[project.optional-dependencies]
+dev = [
+    "ipython",
+    "pre-commit~=4.1",
+    "mypy~=1.15",
+    "pytest~=8.3",
+    "pytest-asyncio~=0.23",
+    "pytest-cov>=4.1.0",
+    "coverage>=7.4.0",
+]
+
+[project.urls]
+repository = "https://gitlab.desy.de/corel/corel-mmio"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+required-version = ">=0.6.0"
+default-groups = []
+
+[tool.pytest.ini_options]
+minversion = "8"
+xfail_strict = true
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+log_cli_level = "DEBUG"
+
+[tool.ruff]
+line-length = 90
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = [
+    "I", # isort
+    "N", # pep8 naming
+    "D", # pydocstyle
+    "NPY", # numpy
+    "PT", # pytest
+    "UP", # pyupgrade
+    "COM", # flake8-commas
+    "ISC", # implicit string concat rules
+    "ICN", # import name conventions
+    "G", # logging
+]
+ignore = [
+    "COM812", # incompatible with ruff format
+    "ISC001", # incompatible with ruff format
+    "G004", # premature optimization, f-strings are more convenient
+    "D401", # don't force imperative mood
+    "D105", # don't force docstring for magic methods
+    "PT013", # useful for pytest.approx
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+ignore-decorators = [  # Functions with these decorators don't have to have docstrings.
+    "typing.overload",  # Default configuration
+    # The next four are all variations on override, so child classes don't have to repeat parent classes' docstrings.
+    "overrides.override",
+    "overrides.overrides",
+    "typing.override",
+    "typing_extensions.override",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# no documentation linting for test files
+"**/tests/**" = ["D"]
+"**/tests_*.py" = ["D"]
+"*test*.py" = ["D"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.isort]
+profile = "black"
+line_length = 90
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+allow_untyped_defs = true
+allow_incomplete_defs = true
+allow_untyped_calls = true
+disable_error_code = ["var-annotated", "has-type", "abstract"]

corel_mmio-8.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

corel_mmio-8.0.0/src/corel_mmio/__init__.py

@@ -0,0 +1,5 @@
+"""Common Memory-Mapped IO operations and in-memory representations."""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__ or __name__)

corel_mmio-8.0.0/src/corel_mmio/bytes.py

@@ -0,0 +1,108 @@
+"""Tools related to bytes of the memory map and data."""
+
+from collections.abc import Iterator
+from typing import Literal
+
+__all__ = [
+    "word_increments",
+    "pad_data",
+    "flip_byteorder",
+    "flip_integer_byteorder",
+]
+
+
+def word_increments(
+    start_address: int,
+    byte_length: int,
+    bus_width: int,
+    auto_increment: bool,
+) -> Iterator[tuple[int, int]]:
+    """
+    Generator to increment over word addresses.
+
+    Parameters
+    ----------
+    start_address : int
+        Address in the memory map to start from.
+    byte_length : int
+        Total number of bytes to increment over.
+    bus_width : int
+        Byte width of the register bus of the memory map.
+    auto_increment : bool
+        Automatically increment the register address when writing/reading more
+        than the bus length (4 bytes).
+
+    Yields
+    ------
+    current_address: int
+        Address the generator is currently at.
+    remaining_word_bytes
+        Number of bytes left in the current word.
+    """
+    current_address = start_address
+    remaining_byte_length = byte_length
+    word_start_address = (start_address // bus_width) * bus_width
+    while remaining_byte_length > 0:
+        remaining_word_bytes = bus_width - (current_address % bus_width)
+        if remaining_word_bytes > remaining_byte_length:
+            remaining_word_bytes = remaining_byte_length
+
+        yield current_address, remaining_word_bytes
+
+        current_address += remaining_word_bytes
+        if not auto_increment:
+            current_address = word_start_address + (current_address % bus_width)
+        remaining_byte_length -= remaining_word_bytes
+
+
+def pad_data(
+    data: bytes | bytearray,
+    padded_byte_length: int | None,
+) -> bytearray:
+    """
+    Pad the start of a bytearray to have the desired length.
+
+    Parameters
+    ----------
+    data : bytearray
+        Data to be padded.
+    padded_byte_length : int or None
+        Desired length to pad the data to.
+
+    Returns
+    -------
+    data_padded : bytearray
+        Padded data.
+    """
+    if padded_byte_length is None:
+        return bytearray(data)
+
+    byte_length = len(data)
+    if padded_byte_length < len(data):
+        raise ValueError(
+            f"Data (len: {byte_length}) is longer than requested "
+            f"byte_length: {padded_byte_length}"
+        )
+
+    data_padded = bytearray(padded_byte_length - len(data))
+    data_padded.extend(data)
+    return data_padded
+
+
+def flip_byteorder(
+    data_bytes: bytes, from_: Literal["little", "big"], to_: Literal["little", "big"]
+) -> bytes:
+    """Reorder the bytes from one endianness into another."""
+    data_int = int.from_bytes(data_bytes, byteorder=from_)
+    return data_int.to_bytes(len(data_bytes), byteorder=to_)
+
+
+def flip_integer_byteorder(
+    value: int,
+    n_bytes: int,
+    from_: Literal["little", "big"],
+    to_: Literal["little", "big"],
+) -> int:
+    """Flip the byteorder of the integer."""
+    value_bytes = value.to_bytes(n_bytes, byteorder=from_)
+    return int.from_bytes(value_bytes, byteorder=to_)

corel_mmio-8.0.0/src/corel_mmio/cache.py

@@ -0,0 +1,54 @@
+"""Local cache of the hardware memory map register values."""
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from typing_extensions import TypeVar
+
+from corel_mmio.mapping import SliceableMutableMapping
+
+if TYPE_CHECKING:
+    from corel_mmio.memmap.memmap import MemoryMap
+    from corel_mmio.memmap.register import Register
+
+TType = TypeVar("TType")
+
+
+class Cache:
+    """
+    Local cache of the hardware memory map register values.
+
+    Useful for tracking the values written to write-only registers, so that
+    unintentional overwrites can be avoided when writing to fields which
+    share that same register.
+    """
+
+    def __init__(self, size: int):
+        self._size = size
+        self._bus = SliceableMutableMapping(size=size, mapping=defaultdict(lambda: 0))
+
+    def push_address(self, word_address: int, value: int) -> None:
+        """Update the cache with the value of a register at an address."""
+        self._bus[word_address] = value
+
+    def push_register(self, register: "Register", value: int) -> None:
+        """Update the cache with the value of a register."""
+        self.push_address(register.word_address, value)
+
+    def pull_address(self, word_address: int) -> int:
+        """Obtain the currently cached value of a register at an address."""
+        return self._bus[word_address]
+
+    def pull_register(self, register: "Register") -> int:
+        """Obtain the currently cached value of a register."""
+        return self.pull_address(register.word_address)
+
+    def pull_fields(self, register: "Register[TType]") -> dict[str, TType]:
+        """Obtain the currently cached values of the fields in a register."""
+        register_value = self.pull_register(register)
+        return register.extract_field_values(register_value)
+
+    def update_from_defaults(self, memmap: "MemoryMap") -> None:
+        """Update the cache with the default value of each register in the memory map."""
+        for register in memmap.registers:
+            self.push_register(register, register.default_value)

corel_mmio-8.0.0/src/corel_mmio/device.py

@@ -0,0 +1,102 @@
+"""Containers related to device addressing."""
+
+from collections.abc import Iterable, Iterator
+from enum import Flag
+from functools import cache, reduce
+from operator import or_ as _or_
+from typing import TypeVar
+
+from typing_extensions import Self  # TODO: in Python 3.11 use typing.Self
+
+__all__ = [
+    "DeviceFlag",
+]
+
+T = TypeVar("T", bound="DeviceFlag")
+
+
+class DeviceFlag(Flag):
+    """
+    Flag enum for indicating the sub-device involved in an operation.
+
+    Used when addressing multiple devices in a single operation, which is then
+    executed either sequentially or simultaneously (broadcast).
+
+    This class is intended as a baseclass to be inherited, to be defined for
+    the specific sub-devices of a project.
+    """
+
+    # noinspection PyTypeChecker
+    @property
+    def value(self) -> int:
+        """The value of the Enum member."""
+        return super().value
+
+    @property
+    def name(self) -> str:
+        """The name of the Enum member."""
+        class_name = self.__class__.__name__
+        return super().name or str(self).replace(f"{class_name}.", "")
+
+    @property
+    def solo(self) -> bool:
+        """True if the addressed device is solo."""
+        n = self.value
+        return n > 0 and (n & (n - 1)) == 0
+
+    @classmethod
+    @cache
+    def distinct(cls) -> list[Self]:
+        """Obtain a list of the distinct devices."""
+        # TODO: unnecessary in 3.11?
+        return [n for n in cls if n.solo]
+
+    @classmethod
+    @cache
+    def n_distinct(cls) -> int:
+        """Number of distinct devices."""
+        return len(cls.distinct())
+
+    @classmethod
+    def validate_bit_string(cls, string: str) -> None:
+        """Validate that a 32 digit bit string is valid for indicating the device."""
+        n = cls.n_distinct()
+        error_msg = f"Must be a bit string of at-most length {n}"
+
+        if len(string) > n:
+            raise ValueError(error_msg)
+
+        # Test that the string is a binary
+        try:
+            int(string, 2)
+        except ValueError:
+            raise ValueError(error_msg)
+
+    @classmethod
+    def from_bit_string(cls, string: str) -> Self:
+        """Create from a bit string notation."""
+        cls.validate_bit_string(string)
+        return cls(int(string, 2))
+
+    def to_bit_string(self) -> str:
+        """Convert to a bit string notation."""
+        n = self.n_distinct()
+        return f"{self.value:0{n}b}"
+
+    @classmethod
+    def join(cls, devices: Iterable[Self]) -> Self:
+        """Join multiple devices into a single flag."""
+        return cls(reduce(_or_, devices, cls(0)))
+
+    def split(self) -> Iterator[Self]:
+        """Split into solo devices."""
+        for device in self.distinct():
+            if device in self:
+                yield device
+
+    @classmethod
+    @cache
+    def permutations(cls) -> list[Self]:
+        """Obtain a list of all possible permutations of the devices."""
+        n = cls.n_distinct()
+        return [cls(v) for v in range(2**n)]

corel_mmio-8.0.0/src/corel_mmio/doc.py

@@ -0,0 +1,83 @@
+"""Utils for documentation."""
+
+from dataclasses import MISSING
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    Literal,
+    TypeVar,
+    overload,
+)
+
+from typing_extensions import Self
+
+if TYPE_CHECKING:
+    pass
+
+Owner = TypeVar("Owner")
+Value = TypeVar("Value")
+
+___all__ = [
+    "DocDescriptor",
+]
+
+
+class DocDescriptor(Generic[Owner, Value]):
+    """Descriptor to add runtime-retrievable documentation to a dataclass field."""
+
+    # noinspection PyShadowingBuiltins
+    def __init__(
+        self,
+        *,
+        doc: str,
+        default: Value | Literal["MISSING"] = MISSING,  # type: ignore[assignment]
+    ):
+        self._doc = doc
+        self._default = default
+
+        if self._doc:
+            self.__doc__ = doc
+
+    def __set_name__(self, owner: type[Owner], name: str) -> None:
+        self._private_name = "_" + name
+        self._public_name = name
+
+    @overload
+    def __get__(self, obj: None, obj_type: type[Owner] | None) -> Self: ...
+
+    @overload
+    def __get__(self, obj: Owner, obj_type: type[Owner] | None = None) -> Value: ...
+
+    def __get__(
+        self, obj: Owner | None, obj_type: type[Owner] | None = None
+    ) -> Value | Self:
+        # if obj is None:
+        #     return self
+
+        if not hasattr(obj, self._private_name):
+            raise AttributeError(f"'{self._private_name[1:]}' has not been set")
+
+        value: Value = getattr(obj, self._private_name)
+        return value
+
+    def __set__(self, obj: Owner, value: Value | Self) -> None:
+        if value == self:
+            if self._default is not MISSING:
+                value = self._default  # type: ignore[assignment]
+            else:
+                raise TypeError(
+                    f"TypeError: {obj.__class__.__name__}.__init__() missing "
+                    f"required positional argument: '{self._public_name}'"
+                )
+
+        setattr(obj, self._private_name, value)
+
+    @property
+    def doc(self) -> str:
+        """Get the documentation string for this descriptor."""
+        return self._doc
+
+    @property
+    def default(self) -> Value | Literal["MISSING"]:
+        """Get the default value for this descriptor."""
+        return self._default

corel_mmio-8.0.0/src/corel_mmio/eval.py

@@ -0,0 +1,51 @@
+"""Safe evaluation of expressions."""
+
+import ast
+from typing import TypeVar
+
+__all__ = [
+    "UnsupportedClassError",
+    "safe_eval_expr",
+]
+
+_T = TypeVar("_T")
+
+
+class UnsupportedClassError(ValueError):
+    """Raised when a class is not supported."""
+
+
+def safe_eval_expr(expr: str, supported: dict[str, type[_T]]) -> _T:
+    """Safely evaluates an expression of the form ClassName(arg=value)."""
+    tree = ast.parse(expr, mode="eval")
+
+    # Ensure it's a function call
+    if not isinstance(tree.body, ast.Call):
+        raise ValueError("Expression must be a function call")
+
+    # Ensure it's a valid function name
+    if not isinstance(tree.body.func, ast.Name):
+        raise ValueError("Invalid function call")
+
+    class_name = tree.body.func.id
+
+    # Ensure it's a supported class
+    if class_name not in supported:
+        raise UnsupportedClassError(f"Class {class_name} is not allowed")
+
+    # Extract positional arguments
+    args = []
+    for arg in tree.body.args:
+        if not isinstance(arg, ast.Constant):  # Only allow simple constants
+            raise ValueError("Only constant positional arguments are allowed")
+        args.append(arg.value)
+
+    # Extract keyword arguments
+    kwargs = {}
+    for kw in tree.body.keywords:
+        if not isinstance(kw.value, ast.Constant) or not isinstance(kw.arg, str):
+            raise ValueError("Only constant keyword arguments are allowed")
+        kwargs[kw.arg] = kw.value.value
+
+    # Instantiate the class safely
+    return supported[class_name](*args, **kwargs)

corel_mmio-8.0.0/src/corel_mmio/interface/__init__.py

@@ -0,0 +1 @@
+"""Interface definitions between the PC software and remote memory-mapped hardware."""