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

  1. 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.conf change, boot firmware, and disk image layout.

  2. Build edf-platform-disk-image, not edf-linux-disk-image. The amd-edf distro enables the xen distro feature, but the platform image, not the Linux image, installs packagegroup-xen, which provides the Xen hypervisor under /boot and the xl tool in Dom0.

  3. 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

amd-cortexa53-common, amd-cortexa53-mali-common

SD (mmc)

0xC00000

Versal

VEK280, VCK190, VHK158, VPK120, VPK180, VMK180, VRK160, VRK165 (including VRK160/VRK165 revB)

amd-cortexa72-common

SD (mmc)

0xC00000

Versal Gen 2

VEK385, VEK386, VMK365

amd-cortexa78-mali-common

UFS (scsi)

0x20200000

Versal Premium Series Gen 2

VPK360

amd-cortexa72-common

SD (mmc)

0x20200000

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

zynqmp-xen-scr-dom0-template-cfg

zynqmp-xen-scr-dom0less-template-cfg

Versal

versal-xen-scr-dom0-template-cfg

versal-xen-scr-dom0less-template-cfg

Versal Gen 2

versal-2ve-2vm-xen-scr-dom0-template-cfg

versal-2ve-2vm-xen-scr-dom0less-template-cfg

Versal Premium Series Gen 2

versal-xen-scr-dom0-template-cfg

versal-xen-scr-dom0less-template-cfg

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

MEMORY_START, MEMORY_END

DDR window that image-builder places the binaries in. The templates use 0x20000000 to 0x70000000.

XEN, DOM0_KERNEL

Paths of the Xen hypervisor (/boot/xen) and the Dom0 kernel (/boot/Image) on the root filesystem.

XEN_CMD

Xen command line. The templates set dom0_mem=1500M and a dom0_max_vcpus value per SoC family.

DOM0_CMD

Dom0 kernel command line, including root=: /dev/mmcblk0p3 for SD, or /dev/sda3 for USB and UFS.

NUM_DOMUS, DOMU_*

Number and settings of the guest domains that Xen starts at boot. NUM_DOMUS is 0 in the Dom0 templates and 1 in the Dom0-less templates.

LOAD_CMD

U-Boot command that loads the binaries: ext4load mmc 0:3 for SD, ext4load usb 0:3 for USB, or ext4load scsi 0:3 for UFS.

UBOOT_SOURCE, UBOOT_SCRIPT

Output file names. The recipe expects xen_boot.scr, so do not change these values.

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 /root

ZynqMP

core-image-minimal-amd-cortexa53-common.rootfs.cpio.gz

Versal

core-image-minimal-amd-cortexa72-common.rootfs.cpio.gz

Versal Gen 2

core-image-minimal-amd-cortexa78-common.rootfs.cpio.gz

Versal Premium Series Gen 2

core-image-minimal-amd-cortexa72-common.rootfs.cpio.gz

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.

  1. 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
    
  2. Edit custom-cfg and change the image-builder variables that you need, for example LOAD_CMD and root= in DOM0_CMD for a different boot medium.

  3. 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

  1. 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.scr and boots native Linux.

  2. Optionally, confirm that xen_boot.scr and the Xen binaries are present in /boot on partition 3. Use ext4ls with 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)
    
  3. Load and run xen_boot.scr with 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
    

    VEK385 revA, with the disk image on an SD card connected through the onboard USB card reader:

    VEK385 revB, with the disk image on an SD card connected through the onboard USB card reader:

    VEK386, with the disk image on an SD card connected through the onboard USB card reader:

    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_xen must match the boot medium. If you changed LOAD_CMD in a custom configuration, change bootcmd_xen in 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

xen_boot.scr is missing from the deploy directory

u-boot-xen-scr is not in IMAGE_INSTALL, or the machine is not a ZynqMP, Versal, Versal Gen 2, or Versal Premium Series Gen 2 machine. Recheck Step 1, MACHINE, XEN_TEMPLATE_CONFIG, and the u-boot-xen-scr build log.

ext4load cannot find /boot/xen_boot.scr

The interface, device, or partition in bootcmd_xen does not match the boot medium. List the partition with ext4ls as in Step 5.

Board boots native Linux instead of Xen

U-Boot was not stopped, so distro boot ran boot.scr. Stop at the U-Boot prompt and run bootcmd_xen.

Dom0 kernel cannot mount its root filesystem

root= in DOM0_CMD does not match the boot medium. Update it in a custom configuration as described in Step 3.

Dom0-less boot cannot load the DomU RAM disk

The RAM disk is missing from /root, or its name does not match DOMU_RAMDISK[0]. Copy it with wic cp as described in Step 4. Paths prefixed with target: are not checked during the build.

References