Domain Configuration Files Usage in Yocto Machine Definitions

Overview

What is an Execution Domain

Many AMD parts integrate multiple processors. For example, a powerful application processor (APU) runs Linux while a smaller real-time processor (RPU) runs FreeRTOS or Zephyr. An execution domain describes what software runs on which processor and what resources (memory, devices) that software uses.

The System Device Tree Specification defines execution domains using the openamp,domain-v1 compatible binding.

Here is what each domain property means:

  • cpus – which processor cores this domain runs on

  • os,type – which OS to run (linux, freertos, zephyr, baremetal, custom)

  • memory – DDR memory ranges assigned to this domain

  • sram – fast on-chip memory (TCM) for real-time processors

  • access – devices assigned to this domain (including shared devices)

  • chosen – boot settings (console, baud rate)

  • reserved-memory – memory set aside for DMA, firmware, or inter-processor communication (IPC, see Libmetal Overlay)

See Field Reference for the full list of fields and their usage.

Why Domain Configuration Files

The hardware description (what processors and peripherals the chip provides) does not change often – the silicon fixes it. But the software configuration (which OS runs where, how much memory each gets) changes frequently depending on your application.

Domain YAML files keep these two concerns separate:

  • Hardware description (SDT) – describes the chip’s processors, memory controllers, and peripherals. You typically do not edit this.

  • Domain YAML files – describe how you want to use that hardware. This is what you customize for your application.

This separation means you can change your software setup (for example, add FreeRTOS on the RPU or adjust the Contiguous Memory Allocator (CMA) size) without touching the hardware description, and vice versa.

In short, domain YAML files describe how to split the resources of a multi-processor chip across the target application’s domains.

These domain YAML files feed gen-machine-conf, the tool that generates Yocto machine configurations from System Device Trees. The --domain-file argument to gen-machine-conf specifies which domain YAML files to use when generating the machine configuration. For full details on gen-machine-conf options, see the gen-machine-conf options.

How Domain Files Fit in the SHEL Flow

Domain YAML files are one input to the broader Software-Hardware Exchange Loop (SHEL) pipeline:

  1. System Device Tree (SDT) – describes the hardware

  2. Domain YAML files – describe how to partition the hardware across software domains (this page)

  3. gen-machine-conf – reads the SDT + domain YAML files and generates Yocto machine configurations

  4. Yocto build – uses the generated machine configuration to build Linux, RTOS firmware, and boot images

For the full SHEL flow, see Software Hardware Exchange Loop (SHEL) Flow.

Prerequisites

Before working with domain YAML files, make sure you have:

  • gen-machine-conf installed or available in your build environment (see the gen-machine-conf repository)

  • meta-xilinx layers set up (meta-xilinx-standalone-sdt provides the base domain YAML files)

  • A valid System Device Tree (SDT) for your platform

  • Your BSP layer if using board-specific overlays

Architecture: Base + Overlay Composition

Domain YAML configurations use a composable base + overlay pattern. The machine YAML assembles a machine’s domain configuration from multiple files loaded in order through gen-machine-conf’s --domain-file arguments:

args:
    - --domain-file \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/<base>.yaml \
       ${BSPLAYERDIR}/conf/domainyaml/<board-overlay>.yaml \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/<openamp-overlay>.yaml \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/<libmetal-overlay>.yaml

Lopper merges files by domain name – all files referencing APU_Linux contribute to the same domain definition.

In shell commands, repeat --domain-file for each file. Command-line domain files append to any supplied by --template; they do not replace the template’s list.

File Locations

File Type

Location

Purpose

Base files

meta-xilinx/meta-xilinx-standalone-sdt/conf/domainyaml/

Shared processor and domain definitions

Board overlays

Each BSP layer’s conf/domainyaml/

Board-specific memory layouts and boot config

Communication overlays

meta-xilinx/meta-xilinx-standalone-sdt/conf/domainyaml/

OpenAMP and libmetal IPC configuration

Configuration Types

Single Domain (Linux-Only)

Uses a linux-only base file, optionally with a board overlay for memory/console settings. No communication overlays needed.

# Composition: base + optional board overlay
--domain-file <platform>-linux-only-base.yaml \
    --domain-file <board>-linux-overlay.yaml

Multi-Domain (Heterogeneous)

Runs multiple operating systems simultaneously. Uses a multidomain base + board overlay + one or more communication overlays.

# Composition: base + board overlay + communication overlays
--domain-file <platform>-multidomain-base.yaml \
    --domain-file <board>-linux-overlay.yaml \
    --domain-file <platform>-openamp-overlay.yaml \
    --domain-file <platform>-libmetal-overlay.yaml

Note

Not all machines require a board overlay. Machines without specific memory requirements use only the base + communication overlays.

Platform Families

Each platform family has its own set of base files and communication overlays tailored to its processor architecture. The following tables reference IPI channels and TTC peripherals used for inter-domain communication.

Versal Gen 2 (Cortex-A78 + Cortex-R52)

Processors: Cortex-A78 (APU) + Cortex-R52 (RPU)

RTOS: Zephyr on R52 core 0, bare-metal on R52 core 1

Note

This section covers the Cortex-A78 Gen 2 series. Versal Premium Series Gen 2 is a Gen 2 series too, but its APU is Cortex-A72, so it takes the domain files in Versal Premium Series Gen 2 (VPK360 / 2VP).

2VE-2VM variant:

File

Description

versal-2ve-2vm-linux-only-base.yaml

Single domain: APU_Linux (A78, cpumask 0xff, non-secure, EL3)

versal-2ve-2vm-multidomain-base.yaml

Defines 3 domains: APU_Linux (A78, cpumask 0xff, non-secure, EL3), RPU_Zephyr (R52 core 0, cpumask 0x1), RPU_1_BM (R52 core 1, cpumask 0x1 in cluster cpus_r52_1, EL3)

versal-2ve-2vm-openamp-overlay.yaml

OpenAMP with DDR boot support: resource table (256 B) + DDR boot code (375.5 KiB) + trace (4 KiB) + vrings (16 KiB x 2) + shared buffer (480 KiB). Uses IPI_1 <-> IPI_2 non-buffered mailbox. RPU SRAM: R52 ATCM (64 KiB) + BTCM (32 KiB) + CTCM (32 KiB)

versal-2ve-2vm-libmetal-overlay.yaml

Libmetal IPC for RPU_1_BM: ELF region (384 KiB) + descriptors (16 KiB x 2) + data (256 KiB) exposed through UIO. Uses IPI_3 <-> IPI_2 mailbox, timer: ttc3. RPU SRAM: R52 core 1 ATCM/BTCM/CTCM

NET variant:

File

Description

versal-net-linux-only-base.yaml

Single domain: APU_Linux (A78, cpumask 0xff, non-secure, EL3)

versal-net-multidomain-base.yaml

3 domains: APU_Linux (A78, cpumask 0xff, non-secure, EL3), RPU_Zephyr (R52 core 0, cpumask 0x1), RPU_1_BM (R52 core 1, cpumask 0x1 in cluster cpus_r52_1, EL3)

versal-net-openamp-overlay.yaml

OpenAMP with DDR boot + Zephyr console configuration. Uses non-buffered IPI mailbox. SRAM: psx_wizard ATCM/BTCM/CTCM

versal-net-libmetal-overlay.yaml

Libmetal IPC for RPU_1_BM

Versal (Cortex-A72 + Cortex-R5)

Processors: Cortex-A72 (APU) + 2-core Cortex-R5 (RPU)

RTOS: Zephyr on R5 core 0, bare-metal on R5 core 1

File

Description

versal-linux-only-base.yaml

Single domain: APU_Linux (A72, cpumask 0xf, secure, EL3)

versal-multidomain-base.yaml

3 domains: APU_Linux (A72, cpumask 0x3, secure, EL3), R5_0_ZEPHYR (R5 core 0, cpumask 0x1), R5_1_BAREMETAL (R5 core 1, cpumask 0x1 in cluster cpus_r5_1, EL3)

versal-openamp-zephyr-common-overlay.yaml

Shared OpenAMP configuration for R5_0_ZEPHYR: firmware (128 KiB), resource table (256 B), trace (4 KiB), vrings (16 KiB x 2), and RPMsg buffer (480 KiB). Uses IPI_3 <-> IPI_1 mailbox

versal-openamp-zephyr-cips-overlay.yaml

CIPS-specific local TCM names, SRAM assignments, and Zephyr linker sections. Use with the common overlay

versal-openamp-zephyr-ps-wizard-overlay.yaml

PS Wizard-specific local TCM names, SRAM assignments, and Zephyr linker sections. Use with the common overlay

versal-libmetal-overlay.yaml

Libmetal IPC for R5_1_BAREMETAL: ELF (384 KiB) + descriptors (16 KiB x 2) + data (256 KiB) through UIO. Uses IPI_5 <-> IPI_2 mailbox, timer: ttc2. RPU SRAM: psv_r5_1 ATCM (64 KiB)

Versal Premium Series Gen 2 (VPK360 / 2VP)

VPK360 uses Cortex-A72 for Linux and Cortex-R5 for the RPU. Its versal-2vp- machines use the shared Versal domain files, rather than the Cortex-A78/Cortex-R52 versal-2ve-2vm- domain files.

For Linux-only configuration, use the BSP template versal-2vp-vpk360-sdt-seg.yaml. For the supplied multidomain flow, use versal-2vp-vpk360-multidomain.yaml. The multidomain template inherits the Linux-only machine template and supplies the following ordered domain files:

File

Purpose

versal-multidomain-base.yaml

Shared A72 Linux, R5 Zephyr, and R5 bare-metal domains

versal-domain-access-overlay.yaml

BSP domain access configuration

vpk360-linux-overlay.yaml

VPK360 Linux domain configuration

versal-openamp-zephyr-common-overlay.yaml

Shared Zephyr OpenAMP regions and communication settings

versal-openamp-zephyr-ps-wizard-overlay.yaml

PS Wizard R5 memory and linker settings

versal-libmetal-overlay.yaml

R5 bare-metal libmetal configuration

The domain-access and VPK360 Linux overlays are in meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/domainyaml/. The other files are in meta-xilinx/meta-xilinx-standalone-sdt/conf/domainyaml/.

For custom VPK360 hardware, the template supplies this composition:

$ gen-machine-conf parse-sdt \
    --template ../sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2vp-vpk360-multidomain.yaml \
    --hw-description <path-to-sdt-handoff-dir> \
    --machine-name <custom-machine-name> \
    -c <path-to-layer>/conf

To add custom domain changes, append your overlay to that command:

$ gen-machine-conf parse-sdt \
    --template ../sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2vp-vpk360-multidomain.yaml \
    --hw-description <path-to-sdt-handoff-dir> \
    --machine-name <custom-machine-name> \
    -c <path-to-layer>/conf \
    --domain-file <path-to-custom-domain-overlay.yaml>

Repeat --domain-file for each additional overlay. These files append to the template’s domain list; do not repeat the six inherited files. Review the generated machine and domain device trees against your SDT.

Zynq UltraScale+ MPSoC (Cortex-A53 + Cortex-R5)

Processors: 4-core Cortex-A53 (APU) + 2-core Cortex-R5 (RPU)

RTOS: Zephyr on R5 core 0, bare-metal on R5 core 1

File

Description

zynqmp-linux-only-base.yaml

Single domain: APU_Linux (A53, cpumask 0xf, secure, EL3)

zynqmp-multidomain-base.yaml

3 domains: APU_Linux (A53, cpumask 0xf, secure, EL3), R5_0_ZEPHYR (R5 core 0, cpumask 0x1), R5_1_BAREMETAL (R5 core 1, cpumask 0x1 in cluster cpus_r5_1, EL3)

zynqmp-openamp-overlay.yaml

OpenAMP remoteproc for R5_0_ZEPHYR: firmware (128 KiB), resource table (256 B), trace (4 KiB), vrings (16 KiB x 2), and buffer (480 KiB). Uses IPI_7 <-> IPI_1. Includes ATCM/BTCM (64 KiB each) and Zephyr linker configuration

zynqmp-libmetal-overlay.yaml

Libmetal IPC for R5_1_BAREMETAL: ELF + descriptors + data through UIO. Uses IPI_8 <-> IPI_2, timer: ttc2

Zynq-7000 (Cortex-A9)

Processors: 2-core Cortex-A9 (APU only)

Single-domain only – no multidomain or communication overlays available.

File

Description

zynq-linux-only-base.yaml

APU_Linux (A9, cpumask 0x3, secure, EL3). The board configuration supplies boot settings

Communication Overlays

OpenAMP Overlay

Enables Linux to load and communicate with an RTOS running on the RPU using remoteproc (firmware loading) and RPMsg (Remote Processor Messaging).

Memory regions allocated:

Region

Size

Purpose

rproc0 (Versal / ZynqMP)

128 KiB

DDR region available to RPU firmware; the Zephyr linker also assigns sections to TCM

ddrboot (2VE-2VM / NET)

375.5 KiB

DDR boot code and data

trace

4 KiB

Zephyr RAM console

rsctbl (all four OpenAMP platform configurations)

256 B

OpenAMP resource table describing communication resources

vdev0vring0

16 KiB

Virtio ring descriptor (host to remote)

vdev0vring1

16 KiB

Virtio ring descriptor (remote to host)

vdev0buffer

480 KiB

Shared data buffer for RPMsg payloads

Key differences by platform:

  • Versal / ZynqMP: Uses rproc0 region + TCM SRAM for firmware loading

  • Versal Gen 2 (2VE-2VM / NET): Uses ddrboot + rsctbl regions with DDR boot support (xlnx,ddr-boot: true), Zephyr console configuration

Libmetal Overlay

Enables low-level shared-memory Inter-Processor Communication (IPC) between Linux and a bare-metal application on the second RPU core through UIO devices. The top-level axi section defines the libmetal UIO regions.

Memory regions allocated:

Region

Size

Purpose

libmetal_elf

384 KiB

bare-metal ELF code and data

libmetal_desc0

16 KiB

Shared descriptor (direction 0)

libmetal_desc1

16 KiB

Shared descriptor (direction 1)

libmetal_data

256 KiB

Shared data buffer

UIO devices exposed to Linux userspace:

  • Memory-mapped descriptors and data buffers

  • Timer peripheral (for synchronization)

  • Mailbox / IPI peripheral (for notifications)

Creating Custom Domain Configuration Files

Step 1: Choose Base File

Select the base file that matches your platform and configuration type. See Platform Families for the complete list of available base files and their descriptions.

Step 2: Create Board Overlay

Define board-specific memory reservations and boot configuration. Every domain entry must include compatible: openamp,domain-v1. The overlay must also reference the same domain name used in the base file (APU_Linux):

# my-board-linux-overlay.yaml
reserved-memory:
  ranges: true
  "#size-cells": 2
  "#address-cells": 2

  cma_reserved@800000000:
    label: cma_reserved
    start: 0x800000000
    size: 0x80000000          # 2 GiB
    compatible: shared-dma-pool
    reusable: true
    linux,cma-default: true

domains:
  APU_Linux:
    compatible: openamp,domain-v1
    reserved-memory:
      - cma_reserved@800000000
    chosen:
      bootargs: "console=ttyAMA0,115200n8 earlycon"
      stdout-path: "serial0:115200n8"

Common overlay patterns:

  • CMA only: Allocate contiguous memory for DMA/accelerators

  • CMA + firmware reserved: Add no-map regions for PLM, TF-A, or RPU firmware

  • CMA + isolated channels: Reserve entire DDR controllers (no-map) for deterministic access

  • Boot args only: Configure console without memory changes

Step 3: Reference in Machine Configuration

Add your domain YAML files to the --domain-file argument in your machine YAML file. This tells gen-machine-conf which domain files to compose when generating the machine configuration:

inherit:
    ${BSPLAYERDIR}/conf/machineyaml/my-board-sdt-seg.yaml

args:
    - --machine-name my-board-multidomain
    - --domain-file \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-multidomain-base.yaml \
       ${BSPLAYERDIR}/conf/domainyaml/my-board-linux-overlay.yaml \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-openamp-zephyr-common-overlay.yaml \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-openamp-zephyr-cips-overlay.yaml \
       ${LAYER_PATH_xilinx-standalone-sdt}/conf/domainyaml/versal-libmetal-overlay.yaml

Domain Naming Rules

Caution

Domain names are the merge key when composing multiple YAML files. All files contributing to the same domain must use an identical name.

Standard domain names:

Domain Name

Processor

Platform

APU_Linux

Cortex-A72/A78/A53/A9

All platforms

RPU_Zephyr

Cortex-R52 (core 0)

Versal Gen 2

RPU_1_BM

Cortex-R52 (core 1)

Versal Gen 2

R5_0_ZEPHYR

Cortex-R5 (core 0)

Versal, ZynqMP

R5_1_BAREMETAL

Cortex-R5 (core 1)

Versal, ZynqMP

Example – correct merge:

# Base file excerpt
domains:
  APU_Linux:
    compatible: openamp,domain-v1
    os,type: linux
    cpus: ...
# Separate overlay file excerpt
domains:
  APU_Linux:                  # <- same name = merged
    compatible: openamp,domain-v1
    reserved-memory: ...

Example – incorrect (creates conflicting domain):

# overlay uses wrong name
domains:
  Linux_Domain:               # <- different name
    compatible: openamp,domain-v1
    reserved-memory: ...

Using a different domain name in the overlay creates a separate domain instead of merging into APU_Linux, which is almost never what you want.

Field Reference

Domain Fields

Field

Required

Description

domains.<name>

Yes

Domain identifier – merge key across composed files

compatible

Yes

Mandatory. Must be openamp,domain-v1 in every domain entry (base and overlays)

cpus

Yes (base)

CPU configuration (cluster, mask, mode)

os,type

Yes (base)

linux | zephyr | freertos | baremetal

memory

No

DDR memory ranges assigned to this domain

access

No

Device selections for this domain; supports shared devices and wildcard or regular-expression matches

chosen

No

Boot args and console (typically in overlay)

reserved-memory

No

CMA, firmware, IPC memory regions

domain-to-domain

No

Inter-domain communication config

sram

No

TCM/SRAM regions for RPU domains

xlnx,ddr-boot

No

Enable DDR boot for Zephyr (2VE-2VM/NET only)

Processor Fields

Field

Required

Description

cluster

Yes

CPU cluster: cpus_a78, cpus_a72, cpus_a53, cpus_a9, cpus_r52_0, cpus_r52_1, cpus_r5_0, cpus_r5_1

cpumask

Yes

Core bitmask within the selected cluster: 0xff (8), 0xf (4), 0x3 (2), 0x1 (1)

mode.secure

Yes

Security mode: true or false

mode.el

No

Exception level: 0x3 (EL3), 0x2 (EL2), 0x1 (EL1)

cluster_cpu

No

Specific CPU node (for example, psv_cortexr5_0, psu_cortexr5_0, cortexr52_0)

Reserved Memory Fields

Field

Required

Description

label

Yes

Unique identifier for the memory region

start

Yes

Physical start address (hex)

size

Yes

Region size, as a byte count (0x4000) or with a size suffix (64K, 16M, 1G)

compatible / reusable

Yes (CMA pools)

Use compatible: shared-dma-pool and reusable: true for reusable CMA reservations

no-map

No

1 = excluded from Linux memory map (isolated for RPU/firmware)

linux,cma-default

No

true = default CMA pool for Linux DMA allocations

Domain-To-Domain Fields

Field

Required

Description

compatible

Yes

openamp,domain-to-domain-v1

elfload

Yes (remoteproc / libmetal relations)

Firmware load regions in the relation entry

remoteproc-relation

No

Firmware loading config (openamp,remoteproc-v2): remote domain, elfload regions

rpmsg-relation

No

Message passing config (openamp,rpmsg-v1): remote/host, carveouts, mailbox, timers

libmetal-relation

No

Shared memory IPC (libmetal,ipc-v1): remote/host, carveouts, mailbox, timer, elfload

mbox

Yes (RPMsg / libmetal relations)

IPI mailbox channel name (for example, ipi_3_to_ipi_1)

timer

No

Timer peripherals for synchronization (for example, ttc0, ttc2)

carveouts

Yes (RPMsg / libmetal relations)

List of shared memory regions (vrings, buffers, descriptors)

Note

To find the exact domain YAML files used by any machine, check the --domain-file arguments passed to gen-machine-conf in its machine YAML file under conf/machineyaml/.

Validation and Troubleshooting

Common issues when working with domain YAML files:

Symptom

Cause and Fix

Domain not merged (separate domain created)

Domain name in overlay does not match the base file. Make sure all files use the same name (for example, APU_Linux).

compatible field missing error

Every domain entry must include compatible: openamp,domain-v1 – both in the base file and in overlays.

Memory region overlap

Two regions have overlapping start + size ranges. Check all base and overlay files for address conflicts.

gen-machine-conf fails with unknown option

Verify you are using a version of gen-machine-conf that supports --domain-file. See the gen-machine-conf options reference.

RPU firmware not loading

Check that the OpenAMP overlay’s rproc0 or ddrboot region size is large enough for your firmware ELF and that IPI mailbox names match your platform.