Host Programming for Bare-Metal - 2025.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2025-11-20
Version
2025.2 English

In a bare-metal/standalone environment, AMD provides standalone board support package (BSP), drivers, and libraries for applications to use to reduce development effort. You can use theVitis platform component to configure and generate the BSP. To set up the Vitis Platform component and add a standalone domain for the bare-metal environment (refer to this link). To update the BSP with adding or removing libraries, see this link.

The top-level application for bare-metal systems must also integrate and manage the AI Engine graph and PL kernels. For more information, see Host Programming on Linux.

Tip: You can integrate a bare-metal system with the AI Engine graph and PL kernels. The Vitis Reference Guide (UG1702) describes this in the section Creating a Bare-Metal System.
Figure 1. AI Engine Bare-Metal Software Stack

A typical bare-metal host application structure consists of #include statements, #define macros, object instantiations, helper functions, main function body. The following table describe these with example code snippets.

Table 1. Code Constructs for AI Engine Host Applications
Type Example Usage Comment
C/C++ include 
#include <stdio.h>
#include <stdlib.h>
Optional Recommended as it is used for general purpose functions like printf and memory management
AMD include 

#include "xparameters.h"
#include "xil_io.h"
#include "xil_cache.h"
Mandatory Generated through board support package, and is used for accessing and controlling PL and AI Engineresources
Define 

#define MM2S_BASE XPAR_XMM2S_0_BASEADDR
#define S2MM_BASE XPAR_XS2MM_0_BASEADDR

#define MEM_OFFSET 0x10
#define SIZE_OFFSET 0x1C
#define CTRL_OFFSET 0x0
Optional Improves code readability
Object instance 

BaremetalGraph gr("mygraph");
Mandatory Creates object handle named gr for the AI Engine graph named mygraph.
AMD helper functions 

// From xil_cache.h
Xil_DCacheDisable();

// From xil_io.h
Xil_Out32(MM2S_BASE + CTRL_OFFSET, 1);
uint32_t v = Xil_In32(S2MM_BASE + CTRL_OFFSET);
Optional It is recommended to disable cache for bare-metal applications. Xil_In32 and Xil_Out32 provide read and write access to AXI4-Lite PL registers.
Main function 

int main()
{
  // Prepare input stimuli

  // Initialize graph
  gr.init();
  // Run graph
  gr.run(4);

  // Check if results are completed

  // Terminate the graph execution
  gr.end();

  // Check output data

}
Mandatory Host application main body

A complete bare-metal example is available in the Vitis Tutorials.