Installation
Prerequisites
Xilinx Toolchain
To work with Vivado and Vitis, you need to have the tools installed. You can download the tools here. You will need to create an AMD account if you do not already have one. Once you open the installer, select the Vitis option to install both Vivado and Vitis. Be aware that this installation will take some (a lot of) time due to the large download size!
Note
We would recommend not using Xilinx 2024.1 due to a major bug in the API provided for Vitis that requires user intervention after the first build.
Python
You must have Python version 3.9 or greater installed on your machine. See the Python website.
Git
You need to have Git installed on your machine. For Windows, you can download it from here. For Linux, you can use the package manager of your distribution. For example, on Ubuntu, you can use the following command:
sudo apt install git
Note
Verify that Git is available in your path by typing git --version in your terminal. If no version is printed, you need to add it to your path as otherwise the installation of XiBIF will fail.
A Code Editor
There is no limit for code editors out there, but among the most popular is Visual Studio Code. It is an excellent choice for software development and comes with the benefits of countless plugins and Sigasi Support (HDL Editor). You are free to choose whichever editor you like, but be advised that our support capabilities for alternative editors might be limited.
Step-by-Step Installation Guide
Setting up VSCode
You won’t need much to work in VSCode, but there are a number of extensions that we recommend. To browse the extension marketplace, click the four boxes, one of which is flying away on the left side of the screen. In the search bar type “Python” and install the top recommendation with a lot of downloads. This will add basic Python support to the editor. Also search for Sigasi Visual HDL which is useful if you want to edit HDL code in VSCode.
Creating a Virtual Environment
To create a virtual environment, use the following command:
python -m venv .venv-xibif
This will create a virtual environment called .venv-xibif, which means a directory called .venv-xibif is created in your current working directory. It is also the location where all of your packages will be installed.
Note
The dot (.) prefix is a convention used for virtual environment names, since it hides the directory from file system explorer applications by default. You do not have to use it.
Now we proceed to actually activating the environment. You can do this by typing:
. .venv-xibif/bin/activate # Linux/macOS
. .venv-xibif/Scripts/activate # Windows
To test whether the activation worked, type which python to display the path that is used when executing Python. It should display a path to your virtual environment.
Tip
When you type a command (any command) in your terminal, your system needs to know where to look for the corresponding executable. Any command executed in the console is nothing more than a program. The search location for these commands is controlled by the PATH environment variable.
The PATH variable is a list of directories where your system searches for executables. When you enter a command, the system checks each directory in the PATH variable in order until it finds a match. So when you install Python, the installer will automatically add the Python installation directory to the PATH variable.
What happens when you activate a virtual environment is that the activate script prepends the Python path of the virtual environment to the PATH variable. Since your OS checks the variable in order and takes the first match, the terminal will then proceed to use the installation in the virtual environment until that environment is deactivated.
Installing the XiBIF Package
Now that you have a properly set up working environment, you are ready to install the XiBIF package. Typing:
pip install XiBIF --index-url https://gitlab.ost.ch/api/v4/groups/12907/-/packages/pypi/simple
should do the trick.
Testing the Python Package
The explanation below will focus on VSCode.
In your console, you can now type:
xibif
which should give you an output on the console. If this works, the xibif package has been successfully installed.
Getting Help
Get some help! Type:
xibif -h
# or
xibif --help
to print the help screen. It should look something like this:
usage: XiBIF [-h] [-v] [-p PROJECT] [--verbosity {debug,info,warning,error,none}] [--summary] {new,build,flash,register,simulation,testbench,shell,report,upgrade,settings,start} ...
XiBIF – Xilinx Board Interface
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-p PROJECT, --project PROJECT
Specify the XiBIF project file to use (default: None)
--verbosity {debug,info,warning,error,none}
Set the verbosity of the console output (default: info)
--summary Show only a summary of the log output (default: False)
subcommands:
{new,build,flash,register,simulation,testbench,shell,report,upgrade,settings,start}
new Create a new XiBIF project
build Run all build steps for the XiBIF project
flash Flash the FPGA with the generated bitstream
register Update the XiBIF Registers from the register file
simulation Simulate all VHDL testbenches
testbench Generate a testbench from a VHDL file
shell Open an interative shell to communicate with a XiBIF board
report Report an issue to XiBIF's GitLab page
upgrade Upgrade the VHDL and C source-files to the newest XiBIF version
settings Change the settings of the XiBIF project
start Start a tool
This help exists for all subcommands; so if you are ever unsure about how to do something, you’ll probably find a solution in the help screen.
Anaconda (optional)
If you want to generate an user interface, you need to install Gtk 3.0. Gtk is a cross-platform GUI library that allows your application to run on Windows, Linux, and Mac.
Windows
Unfortunately, it is really hard to install on Windows. The best way we have found is to install it using Anaconda. Anaconda is a package manager and environment management tool that supports multiple languages, including Python.
To install Anaconda, follow this link.
Once you have installed Anaconda, you can open the Anaconda Navigator application. There, navigate to the tab “Environments” and click “Import” at the bottom of the window. You will be prompted to specify a YAML-file. Use the conda.yaml file found in the XiBIF repository. Give it a meaningful name and then click “Import”. This should automatically install all dependencies needed to be able to run XiBIF (apart from the Xilinx toolchain of course).
Linux
On Linux, installing Gtk is much easier. Simply use the following command:
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0
Note
apt does not work for all distributions of Linux, but then again, if you are using AlmaLinux, shouldn’t you know how to install packages already? ;-)
Upgrading the XiBIF Package
To upgrade to the latest XiBIF version, first the python package needs to be updated. This can be done by using the following command:
pip install XiBIF --upgrade --index-url https://gitlab.ost.ch/api/v4/groups/12907/-/packages/pypi/simple
Afterwards the VHDL and C source files need to be updated. This can be done by running the following command in the project folder:
xibif upgrade
Note
To upgrade from a version lower than v4.3.0, it is necessary to recreate the Vitis project. XiBIF will prompt you to do so. This is due to the fact that the Vitis project structure has changed in v4.3.0.
To upgrade from a version lower than v4.4.0, it is necessary to update the Vivado block design. XiBIF will do this automatically. In short, a new AXI-Firewall IP is added to the design. This block is needed in order to use the new AXI read and write functions from XiBIF.
To upgrade from a version lower than v4.5.0, it is necessary to update the Vivado block design. XiBIF will do this automatically. In short, the existing XiBIF Streaming IP is replaced with the new version which is built around the open-logic library. This change improves the performance and reliability of the streaming interface.