HPS Xen Hypervisor GSRD

Introduction¶

This page presents the Xen System Example Design, which is based on the HPS Baseline System Example Design User Guide: Agilex 3 FPGA and SoC C-Series Development Kit.

Xen Overview¶

Xen is a free open-source Type-1 hypervisor which enables efficient and secure virtualization of hardware resources to run multiple operating systems on a single physical machine.

In Xen's architecture, there are two domains. Dom0 is the privileged management domain that runs the hypervisor and has full access to physical hardware, acting as the bridge between the hypervisor and other virtual machines. DomUs are unprivileged guest domains that run operating systems or applications, relying on Dom0 for resource allocation. Dom0 and DomUs operate independently, ensuring isolation and security.

Prerequisites¶

The following are required to be able to fully exercise the guides from this page:

Agilex 3 FPGA and SoC C-Series Development Kit, ordering code DK-A3W135BM16AEA.

Host PC with:
- 64 GB of RAM. Less will be fine for only exercising the binaries, and not rebuilding the GSRD.
- Linux OS installed. Ubuntu 22.04LTS was used to create this page, other versions and distributions may work too
- Serial terminal (for example GtkTerm or Minicom on Linux and TeraTerm or PuTTY on Windows)
- SSH server installer, to enable using 'scp' command from target board to host PC
- Altera® Quartus^® Prime Pro Edition Version 26.1.1

Local Ethernet network, with DHCP server
Internet connection. For downloading the files, especially when rebuilding the GSRD.

Prebuilt Binaries¶

The Agilex 3 FPGA and SoC C-Series Development Kit Xen GSRD binaries are located at https://releases.rocketboards.org/2026.08/xen/agilex3_xen.baseline/.

Component Versions¶

Altera® Quartus^® Prime Pro Edition Version 26.1.1 and the following software component versions integrate the 26.1.1 release.

Component	Location	Branch	Commit ID/Tag
Agilex 3 Design	https://github.com/altera-fpga/agilex3c-ed-gsrd	main	QPDS26.1.1_REL_GSRD_PR
Linux	https://github.com/altera-fpga/linux-socfpga	socfpga-6.18.20-lts	QPDS26.1.1_REL_GSRD_PR
Arm Trusted Firmware	https://github.com/altera-fpga/arm-trusted-firmware	socfpga_v2.14.1	QPDS26.1.1_REL_GSRD_PR
U-Boot	https://github.com/altera-fpga/u-boot-socfpga	socfpga_v2026.04	QPDS26.1.1_REL_GSRD_PR
Yocto Project	https://git.yoctoproject.org/poky	wrynose	latest
Yocto meta-altera-fpga Layer	https://github.com/altera-fpga/meta-altera-fpga	wrynose	QPDS26.1.1_REL_GSRD_PR
KAS	https://github.com/siemens/kas/	master	5.4

Note: The combination of the component versions indicated in the table above has been validated through the use cases described in this page and it is strongly recommended to use these versions together. If you decided to use any component with different version than the indicated, there is not warranty that this will work.

Release Notes¶

See https://github.com/altera-fpga/gsrd-socfpga/releases/tag/QPDS26.1.1_REL_GSRD_PR.

Exercise Prebuilt Binaries¶

This section presents how to use the prebuilt binaries included with this Xen example.

Write Binaries¶

This section shows presents downloading and flashing the SD card image and JIC files, and downloading the xen rootfs cpio archive to be used by DomUs VMs.

1. Download and write to SD card the image https://releases.rocketboards.org/2026.08/xen/agilex3_xen.baseline/sdimage.tar.gz

2. Download and write to QSPI flash the JIC file https://releases.rocketboards.org/2026.08/xen/agilex3_xen.baseline/ghrd.hps.jic

3. On the host computer, download the xen rootf cpio archive:

wget https://releases.rocketboards.org/2026.08/xen/agilex3_xen.baseline/xen-image-minimal-agilex3.rootfs.cpio.gz

5. On the Linux on target board, copy over the above downloaded file in 'xen' folder:

cd xen
scp <host_user>@<host-ip>:/<host-folder>/xen-image-minimal-agilex3.rootfs.cpio.gz .

Boot Xen Example Design¶

This section shows how to boot the Xen GSRD. By default, if no other operation is done, the board boots into normal, non-Xen enabled GSRD on a power cycle. In order to boot with the Xen Hypervisor, you need to stop the U-Boot countdown, and boot Linux manually using the commands shown in the below sections. This is provided for convenience, and when used in a real production system, U-Boot can be configured to boot the required Xen configuration automatically.

Boot Without Passthrough

1. Power cycle the board

2. Press any key during U-Boot countdown to stop it

3. Run the following U-Boot commands:

fatls mmc 0:1
fatload mmc 0:1 $loadaddr boot.scr.xen.uimg
source $loadaddr
booti 0x8a000000 - 0x88000000

4. Xen console messages will be shown, then regular Linux boot console messages.

5. Log into Linux as usual with 'root' login and no passoword will be requested

Boot With Passthrough

The instructions are the same as without passthrough, just that the following command needs to be added befote the 'booti' command:

Device Passthrough	Command
QSPI	fdt set /soc@0/spi@108d2000 xen,passthrough
USB	fdt set /soc@0/usb1@11000000 xen,passthrough

Manage VMs¶

This section shows how to use the 'xl' Xen utility to manage VMs running on DomUs. Only a few options are used, refer to 'xl' command help for more options.

1. Boot Xen GSRD as shown above. It can be either with or without passthrough

2. Create VM1 configuration file:

cat << EOT > test_vm_1.cfg
# Guest name
name = "DomU1"

# Kernel image to boot
kernel = "/boot/Image"

ramdisk = "xen-image-minimal-agilex3.cpio.gz"

extra = "root=/dev/ram0 init=/bin/sh console=hvc0 rdinit=/sbin/init"

# Initial memory allocation (MB)
memory = 650
EOT

3. Start VM1:

xl create test_vm_1.cfg

4. List running VMs:

xl list

5. Connect to VM1 console:

xl console DomU1

6. Run some commands in VM1:

pwd
ls -la

7. Exit from VM1 console by pressing CTRL + ]. Note this works only from serial console, and not over SSH connection.

8. Shutdown VM1:

xl shutdown DomU1

The above command politely asks DomU1 to shut down by using the ACPI shutdown signal and letting the OS shut down.

Alternatively, when needed, you can also use 'destroy' commands which acts as a hard power cycle:

xl destroy DomU1

12. List VMs again, it will not show VM1 anymore

xl list

Rebuild Xen System Example Design¶

The embedded software for this System Example Design is built with Yocto, using KAS.

Kas is a Python-based lightweight build orchestration layer on top of BitBake/Yocto. Kas allows you to define your build environment in a YAML manifest, so you can perform checkout, environment setup, configuration, and build invocation with a single command. Kas provides a more maintainable build description, it offers improved reproducibility, reduced setup friction, and a clearer abstraction for managing multiple layers, revisions, and configuration fragments.

The software source code for this System Example Design is released inside the software/yocto_linux directory. Accessing the link will display a README page with details regarding the software.

For more details about Kas, refer to the official documentation at https://kas.readthedocs.io/en/latest/.

Kas Build Prerequisites¶

Firtst, the same prerequisites as for regular Yocto build are required.

1. Make sure you have Yocto system requirements met: https://docs.yoctoproject.org/scarthgap/ref-manual/system-requirements.html#supported-linux-distributions.

The command to install the required packages on Ubuntu 22.04 is:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install openssh-server mc libgmp3-dev libmpc-dev gawk wget git diffstat unzip texinfo gcc \
build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping \
python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint xterm python3-subunit mesa-common-dev zstd \
liblz4-tool git fakeroot build-essential ncurses-dev xz-utils libssl-dev bc flex libelf-dev bison xinetd \
tftpd tftp nfs-kernel-server libncurses5 libc6-i386 libstdc++6:i386 libgcc++1:i386 lib32z1 \
device-tree-compiler curl mtd-utils u-boot-tools net-tools swig -y

On Ubuntu 22.04 you will also need to point the /bin/sh to /bin/bash, as the default is a link to /bin/dash:

 sudo ln -sf /bin/bash /bin/sh

Note: You can also use a Docker container to build the Yocto recipes, refer to https://rocketboards.org/foswiki/Documentation/DockerYoctoBuild for details. When using a Docker container, it does not matter what Linux distribution or packages you have installed on your host, as all dependencies are provided by the Docker container.

In addition to the above, you must also install python3-newt, and python3.10-venv with a command like this:

sudo apt-get install python3-newt python3.10-venv

Build SD Card Binaries¶

The following diagram shows an overview of the building process:

Setup Environment

1. Create the top folder to store all the build artifacts:

sudo rm -rf agilex3_xen
mkdir agilex3_xen
cd agilex3_xen
export TOP_FOLDER=`pwd`

Enable Quartus tools to be called from command line:

source ~/altera_pro/26.1.1/qinit.sh

Build Quartus Design

cd $TOP_FOLDER
rm -rf agilex3_soc_devkit_ghrd && mkdir agilex3_soc_devkit_ghrd && cd agilex3_soc_devkit_ghrd
wget https://github.com/altera-fpga/agilex3c-ed-gsrd/releases/download/QPDS26.1.1_REL_GSRD_PR/dk-a3w135bm16aea-baseline.zip
unzip dk-a3w135bm16aea-baseline.zip
rm -f dk-a3w135bm16aea-baseline.zip
make baseline-install

The following files are created:

$TOP_FOLDER/agilex3_soc_devkit_ghrd/install/binaries/baseline.sof
$TOP_FOLDER/agilex3_soc_devkit_ghrd/install/binaries/baseline_hps_debug.sof
$TOP_FOLDER/agilex3_soc_devkit_ghrd/install/binaries/ghrd.core.rbf

Build Yocto Using Kas

1. Create and enter a new Python virtual environment:

cd $TOP_FOLDER/agilex3_soc_devkit_ghrd/software/yocto_linux
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install --upgrade pip
pip install kas
pip install --upgrade kas
pip install kconfiglib

2. Copy the core.rbf file to where Kas expects it to be:

cp $TOP_FOLDER/agilex3_soc_devkit_ghrd/install/binaries/ghrd.core.rbf \
   $TOP_FOLDER/agilex3_soc_devkit_ghrd/software/yocto_linux/meta-custom/recipes-fpga/fpga-bitstream/files/baseline_hps_debug.core.rbf

3. Build Yocto with Kas:

kas build kas.yml:xen_enable.yml gsrd-console-image

The following relevant files are created in $TOP_FOLDER/agilex3_soc_devkit_ghrd/software/yocto_linux/build/tmp/deploy/images/agilex3/:

gsrd-console-image-agilex3.rootfs.wic
u-boot-spl-dtb.hex

Note: If you experience build failures related to file-locks, you can work around these by reducing the parallelism of your build by running the following commands before running kas:

export PARALLEL_MAKE="-j 8"
export BB_NUMBER_THREADS="8"
export BB_ENV_PASSTHROUGH_ADDITIONS="$BB_ENV_PASSTHROUGH_ADDITIONS PARALLEL_MAKE BB_NUMBER_THREADS"

Build QSPI Image

cd $TOP_FOLDER
rm -f baseline.hps.jic baseline.core.rbf
quartus_pfg \
-c agilex3_soc_devkit_ghrd/install/binaries/baseline.sof baseline.jic \
-o device=MT25QU128 \
-o flash_loader=A3CW135BM16AE6S \
-o hps_path=agilex3_soc_devkit_ghrd/software/yocto_linux/build/tmp/deploy/images/agilex3/u-boot-spl-dtb.hex \
-o mode=ASX4 \
-o hps=1

The following file is created:

$TOP_FOLDER/baseline.hps.jic

Notices & Disclaimers¶

Altera^® Corporation technologies may require enabled hardware, software or service activation. No product or component can be absolutely secure. Performance varies by use, configuration and other factors. Your costs and results may vary. You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Altera or Intel products described herein. You agree to grant Altera Corporation a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document, with the sole exception that you may publish an unmodified copy. You may create software implementations based on this document and in compliance with the foregoing that are intended to execute on the Altera or Intel product(s) referenced in this document. No rights are granted to create modifications or derivatives of this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Altera disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. You are responsible for safety of the overall system, including compliance with applicable safety-related requirements or standards. ^© Altera Corporation. Altera, the Altera logo, and other Altera marks are trademarks of Altera Corporation. Other names and brands may be claimed as the property of others.

OpenCL* and the OpenCL* logo are trademarks of Apple Inc. used by permission of the Khronos Group™.

Last update: September 11, 2026
Created: October 20, 2025