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:
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-confinstalled or available in your build environment (see the gen-machine-conf repository)meta-xilinxlayers set up (meta-xilinx-standalone-sdtprovides 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 |
|
Shared processor and domain definitions |
Board overlays |
Each BSP layer’s |
Board-specific memory layouts and boot config |
Communication overlays |
|
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 |
|---|---|
|
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 |
|---|---|
|
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 |
|---|---|
|
Single domain: APU_Linux (A72, cpumask 0xf, secure, EL3) |
|
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) |
|
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 |
|
CIPS-specific local TCM names, SRAM assignments, and Zephyr linker sections. Use with the common overlay |
|
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) |
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 |
|---|---|
|
Single domain: APU_Linux (A53, cpumask 0xf, secure, EL3) |
|
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 |
|---|---|
|
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:
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:
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 |
|---|---|---|
|
Cortex-A72/A78/A53/A9 |
All platforms |
|
Cortex-R52 (core 0) |
Versal Gen 2 |
|
Cortex-R52 (core 1) |
Versal Gen 2 |
|
Cortex-R5 (core 0) |
Versal, ZynqMP |
|
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 |
cpus |
Yes (base) |
CPU configuration (cluster, mask, mode) |
os,type |
Yes (base) |
|
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 |
|
|
No |
Enable DDR boot for Zephyr (2VE-2VM/NET only) |
Processor Fields
Field |
Required |
Description |
|---|---|---|
cluster |
Yes |
CPU cluster: |
cpumask |
Yes |
Core bitmask within the selected cluster: |
mode.secure |
Yes |
Security mode: |
mode.el |
No |
|
cluster_cpu |
No |
Specific CPU node (for example, |
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 ( |
compatible / reusable |
Yes (CMA pools) |
Use |
no-map |
No |
|
linux,cma-default |
No |
|
Domain-To-Domain Fields
Field |
Required |
Description |
|---|---|---|
compatible |
Yes |
|
elfload |
Yes (remoteproc / libmetal relations) |
Firmware load regions in the relation entry |
remoteproc-relation |
No |
Firmware loading config
( |
rpmsg-relation |
No |
Message passing config ( |
libmetal-relation |
No |
Shared memory IPC ( |
mbox |
Yes (RPMsg / libmetal relations) |
IPI mailbox channel name
(for example, |
timer |
No |
Timer peripherals for synchronization
(for example, |
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,
|
|
Every domain entry must include
|
Memory region overlap |
Two regions have overlapping |
|
Verify you are using a version of |
RPU firmware not loading |
Check that the OpenAMP overlay’s |