Xilinx QEMU: FPGA Emulation & Virtual Development Guide

Every embedded engineer knows the frustration of waiting for hardware. You’ve got firmware ready to test, drivers to debug, and a boot sequence to validate, but the development board is either across the office, in production, or sitting on someone else’s desk. This is exactly where xilinx qemu becomes invaluable, turning your x86 workstation into a virtual Zynq development platform.

QEMU (Quick Emulator) is an open-source machine emulator, and AMD maintains a specialized fork that accurately models Zynq-7000, Zynq UltraScale+ MPSoC, and Versal platforms. This guide covers everything from basic zynq qemu setup to advanced co-simulation with custom PL designs.

What is Xilinx QEMU?

Xilinx QEMU is AMD’s enhanced fork of the standard QEMU project, specifically optimized for emulating AMD adaptive SoC platforms. Unlike generic ARM emulators, xilinx qemu models the specific peripherals, boot sequences, and memory maps found on actual Zynq hardware.

The emulator creates a complete virtual development board on your workstation, including:

Emulated Component	Description
ARM Cortex-A9/A53/R5 CPUs	Full instruction set emulation
Memory Controllers	DDR, OCM, SRAM modeling
Boot ROM	Secure and non-secure boot flows
Peripherals	UART, SPI, I2C, GPIO, USB, Ethernet
Interrupt Controllers	GIC modeling for all cores
FSBL/PMU Firmware	Complete boot chain support

Supported Platforms

Platform	QEMU Machine Type	Notes
Zynq-7000	xilinx-zynq-a9	Dual Cortex-A9
Zynq UltraScale+ MPSoC	arm-generic-fdt	Quad A53 + Dual R5
Versal ACAP	arm-generic-fdt	A72 + R5 + AI Engine
MicroBlaze	microblaze-fdt	Soft processor support

Why Use Zynq QEMU for Development?

Before dismissing emulation as “too slow” or “not accurate enough,” consider the practical benefits that zynq qemu provides in real development workflows:

Development Without Hardware

The most obvious benefit is hardware independence. You can start software development the day you receive a Vivado export, weeks before physical boards arrive. For teams with limited hardware resources, this eliminates scheduling conflicts and increases productivity.

Debugging Capabilities

QEMU integrates directly with GDB, providing debugging capabilities that are difficult or impossible on physical hardware:

Debug Feature	Hardware	QEMU
Pause execution anytime	Limited	Full support
Inspect all memory regions	Restricted	Full access
Set unlimited breakpoints	Hardware limited	Unlimited
Step through boot ROM	Not possible	Supported
Snapshot system state	Not available	Supported

Testing Automation

Since QEMU runs entirely in software, it integrates naturally with CI/CD pipelines. You can spin up virtual boards, run automated tests, and tear them down without any physical infrastructure. This is transformative for projects requiring regression testing.

Reproducibility

Hardware behavior varies due to temperature, power supply noise, and manufacturing tolerances. QEMU provides deterministic execution that produces identical results every time, making it easier to reproduce and debug intermittent issues.

Read more Xilinx FPGA Series:

Setting Up Xilinx QEMU

Building from Source

The recommended approach is building xilinx qemu from AMD’s GitHub repository:

# Clone the Xilinx fork

git clone -b xilinx-v2024.1 https://github.com/Xilinx/qemu.git

cd qemu

# Install build dependencies (Ubuntu/Debian)

sudo apt-get install git libglib2.0-dev libfdt-dev \

    libpixman-1-dev zlib1g-dev ninja-build

# Configure and build

mkdir build && cd build

../configure –target-list=”aarch64-softmmu,microblazeel-softmmu,arm-softmmu”

make -j$(nproc)

# Add to PATH

export PATH=$(pwd)/aarch64-softmmu:$PATH

Using PetaLinux Bundled QEMU

If you’re already using PetaLinux, QEMU comes pre-installed and configured:

# Source PetaLinux environment

source /opt/petalinux/2024.1/settings.sh

# QEMU is now available

petalinux-boot –qemu –kernel

This approach ensures version compatibility between your Linux images and the emulator.

Booting Linux with Zynq QEMU

Basic Zynq-7000 Boot

For a Zynq-7000 target like ZC702 or ZedBoard:

qemu-system-arm \

    -M xilinx-zynq-a9 \

    -serial null \

    -serial mon:stdio \

    -display none \

    -kernel zImage \

    -dtb system.dtb \

    –initrd rootfs.cpio.gz.u-boot \

    -net nic -net user

Zynq UltraScale+ MPSoC Boot

The ZynqMP requires two QEMU instances running in parallel, one for the PMU and one for the APU:

# Terminal 1: PMU (MicroBlaze)

qemu-system-microblazeel \

    -M microblaze-fdt \

    -serial mon:stdio \

    -serial /dev/null \

    -display none \

    -kernel pmu_rom_qemu_sha3.elf \

    -device loader,file=pmufw.elf \

    -hw-dtb zynqmp-qemu-multiarch-pmu.dtb \

    -machine-path /tmp/qemu-shm

# Terminal 2: APU (ARM Cortex-A53)

qemu-system-aarch64 \

    -M arm-generic-fdt \

    -serial null \

    -serial null \

    -serial mon:stdio \

    -m 4G \

    -display none \

    -hw-dtb zynqmp-qemu-arm.dtb \

    -device loader,file=bl31.elf,cpu-num=0 \

    -device loader,file=u-boot.elf \

    -machine-path /tmp/qemu-shm

The -machine-path argument creates shared memory between the two instances, enabling inter-processor communication.

Using PetaLinux Boot Command

PetaLinux simplifies the boot process significantly:

# Boot kernel in QEMU

petalinux-boot –qemu –kernel

# With additional QEMU arguments

petalinux-boot –qemu –kernel –qemu-args “-net nic -net user,hostfwd=tcp::2222-:22”

The second example forwards port 22 from the guest to port 2222 on the host, enabling SSH access to the emulated system.

QEMU Network Configuration

Network connectivity enables file transfer, SSH access, and testing network-dependent applications.

User Mode Networking

The simplest configuration uses QEMU’s built-in user-mode networking:

-net nic -net user,hostfwd=tcp::2222-:22,tftp=/path/to/tftp/root

Option	Purpose
hostfwd=tcp::2222-:22	Forward SSH port
tftp=/path	Enable TFTP server for file transfer

Bridge Mode Networking

For full network integration, create a TAP interface bridged to your physical network:

# Create bridge and TAP (run once)

sudo ip link add br0 type bridge

sudo ip link set br0 up

sudo ip tuntap add tap0 mode tap user $USER

sudo ip link set tap0 master br0

sudo ip link set tap0 up

# Launch QEMU with TAP

qemu-system-aarch64 … \

    -netdev tap,id=net0,ifname=tap0,script=no,downscript=no \

    -device virtio-net-device,netdev=net0

This configuration allows the emulated system to appear as a separate host on your local network.

Read more Xilinx Products:

Co-Simulation: Connecting QEMU to PL Models

Standard zynq qemu emulates only the Processing System (PS). The Programmable Logic (PL) side isn’t modeled by default. For projects with custom IP in the FPGA fabric, AMD provides co-simulation capabilities.

The Remote Port Protocol

Xilinx QEMU includes a “Remote Port” interface that connects the emulated PS to external simulators modeling the PL:

Simulator Integration	Use Case
SystemC/TLM	High-level behavioral models
Riviera-PRO/ModelSim	RTL simulation
QuestaSim	Detailed timing verification

SystemC Co-Simulation Setup

AMD provides a demo repository for SystemC integration:

# Clone the co-simulation demo

git clone https://github.com/Xilinx/systemctlm-cosim-demo.git

cd systemctlm-cosim-demo

git submodule update –init libsystemctlm-soc

# Build with SystemC

export SYSTEMC=/path/to/systemc-2.3.3

make

# Run the SystemC side

./zynqmp_demo unix:../tmp/qemu-rport-_amba@0_cosim@0 10000

On the QEMU side, pass the hardware device tree that enables co-simulation:

petalinux-boot –qemu –kernel \

    –qemu-args “-hw-dtb zynqmp-qemu-multiarch-arm.cosim.dtb \

                 -machine-path ./tmp \

                 -sync-quantum 1000000″

The -sync-quantum parameter controls synchronization frequency between simulators, trading simulation speed for timing accuracy.

Debugging with QEMU

GDB Integration

QEMU’s built-in GDB server enables source-level debugging:

# Start QEMU with GDB server

qemu-system-aarch64 … -gdb tcp::1234 -S

# Connect with cross-debugger

aarch64-linux-gnu-gdb vmlinux

(gdb) target remote localhost:1234

(gdb) continue

The -S flag pauses execution until the debugger attaches, useful for debugging early boot code.

Kernel Debugging

For Linux kernel debugging, ensure your kernel is built with debug symbols (CONFIG_DEBUG_INFO=y):

# In GDB

(gdb) file vmlinux

(gdb) target remote :1234

(gdb) b start_kernel

(gdb) continue

Application Debugging

Applications running on the emulated Linux can be debugged using the built-in gdbserver:

# On guest

gdbserver :5678 ./my_application

# On host

aarch64-linux-gnu-gdb my_application

(gdb) target remote localhost:5678

Useful QEMU Commands and Shortcuts

Shortcut	Action
Ctrl-A X	Exit QEMU
Ctrl-A C	Toggle QEMU monitor console
Ctrl-A H	Show help

QEMU Monitor Commands

Access the monitor with Ctrl-A C:

Command	Purpose
info cpus	Show CPU states
info registers	Dump register values
info mtree	Display memory map
savevm name	Save system snapshot
loadvm name	Restore snapshot
quit	Exit QEMU

Limitations of QEMU Emulation

While xilinx qemu is powerful, understanding its limitations helps set appropriate expectations:

Limitation	Impact	Workaround
No PL emulation	Custom IP not modeled	Use co-simulation
Timing inaccuracy	Not cycle-accurate	Use for functional testing only
Performance	Slower than hardware	Acceptable for boot/driver testing
Some peripherals	Not all models complete	Check Xilinx Wiki for status

Resources and Downloads

Official AMD Resources

Resource	URL
Xilinx QEMU GitHub	https://github.com/Xilinx/qemu
QEMU Wiki Documentation	https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/822247454
SystemC Co-sim Demo	https://github.com/Xilinx/systemctlm-cosim-demo
PetaLinux Downloads	https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html
Board Images	https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/861569243/Boot+Images

Community Resources

Resource	Description
Xilinx Forums	Technical Q&A and troubleshooting
QEMU Mailing List	Upstream QEMU development
GitHub Issues	Bug reports and feature requests

Frequently Asked Questions

Can QEMU emulate custom IP in the FPGA fabric?

Standard zynq qemu emulates only the Processing System (PS), not the Programmable Logic (PL). For custom IP testing, you need co-simulation, connecting QEMU to SystemC models or RTL simulators via the Remote Port interface. AMD provides the systemctlm-cosim-demo repository as a starting point for this workflow.

How does QEMU performance compare to real hardware?

QEMU typically runs 10-100x slower than actual hardware, depending on workload. For boot testing and driver development, this is perfectly acceptable. For performance-critical application testing or real-time validation, you’ll still need physical hardware. The trade-off is development velocity versus execution speed.

Can I debug the FSBL and early boot code with QEMU?

Yes, this is one of QEMU’s significant advantages. By starting with -gdb tcp::1234 -S, QEMU pauses before executing any code, allowing you to attach GDB and step through the First Stage Boot Loader, ATF, U-Boot, and kernel initialization. This level of visibility is essentially impossible on physical hardware.

Does QEMU support Versal ACAP emulation?

Yes, xilinx qemu supports Versal platforms including the VCK190. The setup is similar to ZynqMP but requires additional components for the PLM (Platform Loader and Manager) instead of PMUFW. Check the AMD Wiki for current Versal-specific boot commands and device tree files.

How do I transfer files between host and QEMU guest?

Several methods work: TFTP (built into QEMU’s user networking), SSH/SCP (with port forwarding), shared folders (9p virtio filesystem), or creating a virtual SD card image that both host and guest can access. For quick transfers during development, TFTP with -net user,tftp=/path is the simplest approach.

Best Practices for QEMU-Based Development

Based on experience with multiple Zynq projects, here are practical recommendations for integrating zynq qemu into your workflow:

Create Reproducible Boot Scripts

Rather than typing long command lines, create shell scripts that document your boot configuration:

#!/bin/bash

# boot_zcu102_qemu.sh

IMAGES_DIR=./images/linux

qemu-system-aarch64 \

    -M arm-generic-fdt \

    -serial null -serial null -serial mon:stdio \

    -m 4G -display none \

    -hw-dtb ${IMAGES_DIR}/zynqmp-qemu-arm.dtb \

    -kernel ${IMAGES_DIR}/Image \

    -initrd ${IMAGES_DIR}/rootfs.cpio.gz \

    -net nic -net user,hostfwd=tcp::2222-:22 \

    “$@”

This approach enables version control of your emulation configuration and simplifies team onboarding.

Maintain Hardware Parity

Keep your QEMU device trees synchronized with physical hardware configurations. Discrepancies between emulated and real platforms lead to bugs that only appear during hardware testing, defeating the purpose of emulation.

Integrate Early in Development

Start QEMU testing from day one, not as an afterthought. Build systems that boot in QEMU before hardware arrives, then validate on physical boards. This workflow catches software issues early when they’re cheapest to fix.

Final Thoughts

After years of embedded development, I’ve come to view xilinx qemu as essential infrastructure rather than optional tooling. The ability to test boot sequences, debug drivers, and validate configurations without touching physical hardware fundamentally changes how you approach embedded Linux development.

The zynq qemu setup process has improved significantly over recent PetaLinux releases. What used to require manual device tree hacking and cryptic command lines now works with a single petalinux-boot –qemu –kernel command for basic workflows.

For teams serious about embedded development, investing time in QEMU integration pays dividends in reduced debug cycles, improved test coverage, and faster iteration. Start with basic boot testing, add network connectivity for file transfer and SSH, then explore co-simulation when you need to validate PS-PL interactions. The learning curve exists, but the productivity gains are substantial.