Alveo Getting Started Guide

Prerequisites

  • A version of the Xilinx Runtime (XRT) above or equal 2.3 installed in the system. Previous versions of XRT might still work, but are not explicitly supported. Moreover, the functionalities offered by the Embedded Runtime Library (ERT) will not work with versions of XRT below 2.3.
  • Any XRT-supported version of either RedHat/CentOS or Ubuntu as Operating System
  • Python and PIP must be installed. The minimum Python version is 3.5.2, although the recommended minimum version is 3.6

Install PYNQ

Simply install pynq through PIP

pip install pynq

In case needed, please read the Extended Setup Instructions section for more detailed instructions.

Get the Introductory Examples

Install the pynq-alveo-examples package using PIP

pip install pynq-alveo-examples

Once that is done, run the get-notebooks command in your shell session

pynq get-notebooks

This will deliver all the available notebooks in a pynq-notebooks folder in your current working directory.

You can now move to the newly created pynq-notebooks folder and run Jupyter there

cd pynq-notebooks
jupyter notebook

Note

When retrieving the notebooks using the pynq get-notebooks command, overlays might be downloaded from the web and might be available only for specific cards/shells. The get-notebooks command has a few optional parameters that can be used to customize the notebooks delivery. Please run pynq get-notebooks -h to see them. Refer to the PYNQ Command Line Interface section for more detailed information.

Extended Setup Instructions

Sourcing XRT

The first thing you will have to do before every session, is source the XRT setup script. To do so, open up a bash shell and type:

source /opt/xilinx/xrt/setup.sh

The path /opt/xilinx/xrt is the predefined install path for XRT and should not be changed. Therefore, the setup script will always be located there.

Note

In case you try to use PYNQ without sourcing XRT, you will get a warning asking if XRT was correctly sourced.

Install Conda

To get PYNQ, we recommend to install and use Conda. In particular, we recommend to install Anaconda as it already includes most of the required packages.

To install conda, you can follow either the official conda installation guide, or look at the anaconda instructions.

For instance, to install the latest Anaconda distribution you can do

wget https://repo.anaconda.com/archive/Anaconda3-2019.10-Linux-x86_64.sh
bash Anaconda3-2019.10-Linux-x86_64.sh

After you have installed it make sure conda is in your PATH, and in case is not just source the conda activation script

source <your-conda-install-path>/bin/activate

Using a Conda Environment

In case you want to use a conda environment instead of the base installation, follow these simple steps to get everything you need:

1. Save the content of this GIST as environment.yml

  1. Create the pynq-env environment using the above configuration

    conda env create -f environment.yml
    
  2. Activate the newly created environment

    conda activate pynq-env
    

The provided environment.yml can also be useful to re-create an environment which is already tested and confirmed to be working, in case you are having issues.

Install Jupyter

By default, installing pynq will not install jupyter. In case you want it, you can install it using PIP

pip install jupyter

Or install the pynq-alveo-examples package as previously shown. This package will install Jupyter as a dependency, alongside the other packages required to run the included example notebooks.

Note

When installing jupyter with a version of Python less than 3.6, you will have to make sure to have a compatible version of ipython installed. Therefore, in this case after installing jupyter, force-install ipython with an appropriate version. The recommended is version 7.9, and you can ensure this is the version installed by running pip install --upgrade ipython==7.9.