Installation and Setup

Downloading Vitis AI Development Kit

The Vitis™ AI software is made available through Docker Hub. Vitis AI consists of the following two packages:

The tools container contains the Vitis AI quantizer, AI compiler, and AI runtime for cloud DPU. The Vitis AI runtime package for edge is for edge DPU development, which holds Vitis AI runtime installation package for Xilinx® ZCU102 and ZCU104 evaluation boards, and Arm® GCC cross-compilation toolchain.

Xilinx FPGA devices and evaluation boards supported by the Vitis AI development kit v1.3 release are:

  • Cloud: Alveo™ cards U200, U250, U280, U50, U50LV, and Versal ACAP evaluation board VCK190.
  • Edge: Zynq® UltraScale+™ MPSoC evaluation boards ZCU102 and ZCU104.

Setting Up the Host

The following two options are available for installing the containers with the Vitis AI tools and resources.
  1. Pre-built containers on Docker Hub: xilinx/vitis-ai
  2. Build containers locally with Docker recipes: Docker Recipes
Use the following steps for installation:
  1. Install Docker, if Docker not installed on your machine.
  2. Follow the Post-installation steps for Linux to ensure that your Linux user is in the group Docker.
  3. Clone the Vitis AI repository to obtain the examples, reference code, and scripts.
    git clone --recurse-submodules https://github.com/Xilinx/Vitis-AI  
    
    cd Vitis-AI
  4. Run Docker Container
    • Run the CPU image from Docker Hub
      docker pull xilinx/vitis-ai:latest
      ./docker_run.sh xilinx/vitis-ai
    • Build the CPU image locally and run it
      cd docker
      ./docker_build_cpu.sh
      
      # After build finished
      cd ..
      ./docker_run.sh xilinx/vitis-ai-cpu:latest
    • Build the GPU image locally and run it
      cd docker
      ./docker_build_gpu.sh
      
      # After build finished
      cd ..
      ./docker_run.sh xilinx/vitis-ai-gpu:latest

Setting Up the Host (Using VART)

For Edge (DPUCZDX8G)

Use the following steps to set up the host for Edge:

  1. Download sdk-2020.2.0.0.sh from here.
  2. Install the cross-compilation system environment.
    ./sdk-2020.2.0.0.sh
  3. Follow the prompts to install. The following figure shows the installation process.
    Note: The ~/petalinux_sdk path is recommended for installation. Regardless of the path you choose for the installation, ensure that your chosen path has write permissions. In this section, it is installed in ~/petalinux_sdk.
  4. When the installation is complete, follow the prompts and enter the following command.
    source ~/petalinux_sdk/environment-setup-aarch64-xilinx-linux
    Note: If you close the current terminal, you need to re-execute the above instructions in the new terminal to set up the environment.
  5. Download the vitis_ai_2020.2-r1.3.0.tar.gz from here and install it to the PetaLinux system.
    tar -xzvf vitis_ai_2020.2-r1.3.0.tar.gz -C ~/petalinux_sdk/sysroots/aarch64-xilinx-linux
  6. Cross compile the sample taking resnet50 as an example.
    cd Vitis-AI/demo/VART/resnet50
    bash –x build.sh

    If the compilation process does not report any error and the executable file resnet50 is generated, then the host environment is installed correctly.

For Cloud (DPUCAHX8H)

Use the following steps to set up the host for cloud. These steps apply to U50, U50LV, and U280 cards.

  1. Start the Docker container. After the Docker image is loaded and running, the Vitis AI runtime is automatically installed in the docker system.
  2. Download the xclbin files from here. Untar it, choose the Alveo card and install it. Take U50 as an example.
    tar -xzvf alveo_xclbin-1.3.0.tar.gz
    cd alveo_xclbin-1.3.0/U50/6E300M
    sudo cp dpu.xclbin hbm_address_assignment.txt /usr/lib
    For DPUCAHX8L, take U50lv as an example.
    tar -xzvf alveo_xclbin-1.3.0.tar.gz
    cd alveo_xclbin-1.3.0/U50lv-V3ME/1E250M
    sudo cp dpu.xclbin /opt/xilinx/overlaybins/
    export XLNX_VART_FIRMWARE=/opt/xilinx/overlaybins/dpu.xclbin
Note: If there is more than one card installed on the server and you want to specify some cards to run the program, set XLNX_ENABLE_DEVICES. It takes the following options:
  • To use device 0 for the DPU, set export XLNX_ENABLE_DEVICES=0.
  • To use device 0, device 1, and device 2 for the DPU, set export XLNX_ENABLE_DEVICES=0,1,2.
  • By default, all available devices are used for the DPU if you do not set this environment variable.

Setting Up the Evaluation Board

Setting Up the ZCU102/104 Evaluation Board

The Xilinx ZCU102 evaluation board uses the mid-range ZU9 Zynq® UltraScale+™ MPSoC to enable you to jumpstart your machine learning applications. For more information on the ZCU102 board, see the ZCU102 product page on the Xilinx website: https://www.xilinx.com/ products/boards-and-kits/ek-u1-zcu102-g.html.

The main connectivity interfaces for ZCU102 are shown in the following figure.

Figure 1: Xilinx ZCU102 Evaluation Board and Peripheral Connections

The Xilinx ZCU104 evaluation board uses the mid-range ZU7 Zynq UltraScale+ device to enable you to jumpstart your machine learning applications. For more information on the ZCU104 board, see the Xilinx website: https://www.xilinx.com/products/boards-and-kits/zcu104.html.

The main connectivity interfaces for ZCU104 are shown in the following figure.

Figure 2: Xilinx ZCU104 Evaluation Board and Peripheral Connections

In the following sections, ZCU102 is used as an example to show the steps to setup the Vitis AI running environment on the evaluation boards.

Flashing the OS Image to the SD Card

For ZCU102, the system images can be downloaded from here; for ZCU104, it can be downloaded from here. One suggested software application for flashing the SD card is Etcher. It is a cross-platform tool for flashing OS images to SD cards, available for Windows, Linux, and Mac systems. The following example uses Windows.
  1. Download Etcher from: https://etcher.io/ and save the file as shown in the following figure.

  2. Install Etcher, as shown in the following figure.

  3. Eject any external storage devices such as USB flash drives and backup hard disks. This makes it easier to identify the SD card. Then, insert the SD card into the slot on your computer, or into the reader.
  4. Run the Etcher program by double clicking on the Etcher icon shown in the following figure, or select it from the Start menu.

    Etcher launches, as shown in the following figure.



  5. Select the image file by clicking Select Image. You can select a .zip or .gz compressed file.
  6. Etcher tries to detect the SD drive. Verify the drive designation and the image size.
  7. Click Flash!.

Booting the Evaluation Board

This example uses a ZCU102 board to illustrate how to boot a Vitis AI evaluation board. Follow the steps below to boot the evaluation board.
  1. Connect the power supply (12V ~ 5A).
  2. Connect the UART debug interface to the host and other peripherals as required.
  3. Turn on the power and wait for the system to boot.
  4. Login to the system.
  5. The system needs to perform some configurations for its first boot. Then reboot the board for these configurations to take effect.

Accessing the Evaluation Board

There are three ways to access the ZCU102 board:

  • UART port
  • Ethernet connection
  • Standalone

UART Port

Apart from monitoring the boot process and checking Linux kernel messages for debugging, you can login to the board through the UART. The configuration parameters of the UART are shown in the following example. Log in to the system with username “root” and password “root”.

  • baud rate: 115200 bps
  • data bit: 8
  • stop bit: 1
  • no parity
Note: On a Linux system, you can use Minicom to connect to the target board directly; for a Windows system, a USB to UART driver is needed before connecting to the board through a serial port.

Using the Ethernet Interface

The ZCU102 board has an Ethernet interface, and SSH service is enabled by default. You can log into the system using an SSH client after the board has booted.

Use the ifconfig command via the UART interface to set the IP address of the board, then use the SSH client to log into the system.

Using the Board as a Standalone Embedded System

The ZCU102 board allows a keyboard, mouse, and monitor to be connected. After a successful boot, a Linux GUI desktop is displayed. You can then access the board as a standalone embedded system.

Installing Vitis AI Runtime on the Evaluation Board

To improve the user experience, the Vitis AI Runtime packages, VART samples, Vitis-AI-Library samples and models have been built into the board image. The examples are precompiled. Therefore, you do not need to install Vitis AI Runtime packages and model package on the board separately. However, you can still install the model or Vitis AI Runtime on your own image or on the official image by following these steps.

With an Ethernet connection established, copy the Vitis™ AI runtime (VART) package from github to the evaluation board and set up a Vitis AI running environment for the ZCU102 board.

  1. Download the vitis-ai-runtime-1.3.x.tar.gz from here. Untar it and copy the following files to the board using scp.
    tar -xzvf vitis-ai-runtime-1.3.x.tar.gz
    scp -r vitis-ai-runtime-1.3.x/aarch64/centos root@IP_OF_BOARD:~/
    Note: You can take the rpm package as a normal archive, and extract the contents on the host side, if you only need some of the libraries. Only model libraries can be independent, while the others are common libraries. The operation command is as follows.
    rpm2cpio libvart-1.3.0-r<x>.aarch64.rpm | cpio -idmv
  2. Log in to the board using ssh. You can also use the serial port to login.
  3. Install the Vitis AI runtime. Execute the following commands in order.
    cd ~/centos
    rpm -ivh --force libunilog-1.3.0-r<x>.aarch64.rpm
    rpm -ivh --force libxir-1.3.0-r<x>.aarch64.rpm
    rpm -ivh --force libtarget-factory-1.3.0-r<x>.aarch64.rpm
    rpm -ivh --force libvart-1.3.0-r<x>.aarch64.rpm
    If you want to run the example based on Vitis-AI-Library, execute the following command to install the Vitis-AI-Library runtime package.
    rpm -ivh --force libvitis_ai_library-1.3.0-r<x>.aarch64.rpm

    After the installation is complete, the Vitis AI Runtime library will be installed under /usr/lib.

Setting Up the Custom Board

Vitis AI supports the official ZCU102/ZCU104 as well as user-defined boards.

If you want to run Vitis AI on your custom board, you need to preform the following steps in order. Ensure that you complete a step before proceeding to the next step.

  1. Create the platform system of your custom board. For more information, see Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400) and https://github.com/Xilinx/Vitis_Embedded_Platform_Source/tree/master/Xilinx_Official_Platforms.
  2. Integrate DPU IP. Refer to https://github.com/Xilinx/Vitis-AI/tree/master/dsa/DPU-TRD to complete the integration of DPU IP.
    Note: After this step is completed, an sd_card directory and an sd_card.img image with DPU are created. For more known issues, see to Known issues.
  3. Install the dependent libraries of Vitis AI.

    There are two ways to install the dependent libraries of Vitis AI. One is to rebuild system through the configuration of PetaLinux, the other is to install the Vitis AI dependent libraries online.

    1. Rebuild the system using PetaLinux configuration by executing the following command:
      petalinux-config -c rootfs
    2. Ensure that packagegroup-petalinux-vitisai is selected, as shown in the following figure:



    3. Execute the following command to recompile the system.
      petalinux-build
    4. You can also install the Vitis AI dependent libraries online by executing dnf install packagegroup-petalinux-vitisai to complete the installation, as shown in the following code:
      root@xilinx-zcu104-2020_1:/media/sd-mmcblk0p1# dnf install packagegroup-petalinux-vitisai
      Last metadata expiration check: 1 day, 18:12:25 ago on Wed Jun 17 09:35:01 2020.
      Package packagegroup-petalinux-vitisai-1.0-r0.noarch is already installed.
      Dependencies resolved.
      Nothing to do.
      Complete!
      Note: If you use this method, you need to ensure that the board is connected to the Internet.
    Note: After this step is completed, the 1.2 version of VART is also installed into the system and the system image for Vitis AI is available.
    Note: If you want to compile the example on the target, select the packagegroup-petalinux-vitisai-dev and packagegroup-petalinux-self-hosted and recompile the system.
  4. Flash the image to the SD card.

    See Flashing the OS Image to the SD Card to flash the new image to the SD card.

  5. Update the Vitis AI Runtime libraries to VAI1.3, if needed.

    After the custom board boots up with the above system image, the 1.2 version of VART is installed. If you want to update them to the 1.3, you have to update the following five library packages, as shown below.

    • libunilog
    • libxir
    • libtarget-factory
    • libvart
    • libvitis_ai_library

    See Installing Vitis AI Runtime on the Evaluation Board to install the Vitis AI Runtime libraries.

    After you install the Vitis AI Runtime, a vart.conf file is generated under /etc to indicate the dpu.xclbin file location, as shown below. The Vitis AI examples fetch the dpu.xclbin file by reading vart.conf file. If the dpu.xclbin file on your board is not in the same location as the default, change the dpu.xclbin path in vart.conf.

    Note: This step generates a system that can run the Vitis AI examples.
  6. Run the Vitis AI examples. See Running Examples to run the Vitis AI examples.