Re: [PATCH] dt-bindings: arm: Convert QEMU fw-cfg to DT schema

[Laszlo Ersek <lersek@redhat.com>]

On 03/10/22 02:35, Rob Herring wrote:
> Convert the QEMU fw-cfg binding to DT schema format. As this binding is
> also used on Risc-V now, drop any architecture references and move to a
> common location. The fw-cfg interface has also gained some DMA support
> which is coherent, so add the missing 'dma-coherent'.
> 
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  .../devicetree/bindings/arm/fw-cfg.txt        | 38 -------------
>  .../bindings/firmware/qemu,fw-cfg-mmio.yaml   | 54 +++++++++++++++++++
>  2 files changed, 54 insertions(+), 38 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/arm/fw-cfg.txt
>  create mode 100644 Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml
> 
> diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt
> deleted file mode 100644
> index fd54e1db2156..000000000000
> --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt
> +++ /dev/null
> @@ -1,38 +0,0 @@
> -* QEMU Firmware Configuration bindings for ARM
> -
> -QEMU's arm-softmmu and aarch64-softmmu emulation / virtualization targets
> -provide the following Firmware Configuration interface on the "virt" machine
> -type:
> -
> -- A write-only, 16-bit wide selector (or control) register,
> -- a read-write, 64-bit wide data register.
> -
> -QEMU exposes the control and data register to ARM guests as memory mapped
> -registers; their location is communicated to the guest's UEFI firmware in the
> -DTB that QEMU places at the bottom of the guest's DRAM.
> -
> -The authoritative guest-side hardware interface documentation to the fw_cfg
> -device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.
> -
> -
> -Required properties:
> -
> -- compatible: "qemu,fw-cfg-mmio".
> -
> -- reg: the MMIO region used by the device.
> -  * Bytes 0x0 to 0x7 cover the data register.
> -  * Bytes 0x8 to 0x9 cover the selector register.
> -  * Further registers may be appended to the region in case of future interface
> -    revisions / feature bits.
> -
> -Example:
> -
> -/ {
> -	#size-cells = <0x2>;
> -	#address-cells = <0x2>;
> -
> -	fw-cfg@9020000 {
> -		compatible = "qemu,fw-cfg-mmio";
> -		reg = <0x0 0x9020000 0x0 0xa>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml b/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml
> new file mode 100644
> index 000000000000..3aac9448e7f1
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml
> @@ -0,0 +1,54 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/firmware/qemu,fw-cfg-mmio.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: QEMU Firmware Configuration bindings
> +
> +maintainers:
> +  - Laszlo Ersek <lersek@redhat.com>

Ugh :) I guess this is based on my authorship of historical commit
53275a61bc7a ("devicetree: document ARM bindings for QEMU's Firmware
Config interface", 2015-01-13), and prehaps my R-b on commit
92aed5d6ba90 ("devicetree: update documentation for fw_cfg ARM
bindings", 2016-02-09).

However -- I totally can't maintain this file. (I mean I've probably not
done anything related to it in the past seven years, so I guess it's
time to admit that fact!)

Rob, would you please consider taking it over?

With my name+email replaced with yours:

Acked-by: Laszlo Ersek <lersek@redhat.com>

Thank you!
Laszlo


> +
> +description: |
> +  Various QEMU emulation / virtualization targets provide the following
> +  Firmware Configuration interface on the "virt" machine type:
> +
> +  - A write-only, 16-bit wide selector (or control) register,
> +  - a read-write, 64-bit wide data register.
> +
> +  QEMU exposes the control and data register to guests as memory mapped
> +  registers; their location is communicated to the guest's UEFI firmware in the
> +  DTB that QEMU places at the bottom of the guest's DRAM.
> +
> +  The authoritative guest-side hardware interface documentation to the fw_cfg
> +  device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.
> +
> +
> +properties:
> +  compatible:
> +    const: qemu,fw-cfg-mmio
> +
> +  reg:
> +    maxItems: 1
> +    description: |
> +      * Bytes 0x0 to 0x7 cover the data register.
> +      * Bytes 0x8 to 0x9 cover the selector register.
> +      * Further registers may be appended to the region in case of future interface
> +        revisions / feature bits.
> +
> +  dma-coherent: true
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +
> +    fw-cfg@9020000 {
> +        compatible = "qemu,fw-cfg-mmio";
> +        reg = <0x9020000 0xa>;
> +    };
> +...
>