The current xlnx-zcu102 system documentation does not provide a practical
way to boot a real Linux image on the machine. That makes the board hard
to use as a regression target, especially for changes in devices that are
already modelled by QEMU but normally depend on the ZynqMP firmware stack
when described by a real-board DTB.

This patch documents a direct Linux boot flow using Buildroot's ZCU102
defconfig, the generated kernel Image, the generated real-board DTB, an
SD root filesystem image, and an optional QSPI flash image. It also adds
a small DTB fix-up for direct kernel boot so that the boot-critical UART,
SDHCI, and GQSPI nodes do not require the runtime ZynqMP PM firmware
providers for clocks, resets, power domains, or pin control.

The main motivation is to have a reproducible way to validate future
changes to the ZynqMP GQSPI model. With this flow, Linux can probe the
GQSPI controller and discover the SPI NOR flash and its fixed partitions
without requiring a full FSBL/PMUFW/TF-A/U-Boot boot chain. The same
boot also verifies that the UART console and SD root filesystem path still
work with the real-board DTB.

This is intentionally not a complete emulation of the ZynqMP firmware
environment. Non-boot devices in the ZCU102 DTB may still depend on
board peripherals, external clock chips, firmware services, or power and
pin-control providers that QEMU does not model. The fix-up is limited to
the devices needed for the documented direct boot and GQSPI validation
path.

Tested with Buildroot 2026.05 release. The guest reaches the Buildroot
login prompt, probes the SD root filesystem, and detects the GQSPI SPI
NOR flash and its fixed partitions.


Bin Meng (1):
  hw/arm: xlnx-zcu102: Fix up DTB for direct Linux boot

 docs/system/arm/xlnx-zcu102.rst | 139 +++++++++++++++++++++++++++++++-
 hw/arm/xlnx-zcu102.c            | 109 +++++++++++++++++++++++++
 2 files changed, 247 insertions(+), 1 deletion(-)

-- 
2.34.1