YAML Structure and Field Reference - YAML Structure and Field Reference - 2026.1 English - UG1186

Libmetal and OpenAMP User Guide (UG1186)
Document ID
UG1186
Release Date
2026-06-24
Version
2026.1 English

The OpenAMP overlay YAML file has two top-level sections:

  • reserved-memory
  • domains

reserved-memory Section

Use this section to define physical memory regions that you carve out of normal system use. You share these regions between the host and remote processors. Each entry becomes a node under /reserved-memory in the generated device tree.

Table 1. Fields per Entry
Field Type Required Description
start hex integer Yes Specify the physical base address of the region.
size hex integer Yes Specify the size in bytes.
no-map integer (1) Yes Prevent the kernel from mapping this region. Set it to 1 for all OpenAMP shared regions.
device_type string Conditional Set this to "memory" on the ddrboot region. This marks it as a loadable firmware me
Table 2. Standard OpenAMP Reserved-memory Entries
Node Name Purpose Default Size
ddrboot@<addr> Use this DDR region for Linux remoteproc to load the remote ELF firmware. The name must contain ddrboot. The xlnx_r5_remoteproc Linux driver uses that substring to detect ELFLOAD boot mode. ~384 KB (0x5FF00)
rsctbl@<addr> Use this for the resource table. This data structure describes vring parameters, carveouts, and trace buffers. Remoteproc parses it during firmware loading. 256 B (0x100)
vdev0vring0@<addr> Use this for VirtIO vring 0. It holds the descriptor ring for host-to-remote messages. 16 KB (0x4000)
vdev0vring1@<addr> Use this for VirtIO vring 1. It holds the descriptor ring for remote-to-host messages. 16 KB (0x4000)
vdev0buffer@<addr> Use this shared buffer pool for RPMsg message payloads. 256 KB (0x40000) on newer SoCs; 1 MB (0x100000) on Zynq UltraScale+ MPSoCs and Versal devices.
rproc0@<addr> Use this legacy region only on Zynq UltraScale+ MPSoCs and Versal devices. It combines the firmware and resource table regions. Use it instead of separate ddrboot and rsctbl entries. 384 KB (0x60000)

On XCVN3716 devices and Versal AI Edge Series Gen 2 (2ve-2vm), name the firmware region ddrboot@<addr> and give the resource table its own rsctbl@<addr> node. On older Zynq UltraScale+ MPSoCs and Versal adaptive SoC devices, use one rproc0@<addr> region for both firmware and resource table. This naming difference matters because the Linux remoteproc driver uses the ddrboot substring to select ELF-load mode.

Following is an example for Versal AI Edge Series Gen 2 or XCVN3716 device:
reserved-memory:
  ranges: true
  "#size-cells": 2
  "#address-cells": 2

  ddrboot@9800100:
    no-map: 1
    start: 0x9800100
    size: 0x5FF00
    device_type: "memory"
  rsctbl@9800000:
    start: 0x9800000
    size: 0x100
    no-map: 1
  vdev0vring0@9860000:
    start: 0x9860000
    size: 0x4000
    no-map: 1
  vdev0vring1@9864000:
    start: 0x9864000
    size: 0x4000
    no-map: 1
  vdev0buffer@9868000:
    start: 0x9868000
    size: 0x40000
    no-map: 1
Following is an example for Zynq UltraScale+ MPSoCs or Versal AI Core Series evaluation kit:
reserved-memory:
  ranges: true
  "#size-cells": 2
  "#address-cells": 2

  rproc0@9800000:
    start: 0x9800000
    size: 0x60000
    no-map: 1
  vdev0vring0@9860000:
    start: 0x9860000
    size: 0x4000
    no-map: 1
  vdev0vring1@9864000:
    start: 0x9864000
    size: 0x4000
    no-map: 1
  vdev0buffer@9868000:
    start: 0x9868000
    size: 0x100000
    no-map: 1

domains Section — Host Domain (APU / Linux)

Use the host domain to describe the Linux-side processor and its view of the OpenAMP channel.
domains:
  APU_Linux:
    compatible: openamp,domain-v1
    cpus:
      - cluster: <cpu_cluster_name>
        cpumask: <hex_mask>
        mode:
          secure: <true|false>
          el: <exception_level>
    os,type: linux

    memory:            # optional memory ranges assigned to this domain
    reserved-memory:   # reserved-memory node names shared with the remote
    domain-to-domain:  # relation definitions for remoteproc and rpmsg
Table 3. Top-level domain fields
Field Type Required Description
compatible string Yes Set this to openamp,domain-v1.
cpus list Yes Assign the CPU cluster.
os,type string Yes Set the operating system type to linux, zephyr, freertos, or baremetal.
memory list Optional Assign DDR ranges to this domain.
reserved-memory list Yes Reference the reserved-memory node names that this domain can access.
domain-to-domain mapping Yes Define the inter-domain relations here.
Table 4. cpus Entry Fields
Field Type Required Description
cluster string Yes Reference the CPU cluster node in the system device tree, such as cpus_a78, cpus_a72, or cpus_a53.
cpumask hex Yes Select which CPUs in the cluster belong to this domain.
mode.secure boolean Yes Specify whether the domain runs in secure mode.
mode.el hex Yes Set the exception level, such as 0x3, 0x2, or 0x1.
Table 5. memory Entry Fields (Optional)
Field Type Required Description
dev string Yes Identify the memory range label or reference.
start hex string Yes Specify the physical start address.
size hex string Yes Specify the size in bytes.

domain-to-domain — Remoteproc Relation

Use the remoteproc-relation to tell Lopper how to generate the Linux remoteproc device tree node. You specify which remote domain Linux manages and which memory regions remoteproc uses for ELF loading.
    domain-to-domain:
      compatible: openamp,domain-to-domain-v1

      remoteproc-relation:
        compatible: openamp,remoteproc-v2
        relation0:
          remote: <remote_domain_name>
          elfload: [ <tcm_and_ddr_regions...> ]
Table 6. remoteproc-relation Fields
Field Type Required Description
compatible string Yes Set this to openamp,remoteproc-v2.

Within remoteproc-relation, the node name relation0 is an arbitrary label. You use it as a convention for the first relation instance. You can define multiple relations, such as relation0, relation1, and relation2, in the same block. Use them to describe channels to different remote processors. The name itself has no semantic meaning to Lopper. Only the fields inside it matter.

Table 7. relationX Fields in remoteproc-relation
Field Type Required Description
remote string Yes Set the remote domain name. It must match a domain defined in this YAML. This identifies which RPU core Linux manages.
elfload list of strings Yes List the memory regions that remoteproc can load ELF segments into. Include TCM names for the generated sram property. Include DDR boot and resource table regions for the generated memory-region property.

The elfload list is critical. Lopper splits it into two categories when it generates the Linux device tree:

  • TCM entries such as r52_0a_atcm_global or psu_r5_0_atcm_global become sram = <&label> phandles in the remoteproc node.
  • DDR or reserved-memory entries such as ddrboot@9800100, rproc0@9800000, or rsctbl@9800000 become memory-region = <&label> phandles.
Following is an example for Versal AI Edge Series Gen 2:
    remoteproc-relation:
        compatible: openamp,remoteproc-v2
        relation0:
          remote: RPU_Zephyr
          elfload: [ r52_0a_atcm_global, r52_0a_btcm_global, r52_0a_ctcm_global, ddrboot@9800100, rsctbl@9800000 ]
Following is an example for Zynq UltraScale+ MPSoCs:
      remoteproc-relation:
        compatible: openamp,remoteproc-v2
        relation0:
          remote: R5_0_FREERTOS
          elfload: [ psu_r5_0_atcm_global@ffe00000, psu_r5_0_btcm_global@ffe20000, rproc0@9800000 ]

domain-to-domain — RPMsg Relation (Host Side)

Use the rpmsg-relation to tell Lopper how to generate the VirtIO and RPMsg communication channel nodes.

      rpmsg-relation:
        compatible: openamp,rpmsg-v1
        relation0:
          remote: <remote_domain_name>
          carveouts: [ <vring_and_buffer_regions...> ]
          mbox: <ipi_channel_name>

Within rpmsg-relation, the node name relation0 is also an arbitrary label. You can define multiple relation instances in the same block.

Table 8. relationX Fields in rpmsg-relation (Host Side)
Field Type Required Description
remote string Yes Set the remote domain name. It must match the same remote domain that you use in remoteproc-relation.
carveouts list of strings Yes List the vring and buffer reserved-memory regions. Keep the order as [vring0, vring1, buffer].
mbox string Yes Set the IPI mailbox channel name from the system device tree. This identifies the IPI pair for host-to-remote notifications. The name must match a mailbox child node label in the SDT.
The following example shows a host-side rpmsg-relation that connects Linux to RPU_Zephyr by using the shared vrings, buffer carveouts, and the APU-side IPI mailbox channel.
      rpmsg-relation:
        compatible: openamp,rpmsg-v1
        relation0:
          remote: RPU_Zephyr
          carveouts: [ vdev0vring0@9860000, vdev0vring1@9864000, vdev0buffer@9868000 ]
          mbox: ipi_1_nobuf_to_ipi_2_nobuf

domains Section — Remote Domain (RPU)

Use the remote domain to describe the RPU processor that runs the firmware Linux manages.
  RPU_Zephyr:
    compatible: openamp,domain-v1
    cpus:
      - cluster: <rpu_cluster>
        cluster_cpu: <specific_cpu_node>
        cpumask: <hex_mask>
        mode:
          secure: true
          el: 0x3
    os,type: <zephyr|freertos|baremetal>
    xlnx,ddr-boot: true

    domain-to-domain:
      compatible: openamp,domain-to-domain-v1
      rpmsg-relation:
        compatible: openamp,rpmsg-v1
        relation0:
          host: <host_domain_name>
          mbox: <ipi_channel_name>
          carveouts: [ <same_vring_and_buffer_regions> ]

    sram:
      - dev: <ddrboot_region>
        start: <addr>
        size: <size>
      - dev: <tcm_region>
        label: <label>
        size: <size>
        spec_name: <spec_name>
        start: <addr>

    reserved-memory:
      - <ddrboot_region_name>
Table 9. Remote-specific Domain Fields
Field Type Required Description
cpus[].cluster_cpu string Yes Set the specific CPU node name inside the cluster, such as cortexr52_0 or psu_cortexr5_0. This tells Lopper which core to target.
xlnx,ddr-boot boolean Conditional Use this only for R52 cores. Set it to true for OpenAMP IPC remote domains on R52. This is required today for the remoteproc ELF-load flow on Cortex®-R5F2 platforms such as XCVN3716 devices and Versal AI Edge Series Gen 2. For Libmetal IPC remote domains, set it to false or omit it because PLM assumes TCM boot from the Boot PDI. Do not set this property on R5 remote domains.
sram list Yes List the memory regions the RPU can access. Include the DDR boot region and all TCM banks. Lopper uses these to generate the Zephyr zephyr,sram chosen property and linker memory regions.
Table 10. sram Entry Fields
Field Type Required Description
dev string Yes Reference a reserved-memory entry or a TCM node in the SDT.
start hex Yes Specify the physical base address.
size hex or human-readable Yes Specify the size, such as 0x5FF00, 64K, or 32K.
label string Optional Set a label for phandle reference in the generated device tree.
spec_name string Optional Set the specification-level name for the TCM, if needed by tooling.
Table 11. Remote-side rpmsg-relation
Field Type Required Description
host string Yes Set the host domain name. This replaces remote on the host side.
mbox string Yes Set the RPU-side IPI channel name. This is the reverse direction from the host. For example, if the host uses ipi_1_nobuf_to_ipi_2_nobuf, the remote uses ipi_2_nobuf_to_ipi_1_nobuf.
carveouts list Yes Use the same vring and buffer regions as the host side. They must match exactly.

The remote domain mirrors the host rpmsg-relation, but you use host instead of remote.