Skip to main content

Setting up the CI Environment for Vivado and FPGAs

In this first part of the tutorial series, you will be setting up the CI Environment. You will learn how to set up and configure your continuous integration software to work with Vivado. This will include setting up a repository for your FPGA projects and configuring the build environment on a Virtual Machine (VM).

Downloading and installing Vivado​

If you already have Vivado downloaded and installed, you can skip this section.

  1. Download and install VirtualBox on your computer from the official website.
  2. Download the Ubuntu 18.04.4 LTS (Long-Term Support) VM image from the official Ubuntu website . Download ubuntu-18.04.4-desktop-amd64.iso (assuming that you have an x86_64 system).
  3. Open VirtualBox and click the Menu button next to the tools option and click Welcome. Click on the New button to create a new virtual machine.
  4. In the Create Virtual Machine window, give the VM a name (e.g. Ubuntu 18.04), select Linux as the type and Ubuntu as the version.
  5. Set the amount of memory and hard disk space for the VM. It's recommended to have at least 16GB of RAM and 100GB of hard disk space for the VM. Also set the number of CPUs to more than four.
  6. Once you create the VM, select the VM and click Settings. Go to Storage settings. Click the line with a CD icon that says Empty. Under Attributes, you will see IDE Secondary Device 0. Click the CD icon next to that, and click Choose Disk File.
  7. Browse to the location where you downloaded the Ubuntu 18.04 VM image and select the file. Select the file, click Open and click OK.
  8. Start the virtual machine by clicking on the Start button – it will boot using the ISO image that you added in the previous step. The Ubuntu 18.04.4 installation process will begin.
  9. Follow the on-screen instructions to complete the Ubuntu 18.04 installation. You can then start your Ubuntu VM. You may be prompted to upgrade you version of Ubuntu, but do not do this. Vivado is not compatible with certain versions of Ubuntu.
  10. Open the terminal and run the following command:
sudo apt-get update
sudo apt-get install -y libgtk2.0-0 libxtst6 libxi6
  1. In the VM download the Vivado 2020.1 installer from the official Xilinx website .
  2. Open a terminal in the directory where the Xilinx installer was saved and run the following commands in the terminal:
sudo chmod +x ./Xilinx_Unified_2020.1_0602_1208_Lin64.bin

sudo ./Xilinx_Unified_2020.1_0602_1208_Lin64.bin --keep --noexec --target /opt/Xilinx/Vivado

sudo apt-get update -y
sudo apt-get -y install xz-utils gcc python3 git make gcc-multilib g++-multilib parted udev net-tools expect 
sudo rm -rf /var/lib/apt/lists/*
sudo /opt/Xilinx/Vivado/xsetup  Add -a XilinxEULA,3rdPartyEULA
  1. Follow the on-screen instructions to complete the Vivado 2020.1 installation.
note

If you are running the Ubuntu VM in headless mode, you can use ssh to connect and run the Vivado installer and follow the instructions on the terminal. You can install the Vivado Design Edition or System Edition, but it is recommended to use the Design Edition unless you require the additional features of the System Edition

Making a template Vivado project​

  1. Open Vivado. You can open it by typing the following commands in the terminal:
source /tools/Xilinx/Vivado/2020.1/settings64.sh
vivado

and create a new project by clicking on Create New Project in the Welcome screen or going to File > New > Project.

  1. In the Project Name field, enter a name for your project (e.g., VHDL Tutorial). Choose a location for the project files and select RTL Project as the project type. Click Next.
  2. In the Default Part screen, select Boards and choose a board that you have access to or None if you don't have any board. Click Next.
  3. In the Add Sources screen, click on the Add button. In the Add Sources window, select Create File and enter a name for the file (e.g., half_adder). Select VHDL as the file type and click OK.
  4. A new VHDL file will be created and opened in the Vivado text editor. Enter the following VHDL code in the file:
half_adder.vhd
library ieee;
use ieee.std_logic_1164.all;

entity half_adder is
  port (a, b : in std_logic;
        sum, carry : out std_logic
    );
end half_adder;

architecture arch of half_adder is
begin
  sum <= a xor b;
  carry <= a and b;
end arch;

This code creates an entity called half_adder.

  1. Save the file by going to File > Save.
  2. Go to the Sources tab in the left sidebar, right-click on the half_adder.vhd file and select Add to sources as > Top-level Entity.
  3. In the Sources tab, right-click on the project name and select Create Simulation Sources.
  4. In the Create Simulation Sources window, select VHDL Test Bench as the type and enter a name for the file (e.g., main_tb). Click OK.
  5. A new VHDL file will be created and opened in the Vivado text editor. Enter the following VHDL code in the file:
half_adder_simple_tb.vhd
library ieee;
use ieee.std_logic_1164.all;


entity half_adder_simple_tb is
end half_adder_simple_tb;

architecture tb of half_adder_simple_tb is
    signal a, b : std_logic;  -- inputs
    signal sum, carry : std_logic;  -- outputs
begin
    -- connecting testbench signals with half_adder.vhd
    UUT : entity work.half_adder port map (a => a, b => b, sum => sum, carry => carry);

    -- inputs
    -- 00 at 0 ns
    -- 01 at 20 ns, as b is 0 at 20 ns and a is changed to 1 at 20 ns
    -- 10 at 40 ns
    -- 11 at 60 ns
    a <= '0', '1' after 20 ns, '0' after 40 ns, '1' after 60 ns;
    b <= '0', '1' after 40 ns;
end tb ;
  1. Click save and exit vivado.

Setup BeetleboxCI to automate Vivado​

Expanding the VM disk size​

First you will need to download BeetleboxCI, this can be done for free by signing up on the website here. When you sign up follow the instructions and return back to the tutorial. The quick start version of BeetleboxCI works by running a small VM in the background that contains the BeetleboxCI software. By default this VM is not large enough to contain Vivado, so you need to expand the disk.

Expanding the disk size of the CI to work for FPGA development:

  1. Make sure the Ubuntu Server VM that runs BeetleboxCI is shut down.
  2. On the host machine, open Oracle VirtualBox.
  3. Go to File > Tools > Virtual Media Manager
  4. Under the virtual media manager section, select the virtual hard drive that you want to expand.
  5. In the Attributes tab below, increase the Size of the virtual hard drive to the desired size of 250GB.
  6. Click on Apply to save the changes.
  7. Start the Ubuntu Server VM and log in to the system.
  8. Run the following commands and the disk should expand:
sudo apt-get install parted 
sudo parted /dev/sda resizepart 3 250G   
sudo pvresize /dev/sda3 250G
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
sudo resize2fs /dev/mapper/ubuntu--vg-ubuntu--lv

Mounting the folder​

You will need an easy way of sharing files between the BeetleboxCI Ubuntu VM and your host machine. The best way to do this is to mount a shared folder between the two, which you will do now.

  1. On the host machine, create a folder that you want to mount to the Ubuntu VM. For example, you can create a folder named shared in the home directory by running the following command:
mkdir ~/\<folder name\>
  1. On the BeetleboxCI VM, install the VirtualBox Guest Additions by going to Devices > Insert Guest Additions CD image.
  2. Open a terminal in the Ubuntu VM and run the following commands:
sudo apt-get install build-essential
sudo apt-get install linux-headers-$(uname -r)
sudo apt-get install vboxadd
sudo mkdir -p /media/cdrom
sudo mount /dev/cdrom /media/cdrom
sudo /media/cdrom/./VBoxLinuxAdditions.run
sudo reboot

To set up the shared folder mount:

  1. In VirtualBox, select your BeetleboxCI VM, and click Settings.
  2. Click Shared Folders in the left had column on of the settings panel.
  3. Click the + sign on the right hand side to add a shared folder.
  4. Specify the location of the folder on the host machine in Folder Path.
  5. Specify the mount point inside the VM in Mount Point.
  6. For the Folder Name, give it a label, such as dockerfolder.
  7. You can then proceed to mount the folder inside the VM by running the following commands inside the VM:
sudo mount -t vboxsf dockerfolder ~/shared
sudo docker load -i file_name

Containerize Vivado​

Here are the steps you can follow to containerize Vivado:

  1. Make sure you have Docker installed on your system. You can check if Docker is installed by running the command:
docker -v

If it's not installed, follow the instructions on the Docker website to install it.

  1. Create a new directory on your system and navigate to it in your command line. This will be the directory where you will build your image.
  2. Download the Xilinx_Unified_2020.1_0602_1208_Lin64.bin file from the Xilinx website and copy this into the folder.
  3. Create a new file in the directory and name it Dockerfile (with no file extension)
  4. Copy the contents of the Dockerfile provided to your newly created file:
# Use an official Ubuntu image as the base image
FROM ubuntu:18.04

# Update the package manager and install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libxslt1-dev \
    libssl-dev \
    libreadline-dev \
    zlib1g-dev \
    libx11-6 \
    libxext6 \
    libxrender1 \
    libxrandr2 \
    libxft2 \
    libgl1-mesa-glx \
    libglib2.0-0 \
    libsm6 \
    libfontconfig1 \
    libice6 \
    libxinerama1 \
    libxcursor1 \
    libxdamage1 \
    libxcomposite1 \
    libxfixes3 \
    libx11-xcb1 \
    libxcb-glx0 \
    libxcb-shape0 \
    libxcb-xfixes0 \
    libxcb-sync1 \
    libxcb-xinerama0 \
    libxcb-xkb1 \
    libxcb-render0 \
    libxcb-randr0 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-icccm4 \
    libxcb-damage0 \
    libxcb-composite0 

# Copy the Vivado installer to the container
COPY Xilinx_Unified_2020.1_0602_1208_Lin64.bin /root/

# Make the installer file executable
RUN chmod +x /root/Xilinx_Unified_2020.1_0602_1208_Lin64.bin

# Run the installer in interactive mode
RUN /root/Xilinx_Unified_2020.1_0602_1208_Lin64.bin --keep --noexec --target /opt/Xilinx/Vivado

  1. Run the following command in your command line to build the image: 
docker build -t vivado .
  1. The -t option is used to specify a tag for the image and the . at the end of the command tells Docker to use the current directory as the build context.
  2. Once the build process is finished, you can check that the image has been created successfully by running the command docker images.
  3. To run the container, use the command:
docker run --network host -it vivado.

The -it option runs the container in interactive mode and the --name option gives the container a name. 10. You should now be inside the container and you can run the following commands to finish the Vivado installation. Fill in the correct details when asked:

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
rm -rf /var/lib/apt/lists/*
/opt/Xilinx/Vivado/xsetup -b ConfigGen
/opt/Xilinx/Vivado/xsetup -b AuthTokenGen
/opt/Xilinx/Vivado/xsetup -b Add -a XilinxEULA,3rdPartyEULA -c /root/.Xilinx/install_config.txt
  1. To stop the container, you can use the command:
docker stop vivado-container.

Or exit inside the container

note

This tutorial provides a basic example of how to containerize Vivado using Docker and it may vary depending on your specific needs and environment. Also keep in mind that you'll need to have a valid license of Vivado to use it inside the container.

Upload container to BeetleboxCI​

On the host machine

  1. Open a new terminal.
  2. Get the container ID by running:
docker ps -a
  1. Create a new image from the container by running:
docker commit <container id>
  1. View the list of images by running:
docker images
  1. Tag the image with a desired name by running:
docker tag <image id> vivado_bbx
  1. Save the image as a tar file by running:
docker save -o vivado_bbx.tar vivado_bbx
  1. Copy the tar file to a shared folder by running:
sudo cp vivado_bbx.tar <shared folder location>
  1. Change the permissions of the tar file in the shared folder by running:
sudo chmod 755 <shared folder location>/vivado_bbx.tar

Now move to the BeetleboxCI VM 9. Load the image from the tar file by running:

sudo docker load -i vivado_bbx.tar
  1. Verify the image is loaded by running:
docker images
  1. Tag the container with a desired name by running:
docker tag <container id> work1-virtualbox:5000/ubuntu-vivado-2020-1:latest
  1. Push the container to a registry by running:
docker push work1-virtualbox:5000/ubuntu-vivado-2020-1:latest
  1. When finished run the following command to clear the VM docker cache:
docker system prune -a
  1. Navigate to beetleboxCI on your host machine (i.e. type the following command in a web browser):
127.0.0.1:32767
  1. Navigate to the images page and you should see the container ready to run Vivado.

Getting started CI environment for Vivado container image page

Conclusion​

In this tutorial you stepped through how to set up and configure a build environment using VirtualBox and Ubuntu 18.04, and install Vivado 2020.1 on the virtual machine and a container for use in a CI environment. It also includes steps on how to create a template project in Vivado using VHDL, including creating and adding source files. The tutorial also includes commands that need to be run on the terminal to install dependencies and updates.

What’s coming in the next tutorial​

In the next tutorial you will be designing the FPGA. In this tutorial, you will learn how to use the Vivado design tools to create a basic digital circuit and how to simulate its behavior. You will also learn how to configure your design to be built and tested automatically by the CI software.