Build the VEK385 AI Reference Design

Build the VEK385 AI Reference Design#

This section explains how to build the reference design from source code on your host machine.

Reference Design Build flow#

../../_images/build_reference_design.png

Prerequisites#

Before starting:

  • Refer to Obtaining License for instructions to obtain the AIE-MLv2 Compiler and Vivado ML Enterprise Edition licenses.

  • The XILINXD_LICENSE_FILE environment variable set to your license file path

Setup Environment#

Setup Vitis Environment#

Navigate to the platform directory:

// RevA platform
cd <sources_path>/versal_2ve/reference_design/vek385/rev-a

// RevB platform
cd <sources_path>/versal_2ve/reference_design/vek385/rev-b

Set license file (if not already configured):

# run this only if XILINXD_LICENSE_FILE is not set
export XILINXD_LICENSE_FILE=<path_to AIE / Vivado license_file>

Source Vitis tools:

source <vitis_install_dir>/2026.1/Vitis/settings64.sh

Building Vitis Platform#

Follow these steps to generate the extensible Vitis platform (XSA) for Vitis application integration and the fixed XSA for software artifacts generation.

  1. Tool Setup

  2. Run the following script to create Hardware Platform:

    source ./create_pfm_hw.sh

    This script performs the following:

    • Creates the Vivado design.

    • Runs synthesis and implementation.

    • Generates hardware artifacts in the hw folder.

  3. Generated Artifacts

    • Fixed XSA:

      • Contains boot.pdi.

      • Used by Yocto to generate:

        • BOOT.bin

    • Extensible XSA:

      • Includes platform ports.

      • Used by Vitis tools to add custom kernels.

      • System Device Tree (SDT)

Building Software Components Using Yocto#

This section outlines the process of generating software artifacts using the Yocto build system, based on the Fixed XSA generated during the Vitis platform creation.

  1. Environment Setup

    • Install Yocto prerequisites

      • The Reference Design Source Compilation uses Yocto sources and depends on specific applications. Refer to the requirements documentation for detailed dependencies in system-requirements

      • Supported host operating systems:

        • Ubuntu 22.04.4 LTS – A Linux-based operating system for use as a server/host.

        • Ubuntu 24.04 LTS – Supported, with additional configuration described below.

      • Install the following mandatory packages required for the Yocto build:

      sudo apt install curl build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 liblz4-tool locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd graphviz

    Note

    On Ubuntu 24.04 (LTS), Yocto/BitBake uses unprivileged user namespaces for build task sandboxing. Ubuntu 24.04 blocks unprivileged user namespaces by default via AppArmor, which causes the build to fail with an error similar to:

    ERROR: User namespaces are not usable by BitBake, possibly due to AppArmor.

    To allow Yocto to use unprivileged user namespaces, run the following command on the host system:

    sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

    This issue is not seen on Ubuntu 22.04.

    • Set locale for Yocto

    export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

    • Update user git configuration information with the following sample commands.

    git config --global user.email "user@example.com"
git config --global user.name "User Name"

    Note

    Replace “user@example.com” and “User Name” with your own details

  2. Run Yocto Build Script

    Execute:

    source ./create_pfm_sw.sh

  3. Generated Artifacts

    • BOOT.bin

    • Image

    • Root Filesystem

    • sdk.sh

    All artifacts are copied to: artifact/amd/boot_images

    These files provide all that is needed to perform the initial boot of the target device. You can now create and run applications on the A78 ARM processor. However, these files do not include any programmed programmable logic (PL) or AI Engine (AIE) overlay files. Programming of the PL and AIE occurs later when you apply the generated overlay created by the Vitis application, as described in the next steps.

  4. Adding User Packages to Rootfs

    To customize the root filesystem:

    • Modify the script: sw/yocto/create_yocto.sh

    • Add the required user packages.

    • Clean the Yocto workspace, in sw/yocto:

    source create_yocto.sh -c

    • Rerun the build:

    source ./create_pfm_sw.sh

  5. Preparing the UFS Boot Image for Rev-B

    Perform the following steps on the host system to prepare the UFS boot image for Rev-B.

    • Refer to Vitis AI SDK to install the sysroot and set up the environment.

    • Run the following script to create the UFS boot image:

    source ./create_ufs_image.sh

Vitis Application Development#

This section describes the process of building programmable logic (PL) and AI Engine (AIE) kernels using Vitis tools. The build generates the PDI and overlay files. These files are used to configure and program the PL and AIE on a target device that has already been booted. This multi-stage boot process is enabled through Segmented Configuration.

Segmented configuration allows the processors in a Versal device to boot and access DDR memory before the programmable logic (PL) is configured. This approach lets DDR-based software such as Linux start first, with the PL configured afterward as needed from a boot device or DDR image, enhancing boot flexibility and efficiency. For more information, see the Segmented Configuration Documentation

Steps:

  1. Navigate to the “<sources_path>/versal_2ve/reference_design/vek385/<rev-a/rev-b>” directory.

  2. Run the script:

    source ./create_vitis_app.sh

    This invokes:

    • Vitis linker

    Generated application artifacts:

    • PL AIE PDI

    • DTB Overlays

    The generated artifacts are copied to: artifact/amd/boot_images/overlay

Contents