Repository files navigation

for PYNQ on Zynq and Alveo

This repository contains a variety of customized FPGA neural network acceleratorexamples built usingtheFINN compiler, whichtargets few-bit quantized neural networks with emphasis ongenerating dataflow-style architectures customized for each network.

The examples here come withpre-built bitfiles, PYNQ Python drivers and Jupyter notebooks to get started,and you can rebuild them from source.Both PYNQ on Zynq and Alveo are supported.

Need help with a problem in this repo, or got a question? Feel free to ask for help in theGitHub discussions.In the past, we also had aGitter channel. Please be aware that this is no longer maintained by us but can still be used to search for questions previous users had.

We recommend PYNQ version 3.0.1, but older installations of PYNQ should also work. For PYNQ v2.6.1, please refer for set-up instructions toFINN-examples v0.0.5.

For ZYNQ boards, all commands below must be prefixed withsudo or by first going intosudo su.

First, source the PYNQ and XRT virtual environment:

source /etc/profile.d/pynq_venv.shsource /etc/profile.d/xrt_setup.sh

Next, ensure that yourpip andsetuptools installations are up-to-dateon your PYNQ board:

python3 -m pip install pip==23.0 setuptools==67.1.0

Since we are going to install finn-examples without build-isolation, we need to ensure all dependencies are installed. For that, installsetuptools_scm as well:

python3 -m pip install setuptools_scm==7.1.0

Install thefinn-examples package usingpip:

# remove previous versions with: pip3 uninstall finn-examplespip3 install finn-examples --no-build-isolation# to install particular git branch:# pip3 install git+https://github.com/Xilinx/finn-examples.git@dev --no-build-isolation

Retrieve the example Jupyter notebooks using the PYNQ get-notebooks command. An example of how to run the Jupyter notebook server, assuming we are forwarding port 8888 from the target to some port on our local machine, is also shown below:

# on PYNQ boards, first cd /home/xilinx/jupyter_notebookspynq get-notebooks --from-package finn-examples -p. --forcejupyter-notebook --no-browser --allow-root --port=8888

For Alveo we recommend setting up everything inside a virtualenv as describedhere.

First, create & source a virtual environment:

conda create -n<virtual-env> python=3.8conda activate<virtual-env>

Next, ensure that yourpip andsetuptools installations are up-to-date:

python3 -m pip install --upgrade pip==23.0 setuptools==67.2.0

Finally, we can now install Pynq, FINN-examples and Jupyter (please note to source the XRT environment before):

pip3 install pynq==3.0.1python3 -m pip install setuptools_scm==7.1.0 ipython==8.9.0pip3 install finn-examples --no-build-isolation# to install particular git branch:# pip3 install git+https://github.com/Xilinx/finn-examples.git@dev --no-build-isolationpython3 -m pip install jupyter==1.0.0

Retrieve the example Jupyter notebooks using the PYNQ get-notebooks command. An example of how to run the Jupyter notebook server is also shown below:

pynq get-notebooks --from-package finn-examples -p. --forcejupyter-notebook --no-browser --port=8888

You can now navigate the provided Jupyter notebook examples, or just use theprovided accelerators as part of your own Python program:

fromfinn_examplesimportmodelsimportnumpyasnp# instantiate the acceleratoraccel=models.cnv_w2a2_cifar10()# generate an empty numpy array to use as inputdummy_in=np.empty(accel.ishape_normal(),dtype=np.uint8)# perform inference and get outputdummy_out=accel.execute(dummy_in)

Please note that you can target other boards (such as the Pynq-Z2 or ZCU102) by changing the build script manually, but these accelerators have not been tested.

We welcome community contributions to add more examples to this repo!

Note that the larger NNs are only available on Alveo or selected Zynq boards.

finn-examples provides pre-built FPGA bitfiles for the following boards:

• Edge: Pynq-Z1, Ultra96 and ZCU104
• Datacenter: Alveo U250

It's possible to generate Vivado IP for the provided examples to targetanymodern Xilinx FPGA of sufficient size.In this case you'll have to manually integrate the generated IP into your designusing Vivado IPI.You can read more about thishere.

All of the examples here are built using theFINN compiler, and can be re-built or customized.See thebuild/README.md for more details.