[kernel PATCH v2 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[kernel PATCH v2 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Laszlo Ersek]

V2 seeks to address comments raised in the v1 review. Changes are broken
out per patch, as git notes.

Thanks
Laszlo

Laszlo Ersek (2):
  devicetree: document the "qemu" and "virtio" vendor prefixes
  devicetree: document ARM bindings for QEMU's Firmware Config interface

 Documentation/devicetree/bindings/arm/fw-cfg.txt   | 57 ++++++++++++++++++++++
 .../devicetree/bindings/vendor-prefixes.txt        |  2 +
 2 files changed, 59 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/fw-cfg.txt

-- 
1.8.3.1

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[kernel PATCH v2 1/2] devicetree: document the "qemu" and "virtio" vendor prefixes

[Laszlo Ersek]

The QEMU open source machine emulator and virtualizer presents firmware
and operating systems running in virtual machines ("guests") with purely
virtual hardware (ie. hardware that has never existed in physical form).
Since QEMU exposes some of these devices in a DTB, it makes sense to
define "qemu" and "virtio" as vendor prefixes.

The qemu definition is from [1], revision 4451 (22:24, 25 November 2014).

The virtio definition is composed from [2] and [3].

[1] http://wiki.qemu.org/Main_Page
[2] http://docs.oasis-open.org/virtio/virtio/v1.0/csprd01/virtio-v1.0-csprd01.html
[3] http://en.wikipedia.org/wiki/OASIS_%28organization%29

Suggested-by: Mark Rutland <mark.rutland-5wv7dgnIgG8@public.gmane.org>
Suggested-by: Arnd Bergmann <arnd-r2nGTMty4D4@public.gmane.org>
Signed-off-by: Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---

Notes:
    v2:
    - new in v2 [Mark Rutland, Arnd Bergmann]

 Documentation/devicetree/bindings/vendor-prefixes.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt
index a344ec2..df095c1 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.txt
+++ b/Documentation/devicetree/bindings/vendor-prefixes.txt
@@ -119,6 +119,7 @@ pixcir  PIXCIR MICROELECTRONICS Co., Ltd
 powervr	PowerVR (deprecated, use img)
 qca	Qualcomm Atheros, Inc.
 qcom	Qualcomm Technologies, Inc
+qemu	QEMU, a generic and open source machine emulator and virtualizer
 qnap	QNAP Systems, Inc.
 radxa	Radxa
 raidsonic	RaidSonic Technology GmbH
@@ -159,6 +160,7 @@ usi	Universal Scientific Industrial Co., Ltd.
 v3	V3 Semiconductor
 variscite	Variscite Ltd.
 via	VIA Technologies, Inc.
+virtio	Virtual I/O Device Specification, developed by the OASIS consortium
 voipac	Voipac Technologies s.r.o.
 winbond Winbond Electronics corp.
 wlf	Wolfson Microelectronics
-- 
1.8.3.1


--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[kernel PATCH v2 2/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Laszlo Ersek]

Peter Maydell suggested that we describe new devices / DTB nodes in the
kernel Documentation tree that we expose to arm "virt" guests in QEMU.

Although the kernel is not required to access the fw_cfg interface,
"Documentation/devicetree/bindings/arm" is probably the best central spot
to keep the fw_cfg description in.

Suggested-by: Peter Maydell <peter.maydell-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
Signed-off-by: Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---

Notes:
    v2:
    - more info on what the fw_cfg device is used for, versioning, blobs etc
      [Mark Rutland]
    - drop generic statements about DTB [Mark Rutland]
    - drop uint64_t language [Mark Rutland]
    - cover both registers with one contiguous region, of size 0x1000 [Mark
      Rutland, Arnd Bergmann]
    - specify "qemu,fw-cfg-mmio" for the "compatible" property [Mark
      Rutland, Arnd Bergmann]
    - reorder DTS snippet so that "compatible" come first [Mark Rutland]

 Documentation/devicetree/bindings/arm/fw-cfg.txt | 57 ++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/fw-cfg.txt

diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt
new file mode 100644
index 0000000..15e2ae3
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt
@@ -0,0 +1,57 @@
+* 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, 8-bit wide data register.
+
+The guest writes a selector value (a key) to the selector register, and then
+can read the corresponding data (produced by QEMU) via the data register. If
+the selected entry is writable, the guest can rewrite it through the data
+register.
+
+The interface allows guest firmware to download various parameters and blobs
+that affect how the firmware works and what tables it installs for the guest
+OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and
+initrd images for direct kernel booting, virtual machine UUID, SMP information,
+virtual NUMA topology, and so on.
+
+The authoritative registry of the valid selector values and their meanings is
+the QEMU source code; the structure of the data blobs corresponding to the
+individual key values is also defined in the QEMU source code.
+
+The outermost protocol (involving the write / read sequences of the control and
+data registers) is unversioned and considered stable. Versioning of individual
+blobs is theoretically possible, but it is not specified on this level (and is
+not done in practice as yet).
+
+QEMU exposes the control and data register to x86 guests at fixed IO ports. ARM
+guests can access them as memory mapped registers, and 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 guest kernel is not expected to use these registers (although it is
+certainly allowed to); the device tree bindings are documented here because
+this is where device tree bindings reside in general.
+
+Required properties:
+
+- compatible: "qemu,fw-cfg-mmio".
+
+- reg: the MMIO region used by the device.
+  * The first two bytes in the region cover the control register.
+  * The third byte covers the data register.
+
+Example:
+
+/ {
+	#size-cells = <0x2>;
+	#address-cells = <0x2>;
+
+	fw-cfg@9020000 {
+		compatible = "qemu,fw-cfg-mmio";
+		reg = <0x0 0x9020000 0x0 0x1000>;
+	};
+};
-- 
1.8.3.1

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [kernel PATCH v2 2/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Peter Maydell]

On 30 November 2014 at 16:51, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> +Example:
> +
> +/ {
> +       #size-cells = <0x2>;
> +       #address-cells = <0x2>;
> +
> +       fw-cfg@9020000 {
> +               compatible = "qemu,fw-cfg-mmio";
> +               reg = <0x0 0x9020000 0x0 0x1000>;
> +       };

I've just noticed that this example claims a register
region size of 0x1000. This seems wrong, because the
underlying device doesn't have a register range that
big. Surely this should be a size of 0x3 ?

thanks
-- PMM
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [kernel PATCH v2 2/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Laszlo Ersek]

On 12/05/14 19:57, Peter Maydell wrote:
> On 30 November 2014 at 16:51, Laszlo Ersek <lersek@redhat.com> wrote:
>> +Example:
>> +
>> +/ {
>> +       #size-cells = <0x2>;
>> +       #address-cells = <0x2>;
>> +
>> +       fw-cfg@9020000 {
>> +               compatible = "qemu,fw-cfg-mmio";
>> +               reg = <0x0 0x9020000 0x0 0x1000>;
>> +       };
> 
> I've just noticed that this example claims a register
> region size of 0x1000. This seems wrong, because the
> underlying device doesn't have a register range that
> big. Surely this should be a size of 0x3 ?

Arnd said I should round up the region to 0x1000.

http://thread.gmane.org/gmane.linux.drivers.devicetree/101173/focus=101176

If that's incorrect I'd prefer to post incremental patches, because 4
other series already depend on this kernel docs patch.

Thanks
Laszlo

Re: [kernel PATCH v2 2/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Peter Maydell]

On 5 December 2014 at 19:04, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On 12/05/14 19:57, Peter Maydell wrote:
>> On 30 November 2014 at 16:51, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>>> +Example:
>>> +
>>> +/ {
>>> +       #size-cells = <0x2>;
>>> +       #address-cells = <0x2>;
>>> +
>>> +       fw-cfg@9020000 {
>>> +               compatible = "qemu,fw-cfg-mmio";
>>> +               reg = <0x0 0x9020000 0x0 0x1000>;
>>> +       };
>>
>> I've just noticed that this example claims a register
>> region size of 0x1000. This seems wrong, because the
>> underlying device doesn't have a register range that
>> big. Surely this should be a size of 0x3 ?
>
> Arnd said I should round up the region to 0x1000.

Right; I replied here as a reasonable place to do so
on an email with the device-tree folk in cc.

> http://thread.gmane.org/gmane.linux.drivers.devicetree/101173/focus=101176

Arnd, what was your reasoning in requesting the round-up?
I would have expected that a dtb with an overlarge range
is telling the guest it can access things that in fact
just aren't there (ie the equivalent of unmapped space which
on h/w would give you an external abort/decode error).

> If that's incorrect I'd prefer to post incremental patches, because 4
> other series already depend on this kernel docs patch.

Docs patches aren't hard dependencies :-)

-- PMM
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [kernel PATCH v2 2/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Arnd Bergmann]

On Friday 05 December 2014 19:08:46 Peter Maydell wrote:
> On 5 December 2014 at 19:04, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> > On 12/05/14 19:57, Peter Maydell wrote:
> >> On 30 November 2014 at 16:51, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> >>> +Example:
> >>> +
> >>> +/ {
> >>> +       #size-cells = <0x2>;
> >>> +       #address-cells = <0x2>;
> >>> +
> >>> +       fw-cfg@9020000 {
> >>> +               compatible = "qemu,fw-cfg-mmio";
> >>> +               reg = <0x0 0x9020000 0x0 0x1000>;
> >>> +       };
> >>
> >> I've just noticed that this example claims a register
> >> region size of 0x1000. This seems wrong, because the
> >> underlying device doesn't have a register range that
> >> big. Surely this should be a size of 0x3 ?
> >
> > Arnd said I should round up the region to 0x1000.
> 
> Right; I replied here as a reasonable place to do so
> on an email with the device-tree folk in cc.
> 
> > http://thread.gmane.org/gmane.linux.drivers.devicetree/101173/focus=101176
> 
> Arnd, what was your reasoning in requesting the round-up?
> I would have expected that a dtb with an overlarge range
> is telling the guest it can access things that in fact
> just aren't there (ie the equivalent of unmapped space which
> on h/w would give you an external abort/decode error).

I was expecting that qemu would be allowed to put additional
registers in there for future extensions. My comment was mainly
directed at having two distinct but consecutive register ranges,
which can be better expressed by having a longer one.

As long as qemu knows exactly how long the register area is
(and it better should know), having the correct length in there
is probably best.


	Arnd
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [kernel PATCH v2 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Peter Maydell]

On 30 November 2014 at 16:51, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> V2 seeks to address comments raised in the v1 review. Changes are broken
> out per patch, as git notes.
>
> Thanks
> Laszlo
>
> Laszlo Ersek (2):
>   devicetree: document the "qemu" and "virtio" vendor prefixes
>   devicetree: document ARM bindings for QEMU's Firmware Config interface
>
>  Documentation/devicetree/bindings/arm/fw-cfg.txt   | 57 ++++++++++++++++++++++
>  .../devicetree/bindings/vendor-prefixes.txt        |  2 +
>  2 files changed, 59 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/arm/fw-cfg.txt

If the device tree folks are happy with this binding then it
works for me on the QEMU side.

Acked-by: Peter Maydell <peter.maydell-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>

-- PMM
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html