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.
