The latest development version of this page may be more current than this released v2026.04.0 version.

7. Domain Specific YAML Simplifications (Under Discussion)

Note

The contents of this chapter are still under discussion.

For simplicity and ease of use, System Device Tree comes with an alternative representation in YAML, see Simplified YAML (Under Discussion).

This document describes the domain-oriented YAML conventions currently used by lopper, including the OpenAMP and Libmetal overlay patterns shipped in meta-xilinx-standalone-sdt/conf/domainyaml.

7.1. Current Reference Overlays

The current reference overlays are grouped into two families:

OpenAMP overlays: openamp-overlay-zynqmp.yaml, openamp-overlay-versal.yaml, openamp-overlay-versal-net.yaml, and openamp-overlay-versal-2ve-2vm.yaml
Libmetal overlays: libmetal-overlay-zynqmp.yaml, libmetal-overlay-versal.yaml, libmetal-overlay-versal-net.yaml, and libmetal-overlay-versal-2ve-2vm.yaml

These files all use the same three top-level sections:

reserved-memory for named carveouts
optional axi for UIO or MMIO helper nodes
domains for execution domains and domain-to-domain relations

7.2. Hierarchy

Domains are still represented under /domains.

In YAML this appears as a top-level domains: mapping whose keys are the domain names:

domains:
  APU_Linux:
    compatible: openamp,domain-v1

  RPU_Zephyr:
    compatible: openamp,domain-v1

7.3. Parent

Optionally, the name of the parent node can be explicitly specified using the parent key. This remains useful when domain information is spread across multiple YAML files.

domains:
  parent-domain:
    compatible: openamp,domain-v1

  child-domain:
    parent: parent-domain
    compatible: openamp,domain-v1

7.4. Reserved Memory

Current OpenAMP and Libmetal overlays define carveouts at the top level under reserved-memory. Each entry is named using the final device tree node name, typically name@address.

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

Two reference styles are used from domains and relations:

a domain’s reserved-memory property is a list of node names
relation properties such as elfload and carveouts also use node names

Example:

domains:
  APU_Linux:
    reserved-memory:
      - vdev0buffer@9868000
      - vdev0vring1@9864000
      - vdev0vring0@9860000
      - rproc0@9800000

    domain-to-domain:
      remoteproc-relation:
        compatible: openamp,remoteproc-v2
        relation0:
          elfload:
            - psu_r5_0_atcm_global@ffe00000
            - psu_r5_0_btcm_global@ffe20000
            - rproc0@9800000

      rpmsg-relation:
        compatible: openamp,rpmsg-v1
        relation0:
          carveouts:
            - vdev0vring0@9860000
            - vdev0vring1@9864000
            - vdev0buffer@9868000

7.5. AXI Helper Nodes

Libmetal overlays add an axi section for nodes that should appear in the generated device tree as MMIO helper devices, typically compatible = "uio" timer, mailbox, and shared-memory descriptors.

axi:
  libmetal_uio_desc0@99c8000:
    start: 0x99c8000
    size: 0x4000
    compatible: "uio"

  timer@ff130000:
    compatible: "uio"

  mailbox@ff350000:
    compatible: "uio"

7.6. Access

The access property of domain nodes is specified with the following key: value pairs:

dev: device reference
flags: flags

Example:

access:
    - dev: serial0
      flags: {read-only: true}

The device references specified using the ‘dev’ key has to be a subset of the parent domain’s access list of devices.

Instead of a device reference, it is also possible to pass a GLOB pattern matching string. It will be matched against the parent domain’s access list. Please refer to [GLOB] for more details.

Example:

access:
    - dev: "*"

7.7. Memory and Sram

The memory and sram properties to specify the memory and sram allocations to a domain are specified in YAML using start and size key: value pairs to increase readability.

Example:

sram:
    - start: 0xfffc0000
      size: 0x1000
      flags: {read-only: true}

7.8. Cpus

The cpus property of domain nodes is specified with the following key: value pairs:

cluster: cpu cluster reference
cpumask: cpumask in hex
mode: unordered key: value pairs specifying the cpu mode
- secure: true/false
- el: the execution level

Example:

cpus:
    - cluster: cpus_a72
      cpumask: 0x3
      mode:
          secure: true
          el: 0x3

7.9. Domain-to-Domain Relations

Current overlays use domain-to-domain with one of three relation compatibles:

openamp,remoteproc-v2 for Linux remoteproc generation
openamp,rpmsg-v1 for RPMsg channels
libmetal,ipc-v1 for Libmetal IPC and UIO helper generation

Each relation block contains one or more relationN children. The common keys are:

remote or host: the peer domain
elfload: firmware or TCM memory references for remoteproc
carveouts: reserved-memory or AXI helper references
mbox: mailbox device reference
timer: timer device reference or list of timer references

Example:

domain-to-domain:
  compatible: openamp,domain-to-domain-v1

  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

  rpmsg-relation:
    compatible: openamp,rpmsg-v1
    relation0:
      remote: RPU_Zephyr
      mbox: ipi_nobuf3_to_ipi_nobuf1
      carveouts:
        - vdev0vring0@9860000
        - vdev0vring1@9864000
        - vdev0buffer@9868000

  libmetal-relation:
    compatible: libmetal,ipc-v1
    relation0:
      remote: RPU_1_BM
      mbox: ipi_5_to_ipi_2
      timer: ttc2
      carveouts:
        - libmetal_uio_desc0@99c8000
        - libmetal_uio_desc1@99cc000
        - libmetal_uio_data@99d0000

7.10. Conditional Properties and `lopper,activate`

A single YAML file can describe multiple OS or configuration variants using conditional property sigils. A sigil is appended to a property name or node name using ! as a delimiter:

property-name!condition!merge-scheme: value
node-name!condition:
  child-key: value

Supported merge schemes are replace (default), append, prepend, and delete. The condition name may be any string (e.g. linux, zephyr, baremetal).

Sigils may appear on any node in the tree, including nodes that are not under /domains/. This is the common pattern for per-domain driver binding:

axi:
  timer@f1e90000:
    compatible: "cdns,ttc"          # base — all domains without activation
    compatible!linux: "uio"         # linux overlay replaces with UIO binding

domains:
  APU_Linux:
    compatible: openamp,domain-v1
    lopper,activate: linux          # selects overlay_tree('linux')
    cpus: ...
    memory: ...

  RPU1_BM:
    compatible: openamp,domain-v1
    # no lopper,activate — base tree used, compatible stays "cdns,ttc"
    cpus: ...
    memory: ...

When domain_access processes APU_Linux it reads lopper,activate, calls overlay_tree('linux'), and uses that merged tree for all subsequent processing. The resulting tree has compatible = "uio" at the timer node. When it processes RPU1_BM the base tree is used unchanged.

The lopper,activate property replaces and supersedes os,type for overlay selection. If lopper,activate is absent, os,type is used as a fallback so existing domain YAML files work without modification.

For full syntax reference and API documentation see docs/conditional-properties.md.

7.11. OS and Vendor Extensions

The shipped overlays make regular use of the generic os,type Property property:

os,type: linux
os,type: freertos
os,type: baremetal
os,type: zephyr

The current AMD Xilinx OpenAMP overlays also use these vendor-specific keys on remote domains:

xlnx,ddr-boot: boolean flag indicating that firmware is loaded from DDR
xlnx,zephyr,mems: list of memory nodes that should be treated as Zephyr memory regions

Example:

RPU_Zephyr:
  compatible: openamp,domain-v1
  os,type: zephyr
  xlnx,ddr-boot: true
  xlnx,zephyr,mems: [ ddrboot@9800100 ]

7.12. Flags

In YAML the following simplifications are used for access, memory, and sram flags definitions and usage:

To define flags use key: value pairs
When defining flags values, give individual flags setting a name rather than just a number, e.g. use read-only instead of (1<<2). The name and corresponding numeric values should be specified in lopper.
no *-flags-cells

access:
    - dev: can0
      flags: {requested: true, read-only: true}

7.13. Implicit Flags Example

The Implicit Flags Properties in the system devicetree specification can also be defined in YAML. For example:

access-implicit-default:
  secure: true
  allow-secure: true
  requested: true
  coherent: false
  virtualized: true
  qos: 99

7.14. Bus Firewalls

In YAML the following simplifications are used to represent firewallconf and firewallconf-default:

no “block-desireable”, instead use the priority number directly as value of the block key
no “allow”, instead use “never” as value of the block key
no “firewallconf-default” property, instead use firewallconf with a single value and no domain references

Example:

firewallconf:
  - domain: bm1
    block: 10
  - domain: bm2
    block: never
  - block: 5

7.15. Full Example

domains:
    xen:
        compatible: openamp,domain-v1

        id: 0xffff
        cpus:
            - cluster: cpus_a72
              cpumask: 0x3
              mode:
                  secure: false
                  el: 0x2
        memory:
            - start: 0x500000
              size: 0x7fb00000

        access:
            - dev: serial0
              flags: { xen-flag-example1: true }
            - dev: mmc0
              flags: { xen-flag-example1: true }

        domains:
            linux1:
                compatible: openamp,domain-v1

                id: 0x0
                cpus:
                    - cluster: cpus_a72
                      cpumask: 0x3
                      mode:
                          secure: false
                          el: 0x1
                memory:
                    - size: 1G
                access:
                    - dev: mmc0
                sram:
                    - start: 0xfffc0000
                      size: 0x1000
                      flags: { read-only: true }
                firewallconf:
                    domain: bm1
                    block: 0x12

            bm1:
                compatible: openamp,domain-v1

                id: 0x1
                cpus:
                    - cluster: cpus_a72
                      cpumask: 0x3
                      mode:
                          secure: false
                          el: 0x1
                memory:
                    - size: 512M
                access:
                    - dev: ethernet0
                firewallconf:
                    domain: linux1
                    block: always

domains:
    freertos1:
        compatible: openamp,domain-v1

        id: 0x5
        cpus:
            - cluster: cpus_r5
              cpumask: 0x3
              mode: {secure: true, el: 1}
        memory:
            - size: 2M
        access:
            - dev: can0

    bm2:
        compatible: openamp,domain-v1

        id: 0x6
        cpus:
            - cluster: microblaze0
              cpumask: 0x1
              mode: {}
        memory:
            - size: 1M
        access:
            - dev: serial1
        sram:
            - start: 0xfffc0000
              size: 0x1000
              flags: { read-only: true }

7. Domain Specific YAML Simplifications (Under Discussion)

7.1. Current Reference Overlays

7.2. Hierarchy

7.3. Parent

7.4. Reserved Memory

7.5. AXI Helper Nodes

7.6. Access

7.7. Memory and Sram

7.8. Cpus

7.9. Domain-to-Domain Relations

7.10. Conditional Properties and lopper,activate

7.11. OS and Vendor Extensions

7.12. Flags

7.13. Implicit Flags Example

7.14. Bus Firewalls

7.15. Full Example

7.10. Conditional Properties and `lopper,activate`