vd100-bare-metal-system-project

Vitis system project for bare-metal applications on the VD100 board (Versal AI Edge XCVE2302). Links the AIE kernel, HLS DMA kernels, and PS bare-metal ELF into a bootable BOOT.BIN SD image.

This is the hardware integration layer — it does not contain application code. The PS ELF is specified in package.cfg and can be switched to any of the three bare-metal application repos without rebuilding the hardware.

---

What It Does

vd100_platform (XSA)
    │
    ├── vd100-aie-ma-crossover  [AIE Engine]   → AIE ELF + CDOs
    ├── mm2s                    [HLS]           → PL DMA source kernel
    ├── s2mm                    [HLS]           → PL DMA sink kernel
    │
    └── v++ link → binary_container_1.xsa + xclbin
            │
            └── v++ package → BOOT.BIN
                    ├── system.pdi          (PL bitstream)
                    ├── aie_dev_part CDO    (AIE partition reset)
                    ├── aie_image CDO       (AIE ELF + init)
                    └── PS ELF (A72-0)      (bare-metal application)

Boot from SD card — no Linux, no Yocto, no XRT required.

---

Hardware

Item	Value
Board	VD100
Device	XCVE2302-SFVA784-1LP-E-S
Platform	vd100_platform (Vivado XSA)
AIE kernel	vd100-aie-ma-crossover (mygraph)
HLS kernels	mm2s, s2mm
Vitis	2025.2

---

Repository Structure

vd100-bare-metal-system-project/
├── hw_link/
│   └── binary_container_1-link.cfg   # v++ link config
├── package/
│   └── package.cfg                   # v++ package config — specifies PS ELF
└── README.md

---

Switching the PS Application

To switch which bare-metal app boots, edit package/package.cfg:

# Bare-metal echo only (no AIE):
[package]
boot_mode=sd
Baremetal Elf=/path/to/vd100-bare-metal-uart-echo.elf,a72-0

# Auto-run AIE MA crossover:
[package]
boot_mode=sd
Baremetal Elf=/path/to/vd100-bare-metal-ma-aie-app.elf,a72-0

# Interactive UART-commanded AIE:
[package]
boot_mode=sd
Baremetal Elf=/path/to/vd100-bare-metal-ma-aie-interactive.elf,a72-0

Then rebuild PACKAGE only — no need to relink hardware.

---

Build Flow

HARDWARE EMULATION (for XSA generation):
    LINK → binary_container_1    ← generates XSA for platform

HARDWARE (for SD image):
    LINK → binary_container_1    ← links AIE + HLS kernels
    PACKAGE                      ← generates BOOT.BIN

After PACKAGE completes:

# Copy to SD card FAT partition
cp build/package/BOOT.BIN           /media/sdcard/
cp build/package/binary_container_1.xclbin  /media/sdcard/

Boot VD100 from SD. Connect minicom at 115200 baud on /dev/ttyUSB0.

---

Critical Notes

Full clean rebuild required after any change

Deleting output files alone is not sufficient. After any change to AIE kernel, HLS kernels, platform, or package.cfg:

# In Vitis: right-click system project → Clean
# Or manually:
rm -rf build/
# Then rebuild from LINK step

Incremental builds frequently produce stale BOOT.BIN that does not reflect the latest changes.

BOOT.BIN must include AIE CDO partitions

The generated boot_image.bif must contain:

image { name=aie_dev_part, id=0x18800000
    { type=cdo, file="aie.cdo.device.partition.reset.bin" }
}
image { name=aie_image, id=0x18800000
    { type=cdo, file="aie.merged.cdo.bin" }
}

Without these partitions AIE tiles remain clock-gated and BaremetalGraph::run() hangs silently forever. Verify the BIF after each package build.

Uses vd100_platform not vd100-bare-metal-aie-platform

The system project uses the base vd100_platform XSA (from Vivado) for hardware linking. The vd100-bare-metal-aie-platform is a downstream platform built from this system project's output XSA.

Dependency order:

vd100_platform (Vivado XSA)
    └── vd100-bare-metal-system-project (links hardware, generates XSA)
            └── vd100-bare-metal-aie-platform (BSP platform from system XSA)
                    └── application components (bare-metal apps)

PS_BARE_METAL define required in application components

In each application's UserConfig.cmake → Defined Symbols:

__PS_BARE_METAL__

This is required for baremetal_metadata_compile.cpp to compile correctly. Without it the AIE metadata is generated for XRT Linux mode.

---

Versal Bare-Metal Series

Repo	Description
vd100-bare-metal-aie-platform	Shared BSP platform
vd100-bare-metal-system-project	This repo — hardware link + packaging
vd100-bare-metal-uart-echo	Application: PS UART echo
vd100-bare-metal-ma-aie-app	Application: auto-run AIE MA crossover
vd100-bare-metal-ma-aie-interactive	Application: UART-commanded AIE MA crossover