Booting Xen With U-Boot Distro Boot
Overview
On boards that support it, EDF boots through UEFI by default,
and the EDF Xen systemd-boot menu entry starts the Xen hypervisor.
When a platform uses the U-Boot distro boot flow, that menu is not
available. Instead, U-Boot loads Xen from a boot script, xen_boot.scr,
which the u-boot-xen-scr recipe in meta-xilinx-virtualization generates
at build time with the Yocto-integrated Image Builder tool.
BitBake fetches and builds image-builder-native from the revision
pinned by SRCREV in the release’s image-builder recipe.
The following procedure applies to ZynqMP, Versal, Versal Gen 2, and Versal Premium Series Gen 2 platforms and supports two configurations:
Dom0 (default): Xen boots a single privileged Linux domain, Dom0.
Dom0-less: Xen boots Dom0 and also starts one or more guest domains (DomU) directly at boot, without Dom0 creating them.
This procedure covers the boards listed in Supported Platforms. Kria ZynqMP boards are outside the scope of this guide.
Select your board in the documentation’s board selector for its boot commands. VEK280 uses the Versal templates and SD commands. VEK385 and VEK386 use the Versal Gen 2 templates and UFS commands by default.
Prerequisites
Complete the U-Boot distro boot flow in Configuring EDF for U-Boot Distro Boot through Step 7, so that the board boots native Linux from
boot.scr. Xen boot reuses the same workspace,build/conf/local.confchange, boot firmware, and disk image layout.Build
edf-platform-disk-image, notedf-linux-disk-image. Theamd-edfdistro enables thexendistro feature, but the platform image, not the Linux image, installspackagegroup-xen, which provides the Xen hypervisor under/bootand thexltool in Dom0.Build the board firmware, platform disk image, and guests from the same release checkout. Before combining downloaded artifacts with local builds, check that their release versions match. Replace or rebuild any artifacts from a different release.
The Xen boot script README describes the templates and partition layout.
The Image Builder target-path documentation defines the target:
prefix used in those templates.
The default EDF bblayers.conf already includes
meta-xilinx-virtualization, so no layer changes are needed.
For the VEK280 multidomain configuration, use
versal-vek280-multidomain as <board-machine> and
amd-cortexa72-common as <machine> in the prerequisite flow.
Build edf-ospi for the board’s OSPI firmware and use the
SD disk image for Dom0. The Linux guest RAM disk also uses
amd-cortexa72-common as <common-machine> in Step 4.
Supported Platforms
SoC family |
Boards |
Common machine |
Default boot medium |
Script load address |
|---|---|---|---|---|
ZynqMP |
ZCU102, ZCU104, ZCU106, ZCU111, ZCU208, ZCU216 |
|
SD ( |
|
Versal |
VEK280, VCK190, VHK158, VPK120, VPK180, VMK180, VRK160, VRK165 (including VRK160/VRK165 revB) |
|
SD ( |
|
Versal Gen 2 |
VEK385, VEK386, VMK365 |
|
UFS ( |
|
Versal Premium Series Gen 2 |
VPK360 |
|
SD ( |
|
For Versal Gen 2, build the platform disk image with
amd-cortexa78-mali-common. The amd-cortexa78-common machine uses the
versal-net SoC override, which u-boot-xen-scr does not support. Use
that machine only for the Linux guest RAM disk in Step 4.
Step 1 — Add the Xen Boot Script to the Image
Add the following line to the end of build/conf/local.conf, after the
efi removal from the distro boot flow:
IMAGE_INSTALL:append:pn-edf-platform-disk-image = " u-boot-xen-scr"
The recipe override adds the script only to edf-platform-disk-image.
It keeps u-boot-xen-scr out of the core-image-minimal guest build,
including the Versal Gen 2 guest built for amd-cortexa78-common.
The u-boot-xen-scr recipe runs the image-builder uboot-script-gen
script against a configuration file, installs the resulting xen_boot.scr
into /boot on the root filesystem, and deploys a copy to
tmp/deploy/images/<machine>/.
Step 2 — Choose an Image-Builder Configuration
The recipe ships a Dom0 and a Dom0-less template configuration for each SoC
family in
sources/meta-xilinx/meta-xilinx-virtualization/recipes-bsp/u-boot/u-boot-xen-scr/.
The templates match the EDF platform disk image layout: Xen, the kernel
Image, and xen_boot.scr are all loaded from /boot on partition 3,
the root filesystem.
SoC family |
Dom0 template (default) |
Dom0-less template |
|---|---|---|
ZynqMP |
|
|
Versal |
|
|
Versal Gen 2 |
|
|
Versal Premium Series Gen 2 |
|
|
Versal Premium Series Gen 2 shares the Versal templates, but U-Boot loads
xen_boot.scr at a different address, as listed in Supported Platforms.
The recipe uses the Dom0 template for your SoC family by default. To select a
different configuration, set XEN_TEMPLATE_CONFIG in
build/conf/local.conf. For a Dom0-less configuration, use the setting for
your board:
ZynqMP:
XEN_TEMPLATE_CONFIG = "zynqmp-xen-scr-dom0less-template-cfg"
Versal and Versal Premium Series Gen 2:
XEN_TEMPLATE_CONFIG = "versal-xen-scr-dom0less-template-cfg"
Versal Gen 2:
XEN_TEMPLATE_CONFIG = "versal-2ve-2vm-xen-scr-dom0less-template-cfg"
The setting applies to every machine built in the workspace, so name a configuration that matches the SoC family of the machine you are building.
The templates use paths such as target:/boot/xen and
target:/boot/Image. As described in the
Image Builder target-path documentation, target: identifies a file
on the target storage and skips build-host validation. It does not copy
that file into the disk image. The image recipes install Xen and the
kernel; copy the Linux guest RAM disk as described in Step 4.
Each template sets the following Image Builder variables. See the
Image Builder README for the full list. The Image Builder links in this
page use the source revision pinned by the release’s
image-builder recipe.
Variable |
Purpose |
|---|---|
|
DDR window that image-builder places the binaries in. The
templates use |
|
Paths of the Xen hypervisor ( |
|
Xen command line. The templates set |
|
Dom0 kernel command line, including |
|
Number and settings of the guest domains that Xen starts at boot.
|
|
U-Boot command that loads the binaries: |
|
Output file names. The recipe expects |
Note
The boot medium is fixed in xen_boot.scr at build time. The ZynqMP,
Versal, and Versal Premium Series Gen 2 templates load from SD
through mmc, and the Versal Gen 2 templates load from UFS
through scsi. If the disk image is on a different medium, adjust the
template in a custom configuration before you build, as described in the
following step. Change the interface in LOAD_CMD to mmc, scsi, or
usb, and set root= in DOM0_CMD to the device that Linux sees.
Change the interface in bootcmd_xen in Step 5 in the same way.
The interface depends on how the board connects the medium, not on the SoC
family. For example, VMK365 wires its SD card slot to an SD host
controller in the SoC, so an SD card uses mmc and /dev/mmcblk0p3.
VEK385 and VEK386 have no SD host controller enabled. Their microSD slot
sits behind a USB SD card reader on the onboard USB hub. U-Boot and
Linux see the SD card as a USB mass storage device, so it uses usb and
appears as /dev/sda3, the same as UFS.
The Dom0-less templates start one DomU that boots the kernel Image with a
core-image-minimal RAM disk loaded from /root on the root filesystem.
DOMU_RAMDISK[0] fixes the file name for each SoC family. The name uses the
common machine without -mali, even when you build the disk image for the
-mali variant:
SoC family |
RAM disk file in |
|---|---|
ZynqMP |
|
Versal |
|
Versal Gen 2 |
|
Versal Premium Series Gen 2 |
|
The RAM disk is not part of edf-platform-disk-image. Step 4 shows how to
build it and copy it into the disk image.
Step 3 — Use a Custom Configuration (Optional)
To boot with a shipped template unchanged, skip to Step 4.
To change any of the template values, create a custom image-builder
configuration next to the shipped templates and select it with
XEN_TEMPLATE_CONFIG. The shipped templates stay unchanged.
Copy the template that matches your SoC family and configuration to a new file, for example
custom-cfg. The following example starts from the Versal Gen 2 Dom0 template:$ cp sources/meta-xilinx/meta-xilinx-virtualization/recipes-bsp/u-boot/u-boot-xen-scr/versal-2ve-2vm-xen-scr-dom0-template-cfg \ sources/meta-xilinx/meta-xilinx-virtualization/recipes-bsp/u-boot/u-boot-xen-scr/custom-cfg
Edit
custom-cfgand change the image-builder variables that you need, for exampleLOAD_CMDandroot=inDOM0_CMDfor a different boot medium.Select the custom configuration in
build/conf/local.conf:XEN_TEMPLATE_CONFIG = "custom-cfg"
Note
custom-cfg lives in the meta-xilinx layer checkout, which a fresh
workspace or a layer update does not preserve. Keep a copy of your
configuration outside sources/.
Step 4 — Build and Flash the Image
Build the disk image for the common machine, as in Step 3 of the distro boot flow:
$ MACHINE=<machine> bitbake edf-platform-disk-image
Where <machine> is the common machine for your board, as listed in
Supported Platforms, for example amd-cortexa53-mali-common for ZCU102.
Confirm that the build generated the Xen boot script:
$ ls tmp/deploy/images/<machine>/xen_boot.scr
For a Linux DomU, started from Dom0 or at boot with the Dom0-less
configuration, also build the guest RAM disk. EDF already
adds cpio.gz to IMAGE_FSTYPES for core-image-minimal. Build it for
the common machine named in the RAM disk file:
$ MACHINE=<common-machine> bitbake core-image-minimal
Where <common-machine> is the common machine without -mali:
amd-cortexa53-common (ZynqMP), amd-cortexa72-common (Versal and Versal
Premium Series Gen 2), or amd-cortexa78-common (Versal Gen 2). For ZCU102,
<machine> is amd-cortexa53-mali-common and <common-machine> is
amd-cortexa53-common.
If you build the RAM disk for the -mali variant of the common machine, the
file name includes -mali and no longer matches DOMU_RAMDISK[0]. Update
DOMU_RAMDISK[0] in a custom configuration as described in Step 3.
Copy the RAM disk into /root on partition 3 of the .wic image with the
wic tool, and confirm that it is there. The Yocto Project build environment
does not put wic on PATH, so use the wic tool from the EDF
SDK. Install the SDK and source its environment setup script
as described in SDK Installation, in a separate shell from
the one that runs bitbake. The following example runs from the build
directory, for a ZCU102 that uses the amd-cortexa53-mali-common disk image:
$ oe-run-native wic-native wic cp tmp/deploy/images/amd-cortexa53-common/core-image-minimal-amd-cortexa53-common.rootfs.cpio.gz \
tmp/deploy/images/amd-cortexa53-mali-common/edf-platform-disk-image-amd-cortexa53-mali-common.rootfs.wic:3/root
$ oe-run-native wic-native wic ls tmp/deploy/images/amd-cortexa53-mali-common/edf-platform-disk-image-amd-cortexa53-mali-common.rootfs.wic:3/root
debugfs 1.47.4 (6-Mar-2025)
783 40700 (2) 0 0 4096 20-Oct-2026 17:44 .
2 40755 (2) 0 0 4096 20-Oct-2026 17:45 ..
784 100644 (1) 0 0 64925240 5-Apr-2011 23:00 core-image-minimal-amd-cortexa53-common.rootfs.cpio.gz
258822 40700 (2) 0 0 4096 20-Oct-2026 17:44 .ssh
Confirm that the listing contains the archive. Repeat the copy after rebuilding the platform disk image, because the build replaces the image.
Copy the RAM disk into the image file that you flash or boot. For example, use
the .rootfs.wic.ufs file for UFS on Versal Gen 2, or the
.rootfs.wic.qemu-sd file for QEMU.
Check that partition 3 also contains the Xen boot artifacts:
$ oe-run-native wic-native wic ls tmp/deploy/images/<machine>/edf-platform-disk-image-<machine>.rootfs.wic:3/boot
The listing must contain xen, Image, and xen_boot.scr. Use the
image suffix for your boot medium, as with the RAM disk copy.
Then inject boot.bin for single-stage booting, if applicable, and flash
the modified .wic image as described in Steps 4 and 5 of the distro boot
flow. A previously compressed .wic.xz does not contain the changes.
Step 5 — Boot Xen From U-Boot
Power on the board and press any key during the U-Boot autoboot countdown to stop at the U-Boot prompt. If you do not stop U-Boot, distro boot runs
boot.scrand boots native Linux.Optionally, confirm that
xen_boot.scrand the Xen binaries are present in/booton partition 3. Useext4lswith the interface for your boot medium, as listed in Supported Platforms.For a Versal board that boots from SD:
Versal> mmc dev 0; mmc part; ext4ls mmc 0:3 /boot switch to partitions #0, OK mmc0 is current device Partition Map for mmc device 0 -- Partition Type: DOS Part Start Sector Num Sectors UUID Type 1 8 2097152 076c4a2a-01 0c Boot 2 2097160 4194304 076c4a2a-02 0c 3 6291464 7870604 076c4a2a-03 83 ./ ../ <SYM> Image 31750656 Image-6.18.40-xilinx-g59d213656d69 <SYM> xen <SYM> xen-4 <SYM> xen-4.21 1179680 xen-4.21.0 5127 xen-4.21.0.config 1509 xen_boot.scr 61752 zephyr-synchronization-xenvmgicv3.bin 9 file(s), 2 dir(s)
Load and run
xen_boot.scrwith the command for your SoC family. The script loads Xen, the Dom0 kernel, and any DomU images, and then starts Xen.ZynqMP, booting from SD:
ZynqMP> setenv bootcmd_xen 'mmc dev 0 && ext4load mmc 0:3 0xC00000 /boot/xen_boot.scr && source 0xC00000' ZynqMP> printenv bootcmd_xen ZynqMP> run bootcmd_xen
Versal, booting from SD:
Versal> setenv bootcmd_xen 'mmc dev 0 && ext4load mmc 0:3 0xC00000 /boot/xen_boot.scr && source 0xC00000' Versal> printenv bootcmd_xen Versal> run bootcmd_xen
Versal Premium Series Gen 2, booting from SD:
versalpremium2> setenv bootcmd_xen 'mmc dev 0 && ext4load mmc 0:3 0x20200000 /boot/xen_boot.scr && source 0x20200000' versalpremium2> printenv bootcmd_xen versalpremium2> run bootcmd_xen
Versal Gen 2, booting from UFS:
versal2> setenv bootcmd_xen 'scsi dev 0 && ext4load scsi 0:3 0x20200000 /boot/xen_boot.scr && source 0x20200000' versal2> printenv bootcmd_xen versal2> run bootcmd_xen
VMK365, with the disk image on an SD card:
versal2> setenv bootcmd_xen 'mmc dev 0 && ext4load mmc 0:3 0x20200000 /boot/xen_boot.scr && source 0x20200000' versal2> printenv bootcmd_xen versal2> run bootcmd_xen
versal2> setenv bootcmd_xen 'usb dev 0 && ext4load usb 0:3 0x20200000 /boot/xen_boot.scr && source 0x20200000' versal2> printenv bootcmd_xen versal2> run bootcmd_xen
The interface, device, and partition in
bootcmd_xenmust match the boot medium. If you changedLOAD_CMDin a custom configuration, changebootcmd_xenin the same way.
Step 6 — Verify Xen
After Dom0 boots, log in on the console and check that Xen is running:
amd-edf:~$ sudo xl list
amd-edf:~$ sudo xl info
xl list shows Domain-0 in the running state. xl info reports the
Xen version and the xen_commandline that XEN_CMD set.
Check the Dom0-less Guest
With a Dom0-less configuration, check the serial log for Xen starting the
guest and confirm that xl list includes it. The supplied templates
start one Linux DomU with 800 MiB of memory and one virtual CPU. The guest
may appear with the name (null). Do not use xl create to validate
this configuration: the guest must start as part of Xen boot.
Run Guests from Dom0
Use the Dom0 template when creating guests from Dom0 with xl.
Run the Packaged Zephyr Guest
Follow Run a Zephyr Guest with Dom0 already running. Those shared instructions cover the packaged configuration, guest creation, console attachment, and shutdown.
To build a custom Zephyr RTOS DomU image, see Build and Deploy Zephyr RTOS DomU Guest OS Image.
Run a Linux Guest
Build and copy the Linux RAM disk as described in
Step 4 — Build and Flash the Image. In Dom0, save the following configuration as
/root/linux-domu.cfg, replacing <common-machine> with the machine
used to build the RAM disk:
name = "linux-domu"
kernel = "/boot/Image"
ramdisk = "/root/core-image-minimal-<common-machine>.rootfs.cpio.gz"
memory = 800
vcpus = 1
extra = "console=hvc0 init=/bin/sh root=/dev/ram0"
The guest command line matches DOMU_CMD[0] in the shipped Dom0-less
templates, which use the same kernel and RAM disk.
For example, VEK280 uses amd-cortexa72-common. Confirm that the RAM disk
path matches the file copied into the disk image. Start the guest and
attach to its console:
amd-edf:~$ sudo xl create /root/linux-domu.cfg
amd-edf:~$ sudo xl list
amd-edf:~$ sudo xl console linux-domu
The guest boots to a Linux shell. Press Ctrl+] to return to Dom0.
Confirm that xl list reports 800 MiB of memory and one virtual CPU for
linux-domu.
Troubleshooting
Symptom |
Cause and fix |
|---|---|
|
|
|
The interface, device, or partition in |
Board boots native Linux instead of Xen |
U-Boot was not stopped, so distro boot ran |
Dom0 kernel cannot mount its root filesystem |
|
Dom0-less boot cannot load the DomU RAM disk |
The RAM disk is missing from |