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

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

reserved-memory Section

Defines physical memory regions carved out of normal system use and shared 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 Physical base address of the region
size hex integer Yes Size in bytes
no-map integer (1) Yes Prevents the kernel from mapping this region. Set to 1 for all OpenAMP shared regions.
device_type string Conditional Set to memory on the ddrboot region. This indicates a loadable firmware memory region. The Zephyr build requires this so it can recognize the memory for linker sections.
Table 2. Standard OpenAMP Reserved-memory Entries
Node Name Purpose Default Size
ddrboot@<addr> DDR region where Linux remoteproc loads the remote ELF firmware. The design has changed starting with the 2026.1 release. The Linux driver no longer makes the DDR boot decision based on the device-tree node name. Instead, the Linux remoteproc framework makes the decision based on the boot address retrieved from the ELF. ~384 KB (0x5FF00)
rsctbl@<addr> Resource table: a data structure describing vring parameters, carveouts, and trace buffers. Remoteproc parses this during firmware loading. 256 B (0x100)
vdev0vring0@<addr> VirtIO vring 0: descriptor ring for the host-to-remote message direction 16 KB (0x4000)
vdev0vring1@<addr> VirtIO vring 1: descriptor ring for the remote-to-host message direction 16 KB (0x4000)
vdev0buffer@<addr> Shared buffer pool for RPMsg message payloads 256 KB (0x40000) on newer SoCs; 1 MB (0x100000) on ZynqMP/Versal
rproc0@<addr> Legacy, AMD Zynq™ UltraScale+™ MPSoC and AMD Versal™ devices only. Combined firmware and resource-table region. Use this instead of separate ddrboot and rsctbl entries. 384 KB (0x60000)
Note: ddrboot vs rproc0 naming: On XCVN3716 and Versal AI Edge Series Gen 2 (2ve-2vm), you name the firmware region ddrboot@<addr> and give the resource table its own rsctbl@<addr> node. On older Zynq UltraScale+ MPSoCs and Versal devices, a single rproc0@<addr> region holds both firmware and resource table.
Example (Versal AI Edge Series Gen 2 and XCVN3716):
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
Example (Zynq UltraScale+ MPSoC and Versal devices):
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 and Linux)

The host domain describes 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:   # list of reserved-memory node names shared with remote
    domain-to-domain:  # relation definitions (remoteproc + rpmsg)
Table 3. Top-level Domain Fields
Field Type Required Description
compatible string Yes Must be openamp,domain-v1
cpus list Yes CPU cluster assignment (refer to the following table)
os,type string Yes Operating system type: linux, zephyr, freertos, or baremetal
memory list Optional DDR ranges assigned to this domain
reserved-memory list Yes References to reserved-memory node names that this domain can access
domain-to-domain mapping Yes Contains the relation definitions
Table 4. cpus Entry Fields
Field Type Required Description
cluster string Yes Reference to the CPU cluster node in the system device tree (for example, cpus_a78, cpus_a72, cpus_a53)
cpumask hex Yes Bitmask selecting which CPUs in the cluster belong to this domain
mode.secure boolean Yes Whether the domain runs in secure mode
mode.el hex Yes Exception level (for example, 0x3 = EL3, 0x2 = EL2, 0x1 = EL1)
Table 5. memory Entry Fields (optional)
Field Type Required Description
dev string Yes Label or reference for the memory range
start hex string Yes Physical start address
size hex string Yes Size in bytes

domain-to-domain Remoteproc Relation

The remoteproc-relation tells lopper how to generate the Linux remoteproc device tree node. It specifies which remote domain to manage and which memory regions are used 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 Must be openamp,remoteproc-v2

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

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

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

  • TCM entries (for example, r52_0a_atcm_global, psu_r5_0_atcm_global) become sram = <&label> phandles in the remoteproc node.
  • DDR / reserved-memory entries (for example, ddrboot@9800100, rproc0@9800000, rsctbl@9800000) become memory-region = <&label> phandles.

Example (Versal AI Edge Series Gen 2):

   remoteproc-relation:
        compatible: openamp,remoteproc-v2
        relation0:                        # arbitrary name; use relation1, relation2, etc. for additional channels
          remote: RPU_Zephyr
          elfload: [ r52_0a_atcm_global, r52_0a_btcm_global, r52_0a_ctcm_global, ddrboot@9800100, rsctbl@9800000 ]

Example (Zynq UltraScale+ MPSoC):

      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 ]

1.2.4 domain-to-domain: RPMsg Relation (Host Side)

The rpmsg-relation tells 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>
Table 8. relationX Fields (within rpmsg-relation Host Side):
Field Type Required Description
remote string Yes Name of the remote domain. This must match the same remote as in remoteproc-relation.
carveouts list of strings Yes The vring and buffer reserved-memory regions. Order matters, use this convention: [vring0, vring1, buffer].
mbox string Yes IPI mailbox channel name from the system device tree. This identifies which IPI pair you use for host-to-remote notifications. The name must match a mailbox child node label in the SDT.
Note: As with the remoteproc-relation, relation0 is an arbitrary name. Multiple relation instances can coexist within the same rpmsg-relation block.

Example:

     rpmsg-relation:
        compatible: openamp,rpmsg-v1
        relation0:                                     # arbitrary name
          remote: RPU_Zephyr
          carveouts: [ vdev0vring0@9860000, vdev0vring1@9864000, vdev0buffer@9868000 ]
          mbox: ipi_1_nobuf_to_ipi_2_nobuf             # APU-side IPI channel

domains Section: Remote Domain (RPU)

The remote domain describes the RPU processor running the firmware that 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 Specific CPU node name within the cluster (for example, cortexr52_0, psu_cortexr5_0). This tells Lopper exactly which core to target.
xlnx,ddr-boot boolean Conditional R52 cores only. Set true for OpenAMP IPC remote domains on R52. This is required for the remoteproc ELF-load flow on Cortex-R52 platforms such as XCVN3716 devices and Versal AI Edge Series Gen 2. For Libmetal IPC remote domains, set false or omit this field, because PLM assumes TCM boot from the boot PDI. Do not set this property on R5 (Cortex-R5) remote domains.
sram list Yes 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 Device or region reference matching a reserved-memory entry or a TCM node in the SDT
start hex Yes Physical base address
size hex or human-readable Yes Size (for example, 0x5FF00, 64K, 32K)
label string Optional Label for phandle reference in generated device tree
spec_name string Optional Specification-level name for the TCM, used by some tooling
Table 11. Remote-side rpmsg-relation
Field Type Required Description
host string Yes Name of the host domain (replaces remote on the host side)
mbox string Yes IPI channel name. This is the RPU-side IPI channel, which 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 Same vring and buffer regions as the host side. These must be identical.
Note: The remote domain mirrors the host's rpmsg-relation, but uses host instead of remote: