On Sun, Jun 26, 2022 at 8:40 AM Simon Sapin <simon.sa...@exyr.org> wrote:
>
> Signed-off-by: Simon Sapin <simon.sa...@exyr.org>
Reviewed-by: Alistair Francis <alistair.fran...@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
>
>
