Skip to main content

Setting up Vitis in BeetleboxCI

Building the project on your host PC​

The first part of any Continuous Integration project is to build locally on your machine. The compilation of code in Vitis is handled through makefiles. There are two ways of handling these makefiles with Vitis:

  1. User-created makefiles. Through makefiles users are able to invoke Vitis. This method invokes vitis through the command-line and requires no IDE. Users have complete control over the makefile.
  2. Vitis IDE generated makefiles. By default, Vitis IDE generates makefiles automatically. This can significantly reduce the time taken in the difficult process of creating and managing makefiles. This is generally the preferred method for early development of FPGA designs.

If you are using the using the Vitis IDE to automatically generate makefiles, then projects, platforms and libraries will be need to be placed in specific locations to ensure that the makefile implements relative directories. Not using these locations will result in the makefile generating absolute directories that will only work on your host PC and limit the ability of BeetleboxCI to compile these files.

caution

Do not attempt to manually edit makefiles generated by Vitis IDE. This may lead to any changes being overwritten by Vitis IDE on next compilation.

The following must be placed in specific file directories:

  • Platforms Platforms must be placed in $XILINX_VITIS/platforms, where $XILINX_VITIS is the installation directiory of Vitis.
  • Firmware files
  • Workspace
  • Libraries

Vitis Images​

If you are creating an image with a particular version of Vitis on it, the name of the image must end in the version of Vitis that is on the image. For example, for an image with Vitis 2020.1, the name of the image must end in 2020-1.

Let's assume that the user is running their Kubernetes cluster on a machine named work1-virtualbox and they want to create a customised image with Xilinx Vitis 2020.1 on it. The user will need to download the Vitis offline installer from their official website. This is a very large file and it may take several hours to download. For Vitis 2020.1, this can be downloaded from (you will need to register and enter your details):

https://www.xilinx.com/member/forms/download/xef.html?filename=Xilinx_Unified_2020.1_0602_1208.tar.gz

After downloading, the tarball will need to be unzipped into a local folder, such as /home/ubuntu/Downloads/xilinx.

tar -xzf Xilinx_Unified_2020.1_0602_1208.tar.gz

You will find the contents of the tarball inside /home/ubuntu/Downloads/xilinx/Xilinx_Unified_2020.1_0602_1208/

You also need to download Xilinx Runtime (XRT):

https://www.xilinx.com/bin/public/openDownload?filename=xrt_202010.2.6.655_18.04-amd64-xrt.deb

This file should be saved the same directory which the tarball was unzipped to, such as /home/ubuntu/Downloads/xilinx

To create an image with Vitis, the user can begin with an official Ubuntu image from Dockerhub (makre sure you use a version of Linux that is supported by the version of Vitis that you are installing):

sudo systemctl start docker # ensures that the Docker service is running
docker pull ubuntu:20.04 
docker images
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
ubuntu       latest    df5de72bdb3b   2 weeks ago   77.8MB

We can see that the Ubuntu image has been pulled. The image ID may be different from the one shown here.

We can then start a container using this image. The following command creates a container then mounts the folder with the offline installer and XRT (/home/ubuntu/Downloads/xilinx) into the container at /mnt/xilinx:

docker run --privileged \
           -v /home/ubuntu/Downloads/xilinx:/mnt/xilinx \
           -it df5de72bdb3b
root@d525852fc258:/#

Docker will assign an ID to the container, which is distinct from the ID of the image. In this case, the assigned container ID is d525852fc258.

Once inside the container, you will need to enter the folder that has been mounted:

cd /mnt/xilinx/Xilinx_Unified_2020.1_0602_1208/

Run the following command to see information about the offline installation process:

./xsetup --help

Run the following command to generate to generate an authentication token. You will be prompted to enter your Xilinx login details:

./xsetup -b AuthTokenGen

Run the following command to generate the config settings to install Vitis. You may be prompted for information while it runs:

./xsetup -b ConfigGen

A number of dependencies need to be installed on the container before Vitis can be installed, since the docker container runs a bare-bones copy of Ubuntu.

apt-get update -y
apt-get -y install xz-utils gcc python3 git make gcc-multilib g++-multilib parted udev net-tools expect psmisc  python3-pip locales
locale-gen "en_US.UTF-8"
update-locale LANG=en_US.UTF-8
localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
rm -rf /var/lib/apt/lists/*

We can then install Vitis:

./xsetup --a XilinxEULA,3rdPartyEULA,WebTalkTerms -b Install -c /root/.Xilinx/install_config.txt

Once completed, XRT may need to be installed (depending on your specific needs):

cd /mnt/xilinx
apt-get update
apt-get install /mnt/xilinx/xrt_202010.2.6.655_18.04-amd64-xrt.deb

Some dependencies for XRT will need to be installed:

cd ~/
git clone https://github.com/Xilinx/XRT
cd XRT/src/runtime_src/tools/scripts
./xrtdeps.sh
cd ~/
rm -rf ~/XRT

Afterwards, we can exit the container:

root@d525852fc258:/# exit

We can check the status of the container(s) that are on the machine:

docker ps -a
CONTAINER ID   IMAGE          COMMAND   CREATED              STATUS                     PORTS     NAMES
d525852fc258   df5de72bdb3b   "bash"    About a minute ago   Exited (0) 4 seconds ago             kind_benz

The user can then create a new image from the container using the following command:

docker commit d525852fc258

It must be noted that when running Vitis 2020.1 in Ubuntu, a specific environment variable needs to be set, so an extra flag must be specified:

docker commit --change "ENV LIBRARY_PATH=/usr/lib/x86_64-linux-gnu" d525852fc258 
5609a37ae4b2

We can see the image that we just created using:

docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
<none>       <none>    5609a37ae4b2   20 seconds ago   77.8MB
ubuntu       latest    df5de72bdb3b   2 weeks ago      77.8MB

You can check that the environment variables in the image have seen set correctly using the following command:

docker inspect -f "{{ .Config.Env }}" 5609a37ae4b2

This image then needs to be tagged. The tag shows the repository where the image will be stored ("work1-virtualbox:5000"), the image name ("ubuntu_vitis_2020_1"), and the image version ("latest").

docker tag 5609a37ae4b2 work1-virtualbox:5000/ubuntu_vitis_2020_1:latest

Finally, the tagged image can be pushed. Docker will push to the registry specified in the tag.

docker push work1-virtualbox:5000/ubuntu_vitis_2020_1:latest

The image work1-virtualbox:5000/ubuntu_vitis_2020_1:latest can now be used to create containers for users to run jobs in BeetleboxCI, by specifying this in the config file included within the user's codebase.