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.

Refer to Operating System Integration and Development.

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

zynqmp-zcu102-multidomain

Cortex-R5 #1

ZCU102

xilinx-bootbin

zynqmp-zcu104-multidomain

Cortex-R5 #1

ZCU104

edf-qspi

zynqmp-zcu106-multidomain

Cortex-R5 #1

ZCU106

xilinx-bootbin

zynqmp-zcu111-multidomain

Cortex-R5 #1

ZCU111

xilinx-bootbin

zynqmp-zcu208-multidomain

Cortex-R5 #1

ZCU208

xilinx-bootbin

zynqmp-zcu216-multidomain

Cortex-R5 #1

ZCU216

xilinx-bootbin

k24c-sm-sdt

Cortex-R5 #1

K24C

xilinx-bootbin

k24i-sm-sdt

Cortex-R5 #1

K24I

xilinx-bootbin

k24-smk-kd-sdt-multidomain

Cortex-R5 #1

KD240

kria-qspi

k26-smk-kr-sdt-multidomain

Cortex-R5 #1

KR260

kria-qspi

k26-smk-kv-sdt-multidomain

Cortex-R5 #1

KV260

kria-qspi

versal-vck190-multidomain

Cortex-R5 #1

VCK190

edf-qspi

versal-vmk180-multidomain

Cortex-R5 #1

VMK180

edf-qspi

versal-vek280-multidomain

Cortex-R5 #1

VEK280

edf-ospi

versal-vpk120-multidomain

Cortex-R5 #1

VPK120

edf-qspi

versal-vpk180-multidomain

Cortex-R5 #1

VPK180

edf-qspi

versal-vrk160-multidomain

Cortex-R5 #1

VRK160

edf-ospi

versal-vrk160-revb-multidomain

Cortex-R5 #1

VRK160 RevB

edf-ospi

versal-vrk165-multidomain

Cortex-R5 #1

VRK165

edf-ospi

versal-vrk165-revb-multidomain

Cortex-R5 #1

VRK165 RevB

edf-ospi

versal-vhk158-multidomain

Cortex-R5 #1

VHK158

edf-ospi

versal-vm-p-m1369-00-reva-x-prc-01-reva-multidomain

Cortex-R5 #1

VM-P-M1369 Rev A

xilinx-bootbin

versal-2vp-vpk360-multidomain

Cortex-R5 #1

VPK360

edf-ospi

versal-2ve-2vm-vek385-multidomain

Cortex-R52 #1

VEK385

edf-ospi

versal-2ve-2vm-vek385-revb-multidomain

Cortex-R52 #1

VEK385 RevB

edf-ospi

versal-2ve-2vm-vek386-multidomain

Cortex-R52 #1

VEK386

edf-ospi

versal-2ve-2vm-vmk365-multidomain

Cortex-R52 #1

VMK365

xilinx-bootbin

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

  1. Write the generated boot image to your boot medium by using your board workflow from Discovery and Evaluation AMD Versal Device Portfolio.

  2. Boot the board with the updated image and log in to Linux.

  3. 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.sh writes platform.conf only when you pass -o. A bare invocation prints KEY=value entries to stdout and leaves no file behind. Run irq_shmem_demo from the same directory as platform.conf.

  4. 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 memory

    • HOST: 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-remote on RPU core 1

  • versal-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

libmetal_elf

0x9968000

0x60000 (384 KB)

Remote ELF load region

libmetal_desc0

0x99c8000

0x4000 (16 KB)

Shared descriptor (direction 0)

libmetal_desc1

0x99cc000

0x4000 (16 KB)

Shared descriptor (direction 1)

libmetal_data

0x99d0000

0x40000 (256 KB)

Shared data buffer

For the overlay structure and the UIO devices it exposes to Linux user space, see Libmetal Overlay.