Re: [PATCH] Add some documentation for "dtb" devices tree blobs

[Peter Maydell]

On Sat, 25 Jun 2022 at 23:39, Simon Sapin <simon.sapin@exyr.org> wrote:
>
> Signed-off-by: Simon Sapin <simon.sapin@exyr.org>
> ---
>  docs/specs/device-trees.rst                | 57 ++++++++++++++++++++++
>  docs/specs/index.rst                       |  1 +
>  docs/system/arm/virt.rst                   |  5 +-
>  docs/system/arm/xlnx-versal-virt.rst       |  3 +-
>  docs/system/ppc/ppce500.rst                |  3 +-
>  docs/system/riscv/microchip-icicle-kit.rst |  3 +-
>  docs/system/riscv/sifive_u.rst             |  3 +-
>  docs/system/riscv/virt.rst                 |  3 +-
>  qemu-options.hx                            |  5 ++
>  9 files changed, 77 insertions(+), 6 deletions(-)
>  create mode 100644 docs/specs/device-trees.rst

Hi; thanks for writing this documentation.

> diff --git docs/specs/device-trees.rst docs/specs/device-trees.rst
> new file mode 100644
> index 0000000000..8160342124
> --- /dev/null
> +++ docs/specs/device-trees.rst
> @@ -0,0 +1,57 @@
> +============
> +Device Trees
> +============
> +
> +On some targets, guests can find out what devices are emulated and how to 
> access them
> +through a *Device Tree Blob* (dtb), also called *Flattened Device Tree* 
> (fdt).
> +The dtb can be passed by the user through the ``-dtb file`` command-line 
> options,
> +or automatically generated by QEMU.
> +
> +Host: dumping the dtb
> +=====================
> +
> +The (possibly generated) dtb can be written to a file with
> +the ``dumpdtb`` property of the ``machine`` command-line option.
> +Then `dtc <Device Tree Compiler_>`_ can convert it to Device Tree Source 
> text "dts" format
> +For example::
> +
> +    qemu-system-riscv32 -machine virt,dumpdtb=rv32-virt.dtb
> +    dtc -q rv32-virt.dtb -o rv32-virt.dts
> +    head -n 7 rv32-virt.dts
> +
> +::
> +
> +    qemu-system-riscv32: info: dtb dumped to rv32-virt.dtb. Exiting.
> +    /dts-v1/;
> +
> +    / {
> +        #address-cells = <0x02>;
> +        #size-cells = <0x02>;
> +        compatible = "riscv-virtio";
> +        model = "riscv-virtio,qemu";
> +
> +Guest: finding the dtb
> +======================
> +
> +On startup, the dtb is memory-mapped and its address is passed to the guest
> +in a target-specific way:
> +
> +* Arm: :ref:`arm-baremetal`
> +* **TODO**: document other targets

Don't leave TODO notes in the docs, please.

Also, the DTB is not necessarily memory-mapped. For instance on
Arm platforms if the user requests a bios/firmware image to be
run, then we put the dtb (like the kernel and initrd) in the
fw_cfg device for the firmware to extract.

> diff --git qemu-options.hx qemu-options.hx
> index 377d22fbd8..eea75ddb37 100644
> --- qemu-options.hx
> +++ qemu-options.hx
> @@ -38,6 +38,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>      "                hmat=on|off controls ACPI HMAT support (default=off)\n"
>      "                memory-backend='backend-id' specifies explicitly 
> provided backend for main RAM (default=none)\n"
>      "                
> cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n",
> +    "                dumpdtb=file dump current device tree blob to a file 
> and quit\n"
>      QEMU_ARCH_ALL)
>  SRST
>  ``-machine [type=]name[,prop=value[,...]]``
> @@ -157,6 +158,10 @@ SRST
>          ::
>
>              -machine 
> cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512k
> +
> +    ``dumpdtb=file``
> +        Dump the current :doc:`Device Tree Blob </specs/device-trees>`
> +        to the give file name, then exit.

 to the given file name, then exit QEMU without running the guest.
 This is primarily useful for debugging, as it allows you to see the
 contents of the DTB including all additions and modifications that
 QEMU makes before handing it to the guest.

 This option is ignored on machine types which do not use a DTB.

>  ERST
>
>  DEF("M", HAS_ARG, QEMU_OPTION_M,


thanks
-- PMM