AMD Vitis Tutorials

https://github.com/xilinx/vitis-tutorials
Admin
AMD Vitis Tutorials is a comprehensive collection of in-depth tutorials for learning the Vitis...
Tokens:575,788
Snippets:4,385
Trust Score:9.3
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Initialize Vitis Environment and Build Project

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VEK280/README.md

Commands to source the Vitis installation settings, define the common image path for Versal platforms, and trigger the compilation process via Makefile.

```bash
source <path_to_vitis_install>/settings64.sh
export COMMON_IMAGE_VERSAL=<path_to_common_image: xilinx-versal-common-v2025.2>
cd <path_to_Tutorial>/Getting_Started/Vitis/Versal_w_PetaLinux/VEK280/
make all
```

--------------------------------

### Launch Vitis Unified IDE

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis_HLS/README.md

Command to open the Vitis Unified IDE and load a specific workspace directory.

```bash
vitis -w workspace
```

--------------------------------

### Load Device and XCLBIN using XRT

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/Host_srcs/README.md

This snippet demonstrates how to initialize the XRT device and load the XCLBIN file, which contains the hardware design. It takes the XCLBIN filename as input and returns the XCLBIN UUID.

```cpp
unsigned int dev_index = 0;
char* xclbinFilename = argv[1];
auto device = xrt::device(dev_index);
auto xclbin_uuid = device.load_xclbin(xclbinFilename);
```

--------------------------------

### Open and Launch Kernels using XRT

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/Host_srcs/README.md

This code snippet demonstrates how to open specific kernels (e.g., mm2s, s2mm) and a graph from the loaded XCLBIN using their names. It then launches the kernels with their respective input/output buffers and sizes, and initiates the graph execution.

```cpp
auto mm2s_1 = xrt::kernel(device, xclbin_uuid, "mm2s:{mm2s_1}");
auto mm2s_1_rhdl = mm2s_1(in_bohdl0, nullptr, sizePLIn0 );
auto mm2s_2 = xrt::kernel(device, xclbin_uuid, "mm2s:{mm2s_2}");
auto mm2s_2_rhdl = mm2s_2(in_bohdl1, nullptr, sizePLIn1 );
auto s2mm_1 = xrt::kernel(device, xclbin_uuid, "s2mm:{s2mm}");
auto s2mm_1_rhdl = s2mm_1(out_bohdl0, nullptr, sizePLOut0 );
auto graph = xrt::graph(device, xclbin_uuid, "mygraph");
```

--------------------------------

### Connect Graph Components with Buffer Parameters

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE-ML/Design_Tutorials/03-AIE-ML-lenet_tutorial/README.md

This example demonstrates how to establish connections between different components within an AI Engine graph using the `connect<>` object. It shows connecting an input PLIO port to a kernel input port and specifies buffer dimensions for efficient data transfer. It also includes an example of connecting a lookup table to a kernel.

```cpp
connect(in[0].out[0], core01.in[0]);
dimensions(core01.in[0]) = {(ROW_A * COL_A)/4};

connect<>(core01lut,core01);
```

--------------------------------

### Set Platform Repository Path

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis_HLS/README.md

Environment variable configuration to inform the Vitis toolchain of the location of installed hardware platforms.

```bash
export PLATFORM_REPO_PATHS=<path to platforms>
```

--------------------------------

### Prepare Boot Components

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/04_Edge_VCK190_DFX/step2.md

Creates the boot directory and copies essential ELF and device tree files from the common image source.

```bash
mkdir step2_sw/build/boot
cp step2_sw/build/common/bl31.elf step2_sw/build/boot
cp step2_sw/build/common/u-boot.elf step2_sw/build/boot
cp step2_sw/build/vck190_custom_dt/psv_cortexa72_0/device_tree_domain/bsp/system.dtb step2_sw/build/boot
```

--------------------------------

### Prepare Linux Software Components

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/04_Edge_VCK190_DFX/step2.md

Sets up the software component directory by copying the kernel image, root filesystem, and installing the sysroot.

```bash
mkdir step2_sw/build/sw_comp
cd sw_comp
cp <COMMON_IMAGE_PATH>/Image .
cp <COMMON_IMAGE_PATH>/rootfs.ext4 .
<COMMON_IMAGE_PATH>/sdk.sh -d ./ -y
```

--------------------------------

### Load FPGA Configuration and Run Application

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_EDF/VEK385/README.md

This section shows the commands to load the FPGA configuration using `fpgautil` and then execute the application. The application is launched with the XCLBIN file as an argument. The expected output on the UART console is also provided.

```bash
ls 
application container.dtbo container.xclbin vpl_gen_fixed_pld.pdi
fpgautil -b container.pdi  -o container.dtbo
./application container.xclbin
```

--------------------------------

### Configure Vitis Environment Variables

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis_HLS/README.md

Commands to source the necessary Vitis and XRT environment scripts to enable command-line access to the Vitis toolchain.

```bash
source <Vitis_install_path>/settings64.sh
source /opt/xilinx/xrt/setup.sh
```

--------------------------------

### Source Vitis Environment

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/README.md

This command sources the Vitis 2025.2 environment script, setting up necessary environment variables for using Vitis tools. It requires the path to your Vitis installation.

```shell
source <path_to_vitis_install>/settings64.sh
```

--------------------------------

### Setup Emulated Linux Environment

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE-ML/Feature_Tutorials/05-AI-engine-versal-integration/README.md

These commands set up the environment within the emulated Linux prompt for running the design. They navigate to the media directory, set the XILINX_XRT path, and suppress unnecessary kernel messages.

```bash
cd /run/media/*1
export XILINX_XRT=/usr
dmesg -n 4 && echo "Hide DRM messages..."
```

--------------------------------

### Get Specific Property from HwDesign (Python)

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Embedded_Software/Feature_Tutorials/04-vitis_scripting_flows/README.md

Retrieves a specific property from the `HwDesign` object. In this example, the `FAMILY` property is accessed and printed, demonstrating how to get individual hardware details.

```python
arch = HwDesign.FAMILY
print(arch)
```

--------------------------------

### Display Directory Structure

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/04_Edge_VCK190_DFX/step2.md

Visualizes the prepared directory structure for the Vitis platform using the tree command.

```bash
tree -L 3 --charset ascii
```

--------------------------------

### Setup Vitis Tools Environment

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_System_Design/Design_Tutorials/02-Versal_Vitis_Subsystem_Flow/README.md

This command sets up the necessary environment variables for using the Vitis 2025.2 tools. It should be sourced from the Vitis installation directory.

```bash
source <Vitis_Installation_Path>/settings64.sh
```

--------------------------------

### Build and Launch Hardware Emulation for LeNet

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE/Design_Tutorials/01-aie_lenet_tutorial/README.md

Builds the entire LeNet tutorial design and subsequently launches hardware emulation. This command simplifies the process of testing the design in an emulated environment.

```bash
make run TARGET=hw_emu
```

--------------------------------

### Compile Binaries with Makefile

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/README.md

This command navigates to the specified tutorial directory and executes 'make all' to compile the necessary binaries. It relies on a Makefile for detailed build instructions.

```shell
cd <path_to_Tutorial>/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/
make all
```

--------------------------------

### Build and Execute on Hardware

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE/Feature_Tutorials/04-packet-switching/buffer_based_mix_data_type.md

Commands to package the system for hardware deployment and execute the host application on the target platform.

```bash
make package TARGET=hw

# Inside Linux prompt:
mount /dev/mmcblk0p1 /mnt
cd /mnt
export XILINX_XRT=/usr
./host.exe a.xclbin
```

--------------------------------

### Export Common Image Variable

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/README.md

This command exports the COMMON_IMAGE_VERSAL environment variable, which is required for compiling binaries. The value should be the path to the common image, typically 'xilinx-versal-common-v2025.2'.

```shell
export COMMON_IMAGE_VERSAL=<path_to_common_image: xilinx-versal-common-v2025.2>
```

--------------------------------

### Initialize and Sync Input Memory using XRT in C++

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE/Feature_Tutorials/04-packet-switching/buffer_based_aie_kernel.md

Illustrates initializing host memory buffers with data and then synchronizing them to the device using XRT. This prepares the input data for the kernels. It involves writing data to the mapped host pointers and then performing a device sync.

```cpp
// initialize input memory
    for(int i=0;i<mem_size/sizeof(int);i++){
      *(host_in1+i)=i;
      *(host_in2+i)=2*i;
      *(host_in3+i)=3*i;
      *(host_in4+i)=4*i;
    }
    // sync input memory
    xrtBOSync(in_bo1, XCL_BO_SYNC_BO_TO_DEVICE , mem_size,/*OFFSET=*/ 0);
    ...
```

--------------------------------

### XRT API Graph Initialization

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE-ML/Design_Tutorials/06-farrow_filter/README.md

Example of initializing an XRT device, loading an xclbin file, and configuring an AI Engine graph for execution.

```cpp
auto xclbin_uuid = my_device.load_xclbin(a.xclbin);
auto my_graph  = xrt::graph(my_device, xclbin_uuid, "aie_dut");
my_graph.reset();
xrt::aie::profiling handle(my_device);
my_graph.run( ITERATION=4 );
```

--------------------------------

### Constructing AI Engine Input Data Packets

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/AI_Engine_Development/AIE/Feature_Tutorials/04-packet-switching/buffer_based_aie_kernel.md

Example format for input data files used by the AI Engine simulator. Each packet starts with a 32-bit header followed by data words, with the TLAST keyword indicating the final word of a packet.

```text
2415853568
0
1
2
3
4
5
6
TLAST
7
```

```text
2415853568 0
1 2
3 4
5 6
TLAST
7
```

--------------------------------

### Wait for Kernel Execution Completion

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/Host_srcs/README.md

This snippet shows how to wait for the completion of asynchronous kernel executions. It uses the 'wait()' method on the handles returned when launching the kernels and the graph to ensure all operations are finished before proceeding.

```cpp
graph.run(N_ITER);
mm2s_1_rhdl.wait();
mm2s_2_rhdl.wait();
s2mm_1_rhdl.wait();
```

--------------------------------

### Build Entire Project (Bash)

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/03_Edge_VCK190/step1.md

This bash command builds all steps (1 to 3) of the Vitis tutorial project from the 'ref_files' directory. It requires specifying the path to a common image using the COMMON_IMAGE_VERSAL argument. This script generates the platform with pre-built software and runs the vadd application and aie_adder for software emulation.

```bash
cd ref_files
make all COMMON_IMAGE_VERSAL=<path/to/common_image/>
```

--------------------------------

### Set up Vivado Environment and Create Project Directory

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/02-Edge-AI-ZCU104/step1.md

This snippet demonstrates how to source the Vivado environment script, create a workspace directory, and set up a specific directory for the ZCU104 hardware platform project. It prepares the environment for launching Vivado.

```bash
source <Vivado_Install_Directory>/settings64.sh
mkdir WorkSpace
cd WorkSpace
mkdir zcu104_hardware_platform  #create directory for our step1 
cd zcu104_hardware_platform
vivado &
```

--------------------------------

### S2MM HLS Kernel C++ Code

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/HLS_Kernels/README.md

Defines the S2MM (Stream to Memory Map) HLS kernel in C++. It takes an AXI-Stream input ('s') and produces an AXI-MM output ('mem'), transferring data based on the 'size' parameter.

```cpp
void s2mm(ap_int<32>* mem, hls::stream<ap_axis<32, 0, 0, 0>  >& s, int size) {
	for(int i = 0; i < size; i++) {
		ap_axis<32, 0, 0, 0> x = s.read();
		mem[i] = x.data;
	}

```

--------------------------------

### Initialize Vitis Workspace for DFX Testing

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_Platform_Creation/Design_Tutorials/04_Edge_VCK190_DFX/step3.md

Sets up the directory structure and launches the Vitis IDE environment to begin the acceleration project workflow.

```bash
mkdir -p ref_files/step3_verify
cd ref_files/step3_verify
vitis -w .
```

--------------------------------

### MM2S HLS Kernel C++ Code

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/HLS_Kernels/README.md

Defines the MM2S (Memory Map to Stream) HLS kernel in C++. It takes an AXI-MM input ('mem') and produces an AXI-Stream output ('s'), transferring data based on the 'size' parameter.

```cpp
void mm2s(ap_int<32>* mem, hls::stream<ap_axis<32, 0, 0, 0>  > &s, int size) {
	for(int i = 0; i < size; i++) {
		ap_axis<32, 0, 0, 0> x;
		x.data = mem[i];
		s.write(x);

```

--------------------------------

### Configure and Start Hardware Emulator

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Vitis_System_Design/Design_Tutorials/03-Versal_AI_Edge_Gen2_Design_Flow/step3.md

Command line arguments used in the Vitis Emulator configuration to define the QEMU config path, login credentials, and the startup application script.

```bash
-qemu-config <path-to-WorkSpace>/amd-cortexa78-mali-common_vek385_qemu_prebuilt/combined.qemuboot.conf  -login "amd-edf" -password "amd-edf" -run-app "mount /dev/sda2 /media; cd /media; ./run_app_hw_emu.sh"
```

--------------------------------

### Compare Output with Golden Data

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/Host_srcs/README.md

This code iterates through the output buffer and compares each element with the corresponding golden data. It prints an error message and increments an error counter if any mismatch is found. The comparison is done using signed integer types.

```cpp
int errorCount = 0;
for (int i = 0; i < sizePLOut0; i++) {
	if ((signed)out_bomapped0[i] != (signed)goldenPL0[i]) {
		printf("Error found @ %d, %ld != %ld\n", i, (long int)out_bomapped0[i], (long int)goldenPL0[i]);
		errorCount++;
	}
}
```

--------------------------------

### Create Vivado Project and Add Sources

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis_Libraries/README.md

This snippet demonstrates the command-line steps to create a new Vivado project and add necessary RTL source files and constraints. It requires Vivado to be installed and accessible.

```bash
mkdir vivado
cd ./vivado
vivado &

```

--------------------------------

### Compile S2MM HLS Kernel using Vitis

Source: https://github.com/xilinx/vitis-tutorials/blob/2025.2/Getting_Started/Vitis/Versal_w_PetaLinux/VCK190/HLS_Kernels/README.md

Compiles the C++ code for the S2MM (Stream to Memory Map) HLS kernel. This kernel converts AXI-Stream data to AXI-MM. The compilation uses the v++ command with specified platform and configuration.

```shell
v++ -c --mode hls --platform $(PLATFORM) --config s2mm.cfg
```
Tokens:
Raw