finn-plus-driver 1.5.0__tar.gz

finn_plus_driver-1.5.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: finn-plus-driver
+Version: 1.5.0
+Summary: PYNQ runtime driver for FPGA accelerators generated by finn-plus
+Maintainer: Felix Jentzsch
+Maintainer-email: felix.jentzsch@upb.de
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: bitstring (>=4.0)
+Requires-Dist: click (>=8.0)
+Requires-Dist: finn-dataset-loading (>=0.0.5)
+Requires-Dist: grpcio (==1.64.0)
+Requires-Dist: h5py (>=3.0)
+Requires-Dist: matplotlib (>=3.4)
+Requires-Dist: numpy (>=1.21,<2.0.0)
+Requires-Dist: pillow (>=9.0)
+Requires-Dist: qonnx (>=1.0.0)
+Project-URL: EKI Project, https://www.eki-project.tech/
+Project-URL: GitHub, https://github.com/eki-project/finn-plus
+Description-Content-Type: text/markdown
+
+# finn-plus-driver
+
+Runtime driver for FPGA accelerators generated by
+[finn-plus](https://github.com/eki-project/finn-plus) and deployed to ZYNQ/PYNQ boards.
+
+This package contains everything needed to *run* a FINN-generated accelerator and nothing
+of the compiler itself. It is installed on the board, while the accelerator-specific
+artifacts (bitfile, `settings.json`, runtime weights) are produced by the finn-plus build
+flow and copied to the board separately.
+
+## Installation
+
+On a PYNQ board, inside the PYNQ virtual environment:
+
+```bash
+sudo pip install finn-plus-driver
+```
+
+`pynq` itself is not declared as a dependency: it is part of the board image.
+
+To install the version matching a repository checkout (e.g. in CI):
+
+```bash
+sudo pip install ./driver
+```
+
+## Usage
+
+The driver is usually invoked through its CLI, which instantiates the driver class named in
+`settings.json` and calls one of its member functions:
+
+```bash
+finn-plus-driver -b bitfile/finn-accel.bit -s driver/settings.json -f throughput_test
+```
+
+It can equally be used as a library:
+
+```python
+from finn_plus_driver import FINNDMAOverlay
+
+accel = FINNDMAOverlay("finn-accel.bit", io_shape_dict=io_shape_dict)
+output = accel.execute(input_array)
+```
+
+## Contents
+
+| Module | Purpose |
+| --- | --- |
+| `finn_plus_driver.overlays.dma` | `FINNDMAOverlay`, the standard DMA-based accelerator driver |
+| `finn_plus_driver.overlays.instrumentation` | `FINNInstrumentationOverlay`, DMA-less instrumentation runs |
+| `finn_plus_driver.overlays.live_fifo` | `FINNLiveFIFOOverlay`, live FIFO sizing experiments |
+| `finn_plus_driver.overlays.dma_instrumentation` | `FINNDMAInstrumentationOverlay`, combined DMA + instrumentation |
+| `finn_plus_driver.packing` | Data packing/unpacking between numpy and the accelerator's bit-level format |
+| `finn_plus_driver.validate` | Dataset-specific accuracy validation (MNIST, CIFAR, ImageNet, RadioML, UNSW-NB15) |
+| `finn_plus_driver.cli` | Command line interface |
+

finn_plus_driver-1.5.0/README.md

@@ -0,0 +1,55 @@
+# finn-plus-driver
+
+Runtime driver for FPGA accelerators generated by
+[finn-plus](https://github.com/eki-project/finn-plus) and deployed to ZYNQ/PYNQ boards.
+
+This package contains everything needed to *run* a FINN-generated accelerator and nothing
+of the compiler itself. It is installed on the board, while the accelerator-specific
+artifacts (bitfile, `settings.json`, runtime weights) are produced by the finn-plus build
+flow and copied to the board separately.
+
+## Installation
+
+On a PYNQ board, inside the PYNQ virtual environment:
+
+```bash
+sudo pip install finn-plus-driver
+```
+
+`pynq` itself is not declared as a dependency: it is part of the board image.
+
+To install the version matching a repository checkout (e.g. in CI):
+
+```bash
+sudo pip install ./driver
+```
+
+## Usage
+
+The driver is usually invoked through its CLI, which instantiates the driver class named in
+`settings.json` and calls one of its member functions:
+
+```bash
+finn-plus-driver -b bitfile/finn-accel.bit -s driver/settings.json -f throughput_test
+```
+
+It can equally be used as a library:
+
+```python
+from finn_plus_driver import FINNDMAOverlay
+
+accel = FINNDMAOverlay("finn-accel.bit", io_shape_dict=io_shape_dict)
+output = accel.execute(input_array)
+```
+
+## Contents
+
+| Module | Purpose |
+| --- | --- |
+| `finn_plus_driver.overlays.dma` | `FINNDMAOverlay`, the standard DMA-based accelerator driver |
+| `finn_plus_driver.overlays.instrumentation` | `FINNInstrumentationOverlay`, DMA-less instrumentation runs |
+| `finn_plus_driver.overlays.live_fifo` | `FINNLiveFIFOOverlay`, live FIFO sizing experiments |
+| `finn_plus_driver.overlays.dma_instrumentation` | `FINNDMAInstrumentationOverlay`, combined DMA + instrumentation |
+| `finn_plus_driver.packing` | Data packing/unpacking between numpy and the accelerator's bit-level format |
+| `finn_plus_driver.validate` | Dataset-specific accuracy validation (MNIST, CIFAR, ImageNet, RadioML, UNSW-NB15) |
+| `finn_plus_driver.cli` | Command line interface |

finn_plus_driver-1.5.0/finn_plus_driver/__init__.py

@@ -0,0 +1,48 @@
+"""Runtime driver for FPGA accelerators generated by finn-plus.
+
+The overlay classes require ``pynq``, which is only available on a PYNQ board image. They
+are therefore imported lazily, so that helper modules such as :mod:`finn_plus_driver.packing`
+remain usable off-board (for example in tests or on a build host).
+"""
+
+from typing import Any
+
+#: Maps the driver type names emitted into ``settings.json`` by the finn-plus build flow to
+#: the module that implements them. Used instead of module introspection so the mapping is
+#: explicit and does not depend on import side effects.
+DRIVER_TYPES: dict[str, str] = {
+    "FINNDMAOverlay": "finn_plus_driver.overlays.dma",
+    "FINNInstrumentationOverlay": "finn_plus_driver.overlays.instrumentation",
+    "FINNLiveFIFOOverlay": "finn_plus_driver.overlays.live_fifo",
+    "FINNDMAInstrumentationOverlay": "finn_plus_driver.overlays.dma_instrumentation",
+}
+
+__all__ = [*DRIVER_TYPES, "DRIVER_TYPES", "get_driver_class"]
+
+
+def get_driver_class(driver_type: str) -> type:
+    """Return the overlay class for the given driver type name.
+
+    Args:
+        driver_type: Name of the driver class, as stored in ``settings.json``.
+
+    Returns:
+        The overlay class matching ``driver_type``.
+
+    Raises:
+        ValueError: If ``driver_type`` is not a known driver type.
+    """
+    from importlib import import_module
+
+    if driver_type not in DRIVER_TYPES:
+        raise ValueError(
+            f"Unknown driver type '{driver_type}'. Known types: {sorted(DRIVER_TYPES)}"
+        )
+    return getattr(import_module(DRIVER_TYPES[driver_type]), driver_type)
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve overlay classes lazily so importing this package does not require pynq."""
+    if name in DRIVER_TYPES:
+        return get_driver_class(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

finn_plus_driver-1.5.0/finn_plus_driver/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the driver CLI via ``python -m finn_plus_driver``."""
+
+from finn_plus_driver.cli import driver_cli
+
+if __name__ == "__main__":
+    driver_cli()

finn_plus_driver-1.5.0/finn_plus_driver/cli.py

@@ -0,0 +1,97 @@
+"""Command line interface for the FINN PYNQ runtime driver."""
+
+import click
+import json
+
+from finn_plus_driver import get_driver_class
+
+
+def parse_kv(ctx, self, value):
+    """Parse key-value pairs from CLI arguments."""
+    result = {}
+    for item in value:
+        if len(item) != 2:
+            print(item)
+            raise click.UsageError(
+                "Items must be in form: key=val TYPE. "
+                'With datatypes ["Str", "Int", "Bool", "Float"] being supported'
+            )
+        if item[0].count("=") != 1:
+            raise click.BadParameter("Items must be key=value")
+        k, v = item[0].split("=", 1)
+
+        data_type = item[1]
+        if data_type == "Str":
+            v = v
+        elif data_type == "Int":
+            v = int(v)
+        elif data_type == "Bool":
+            # Is always True except for v == False
+            v = not (v == "False")
+        elif data_type == "Float":
+            v = float(v)
+        else:
+            raise click.BadParameter(
+                f'Only datatypes ["Str", "Int", "Bool", "Float"] '
+                f"are supported. Used datatype: {data_type}"
+            )
+
+        result[k] = v
+    return result
+
+
+@click.command(
+    "Example: finn-plus-driver -b ../bitfile/finn-accel.bit "
+    "-s ./settings.json -f experiment_instrumentation "
+    "-ck seed=42 Int -fk runtime=10 Int "
+    "-fk report_dir='./report_dir/' Str"
+)
+@click.option("--bitfile_name", "-b", help="Path to the Bitstream")
+@click.option("--settings", "-s", help="Path to the settings.json")
+@click.option("--function", "-f", help="Function to be executed")
+@click.option(
+    "--ckwarg",
+    "-ck",
+    multiple=True,
+    callback=parse_kv,
+    nargs=2,
+    help=("Keyword argument for the class instance: ... -ck key1=val1 TYPE -ck key2=val2 TYPE"),
+)
+@click.option(
+    "--fkwarg",
+    "-fk",
+    multiple=True,
+    callback=parse_kv,
+    nargs=2,
+    help=("Keyword argument for the called function: ... -fk key1=val1 TYPE -fk key2=val2 TYPE"),
+)
+def driver_cli(bitfile_name, settings, function, ckwarg, fkwarg):
+    """CLI tool to instantiate driver and execute functions.
+
+    Instantiates a driver class and executes a member function.
+    The instantiation implicitly loads a bitstream to the FPGA.
+    Requires FINN generated bitstream file and settings.json.
+    Driver class is inferred from settings.json, while the called
+    member function must be chosen via the function option.
+    Kwargs for class instantiation or function call can be input
+    via --ckwarg or --fkwarg options respectively.
+    Class Kwargs take precedence over settings.json Kwargs.
+    """
+    with open(settings, encoding="utf-8") as f:
+        driver_settings = json.load(f)["driver_information"]
+
+    if ckwarg is None:
+        ckwarg = {}
+    if fkwarg is None:
+        fkwarg = {}
+
+    driver_type = driver_settings["driver_type"]
+    input_kwargs = {
+        **driver_settings,
+        **ckwarg,
+    }  # ckwarg has precedence when a key conflict happens
+
+    cla = get_driver_class(driver_type)
+    inst = cla(bitfile_name, **input_kwargs)
+    func = getattr(inst, function)
+    print(func(**fkwarg))

finn_plus_driver-1.5.0/finn_plus_driver/hwh.py

@@ -0,0 +1,32 @@
+"""Helpers for reading metadata out of the HWH file accompanying a bitfile."""
+
+import os
+import xml.etree.ElementTree as ET
+
+
+def get_clk_wiz_params_from_hwh(bitfile_name):
+    """Parse the HWH file to get clk_wiz_0 parameters.
+
+    PYNQ's ip_dict only contains IPs with an AXI-Lite slave interface, so the
+    Clocking Wizard (when configured without AXI-Lite) will not appear there.
+    This function reads the HWH XML directly to retrieve its parameters.
+
+    Returns a dict of parameter name -> value strings. The dict is empty when the HWH file
+    is missing, unparsable, or contains no Clocking Wizard, so that callers can fall back to
+    their configured frequency via ``dict.get(..., default)`` without a None check.
+    """
+    hwh_path = os.path.splitext(bitfile_name)[0] + ".hwh"
+    if not os.path.exists(hwh_path):
+        return {}
+    try:
+        tree = ET.parse(hwh_path)
+        root = tree.getroot()
+        for module in root.iter("MODULE"):
+            if module.get("INSTANCE") == "clk_wiz_0":
+                params = {}
+                for param in module.iter("PARAMETER"):
+                    params[param.get("NAME")] = param.get("VALUE")
+                return params
+    except ET.ParseError:
+        return {}
+    return {}

finn_plus_driver-1.5.0/finn_plus_driver/overlays/__init__.py

@@ -0,0 +1,13 @@
+"""Overlay classes for FINN-generated accelerators."""
+
+from finn_plus_driver.overlays.dma import FINNDMAOverlay
+from finn_plus_driver.overlays.dma_instrumentation import FINNDMAInstrumentationOverlay
+from finn_plus_driver.overlays.instrumentation import FINNInstrumentationOverlay
+from finn_plus_driver.overlays.live_fifo import FINNLiveFIFOOverlay
+
+__all__ = [
+    "FINNDMAInstrumentationOverlay",
+    "FINNDMAOverlay",
+    "FINNInstrumentationOverlay",
+    "FINNLiveFIFOOverlay",
+]