docs/system/arm: Document Zynq Buildroot boot

[PATCH] docs/system/arm: Document Zynq Buildroot boot

Posted by Bin Meng 3 weeks, 6 days ago

The Zynq board documentation only showed a generic direct kernel
boot command.

Add Buildroot ZC702 commands for booting through U-Boot proper
with the generic loader and for direct Linux boot from the
generated SD image.

Signed-off-by: Bin Meng <bin.meng@processmission.com>

---

 docs/system/arm/xlnx-zynq.rst | 54 ++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/docs/system/arm/xlnx-zynq.rst b/docs/system/arm/xlnx-zynq.rst
index aa37df2926..95538cd32f 100644
--- a/docs/system/arm/xlnx-zynq.rst
+++ b/docs/system/arm/xlnx-zynq.rst
@@ -30,16 +30,56 @@ The QEMU xilinx-zynq-a9 board supports the following devices:
 - DDR Memory
 - USB 2.0 x2
 
-Running
-"""""""
-Direct Linux boot of a generic Arm upstream Linux kernel:
+Running Buildroot ZC702 Images
+""""""""""""""""""""""""""""""
+
+Buildroot has a ZC702 defconfig. Buildroot 2026.05 release is tested at the
+time of writing. From the Buildroot source tree:
+
+.. code-block:: bash
+
+  $ make zynq_zc702_defconfig
+  $ make
+
+The generated files are in ``output/images/``. The examples below use:
+
+ * ``u-boot.bin``
+ * ``uImage``
+ * ``sdcard.img``
+
+QEMU's SD card model requires a power-of-two image size. Work on a copy
+of the Buildroot SD image and resize the copy, not the original output:
+
+.. code-block:: bash
+
+  $ cp output/images/sdcard.img sdcard-qemu.img
+  $ qemu-img resize -f raw sdcard-qemu.img 128M
+
+To boot through the U-Boot image generated by Buildroot, use the generic
+loader device to place the raw ``u-boot.bin`` at the address it was linked
+for and start the CPU there.  The ``zynq_zc702_defconfig`` U-Boot image is
+U-Boot proper, not a Zynq boot ROM image, and is linked at ``0x04000000``:
+
+.. code-block:: bash
+
+  $ qemu-system-arm -M xilinx-zynq-a9 -m 1G \
+      -machine boot-mode=sd \
+      -display none -serial null -serial mon:stdio \
+      -device loader,file=output/images/u-boot.bin,addr=0x04000000,cpu-num=0 \
+      -drive file=sdcard-qemu.img,if=sd,format=raw
+
+Direct Linux boot of the generated Buildroot image is also supported. The Zynq
+ZC702 DTB is generated by Buildroot and is located in
+``output/images/zynq-zc702.dtb``. The kernel image is generated as a uImage:
 
 .. code-block:: bash
 
-  $ qemu-system-aarch64 -M xilinx-zynq-a9 \
-        -dtb zynq-zc702.dtb  -serial null -serial mon:stdio \
-        -display none  -m 1024 \
-        -initrd rootfs.cpio.gz -kernel zImage
+  $ qemu-system-arm -M xilinx-zynq-a9 -m 1G \
+      -display none -serial null -serial mon:stdio \
+      -kernel output/images/uImage \
+      -dtb output/images/zynq-zc702.dtb \
+      -append "console=ttyPS0,115200 root=/dev/mmcblk0p2 rw rootwait" \
+      -drive file=sdcard-qemu.img,if=sd,format=raw
 
 For configuring the boot-mode provide the following on the command line:
 
-- 
2.34.1

Re: [PATCH] docs/system/arm: Document Zynq Buildroot boot

Posted by Alistair Francis 3 weeks, 6 days ago

On Sun, Jun 28, 2026 at 9:51 PM Bin Meng <bin.meng@processmission.com> wrote:
>
> The Zynq board documentation only showed a generic direct kernel
> boot command.
>
> Add Buildroot ZC702 commands for booting through U-Boot proper
> with the generic loader and for direct Linux boot from the
> generated SD image.
>
> Signed-off-by: Bin Meng <bin.meng@processmission.com>

Acked-by: Alistair Francis <alistair.francis@wdc.com>

>
> ---
>
>  docs/system/arm/xlnx-zynq.rst | 54 ++++++++++++++++++++++++++++++-----
>  1 file changed, 47 insertions(+), 7 deletions(-)
>
> diff --git a/docs/system/arm/xlnx-zynq.rst b/docs/system/arm/xlnx-zynq.rst
> index aa37df2926..95538cd32f 100644
> --- a/docs/system/arm/xlnx-zynq.rst
> +++ b/docs/system/arm/xlnx-zynq.rst
> @@ -30,16 +30,56 @@ The QEMU xilinx-zynq-a9 board supports the following devices:
>  - DDR Memory
>  - USB 2.0 x2
>
> -Running
> -"""""""
> -Direct Linux boot of a generic Arm upstream Linux kernel:
> +Running Buildroot ZC702 Images
> +""""""""""""""""""""""""""""""
> +
> +Buildroot has a ZC702 defconfig. Buildroot 2026.05 release is tested at the
> +time of writing. From the Buildroot source tree:
> +
> +.. code-block:: bash
> +
> +  $ make zynq_zc702_defconfig
> +  $ make
> +
> +The generated files are in ``output/images/``. The examples below use:
> +
> + * ``u-boot.bin``
> + * ``uImage``
> + * ``sdcard.img``
> +
> +QEMU's SD card model requires a power-of-two image size. Work on a copy
> +of the Buildroot SD image and resize the copy, not the original output:
> +
> +.. code-block:: bash
> +
> +  $ cp output/images/sdcard.img sdcard-qemu.img
> +  $ qemu-img resize -f raw sdcard-qemu.img 128M
> +
> +To boot through the U-Boot image generated by Buildroot, use the generic
> +loader device to place the raw ``u-boot.bin`` at the address it was linked
> +for and start the CPU there.  The ``zynq_zc702_defconfig`` U-Boot image is
> +U-Boot proper, not a Zynq boot ROM image, and is linked at ``0x04000000``:
> +
> +.. code-block:: bash
> +
> +  $ qemu-system-arm -M xilinx-zynq-a9 -m 1G \
> +      -machine boot-mode=sd \
> +      -display none -serial null -serial mon:stdio \
> +      -device loader,file=output/images/u-boot.bin,addr=0x04000000,cpu-num=0 \

I'm surprised you can't use -kernel here

Alistair

> +      -drive file=sdcard-qemu.img,if=sd,format=raw
> +
> +Direct Linux boot of the generated Buildroot image is also supported. The Zynq
> +ZC702 DTB is generated by Buildroot and is located in
> +``output/images/zynq-zc702.dtb``. The kernel image is generated as a uImage:
>
>  .. code-block:: bash
>
> -  $ qemu-system-aarch64 -M xilinx-zynq-a9 \
> -        -dtb zynq-zc702.dtb  -serial null -serial mon:stdio \
> -        -display none  -m 1024 \
> -        -initrd rootfs.cpio.gz -kernel zImage
> +  $ qemu-system-arm -M xilinx-zynq-a9 -m 1G \
> +      -display none -serial null -serial mon:stdio \
> +      -kernel output/images/uImage \
> +      -dtb output/images/zynq-zc702.dtb \
> +      -append "console=ttyPS0,115200 root=/dev/mmcblk0p2 rw rootwait" \
> +      -drive file=sdcard-qemu.img,if=sd,format=raw
>
>  For configuring the boot-mode provide the following on the command line:
>
> --
> 2.34.1
>
>

Re: [PATCH] docs/system/arm: Document Zynq Buildroot boot

Posted by Peter Maydell 3 weeks, 2 days ago

On Mon, 29 Jun 2026 at 00:29, Alistair Francis <alistair23@gmail.com> wrote:
>
> On Sun, Jun 28, 2026 at 9:51 PM Bin Meng <bin.meng@processmission.com> wrote:
> >
> > The Zynq board documentation only showed a generic direct kernel
> > boot command.
> >
> > Add Buildroot ZC702 commands for booting through U-Boot proper
> > with the generic loader and for direct Linux boot from the
> > generated SD image.
> >
> > Signed-off-by: Bin Meng <bin.meng@processmission.com>
>
> Acked-by: Alistair Francis <alistair.francis@wdc.com>

> > +  $ qemu-system-arm -M xilinx-zynq-a9 -m 1G \
> > +      -machine boot-mode=sd \
> > +      -display none -serial null -serial mon:stdio \
> > +      -device loader,file=output/images/u-boot.bin,addr=0x04000000,cpu-num=0 \
>
> I'm surprised you can't use -kernel here

I think it's better in our docs to only use '-kernel' for
booting an actual Linux kernel, and to use the generic
loader when what you want is "load some other binary blob",
even if -kernel's historic "do what I mean" handling means it
would also be able to do the job.

Applied to target-arm.next, thanks.

-- PMM