[PATCH v8 02/32] arm: riscv: qemu: Explain how to extract the generated dt

Simon Glass sjg at chromium.org
Fri Dec 17 04:59:09 CET 2021

QEMU currently generates a devicetree for use with U-Boot. Explain how to
obtain it.

Also explain how to merge it to produce a devicetree with the U-Boot
features included.

Signed-off-by: Simon Glass <sjg at chromium.org>

Changes in v8:
- Rebase patch

Changes in v5:
- Merge RISC-V and ARM patches since they are similar

 doc/board/emulation/qemu-arm.rst   |  3 ++
 doc/board/emulation/qemu-riscv.rst |  3 ++
 doc/develop/devicetree/dt_qemu.rst | 48 ++++++++++++++++++++++++++++++
 doc/develop/devicetree/index.rst   |  1 +
 4 files changed, 55 insertions(+)
 create mode 100644 doc/develop/devicetree/dt_qemu.rst

diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst
index 8bd7b60cdb4..ff64ec08c3e 100644
--- a/doc/board/emulation/qemu-arm.rst
+++ b/doc/board/emulation/qemu-arm.rst
@@ -21,6 +21,9 @@ The 'virt' platform provides the following as the basic functionality:
 Additionally, a number of optional peripherals can be added to the PCI bus.
+See :doc:`../../develop/devicetree/dt_qemu` for information on how to see
+the devicetree actually generated by QEMU.
 Building U-Boot
 Set the CROSS_COMPILE environment variable as usual, and run:
diff --git a/doc/board/emulation/qemu-riscv.rst b/doc/board/emulation/qemu-riscv.rst
index 4b8e104a215..3409fff8117 100644
--- a/doc/board/emulation/qemu-riscv.rst
+++ b/doc/board/emulation/qemu-riscv.rst
@@ -13,6 +13,9 @@ The QEMU virt machine models a generic RISC-V virtual machine with support for
 the VirtIO standard networking and block storage devices. It has CLINT, PLIC,
 16550A UART devices in addition to VirtIO and it also uses device-tree to pass
 configuration information to guest software. It implements RISC-V privileged
+See :doc:`../../develop/devicetree/dt_qemu` for information on how to see
+the devicetree actually generated by QEMU.
 architecture spec v1.10.
 Building U-Boot
diff --git a/doc/develop/devicetree/dt_qemu.rst b/doc/develop/devicetree/dt_qemu.rst
new file mode 100644
index 00000000000..c25c4fb053d
--- /dev/null
+++ b/doc/develop/devicetree/dt_qemu.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: GPL-2.0+
+Devicetree in QEMU
+For QEMU on ARM, RISC-V and one PPC target, the devicetree is created on-the-fly
+by QEMU. It is intended for use in Linux but can be used by U-Boot also, so long
+as any nodes/properties needed by U-Boot are merged in.
+When `CONFIG_OF_BOARD` is enabled
+Obtaining the QEMU devicetree
+Where QEMU generates its own devicetree to pass to U-Boot tou can use
+`-dtb u-boot.dtb` to force QEMU to use U-Boot's in-tree version.
+To obtain the devicetree that qemu generates, add `-machine dumpdtb=qemu.dtb`,
+    qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb
+    qemu-system-aarch64 -machine virt -machine dumpdtb=qemu.dtb
+    qemu-system-riscv64 -machine virt -machine dumpdtb=qemu.dtb
+Merging in U-Boot nodes/properties
+Various U-Boot features require nodes and properties in the U-Boot devicetree
+and at present QEMU is unaware of these. To use these you must manually merge
+in the appropriate pieces.
+One way to do this is with dtc. This command runs dtc on each .dtb file in turn,
+to produce a text file. It drops the duplicate header on the qemu one. Then it
+joins them up and runs them through dtc to compile the output::
+    qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb
+    cat  <(dtc -I dtb qemu.dtb) <(dtc -I dtb  u-boot.dtb |grep -v /dts-v1/) |dtc - -o merged.dtb
+You can then run qemu with the merged devicetree, e.g.::
+    qemu-system-arm -machine virt -nographic -bios u-boot.bin -dtb merged.dtb
+Note that there seems to be a bug in some versions of qemu where the output of
+dumpdtb does not quite match what is provided to U-Boot.
diff --git a/doc/develop/devicetree/index.rst b/doc/develop/devicetree/index.rst
index fa5db3eb76e..2edb69572dd 100644
--- a/doc/develop/devicetree/index.rst
+++ b/doc/develop/devicetree/index.rst
@@ -11,3 +11,4 @@ build-time and runtime configuration.
+   dt_qemu

More information about the U-Boot mailing list