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

[Alistair Francis]

On Sun, Jun 26, 2022 at 8:40 AM Simon Sapin <simon.sapin@exyr.org> wrote:
>
> Signed-off-by: Simon Sapin <simon.sapin@exyr.org>

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

Alistair

> ---
>  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
>
> 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
> +
> +Resources
> +=========
> +
> +* `Devicetree Specification <https://www.devicetree.org/specifications/>`_.
> +
> +* Embedded Linux Wiki:
> +
> +  - `Device Tree: What It Is <https://elinux.org/Device_Tree_What_It_Is>`_
> +  - `Device Tree Usage <https://elinux.org/Device_Tree_Usage>`_
> +
> +* `Device Tree Compiler <https://git.kernel.org/pub/scm/utils/dtc/dtc.git>`_:
> +
> +  - ``dtc`` CLI tool (package name might be ``device-tree-compiler``)
> +  - ``libfdt`` C library
> +
> +* ``fdt`` `Rust library <https://crates.io/crates/fdt>`_
> diff --git docs/specs/index.rst docs/specs/index.rst
> index a58d9311cb..3bd69305e2 100644
> --- docs/specs/index.rst
> +++ docs/specs/index.rst
> @@ -8,6 +8,7 @@ guest hardware that is specific to QEMU.
>  .. toctree::
>     :maxdepth: 2
>
> +   device-trees
>     ppc-xive
>     ppc-spapr-xive
>     ppc-spapr-numa
> diff --git docs/system/arm/virt.rst docs/system/arm/virt.rst
> index 3d1058a80c..04a90df613 100644
> --- docs/system/arm/virt.rst
> +++ docs/system/arm/virt.rst
> @@ -153,10 +153,13 @@ need::
>    CONFIG_DRM=y
>    CONFIG_DRM_VIRTIO_GPU=y
>
> +.. _arm-baremetal:
> +
>  Hardware configuration information for bare-metal programming
>  """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
>
> -The ``virt`` board automatically generates a device tree blob ("dtb")
> +The ``virt`` board automatically generates a
> +:doc:`device tree blob ("dtb") </specs/device-trees>`
>  which it passes to the guest. This provides information about the
>  addresses, interrupt lines and other configuration of the various devices
>  in the system. Guest code can rely on and hard-code the following
> diff --git docs/system/arm/xlnx-versal-virt.rst 
> docs/system/arm/xlnx-versal-virt.rst
> index 92ad10d2da..3387c74bfa 100644
> --- docs/system/arm/xlnx-versal-virt.rst
> +++ docs/system/arm/xlnx-versal-virt.rst
> @@ -53,7 +53,8 @@ to use the ``-kernel`` command line option.
>
>  Users can load firmware or boot-loaders with the ``-device loader`` options.
>
> -When loading an OS, QEMU generates a DTB and selects an appropriate address
> +When loading an OS, QEMU generates a :doc:`DTB </specs/device-trees>`
> +and selects an appropriate address
>  where it gets loaded. This DTB will be passed to the kernel in register x0.
>
>  If there's no ``-kernel`` option, we generate a DTB and place it at 0x1000
> diff --git docs/system/ppc/ppce500.rst docs/system/ppc/ppce500.rst
> index 9beef39171..24fd91a084 100644
> --- docs/system/ppc/ppce500.rst
> +++ docs/system/ppc/ppce500.rst
> @@ -24,7 +24,8 @@ The ``ppce500`` machine supports the following devices:
>  Hardware configuration information
>  ----------------------------------
>
> -The ``ppce500`` machine automatically generates a device tree blob ("dtb")
> +The ``ppce500`` machine automatically generates a
> +:doc:`device tree blob ("dtb") </specs/device-trees>`
>  which it passes to the guest, if there is no ``-dtb`` option. This provides
>  information about the addresses, interrupt lines and other configuration of
>  the various devices in the system.
> diff --git docs/system/riscv/microchip-icicle-kit.rst 
> docs/system/riscv/microchip-icicle-kit.rst
> index 40798b1aae..a6c8b46263 100644
> --- docs/system/riscv/microchip-icicle-kit.rst
> +++ docs/system/riscv/microchip-icicle-kit.rst
> @@ -37,7 +37,8 @@ can be loaded from U-Boot. It also supports direct kernel 
> booting via the
>  boot is used, the OpenSBI fw_dynamic BIOS image is used to boot a payload
>  like U-Boot or OS kernel directly.
>
> -The user provided DTB should have the following requirements:
> +The user provided :doc:`DTB </specs/device-trees>`
> +should have the following requirements:
>
>  * The /cpus node should contain at least one subnode for E51 and the number
>    of subnodes should match QEMU's ``-smp`` option
> diff --git docs/system/riscv/sifive_u.rst docs/system/riscv/sifive_u.rst
> index 7b166567f9..fd70ee8278 100644
> --- docs/system/riscv/sifive_u.rst
> +++ docs/system/riscv/sifive_u.rst
> @@ -36,7 +36,8 @@ testing of 32-bit guest software.
>  Hardware configuration information
>  ----------------------------------
>
> -The ``sifive_u`` machine automatically generates a device tree blob ("dtb")
> +The ``sifive_u`` machine automatically generates a
> +:doc:`device tree blob ("dtb") </specs/device-trees>`
>  which it passes to the guest, if there is no ``-dtb`` option. This provides
>  information about the addresses, interrupt lines and other configuration of
>  the various devices in the system. Guest software should discover the devices
> diff --git docs/system/riscv/virt.rst docs/system/riscv/virt.rst
> index f8ecec95f3..81ea53eb20 100644
> --- docs/system/riscv/virt.rst
> +++ docs/system/riscv/virt.rst
> @@ -30,7 +30,8 @@ declaring.
>  Hardware configuration information
>  ----------------------------------
>
> -The ``virt`` machine automatically generates a device tree blob ("dtb")
> +The ``virt`` machine automatically generates a
> +:doc:`device tree blob ("dtb") </specs/device-trees>`
>  which it passes to the guest, if there is no ``-dtb`` option. This provides
>  information about the addresses, interrupt lines and other configuration of
>  the various devices in the system. Guest software should discover the devices
> 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.
>  ERST
>
>  DEF("M", HAS_ARG, QEMU_OPTION_M,
> --
> 2.36.1
>
>