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 that only this domain can use
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:

System Device Tree (SDT) – describes the hardware
Domain YAML files – describe how to partition the hardware across software domains (this page)
gen-machine-conf – reads the SDT + domain YAML files and generates Yocto machine configurations
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.

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 \
              <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 \
              <board>-linux-overlay.yaml \
              <platform>-openamp-overlay.yaml \
              <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: 8-core Cortex-A78 (APU) + Cortex-R52 (RPU)

RTOS: Zephyr on RPU

2VE-2VM variant:

File	Description
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 0x2, EL3)
versal-2ve-2vm-openamp-overlay.yaml	OpenAMP with DDR boot support: resource table (256 B) + DDR boot code (384 KB) + vrings (16 KB x 2) + shared buffer (256 KB). Uses IPI_1 <-> IPI_2 mailbox. RPU SRAM: R52 ATCM (64 KB) + BTCM (32 KB) + CTCM (32 KB)
versal-2ve-2vm-libmetal-overlay.yaml	Libmetal IPC for RPU_1_BM: ELF region (384 KB) + descriptors (16 KB x 2) + data (256 KB) 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-multidomain-base.yaml	3 domains: APU_Linux (A78, cpumask 0xff, non-secure, EL3), RPU_Zephyr (R52 core 0), RPU_1_BM (R52 core 1)
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: 4-core Cortex-A72 (APU) + 2-core Cortex-R5 (RPU)

RTOS: FreeRTOS 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, secure, EL3), R5_0_FREERTOS (R5 core 0, cpumask 0x1), R5_1_BAREMETAL (R5 core 1, cpumask 0x2, EL3)
versal-openamp-overlay.yaml	OpenAMP remoteproc for R5_0_FREERTOS: firmware region (384 KB) + vrings (16 KB x 2) + shared buffer (1 MB). Uses IPI_3 <-> IPI_1 mailbox, timers: TTC0/TTC1/TTC3. RPU SRAM: psv_r5_0 ATCM (64 KB) + BTCM
versal-libmetal-overlay.yaml	Libmetal IPC for R5_1_BAREMETAL: ELF (384 KB) + descriptors (16 KB x 2) + data (256 KB) through UIO. Uses IPI_5 <-> IPI_2 mailbox, timer: ttc2. RPU SRAM: psv_r5_1 ATCM (64 KB)

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

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

RTOS: FreeRTOS on R5 core 0

File	Description
`zynqmp-linux-only-base.yaml`	Single domain: APU_Linux (A53, cpumask 0xf, secure, EL3)
`zynqmp-multidomain-base.yaml`	2 domains: APU_Linux (A53, secure, EL3), R5_0_FREERTOS (R5 core 0, cpumask 0x1, cluster_cpu: psu_cortexr5_0)
zynqmp-openamp-overlay.yaml	OpenAMP remoteproc for R5_0_FREERTOS: firmware (384 KB) + vrings (16 KB x 2) + buffer (1 MB). Uses IPI_7 <-> IPI_1, timers: TTC0/TTC1/TTC3. SRAM: psu_r5_0 ATCM (64 KB)
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). Bootargs: earlycon, stdout: serial0:115200n8

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 / ddrboot	384 KB	ELF firmware code and data for RPU
rsctbl (2VE-2VM only)	256 B	Resource table for DDR boot
vdev0vring0	16 KB	Virtio ring descriptor (host to remote)
vdev0vring1	16 KB	Virtio ring descriptor (remote to host)
vdev0buffer	256 KB - 1 MB	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.

Memory regions allocated:

Region	Size	Purpose
libmetal_elf	384 KB	bare-metal ELF code and data
libmetal_desc0	16 KB	Shared descriptor (direction 0)
libmetal_desc1	16 KB	Shared descriptor (direction 1)
libmetal_data	256 KB	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 GB
    linux,cma-default: 1

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-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_FREERTOS`	Cortex-R5 (core 0)	Versal, ZynqMP
`R5_1_BAREMETAL`	Cortex-R5 (core 1)	Versal, ZynqMP

Example – correct merge:

# base file defines the domain
domains:
  APU_Linux:
    os,type: linux
    cpus: ...

# overlay adds to the SAME domain
domains:
  APU_Linux:                  # <- same name = merged
    reserved-memory: ...

Example – incorrect (creates conflicting domain):

# overlay uses wrong name
domains:
  Linux_Domain:               # <- different name
    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	Devices exclusively assigned to this domain
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`, `cpus_r5_0`, `cpus_r5_1`
cpumask	Yes	Core bitmask: `0xff` (8), `0xf` (4), `0x3` (2), `0x1` (1)
mode.secure	Yes	Security mode: `true` or `false`
mode.el	Yes	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 in bytes (hex)
no-map	No	`1` = excluded from Linux memory map (isolated for RPU/firmware)
linux,cma-default	No	`1` = default CMA pool for Linux DMA allocations

Domain-To-Domain Fields

Field	Required	Description
compatible	Yes	`openamp,domain-to-domain-v1`
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 (in relation)	IPI mailbox channel name (for example, `ipi_3_to_ipi_1`)
timer	No	Timer peripherals for synchronization (for example, `ttc0`, `ttc2`)
carveouts	Yes (in relation)	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.