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

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

[Laszlo Ersek]

The qemu patchset has been turned upside down on qemu-devel during
review (many thanks for that!); one outcome is that now both the
selector and the data registers are big endian. This series has been
updated accordingly.

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   | 72 ++++++++++++++++++++++
 .../devicetree/bindings/vendor-prefixes.txt        |  2 +
 2 files changed, 74 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

[PATCH v4 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:
    v4:
    - no changes
    
    v3:
    - no changes
    
    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 b1df0ad..4a7604f 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.txt
+++ b/Documentation/devicetree/bindings/vendor-prefixes.txt
@@ -127,6 +127,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
@@ -168,6 +169,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

[PATCH v4 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:
    v4:
    - selector and data registers are big endian
    - spell out that the data register must be accessed at its offset 0
    
    v3:
    - advertise the exact size of the region in the DTB [Peter Maydell, Arnd
      Bergmann]
    - update to 64-bit wide data register
    - describe corresponding new region layout
    - describe endianness
    - describe key 0x0000 (signature check) and 0x0001 (interface revision /
      feature bitmap)
    - matches <http://thread.gmane.org/gmane.comp.emulators.qemu/309641>:
      [PATCH v3 0/7] fw_cfg, bootorder, and UEFI+'-kernel' on arm/virt
    
    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 | 72 ++++++++++++++++++++++++
 1 file changed, 72 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..9ea6322
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt
@@ -0,0 +1,72 @@
+* 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 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 selector register takes keys in big endian byte order.
+
+The data register allows accesses with 8, 16, 32 and 64-bit width (only at
+offset 0 of the register). Accesses larger than a byte are interpreted as
+arrays, bundled together only for better performance. The bytes constituting
+such a word, in decreasing address order, correspond to the bytes that would
+have been transferred by byte-wide accesses in chronological order.
+
+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 presence of the registers can be verified by selecting the "signature" blob
+with key 0x0000, and reading four bytes from the data register. The returned
+signature is "QEMU".
+
+The outermost protocol (involving the write / read sequences of the control and
+data registers) is expected to be versioned, and/or described by feature bits.
+The interface revision / feature bitmap can be retrieved with key 0x0001. The
+blob to be read from the data register has size 4, and it is to be interpreted
+as a uint32_t value in little endian byte order. The current value
+(corresponding to the above outer protocol) is zero.
+
+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.
+  * 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>;
+	};
+};
-- 
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: [PATCH v4 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Arnd Bergmann]

On Wednesday 17 December 2014 21:49:44 Laszlo Ersek wrote:
> The qemu patchset has been turned upside down on qemu-devel during
> review (many thanks for that!); one outcome is that now both the
> selector and the data registers are big endian. This series has been
> updated accordingly.
> 
> 

Acked-by: Arnd Bergmann <arnd-r2nGTMty4D4@public.gmane.org>
--
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: [PATCH v4 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Rob Herring]

On Wed, Dec 17, 2014 at 2:49 PM, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> The qemu patchset has been turned upside down on qemu-devel during
> review (many thanks for that!); one outcome is that now both the
> selector and the data registers are big endian. This series has been
> updated accordingly.

I'm assuming this is now settled on the QEMU side and will apply.

Rob

>
> 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   | 72 ++++++++++++++++++++++
>  .../devicetree/bindings/vendor-prefixes.txt        |  2 +
>  2 files changed, 74 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
--
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: [PATCH v4 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Laszlo Ersek]

On 01/07/15 16:43, Rob Herring wrote:
> On Wed, Dec 17, 2014 at 2:49 PM, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> The qemu patchset has been turned upside down on qemu-devel during
>> review (many thanks for that!); one outcome is that now both the
>> selector and the data registers are big endian. This series has been
>> updated accordingly.
> 
> I'm assuming this is now settled on the QEMU side and will apply.

Actually I have a small update for this text file. I thought people
forgot about it and I didn't want to make more noise. If you're still
willing to apply it, then I can post an incremental patch or a new version.

Thanks!
Laszlo

--
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: [PATCH v4 0/2] devicetree: document ARM bindings for QEMU's Firmware Config interface

[Rob Herring]

On Wed, Jan 7, 2015 at 10:33 AM, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On 01/07/15 16:43, Rob Herring wrote:
>> On Wed, Dec 17, 2014 at 2:49 PM, Laszlo Ersek <lersek-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>>> The qemu patchset has been turned upside down on qemu-devel during
>>> review (many thanks for that!); one outcome is that now both the
>>> selector and the data registers are big endian. This series has been
>>> updated accordingly.
>>
>> I'm assuming this is now settled on the QEMU side and will apply.
>
> Actually I have a small update for this text file. I thought people
> forgot about it and I didn't want to make more noise. If you're still
> willing to apply it, then I can post an incremental patch or a new version.

Please send a new version.

Rob
--
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