[PATCH] arm: document "mach-virt" platform.

[PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

mach-virt has existed for a while but it is not written down what it actually
consists of. Although it seems a bit unusual to document a binding for an
entire platform since mach-virt is entirely virtual it is helpful to have
something to refer to in the absence of a single concrete implementation.

I've done my best to capture the requirements based on the git log and my
memory/understanding.

While here remove the xenvm dts example, the Xen tools will now build a
suitable mach-virt compatible dts when launching the guest.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Pawel Moll <pawel.moll@arm.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Kumar Gala <galak@codeaurora.org>
Cc: Olof Johansson <olof@lixom.net>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Marc Zyngier <marc.zyngier@arm.com>
Cc: Will Deacon <will.deacon@arm.com>
Cc: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
Cc: devicetree@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-arm-kernel@lists.infradead.org
---
I'm not sure which tree this sort of thing should go though, sorry for the
huge Cc.
---
 .../devicetree/bindings/arm/mach-virt.txt          |   32 ++++++++
 arch/arm/boot/dts/xenvm-4.2.dts                    |   81 --------------------
 2 files changed, 32 insertions(+), 81 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/arm/mach-virt.txt
 delete mode 100644 arch/arm/boot/dts/xenvm-4.2.dts

diff --git a/Documentation/devicetree/bindings/arm/mach-virt.txt b/Documentation/devicetree/bindings/arm/mach-virt.txt
new file mode 100644
index 0000000..562bcda
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
@@ -0,0 +1,32 @@
+* Mach-virt "Dummy Virtual Machine" platform
+
+"mach-virt" is the smallest, dumbest platform possible, to be used as
+a guest for Xen, KVM and other hypervisors. It has no
+properties/functionality of its own and is driven entirely by device
+tree.
+
+This document defines the requirements for such a platform.
+
+* Required properties:
+
+- compatible: should be one of:
+	"linux,dummy-virt"
+	"xen,xenvm"
+
+In addition to the standard nodes (chosen, cpus, memory etc) the
+platform is required to provide certain other basic functionality
+which must be described in the device tree:
+
+    The platform must provide an ARM Generic Interrupt Controller
+    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
+
+    The platform must provide ARM architected timer, defined in
+    Documentation/devicetree/bindings/arm/arch_timer.txt.
+
+    If the platform is SMP then it must provide the Power State
+    Coordination Interface (PSCI) described in
+    Documentation/devicetree/bindings/arm/psci.txt.
+
+The platform may also provide hypervisor specific functionality
+(e.g. PV I/O), if it does so then this functionality must be
+discoverable (directly or indirectly) via device tree.
diff --git a/arch/arm/boot/dts/xenvm-4.2.dts b/arch/arm/boot/dts/xenvm-4.2.dts
deleted file mode 100644
index 3369151..0000000
--- a/arch/arm/boot/dts/xenvm-4.2.dts
+++ /dev/null
@@ -1,81 +0,0 @@
-/*
- * Xen Virtual Machine for unprivileged guests
- *
- * Based on ARM Ltd. Versatile Express CoreTile Express (single CPU)
- * Cortex-A15 MPCore (V2P-CA15)
- *
- */
-
-/dts-v1/;
-
-/ {
-	model = "XENVM-4.2";
-	compatible = "xen,xenvm-4.2", "xen,xenvm";
-	interrupt-parent = <&gic>;
-	#address-cells = <2>;
-	#size-cells = <2>;
-
-	chosen {
-		/* this field is going to be adjusted by the hypervisor */
-		bootargs = "console=hvc0 root=/dev/xvda";
-	};
-
-	cpus {
-		#address-cells = <1>;
-		#size-cells = <0>;
-
-		cpu@0 {
-			device_type = "cpu";
-			compatible = "arm,cortex-a15";
-			reg = <0>;
-		};
-
-		cpu@1 {
-			device_type = "cpu";
-			compatible = "arm,cortex-a15";
-			reg = <1>;
-		};
-	};
-
-	psci {
-		compatible      = "arm,psci";
-		method          = "hvc";
-		cpu_off         = <1>;
-		cpu_on          = <2>;
-	};
-
-	memory@80000000 {
-		device_type = "memory";
-		/* this field is going to be adjusted by the hypervisor */
-		reg = <0 0x80000000 0 0x08000000>;
-	};
-
-	gic: interrupt-controller@2c001000 {
-		compatible = "arm,cortex-a15-gic", "arm,cortex-a9-gic";
-		#interrupt-cells = <3>;
-		#address-cells = <0>;
-		interrupt-controller;
-		reg = <0 0x2c001000 0 0x1000>,
-		      <0 0x2c002000 0 0x100>;
-	};
-
-	timer {
-		compatible = "arm,armv7-timer";
-		interrupts = <1 13 0xf08>,
-			     <1 14 0xf08>,
-			     <1 11 0xf08>,
-			     <1 10 0xf08>;
-	};
-
-	hypervisor {
-		compatible = "xen,xen-4.2", "xen,xen";
-		/* this field is going to be adjusted by the hypervisor */
-		reg = <0 0xb0000000 0 0x20000>;
-		/* this field is going to be adjusted by the hypervisor */
-		interrupts = <1 15 0xf08>;
-	};
-
-	motherboard {
-		arm,v2m-memory-map = "rs1";
-	};
-};
-- 
1.7.10.4

Re: [PATCH] arm: document "mach-virt" platform.

[Christopher Covington]

Hi Ian,

On 01/30/2014 11:11 AM, Ian Campbell wrote:
> mach-virt has existed for a while but it is not written down what it actually
> consists of. Although it seems a bit unusual to document a binding for an
> entire platform since mach-virt is entirely virtual it is helpful to have
> something to refer to in the absence of a single concrete implementation.
> 
> I've done my best to capture the requirements based on the git log and my
> memory/understanding.
> 
> While here remove the xenvm dts example, the Xen tools will now build a
> suitable mach-virt compatible dts when launching the guest.

[...]

> +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
> @@ -0,0 +1,32 @@
> +* Mach-virt "Dummy Virtual Machine" platform
> +
> +"mach-virt" is the smallest, dumbest platform possible, to be used as
> +a guest for Xen, KVM and other hypervisors.

The platform is also useful to, and used by, simulators like QEMU in TCG mode.

>                                              It has no
> +properties/functionality of its own and is driven entirely by device
> +tree.

I find this wording confusing. I read it as saying the platform has no
properties or functionality. Perhaps you could phrase it slightly differently,
such as having no properties or functionality beyond what's described in the
device tree.

> +This document defines the requirements for such a platform.
> +
> +* Required properties:
> +
> +- compatible: should be one of:
> +	"linux,dummy-virt"
> +	"xen,xenvm"
> +
> +In addition to the standard nodes (chosen, cpus, memory etc) the
> +platform is required to provide certain other basic functionality
> +which must be described in the device tree:
> +
> +    The platform must provide an ARM Generic Interrupt Controller
> +    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
> +
> +    The platform must provide ARM architected timer, defined in
> +    Documentation/devicetree/bindings/arm/arch_timer.txt.
> +
> +    If the platform is SMP then it must provide the Power State
> +    Coordination Interface (PSCI) described in
> +    Documentation/devicetree/bindings/arm/psci.txt.
> +
> +The platform may also provide hypervisor specific functionality
> +(e.g. PV I/O), if it does so then this functionality must be
> +discoverable (directly or indirectly) via device tree.

I think it would be informative to provide pointers here to commonly used
paravirtualized devices, especially VirtIO PCI/MMIO.

Thanks,
Christopher

-- 
Employee of Qualcomm Innovation Center, Inc.
Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
hosted by the Linux Foundation.

Re: [PATCH] arm: document "mach-virt" platform.

[Stefano Stabellini]

On Thu, 30 Jan 2014, Christopher Covington wrote:
> Hi Ian,
> 
> On 01/30/2014 11:11 AM, Ian Campbell wrote:
> > mach-virt has existed for a while but it is not written down what it actually
> > consists of. Although it seems a bit unusual to document a binding for an
> > entire platform since mach-virt is entirely virtual it is helpful to have
> > something to refer to in the absence of a single concrete implementation.
> > 
> > I've done my best to capture the requirements based on the git log and my
> > memory/understanding.
> > 
> > While here remove the xenvm dts example, the Xen tools will now build a
> > suitable mach-virt compatible dts when launching the guest.
> 
> [...]
> 
> > +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
> > @@ -0,0 +1,32 @@
> > +* Mach-virt "Dummy Virtual Machine" platform
> > +
> > +"mach-virt" is the smallest, dumbest platform possible, to be used as
> > +a guest for Xen, KVM and other hypervisors.
> 
> The platform is also useful to, and used by, simulators like QEMU in TCG mode.
> 
> >                                              It has no
> > +properties/functionality of its own and is driven entirely by device
> > +tree.
> 
> I find this wording confusing. I read it as saying the platform has no
> properties or functionality. Perhaps you could phrase it slightly differently,
> such as having no properties or functionality beyond what's described in the
> device tree.

Right, something like making no assumptions on the presence of devices
or hardware interfaces beyond what is described on device tree.


> > +This document defines the requirements for such a platform.
> > +
> > +* Required properties:
> > +
> > +- compatible: should be one of:
> > +	"linux,dummy-virt"
> > +	"xen,xenvm"
> > +
> > +In addition to the standard nodes (chosen, cpus, memory etc) the
> > +platform is required to provide certain other basic functionality
> > +which must be described in the device tree:
> > +
> > +    The platform must provide an ARM Generic Interrupt Controller
> > +    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
> > +
> > +    The platform must provide ARM architected timer, defined in
> > +    Documentation/devicetree/bindings/arm/arch_timer.txt.
> > +
> > +    If the platform is SMP then it must provide the Power State
> > +    Coordination Interface (PSCI) described in
> > +    Documentation/devicetree/bindings/arm/psci.txt.
> > +
> > +The platform may also provide hypervisor specific functionality
> > +(e.g. PV I/O), if it does so then this functionality must be
> > +discoverable (directly or indirectly) via device tree.
> 
> I think it would be informative to provide pointers here to commonly used
> paravirtualized devices, especially VirtIO PCI/MMIO.

In that case I would appreciate a link to the Xen hypervisor node:

Documentation/devicetree/bindings/arm/xen.txt

Re: [PATCH] arm: document "mach-virt" platform.

[Marc Zyngier]

Hi Ian,

On 30/01/14 16:11, Ian Campbell wrote:
> mach-virt has existed for a while but it is not written down what it actually
> consists of. Although it seems a bit unusual to document a binding for an
> entire platform since mach-virt is entirely virtual it is helpful to have
> something to refer to in the absence of a single concrete implementation.
> 
> I've done my best to capture the requirements based on the git log and my
> memory/understanding.
> 
> While here remove the xenvm dts example, the Xen tools will now build a
> suitable mach-virt compatible dts when launching the guest.
> 
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> Cc: Rob Herring <robh+dt@kernel.org>
> Cc: Pawel Moll <pawel.moll@arm.com>
> Cc: Mark Rutland <mark.rutland@arm.com>
> Cc: Kumar Gala <galak@codeaurora.org>
> Cc: Olof Johansson <olof@lixom.net>
> Cc: Arnd Bergmann <arnd@arndb.de>
> Cc: Marc Zyngier <marc.zyngier@arm.com>
> Cc: Will Deacon <will.deacon@arm.com>
> Cc: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
> Cc: devicetree@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org
> Cc: linux-arm-kernel@lists.infradead.org
> ---
> I'm not sure which tree this sort of thing should go though, sorry for the
> huge Cc.
> ---
>  .../devicetree/bindings/arm/mach-virt.txt          |   32 ++++++++
>  arch/arm/boot/dts/xenvm-4.2.dts                    |   81 --------------------
>  2 files changed, 32 insertions(+), 81 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/arm/mach-virt.txt
>  delete mode 100644 arch/arm/boot/dts/xenvm-4.2.dts
> 
> diff --git a/Documentation/devicetree/bindings/arm/mach-virt.txt b/Documentation/devicetree/bindings/arm/mach-virt.txt
> new file mode 100644
> index 0000000..562bcda
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
> @@ -0,0 +1,32 @@
> +* Mach-virt "Dummy Virtual Machine" platform
> +
> +"mach-virt" is the smallest, dumbest platform possible, to be used as
> +a guest for Xen, KVM and other hypervisors. It has no
> +properties/functionality of its own and is driven entirely by device
> +tree.
> +
> +This document defines the requirements for such a platform.
> +
> +* Required properties:
> +
> +- compatible: should be one of:
> +	"linux,dummy-virt"
> +	"xen,xenvm"
> +
> +In addition to the standard nodes (chosen, cpus, memory etc) the
> +platform is required to provide certain other basic functionality
> +which must be described in the device tree:
> +
> +    The platform must provide an ARM Generic Interrupt Controller
> +    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
> +
> +    The platform must provide ARM architected timer, defined in
> +    Documentation/devicetree/bindings/arm/arch_timer.txt.
> +
> +    If the platform is SMP then it must provide the Power State
> +    Coordination Interface (PSCI) described in
> +    Documentation/devicetree/bindings/arm/psci.txt.

I'm afraid I disagree with most of the above. The whole point of
mach-virt is to provide a shell for DT platforms. None of this hardware
is mandated. Instead, all the necessary information should be described
in DT.

Actually, mach-virt doesn't really stand for Virtual Machine. It stands
for virtual mach-* directory! Eventually, mach-virt should become the
default platform, the one we use when we don't match anything else in
the kernel

What you've described here are requirements for a hypervisor like Xen or
KVM. mach-virt itself shouldn't have any of that.

Cheers,

	M.
-- 
Jazz is not dead. It just smells funny...

Re: [PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

On Thu, 2014-01-30 at 11:54 -0500, Christopher Covington wrote:
> > +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
> > @@ -0,0 +1,32 @@
> > +* Mach-virt "Dummy Virtual Machine" platform
> > +
> > +"mach-virt" is the smallest, dumbest platform possible, to be used as
> > +a guest for Xen, KVM and other hypervisors.
> 
> The platform is also useful to, and used by, simulators like QEMU in TCG mode.

I can mention this, although I don't think the list needs to be
exhaustive.
                                      It has no
> > +properties/functionality of its own and is driven entirely by device
> > +tree.
> 
> I find this wording confusing. I read it as saying the platform has no
> properties or functionality. Perhaps you could phrase it slightly differently,
> such as having no properties or functionality beyond what's described in the
> device tree.

Yes, this is what I was trying to say, I'll update with something along
those lines.

> > +The platform may also provide hypervisor specific functionality
> > +(e.g. PV I/O), if it does so then this functionality must be
> > +discoverable (directly or indirectly) via device tree.
> 
> I think it would be informative to provide pointers here to commonly used
> paravirtualized devices, especially VirtIO PCI/MMIO.

Under what criteria would something be eligible/appropriate to be
listed? I was trying to avoid "advocating" any particular type of PV
devices. We already have something of a problem with people incorrectly
assuming that mach-virt == virtio, which is not the case.

If we did want to include an explicit list here at a minimum I would
also want to include the Xen PV devices as well and surely there would
be others which ought to be included too.

Ian.

Re: [PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

On Thu, 2014-01-30 at 17:13 +0000, Marc Zyngier wrote:
> Hi Ian,
> 
> On 30/01/14 16:11, Ian Campbell wrote:
> > mach-virt has existed for a while but it is not written down what it actually
> > consists of. Although it seems a bit unusual to document a binding for an
> > entire platform since mach-virt is entirely virtual it is helpful to have
> > something to refer to in the absence of a single concrete implementation.
> > 
> > I've done my best to capture the requirements based on the git log and my
> > memory/understanding.
> > 
> > While here remove the xenvm dts example, the Xen tools will now build a
> > suitable mach-virt compatible dts when launching the guest.
> > 
> > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> > Cc: Rob Herring <robh+dt@kernel.org>
> > Cc: Pawel Moll <pawel.moll@arm.com>
> > Cc: Mark Rutland <mark.rutland@arm.com>
> > Cc: Kumar Gala <galak@codeaurora.org>
> > Cc: Olof Johansson <olof@lixom.net>
> > Cc: Arnd Bergmann <arnd@arndb.de>
> > Cc: Marc Zyngier <marc.zyngier@arm.com>
> > Cc: Will Deacon <will.deacon@arm.com>
> > Cc: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
> > Cc: devicetree@vger.kernel.org
> > Cc: linux-kernel@vger.kernel.org
> > Cc: linux-arm-kernel@lists.infradead.org
> > ---
> > I'm not sure which tree this sort of thing should go though, sorry for the
> > huge Cc.
> > ---
> >  .../devicetree/bindings/arm/mach-virt.txt          |   32 ++++++++
> >  arch/arm/boot/dts/xenvm-4.2.dts                    |   81 --------------------
> >  2 files changed, 32 insertions(+), 81 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/arm/mach-virt.txt
> >  delete mode 100644 arch/arm/boot/dts/xenvm-4.2.dts
> > 
> > diff --git a/Documentation/devicetree/bindings/arm/mach-virt.txt b/Documentation/devicetree/bindings/arm/mach-virt.txt
> > new file mode 100644
> > index 0000000..562bcda
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
> > @@ -0,0 +1,32 @@
> > +* Mach-virt "Dummy Virtual Machine" platform
> > +
> > +"mach-virt" is the smallest, dumbest platform possible, to be used as
> > +a guest for Xen, KVM and other hypervisors. It has no
> > +properties/functionality of its own and is driven entirely by device
> > +tree.
> > +
> > +This document defines the requirements for such a platform.
> > +
> > +* Required properties:
> > +
> > +- compatible: should be one of:
> > +	"linux,dummy-virt"
> > +	"xen,xenvm"
> > +
> > +In addition to the standard nodes (chosen, cpus, memory etc) the
> > +platform is required to provide certain other basic functionality
> > +which must be described in the device tree:
> > +
> > +    The platform must provide an ARM Generic Interrupt Controller
> > +    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
> > +
> > +    The platform must provide ARM architected timer, defined in
> > +    Documentation/devicetree/bindings/arm/arch_timer.txt.
> > +
> > +    If the platform is SMP then it must provide the Power State
> > +    Coordination Interface (PSCI) described in
> > +    Documentation/devicetree/bindings/arm/psci.txt.
> 
> I'm afraid I disagree with most of the above. The whole point of
> mach-virt is to provide a shell for DT platforms. None of this hardware
> is mandated. Instead, all the necessary information should be described
> in DT.

"Add support for the smallest, dumbest possible platform, to be
 used as a guest for KVM or other hypervisors.

 It only mandates a GIC and architected timers"

(your original commit message :-P)

> Actually, mach-virt doesn't really stand for Virtual Machine. It stands
> for virtual mach-* directory! Eventually, mach-virt should become the
> default platform, the one we use when we don't match anything else in
> the kernel

I can word it more like that for sure, along with the alternative
wording suggested by Christopher/Stefano to clarify the intent that
everything comes from DTB and removal of the specific requirements for
GIC/timer/PSCI I think that suit the (new) intention better?

> What you've described here are requirements for a hypervisor like Xen or
> KVM. mach-virt itself shouldn't have any of that.
> 
> Cheers,
> 
> 	M.

Re: [PATCH] arm: document "mach-virt" platform.

[Marc Zyngier]

On 30/01/14 17:21, Ian Campbell wrote:
> On Thu, 2014-01-30 at 17:13 +0000, Marc Zyngier wrote:
>> Hi Ian,
>>
>> On 30/01/14 16:11, Ian Campbell wrote:
>>> mach-virt has existed for a while but it is not written down what it actually
>>> consists of. Although it seems a bit unusual to document a binding for an
>>> entire platform since mach-virt is entirely virtual it is helpful to have
>>> something to refer to in the absence of a single concrete implementation.
>>>
>>> I've done my best to capture the requirements based on the git log and my
>>> memory/understanding.
>>>
>>> While here remove the xenvm dts example, the Xen tools will now build a
>>> suitable mach-virt compatible dts when launching the guest.
>>>
>>> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
>>> Cc: Rob Herring <robh+dt@kernel.org>
>>> Cc: Pawel Moll <pawel.moll@arm.com>
>>> Cc: Mark Rutland <mark.rutland@arm.com>
>>> Cc: Kumar Gala <galak@codeaurora.org>
>>> Cc: Olof Johansson <olof@lixom.net>
>>> Cc: Arnd Bergmann <arnd@arndb.de>
>>> Cc: Marc Zyngier <marc.zyngier@arm.com>
>>> Cc: Will Deacon <will.deacon@arm.com>
>>> Cc: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
>>> Cc: devicetree@vger.kernel.org
>>> Cc: linux-kernel@vger.kernel.org
>>> Cc: linux-arm-kernel@lists.infradead.org
>>> ---
>>> I'm not sure which tree this sort of thing should go though, sorry for the
>>> huge Cc.
>>> ---
>>>  .../devicetree/bindings/arm/mach-virt.txt          |   32 ++++++++
>>>  arch/arm/boot/dts/xenvm-4.2.dts                    |   81 --------------------
>>>  2 files changed, 32 insertions(+), 81 deletions(-)
>>>  create mode 100644 Documentation/devicetree/bindings/arm/mach-virt.txt
>>>  delete mode 100644 arch/arm/boot/dts/xenvm-4.2.dts
>>>
>>> diff --git a/Documentation/devicetree/bindings/arm/mach-virt.txt b/Documentation/devicetree/bindings/arm/mach-virt.txt
>>> new file mode 100644
>>> index 0000000..562bcda
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
>>> @@ -0,0 +1,32 @@
>>> +* Mach-virt "Dummy Virtual Machine" platform
>>> +
>>> +"mach-virt" is the smallest, dumbest platform possible, to be used as
>>> +a guest for Xen, KVM and other hypervisors. It has no
>>> +properties/functionality of its own and is driven entirely by device
>>> +tree.
>>> +
>>> +This document defines the requirements for such a platform.
>>> +
>>> +* Required properties:
>>> +
>>> +- compatible: should be one of:
>>> +	"linux,dummy-virt"
>>> +	"xen,xenvm"
>>> +
>>> +In addition to the standard nodes (chosen, cpus, memory etc) the
>>> +platform is required to provide certain other basic functionality
>>> +which must be described in the device tree:
>>> +
>>> +    The platform must provide an ARM Generic Interrupt Controller
>>> +    (GIC), defined in Documentation/devicetree/bindings/arm/gic.txt.
>>> +
>>> +    The platform must provide ARM architected timer, defined in
>>> +    Documentation/devicetree/bindings/arm/arch_timer.txt.
>>> +
>>> +    If the platform is SMP then it must provide the Power State
>>> +    Coordination Interface (PSCI) described in
>>> +    Documentation/devicetree/bindings/arm/psci.txt.
>>
>> I'm afraid I disagree with most of the above. The whole point of
>> mach-virt is to provide a shell for DT platforms. None of this hardware
>> is mandated. Instead, all the necessary information should be described
>> in DT.
> 
> "Add support for the smallest, dumbest possible platform, to be
>  used as a guest for KVM or other hypervisors.
> 
>  It only mandates a GIC and architected timers"
> 
> (your original commit message :-P)

Right. 1984, here we come. I'll disappear for a while, rewriting the
history. More seriously, that was just me scheming to get it merged,
hiding my cunning plan for mach-virt world domination!

>> Actually, mach-virt doesn't really stand for Virtual Machine. It stands
>> for virtual mach-* directory! Eventually, mach-virt should become the
>> default platform, the one we use when we don't match anything else in
>> the kernel
> 
> I can word it more like that for sure, along with the alternative
> wording suggested by Christopher/Stefano to clarify the intent that
> everything comes from DTB and removal of the specific requirements for
> GIC/timer/PSCI I think that suit the (new) intention better?

Yes, please! :-)

	M.
-- 
Jazz is not dead. It just smells funny...

Re: [PATCH] arm: document "mach-virt" platform.

[Arnd Bergmann]

On Thursday 30 January 2014, Ian Campbell wrote:
> mach-virt has existed for a while but it is not written down what it actually
> consists of. Although it seems a bit unusual to document a binding for an
> entire platform since mach-virt is entirely virtual it is helpful to have
> something to refer to in the absence of a single concrete implementation.
> 
> I've done my best to capture the requirements based on the git log and my
> memory/understanding.
> 
> While here remove the xenvm dts example, the Xen tools will now build a
> suitable mach-virt compatible dts when launching the guest.

It might be worth noting in the changeset comment that the 'compatible'
string is actually no longer needed on newer kernels: All the members
of the machine descriptor are now the defaults (we should remove the
virt_init() function as well), and the fallback machine descriptor should
work just fine if any other string gets passed.

	Arnd

Re: [PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

On Thu, 2014-01-30 at 17:24 +0000, Marc Zyngier wrote:
> >> I'm afraid I disagree with most of the above. The whole point of
> >> mach-virt is to provide a shell for DT platforms. None of this hardware
> >> is mandated. Instead, all the necessary information should be described
> >> in DT.
> > 
> > "Add support for the smallest, dumbest possible platform, to be
> >  used as a guest for KVM or other hypervisors.
> > 
> >  It only mandates a GIC and architected timers"
> > 
> > (your original commit message :-P)
> 
> Right. 1984, here we come. I'll disappear for a while, rewriting the
> history. More seriously, that was just me scheming to get it merged,
> hiding my cunning plan for mach-virt world domination!

:-)

> >> Actually, mach-virt doesn't really stand for Virtual Machine. It stands
> >> for virtual mach-* directory! Eventually, mach-virt should become the
> >> default platform, the one we use when we don't match anything else in
> >> the kernel
> > 
> > I can word it more like that for sure, along with the alternative
> > wording suggested by Christopher/Stefano to clarify the intent that
> > everything comes from DTB and removal of the specific requirements for
> > GIC/timer/PSCI I think that suit the (new) intention better?
> 
> Yes, please! :-)

OK, I'll come up with an updated version.

Cheers,
Ian.

Re: [PATCH] arm: document "mach-virt" platform.

[Marc Zyngier]

On 30/01/14 17:28, Arnd Bergmann wrote:
> On Thursday 30 January 2014, Ian Campbell wrote:
>> mach-virt has existed for a while but it is not written down what it actually
>> consists of. Although it seems a bit unusual to document a binding for an
>> entire platform since mach-virt is entirely virtual it is helpful to have
>> something to refer to in the absence of a single concrete implementation.
>>
>> I've done my best to capture the requirements based on the git log and my
>> memory/understanding.
>>
>> While here remove the xenvm dts example, the Xen tools will now build a
>> suitable mach-virt compatible dts when launching the guest.
> 
> It might be worth noting in the changeset comment that the 'compatible'
> string is actually no longer needed on newer kernels: All the members
> of the machine descriptor are now the defaults (we should remove the
> virt_init() function as well), and the fallback machine descriptor should
> work just fine if any other string gets passed.

I will ack the patch that removes the mach-virt directory altogether!

	M.
-- 
Jazz is not dead. It just smells funny...

Re: [PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

On Thu, 2014-01-30 at 18:28 +0100, Arnd Bergmann wrote:
> On Thursday 30 January 2014, Ian Campbell wrote:
> > mach-virt has existed for a while but it is not written down what it actually
> > consists of. Although it seems a bit unusual to document a binding for an
> > entire platform since mach-virt is entirely virtual it is helpful to have
> > something to refer to in the absence of a single concrete implementation.
> > 
> > I've done my best to capture the requirements based on the git log and my
> > memory/understanding.
> > 
> > While here remove the xenvm dts example, the Xen tools will now build a
> > suitable mach-virt compatible dts when launching the guest.
> 
> It might be worth noting in the changeset comment that the 'compatible'
> string is actually no longer needed on newer kernels: All the members
> of the machine descriptor are now the defaults (we should remove the
> virt_init() function as well), and the fallback machine descriptor should
> work just fine if any other string gets passed.

So Marc's plan has actually happened. Neat. In that case is there even
any point in listing explicit compatiblity strings (except perhaps as a
historical note) -- I can just say that this is the fallback/default
machine?

I'll leave the virt_init change to a separate patch if that's ok.

Ian.

Re: [PATCH] arm: document "mach-virt" platform.

[Christopher Covington]

Hi Ian,

On 01/30/2014 12:15 PM, Ian Campbell wrote:
> On Thu, 2014-01-30 at 11:54 -0500, Christopher Covington wrote:
>>> +++ b/Documentation/devicetree/bindings/arm/mach-virt.txt
>>> @@ -0,0 +1,32 @@
>>> +* Mach-virt "Dummy Virtual Machine" platform
>>> +
>>> +"mach-virt" is the smallest, dumbest platform possible, to be used as
>>> +a guest for Xen, KVM and other hypervisors.
>>
>> The platform is also useful to, and used by, simulators like QEMU in TCG mode.
> 
> I can mention this, although I don't think the list needs to be
> exhaustive.

Cool, thanks. Agreed, but I thought it'd be nice to list the simulator class.

>                                       It has no
>>> +properties/functionality of its own and is driven entirely by device
>>> +tree.
>>
>> I find this wording confusing. I read it as saying the platform has no
>> properties or functionality. Perhaps you could phrase it slightly differently,
>> such as having no properties or functionality beyond what's described in the
>> device tree.
> 
> Yes, this is what I was trying to say, I'll update with something along
> those lines.
> 
>>> +The platform may also provide hypervisor specific functionality
>>> +(e.g. PV I/O), if it does so then this functionality must be
>>> +discoverable (directly or indirectly) via device tree.
>>
>> I think it would be informative to provide pointers here to commonly used
>> paravirtualized devices, especially VirtIO PCI/MMIO.
> 
> Under what criteria would something be eligible/appropriate to be
> listed? I was trying to avoid "advocating" any particular type of PV
> devices. We already have something of a problem with people incorrectly
> assuming that mach-virt == virtio, which is not the case.

This isn't particularly scientific, but maybe a practical criteria could be
that it's mentioned in this thread? I think if we word the introduction to the
list clearly, readers will know that that these are just a few examples known
to be in use when the binding was written and by no means required. I think
that providing more information is more likely to fix the incorrect assumption
than providing less information.

> If we did want to include an explicit list here at a minimum I would
> also want to include the Xen PV devices as well and surely there would
> be others which ought to be included too.

Yes, I assumed you would include Xen. I'm not aware of any others*, but
perhaps those who do could speak up about them?

(*I do use Angel semihosting and DCC from time to time, but I've never seen
devicetree bindings for these facilities. I'm not sure whether they count in
this context.)

Thanks,
Christopher

-- 
Employee of Qualcomm Innovation Center, Inc.
Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
hosted by the Linux Foundation.

Re: [PATCH] arm: document "mach-virt" platform.

[Rob Herring]

On Thu, Jan 30, 2014 at 11:33 AM, Marc Zyngier <marc.zyngier@arm.com> wrote:
> On 30/01/14 17:28, Arnd Bergmann wrote:
>> On Thursday 30 January 2014, Ian Campbell wrote:
>>> mach-virt has existed for a while but it is not written down what it actually
>>> consists of. Although it seems a bit unusual to document a binding for an
>>> entire platform since mach-virt is entirely virtual it is helpful to have
>>> something to refer to in the absence of a single concrete implementation.
>>>
>>> I've done my best to capture the requirements based on the git log and my
>>> memory/understanding.
>>>
>>> While here remove the xenvm dts example, the Xen tools will now build a
>>> suitable mach-virt compatible dts when launching the guest.
>>
>> It might be worth noting in the changeset comment that the 'compatible'
>> string is actually no longer needed on newer kernels: All the members
>> of the machine descriptor are now the defaults (we should remove the
>> virt_init() function as well), and the fallback machine descriptor should
>> work just fine if any other string gets passed.
>
> I will ack the patch that removes the mach-virt directory altogether!

Did I never send that one out? I know I started something. Finding new
employment has had me distracted...

Rob

Re: [PATCH] arm: document "mach-virt" platform.

[Christoffer Dall]

On Thu, Jan 30, 2014 at 04:11:02PM +0000, Ian Campbell wrote:
> mach-virt has existed for a while but it is not written down what it actually
> consists of. Although it seems a bit unusual to document a binding for an
> entire platform since mach-virt is entirely virtual it is helpful to have
> something to refer to in the absence of a single concrete implementation.
> 
> I've done my best to capture the requirements based on the git log and my
> memory/understanding.

[...]

> 
> +
> +The platform may also provide hypervisor specific functionality
> +(e.g. PV I/O), if it does so then this functionality must be
> +discoverable (directly or indirectly) via device tree.

While this is obviously true, I'm not sure I see the value of this text.

Isn't it more essential to just say that *any* functionality provided to
the platform must be discoverable via device tree?

-Christoffer

Re: [PATCH] arm: document "mach-virt" platform.

[Christoffer Dall]

On Thu, Jan 30, 2014 at 11:54:46AM -0500, Christopher Covington wrote:
> Hi Ian,
> 
> On 01/30/2014 11:11 AM, Ian Campbell wrote:
> > mach-virt has existed for a while but it is not written down what it actually
> > consists of. Although it seems a bit unusual to document a binding for an
> > entire platform since mach-virt is entirely virtual it is helpful to have
> > something to refer to in the absence of a single concrete implementation.
> > 
> > I've done my best to capture the requirements based on the git log and my
> > memory/understanding.
> > 
> > While here remove the xenvm dts example, the Xen tools will now build a
> > suitable mach-virt compatible dts when launching the guest.
> 

[...]

> > +The platform may also provide hypervisor specific functionality
> > +(e.g. PV I/O), if it does so then this functionality must be
> > +discoverable (directly or indirectly) via device tree.
> 
> I think it would be informative to provide pointers here to commonly used
> paravirtualized devices, especially VirtIO PCI/MMIO.
> 

I disagree: that would only encourage limited testing or assumptions
about these specific devices when really this platform is just a
bare-bones platform driven by device tree which should make no
preference, whatsoever, about which devices are used with the platform.

-Christoffer

Re: [PATCH] arm: document "mach-virt" platform.

[Ian Campbell]

On Sun, 2014-02-02 at 20:56 -0800, Christoffer Dall wrote:
> On Thu, Jan 30, 2014 at 11:54:46AM -0500, Christopher Covington wrote:
> > Hi Ian,
> > 
> > On 01/30/2014 11:11 AM, Ian Campbell wrote:
> > > mach-virt has existed for a while but it is not written down what it actually
> > > consists of. Although it seems a bit unusual to document a binding for an
> > > entire platform since mach-virt is entirely virtual it is helpful to have
> > > something to refer to in the absence of a single concrete implementation.
> > > 
> > > I've done my best to capture the requirements based on the git log and my
> > > memory/understanding.
> > > 
> > > While here remove the xenvm dts example, the Xen tools will now build a
> > > suitable mach-virt compatible dts when launching the guest.
> > 
> 
> [...]
> 
> > > +The platform may also provide hypervisor specific functionality
> > > +(e.g. PV I/O), if it does so then this functionality must be
> > > +discoverable (directly or indirectly) via device tree.
> > 
> > I think it would be informative to provide pointers here to commonly used
> > paravirtualized devices, especially VirtIO PCI/MMIO.
> > 
> 
> I disagree: that would only encourage limited testing or assumptions
> about these specific devices when really this platform is just a
> bare-bones platform driven by device tree which should make no
> preference, whatsoever, about which devices are used with the platform.

Thanks, I think this is exactly what I was failing to express coherently
last week ;-)

Ian.

Re: [PATCH] arm: document "mach-virt" platform.

[Christopher Covington]

Hi Christoffer,

On 02/02/2014 11:56 PM, Christoffer Dall wrote:
> On Thu, Jan 30, 2014 at 11:54:46AM -0500, Christopher Covington wrote:
>> I think it would be informative to provide pointers here to commonly used
>> paravirtualized devices, especially VirtIO PCI/MMIO.
> 
> I disagree: that would only encourage limited testing or assumptions
> about these specific devices when really this platform is just a
> bare-bones platform driven by device tree which should make no
> preference, whatsoever, about which devices are used with the platform.

I'd be all for clearly stating that no assumptions can be made. Perhaps you
can explain though how providing less documentation will result in more
testing? The assertion does not currently make sense to me.

Thanks,
Christopher

-- 
Employee of Qualcomm Innovation Center, Inc.
Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
hosted by the Linux Foundation.

Re: [PATCH] arm: document "mach-virt" platform.

[Christoffer Dall]

On Mon, Feb 03, 2014 at 08:46:07AM -0500, Christopher Covington wrote:
> Hi Christoffer,
> 
> On 02/02/2014 11:56 PM, Christoffer Dall wrote:
> > On Thu, Jan 30, 2014 at 11:54:46AM -0500, Christopher Covington wrote:
> >> I think it would be informative to provide pointers here to commonly used
> >> paravirtualized devices, especially VirtIO PCI/MMIO.
> > 
> > I disagree: that would only encourage limited testing or assumptions
> > about these specific devices when really this platform is just a
> > bare-bones platform driven by device tree which should make no
> > preference, whatsoever, about which devices are used with the platform.
> 
> I'd be all for clearly stating that no assumptions can be made. Perhaps you
> can explain though how providing less documentation will result in more
> testing? The assertion does not currently make sense to me.
> 
If the documentation states that this is commonly used with virtio/xen
pv drivers, then I'm afraid people will just assume that's the only
devices the platform is used with.

Any mention of specific devices or features steers the attention away
from the essential point of this documentation.

I don't see how adding this text helps.  Such documentation should go
elsewhere, in QEMU, or a Xen/KVM web page or something like that.

Anyway, I'm not religious about this point.

-Christoffer