Build and Boot the libmetal-demo Application
Overview
The libmetal-demo application is a reference IRQ shared-memory demonstration that validates IPC between the Linux host on the APU and a remote core on the RPU. It exercises the libmetal user-space abstractions over IRQ-based communication across shared-memory regions.
The demo has two components:
Host application (
libmetal-demo-host): runs on the Linux APU, exercising the libmetal user-space abstractions (irq_shmem_demo).Remote firmware (
libmetal-demo-remote): runs as bare-metal firmware on the RPU (Cortex-R5 or Cortex-R52) as the remote side of the shared-memory demo.
Yocto Build Environment Setup
Before building the libmetal-demo application, set up the Yocto EDF build environment.
Configured Platforms
The libmetal-demo-rpu1.inc include file carries per-platform
processor selection for the second RPU core: Cortex-R5 #1 on
ZynqMP, Versal, and Versal 2VP; Cortex-R52 #1 on Versal Gen 2.
This table reflects where the payload include is selected in machine YAML.
Use the boot-image recipe column to match the machine’s supported boot
flow: only the OSPI-capable machines use bitbake edf-ospi directly;
other machines continue with their normal recipe for that board, such as
xilinx-bootbin, edf-qspi, or kria-qspi.
Machine |
Remote core |
Platform |
Boot image recipe |
|---|---|---|---|
|
Cortex-R5 #1 |
ZCU102 |
|
|
Cortex-R5 #1 |
ZCU104 |
|
|
Cortex-R5 #1 |
ZCU106 |
|
|
Cortex-R5 #1 |
ZCU111 |
|
|
Cortex-R5 #1 |
ZCU208 |
|
|
Cortex-R5 #1 |
ZCU216 |
|
|
Cortex-R5 #1 |
K24C |
|
|
Cortex-R5 #1 |
K24I |
|
|
Cortex-R5 #1 |
KD240 |
|
|
Cortex-R5 #1 |
KR260 |
|
|
Cortex-R5 #1 |
KV260 |
|
|
Cortex-R5 #1 |
VCK190 |
|
|
Cortex-R5 #1 |
VMK180 |
|
|
Cortex-R5 #1 |
VEK280 |
|
|
Cortex-R5 #1 |
VPK120 |
|
|
Cortex-R5 #1 |
VPK180 |
|
|
Cortex-R5 #1 |
VRK160 |
|
|
Cortex-R5 #1 |
VRK160 RevB |
|
|
Cortex-R5 #1 |
VRK165 |
|
|
Cortex-R5 #1 |
VRK165 RevB |
|
|
Cortex-R5 #1 |
VHK158 |
|
|
Cortex-R5 #1 |
VM-P-M1369 Rev A |
|
|
Cortex-R5 #1 |
VPK360 |
|
|
Cortex-R52 #1 |
VEK385 |
|
|
Cortex-R52 #1 |
VEK385 RevB |
|
|
Cortex-R52 #1 |
VEK386 |
|
|
Cortex-R52 #1 |
VMK365 |
|
Inspect Source Configuration
Inspect the libmetal-demo-rpu1.inc Configuration
The libmetal-demo-rpu1.inc file configures the
libmetal-demo RPU payload:
$ cat sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/dynamic-layers/meta-amd-edf-core/recipes-bsp/bootbin/libmetal-demo-rpu1.inc
The include file:
Sets the application name to
libmetal-demo-remote.Selects the remote processor per platform (Cortex-R5 #1 on ZynqMP, Versal, and Versal 2VP, and Cortex-R52 #1 on Versal Gen 2).
Defines the multiconfig dependency, deploy path, and boot-image partition entries used to package the remote payload.
Note
Verify the live file content in your checked-out layers before
building. If upstream comments out the payload-specific lines,
bitbake edf-ospi still succeeds but does not include
libmetal-demo-remote in the boot image.
Review How the Machine Selects the RPU Payload
The multi-domain machine YAML selects the RPU payload include file by
setting BOOTBIN_INC. Review the active machine YAML in your source
tree and confirm which include file the boot image uses:
$ cat sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-multidomain.yaml
machine:
post:
BOOTBIN_INC:
comment: 'Enable libmetal application'
op: '='
val: 'libmetal-demo-rpu1.inc'
The same YAML file applies the libmetal overlay that reserves the
shared-memory regions and configures IPC. The --domain-file
argument passes multiple overlay files to gen-machine-conf:
Note
The following snippet is an excerpt. Confirm the exact, current
--domain-file list in your checked-out source tree.
args:
- --domain-file \
${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-2ve-2vm-multidomain-base.yaml \
${BSPLAYERDIR_amd-adaptive-socs-bsp}/conf/domainyaml/vek385-domain-access-overlay.yaml \
${BSPLAYERDIR_amd-adaptive-socs-bsp}/conf/domainyaml/vek385-linux-overlay.yaml \
${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-2ve-2vm-openamp-overlay.yaml \
${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-2ve-2vm-libmetal-overlay.yaml \
${LAYER_PATH_xilinx-multimedia}/conf/domainyaml/isp-overlay-versal-2ve-2vm.yaml
For details of the overlay and the reserved regions it allocates, see Libmetal Overlay.
Regenerate and Build
Regenerate the Machine Configuration
If you edited the machine YAML file to change BOOTBIN_INC, rerun
gen-machine-conf to regenerate the machine configuration:
$ gen-machine-conf --template ../sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-multidomain.yaml
Build the OSPI Boot Image
Machines whose boot image recipe is edf-ospi use the Octal SPI
(OSPI) boot flow. Build the board-specific boot image for the selected
multi-domain machine:
$ MACHINE=versal-2ve-2vm-vek385-multidomain bitbake edf-ospi
This command builds the board-specific Octal SPI (OSPI) boot artifacts
using the payload include selected by the machine YAML. Machines that use
xilinx-bootbin, edf-qspi, or kria-qspi follow their normal
board-specific build command instead.
Write, Boot, and Run irq_shmem_demo
Write the generated boot image to your boot medium by using your board workflow from Discovery and Evaluation AMD Versal Device Portfolio.
Boot the board with the updated image and log in to Linux.
Confirm the host demo application is present, generate the platform configuration, and then run it:
$ mkdir -p ~/libmetal-demo && cd ~/libmetal-demo $ which discover_platform.sh /usr/bin/discover_platform.sh $ which irq_shmem_demo /usr/bin/irq_shmem_demo $ discover_platform.sh -o platform.conf Config written to platform.conf $ ls platform.conf platform.conf $ irq_shmem_demo -c platform.conf
discover_platform.shwritesplatform.confonly when you pass-o. A bare invocation printsKEY=valueentries to stdout and leaves no file behind. Runirq_shmem_demofrom the same directory asplatform.conf.Confirm the console output shows successful mailbox/shared-memory exchanges and that the demo exits without errors. On a successful run, the output includes the startup banner and a final summary line with the packet count and timing values for that run, while the exact numbers vary by board and payload timing. Typical successful output includes the following lines in order:
HOST: IRQ and shared memoryHOST: Start echo flood testing....HOST: Sending msgs to the remote.HOST: Waiting for messages to echo back and verify.HOST: Kick remote to notify shutdown message sent...
If the remote payload is not present in the boot image, the host-side
irq_shmem_demo run does not complete this exchange.
Switch the Boot-Loaded RPU Payload
The machine YAML’s BOOTBIN_INC value selects the boot-loaded RPU
payload. Replace the include file in the machine YAML as needed, then
regenerate the machine configuration. For Octal SPI (OSPI)-based
machines, rebuild edf-ospi for that board.
Supported RPU payload includes:
libmetal-demo-rpu1.inc—libmetal-demo-remoteon RPU core 1versal-hello-world.inc— hello-world application on RPU core 1 (Versal)versal-2ve-2vm-hello-world-r52-1-baremetal.inc— bare-metal hello-world on RPU core 1 (Versal Gen 2)
For the IPI mailbox and reserved-memory details used by the libmetal overlay, see Libmetal Overlay and IPI Mappings, and Domain Configuration Files Usage in Yocto Machine Definitions.
Memory Map Configuration
The libmetal overlay reserves memory regions for IPC, and the libmetal-demo application consumes them. The layout is defined in the libmetal overlay:
sources/meta-xilinx/meta-xilinx-standalone-sdt/conf/domainyaml/versal-2ve-2vm-libmetal-overlay.yaml
The overlay reserves the following regions:
Region |
Address |
Size |
Purpose |
|---|---|---|---|
|
|
|
Remote ELF load region |
|
|
|
Shared descriptor (direction 0) |
|
|
|
Shared descriptor (direction 1) |
|
|
|
Shared data buffer |
For the overlay structure and the UIO devices it exposes to Linux user space, see Libmetal Overlay.