How to contribute to finn-examples

[auphelia]

How to contribute to finn-examples

Do you have an interesting FINN use case that you'd love to showcase and tell people about? If so, this is the blog post for you!

Xilinx/finn-examples is a repository with pre-built dataflow accelerators generated with FINN. It contains bitfiles of accelerators of trained networks for PYNQ boards and Alveo U250, and Jupyter notebooks to run each accelerator on the specified board. Additionally, the repository contains scripts to rebuild most of these examples.

We are very happy that the repository not only contains our own examples but also examples contributed by the community, for example RF modulations recognition (contributed by University of Paderborn), keyword spotting (contributed by University of Heidelberg) and a face mask detection example (contributed by TU Munich).

Below you find a description on how the finn-examples repository is structured and how we expect a PR to look like to be merged into the repository.

Repository structure of finn-examples

Notebooks & bitfiles (PyPI package)
Files in finn-examples folder Bitfiles get published with every new release Every example has dictionary with meta data, e.g. i/o shapes Notebook that shows how to use the bitfile Runs either on the ARM core on the Zynq devices or on the host in a python environment for Alveo cards Images are saved in images/ folder Additional data for example for pre-processing is added in data/ folder

Build flows to reproduce

Folder for each use case Subfolder with script to download models, starting point of the build flows is always onnx file Subfolder with folding configuration, can provide multiple folding configurations depending on for example the target device Build flows to set the builder configuration Custom steps that are used in the build scripts next to the standard steps README with information about the use case & instructions on re-running the build flow

How to add a new use case to finn-examples

Use cases can be contributed with or without possibility to reproduce:

• Without possibility to reproduce:

  • Like the face mask detection, see here.
  • Contribution would be in form of bitfile & Jupyter notebook on how to run the bitfile on a board using the provided driver. The dictionary with meta data about the accelerator will need to be added to allow the correct usage of the pynq driver.

• With possibility to reproduce:

  • Like RadioML, see notebook and build flow here.
  • Contribution like above with the addition of the code to reproduce
  • Build flow, folding configurations, exported model from Brevitas in QONNX or FINN-ONNX format, custom steps if needed, readme with information about use case and steps on how to reproduce

• In general, if images are included, make sure that whoever is the owner has given his or her permission to use the image. Also licenses for data sets need to be checked.

If you have any questions, please reach out to us. You can also open a draft PR, if you are unsure about the style and we can work together from there.

Looking forward to your contributions!

The FINN team