Vitis AI Tutorial – Part 2

Published On: November, 14, 2023 By: Eshtaartha Basu | Updated: November 7, 2024 by Neeraj Dantu

This tutorial will walk you through the steps required to generate Acceleration Ready Petalinux Software Components with Vitis-AI 2.0 and Xilinx Real Time (XRT) support. We will be using the OSDZU3-REF Petalinux BSP as an example starting point.

This tutorial can be used standalone or as Part 2 of a 4-part Acceleration tutorial series that will help you run Vitis-AI DPU-TRD based Face Detection demo, ADAS Detection demo (and other AI demos) on the OSDZU3-REF board. An overview of the flow is shown below:

Pre-requisites

This tutorial assumes the user is already familiar with the OSDZU3-REF Vivado and Vitis Design Flow by going through:

• OSDZU3 Vivado Tutorial
• OSDZU3 Vitis Tutorial

The user has already gone through Part 1 of this Tutorial series and has generated OSDZU3-REF_Accl_Platform.xsa file.

Objectives

To make the existing OSDZU3-REF Petalinux BSP Acceleration Ready, the user needs to:

1. Add new petalinux packages and update existing ones to support PL Acceleration, Vitis-AI 2.0 and Vitis XRT
2. Configure petalinux network, power and package management to support acceleration
3. Suitably update Device Tree
4. Build Petalinux Image

Tutorial Requirements

This tutorial will require the following software setup.

• Petalinux 2021.2 (Xilinx account and licenses may be required)
  • We recommend installing Petalinux 2021.2 in /home directory of your Linux Host PC
• OSDZU3-REF Vivado Hardware Project provided by Octavo System

Note: All the steps in this tutorial have been validated using Petalinux 2021.2 running on Ubuntu 20.04.LTS. However, the overall design flow should be similar for other Petalinux and host OS versions as well.

Create new Petalinux project using OSDZU3-REF Petalinux BSP

This section will describe the steps required to create a new Petalinux project using OSDZU3-REF Petalinux BSP.

1. Make a directory called “petalinux” in your workspace, “cd” into it and download OSDZU3-REF Petalinux BSP into it

   1. mkdir petalinux
      cd petalinux

   2. Download OSDZU3-REF Petalinux BSP
2. Source petalinux environment
   source <your_petaLinux_install_dir>/settings.sh
3. Create a new PetaLinux project utilizing the OSDZU3-REF BSP:
   1. petalinux-create -t project -n osdzu3-ref_accl_platform -s <path_to_osdzu3-ref-2021.2.bsp>
   2. cd osdzu3-ref_accl_platform. The contents of the project folder should look similar to what is shown below.
      
   3. Update the petalinux project’s hardware with the Acceleration Ready OSDZU3-REF hardware (OSDZU3-REF_Accl_Platform.xsa) we created in Vivado as part of Tutorial 1 using the command:
      1. petalinux-config --get-hw-description=<path_to_your_acceleration_ready_vivado_xsa_file>
         In my case, the command is as follows:
         petalinux-config --get-hw-description= ~/Downloads/osdzu3_sip-master_latest/osdzu3_sip-master/Vv_21_2/OSDZU3_Ref_Design/Vivado/ OSDZU3-REF_Accl_Platform.xsa
   4. Once you run the above command, the petalinux configuration window will appear as shown below. You can exit it for now without making any changes. We’ll be making changes as necessary in the following sections.

Rootfs configuration

Add packages required for Acceleration in Rootfs

1. Open “user-rootfsconfig” file and append (copy and paste) the below lines to the end of the file:
   nano project-spec/meta-user/conf/user-rootfsconfig

   # base XRT support:
   CONFIG_xrt
   
   # Packages for easy system management
   CONFIG_dnf
   CONFIG_e2fsprogs-resize2fs
   CONFIG_parted
   CONFIG_resize-part
   
   # Packages for Vitis-AI dependencies support:
   CONFIG_packagegroup-petalinux-vitisai
   
   #Packages for natively building Vitis AI applications on target board:
   CONFIG_packagegroup-petalinux-self-hosted
   CONFIG_cmake
   CONFIG_packagegroup-petalinux-vitisai-dev
   CONFIG_xrt-dev
   CONFIG_opencl-clhpp-dev
   CONFIG_opencl-headers-dev
   CONFIG_packagegroup-petalinux-opencv
   CONFIG_packagegroup-petalinux-opencv-dev
   
   # Packages for running Vitis-AI demo applications with GUI
   CONFIG_mesa-megadriver
   CONFIG_packagegroup-petalinux-x11
   CONFIG_packagegroup-petalinux-v4lutils
   CONFIG_packagegroup-petalinux-matchbox
   
   # To install Vitis AI 2.0, VART 2.0 and dependent packages into rootfs
   CONFIG_vitis-ai-library
   CONFIG_vitis-ai-library-dev
   CONFIG_vitis-ai-library-dbg

2. Press Ctrl key + O on the keyboard to save on Nano editor
3. Press Ctrl key + X to exit Nano editor
   
4. Enable all the added packages:
   1. Open Rootfs Configuration:
      petalinux-config -c rootfs
   2. Select User Packages
   3. Enable all the libraries we added in the previous step by pressing “Y” on the keyboard for each as shown below.

Configure Network Management in Rootfs

Vitis-AI applications may use remote display feature to show machine learning results over SSH. To improve the remote display experience, replace the default Dropbear SSH with OpenSSH. OpenSSH has the potential for up to 4x faster data transmission.

1. In the Rootfs configuration window, go to Image Features
2. Disable ssh-server-dropbear by pressing “N” and enable ssh-server-openssh by pressing “Y”
   
3. Click Exit
4. Go to Filesystem Packages > misc > packagegroup-core-ssh-dropbear > disable packagegroup-core-ssh-dropbear
5. Under Filesystem Packages > console > network > openssh > enable the following:
   1. Openssh
   2. openssh-sftp
   3. openssh-sftp-server
   4. openssh-sshd
   5. openssh-scp
6. Save and Exit

Configure Package Management in Rootfs

1. Go to Image Features > Enable the following:
   1. package-management
   2. debug_tweaks
2. Click OK
3. Exit twice
4. Select Yes to save the changes

Add EXT4 Rootfs Support

Make Petalinux generate EXT4 Rootfs:

1. Run petalinux-config
2. Go to Image Packaging Configuration
3. Set Root File System Type as EXT4
4. Set Device node of SD device to:
   /dev/mmcblk1p2
5. Exit and Save
   

Make Petalinux use EXT4 Rootfs during boot:

1. Run petalinux-config
2. Set DTG settings -> Kernel Bootargs -> generate boot args automatically > NO (press “N”)
3. Update User Set Kernel Bootargs to:
   earlycon console=ttyPS0,115200 clk_ignore_unused root=/dev/mmcblk1p2 rw rootwait cma=512M

Note:

clk_ignore_unused: it tells Linux kernel not to turn off unused clocks. This is useful to keep clocks that only drive PL kernels ON because PL kernels are not represented in device tree.

1. cma = 512M: CMA is used to exchange data between PS and PL kernels. Vitis-AI and DPU PL kernels require at least 512MB CMA.

Make Petalinux generate .EXT4 Root FS image output

1. Run petalinux-config
2. Go to Image Packaging Configuration > Root filesystem formats
   
3. Delete all other default formats and enter the following:
4. Save and exit

Configure Kernel CPU Power Management

During debugging, especially over JTAG, the hardware server on the Host machine talks to the processor regularly. If CPU idles during debugging, the system will hang due to incomplete AXI transactions. Therefore, it is beneficial to disable CPU IDLE during project development. It can be re-enabled in the final product.

1. Disable CPU Idling in Kernel Config
   1. Launch kernel config: petalinux-config -c kernel
   2. Make sure the following items are disabled:
      1. CPU Power Management > CPU Idle > CPU idle PM support
         
      2. CPU Power Management > CPU Frequency scaling > CPU Frequency scaling
         
   3. Exit and Save

Update Device Tree if necessary

Set sdhc1 to low-speed mode by adding the following lines to <your_petalinux_project_dir>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi:

&sdhci1 {
no-1-8-v;
disable-wp;
};

Note: Reducing SD card speed allows for better card compatibility. This is not a requirement for Acceleration design.

Build Petalinux Images

1. From your Petalinux project root, build the petalinux project.
   petalinux-build
2. Create sysroot self-installer for target linux system
   petalinux-build --sdk

Note: The generated sysroot package, sdk.sh, will be available in /images/linux directory. This will be useful in future steps.

Test the Acceleration Ready Petalinux Image

From Petalinux project root,

1. Package the bootloader, PL logic and generate BOOT.BIN:
   petalinux-package --boot --u-boot --fpga --force
   BOOT.BIN file should be available under images/linux
2. Generate a WIC SD card image:
   petalinux-package --wic --wks support/sd-boot.wks
   The SD card image file, petalinux-sdimage.wic, should become available under /images/linux as shown below.
3. Check if the acceleration ready image boots by doing the following:
   1. Flash the petalinux-sdimage.wic image on to a µSD card using a tool like Etcher
   2. Insert the µSD card into the OSDZU3-REF board
   3. Attach 12V input power, µUSB cable (for UART console access) and external monitor to the OSDZU3-REF board (see OSDZU3-REF Getting Started Guide for board bring-up)
   4. Set the boot mode to SD1 (0101)
   5. Turn on the board by toggling the power switch.
   6. You should be able to see boot messages on the UART console of your host PC and a linux login prompt.
      1. Login username: root
      2. Password: root
   7. Desktop GUI should appear on your external monitor as shown below.
      

Further Reading

Continue the OSDZU3 Acceleration journey and generate an Acceleration Ready Vitis Platform by reading Part 3 of the 4-part Acceleration Tutorial.

Revision History

Get notified of updates to this Application Note and all of our Technical Documentation.