diff mbox series

[v5,02/13] dt-bindings: Add binding for gunyah hypervisor

Message ID 20221011000840.289033-3-quic_eberman@quicinc.com
State Superseded
Headers show
Series Drivers for gunyah hypervisor | expand

Commit Message

Elliot Berman Oct. 11, 2022, 12:08 a.m. UTC
When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
Resource Manager applies a devicetree overlay describing the virtual
platform configuration of the guest VM, such as the message queue
capability IDs for communicating with the Resource Manager. This
information is not otherwise discoverable by a VM: the Gunyah hypervisor
core does not provide a direct interface to discover capability IDs nor
a way to communicate with RM without having already known the
corresponding message queue capability ID. Add the DT bindings that
Gunyah adheres for the hypervisor node and message queues.

Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
---
 .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 88 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml

Comments

Rob Herring Oct. 12, 2022, 3:56 p.m. UTC | #1
On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
> Resource Manager applies a devicetree overlay describing the virtual
> platform configuration of the guest VM, such as the message queue
> capability IDs for communicating with the Resource Manager. This
> information is not otherwise discoverable by a VM: the Gunyah hypervisor
> core does not provide a direct interface to discover capability IDs nor
> a way to communicate with RM without having already known the
> corresponding message queue capability ID. Add the DT bindings that
> Gunyah adheres for the hypervisor node and message queues.
> 
> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
> ---
>  .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 88 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> 
> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> new file mode 100644
> index 000000000000..f0a14101e2fd
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> @@ -0,0 +1,87 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Gunyah Hypervisor
> +
> +maintainers:
> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
> +  - Elliot Berman <quic_eberman@quicinc.com>
> +
> +description: |+
> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which

How you end up with the node (applying an overlay) is not relavent to 
the binding.

> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.

Wrap at 80. That is the coding standard still though 100 is deemed 
allowed. And yamllint only complains at 110 because I didn't care to fix 
everyones lines over 100.

> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
> +
> +properties:
> +  compatible:
> +    items:
> +      - const: gunyah-hypervisor-1.0
> +      - const: gunyah-hypervisor

2 compatibles implies a difference between the 2. What's the difference? 
Where does '1.0' come from?

> +
> +  "#address-cells":
> +    description: Number of cells needed to represent 64-bit capability IDs.
> +    const: 2
> +
> +  "#size-cells":
> +    description: must be 0, because capability IDs are not memory address
> +                  ranges and do not have a size.
> +    const: 0
> +
> +patternProperties:
> +  "^gunyah-resource-mgr(@.*)?":
> +    type: object
> +    description:
> +      Resource Manager node which is required to communicate to Resource
> +      Manager VM using Gunyah Message Queues.
> +
> +    properties:
> +      compatible:
> +        items:
> +          - const: gunyah-resource-manager-1-0
> +          - const: gunyah-resource-manager

Same comment here.

> +
> +      reg:
> +        items:
> +          - description: Gunyah capability ID of the TX message queue
> +          - description: Gunyah capability ID of the RX message queue
> +
> +      interrupts:
> +        items:
> +          - description: Interrupt for the TX message queue
> +          - description: Interrupt for the RX message queue
> +
> +    additionalProperties: false
> +
> +    required:
> +      - compatible
> +      - reg
> +      - interrupts
> +
> +additionalProperties: false
> +
> +required:
> +  - compatible
> +  - "#address-cells"
> +  - "#size-cells"
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    hypervisor {
> +        #address-cells = <2>;
> +        #size-cells = <0>;
> +        compatible = "gunyah-hypervisor-1.0", "gunyah-hypervisor";
> +
> +        gunyah-resource-mgr@0 {
> +            compatible = "gunyah-resource-manager-1-0", "gunyah-resource-manager";
> +            interrupts = <GIC_SPI 3 IRQ_TYPE_EDGE_RISING>, /* TX full IRQ */
> +                         <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>; /* RX empty IRQ */
> +            reg = <0x00000000 0x00000000>, <0x00000000 0x00000001>;
> +                  /* TX, RX cap ids */
> +        };
> +    };
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 91d00b00d91c..ef6de7599d98 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8884,6 +8884,7 @@ M:	Elliot Berman <quic_eberman@quicinc.com>
>  M:	Murali Nalajala <quic_mnalajal@quicinc.com>
>  L:	linux-arm-msm@vger.kernel.org
>  S:	Supported
> +F:	Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>  F:	Documentation/virt/gunyah/
>  
>  HABANALABS PCI DRIVER
> -- 
> 2.25.1
> 
>
Elliot Berman Oct. 13, 2022, 11:58 p.m. UTC | #2
On 10/12/2022 8:56 AM, Rob Herring wrote:
> On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
>> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
>> Resource Manager applies a devicetree overlay describing the virtual
>> platform configuration of the guest VM, such as the message queue
>> capability IDs for communicating with the Resource Manager. This
>> information is not otherwise discoverable by a VM: the Gunyah hypervisor
>> core does not provide a direct interface to discover capability IDs nor
>> a way to communicate with RM without having already known the
>> corresponding message queue capability ID. Add the DT bindings that
>> Gunyah adheres for the hypervisor node and message queues.
>>
>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>> ---
>>   .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>>   MAINTAINERS                                   |  1 +
>>   2 files changed, 88 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>> new file mode 100644
>> index 000000000000..f0a14101e2fd
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>> @@ -0,0 +1,87 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Gunyah Hypervisor
>> +
>> +maintainers:
>> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
>> +  - Elliot Berman <quic_eberman@quicinc.com>
>> +
>> +description: |+
>> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
> 
> How you end up with the node (applying an overlay) is not relavent to
> the binding.
> 
>> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
>> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
> 
> Wrap at 80. That is the coding standard still though 100 is deemed
> allowed. And yamllint only complains at 110 because I didn't care to fix
> everyones lines over 100.
> 
>> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
>> +
>> +properties:
>> +  compatible:
>> +    items:
>> +      - const: gunyah-hypervisor-1.0
>> +      - const: gunyah-hypervisor
> 
> 2 compatibles implies a difference between the 2. What's the difference?
> Where does '1.0' come from?
> 

There's no difference. I thought the convention was to have 
device-specific compatible and the generic compatible. "device-specific" 
here would be specific to version of Gunyah since it's software.

We do similar for firmware in the qcom,scm bindings and following that 
principle.

>> +
>> +  "#address-cells":
>> +    description: Number of cells needed to represent 64-bit capability IDs.
>> +    const: 2
>> +
>> +  "#size-cells":
>> +    description: must be 0, because capability IDs are not memory address
>> +                  ranges and do not have a size.
>> +    const: 0
>> +
>> +patternProperties:
>> +  "^gunyah-resource-mgr(@.*)?":
>> +    type: object
>> +    description:
>> +      Resource Manager node which is required to communicate to Resource
>> +      Manager VM using Gunyah Message Queues.
>> +
>> +    properties:
>> +      compatible:
>> +        items:
>> +          - const: gunyah-resource-manager-1-0
>> +          - const: gunyah-resource-manager
> 
> Same comment here.
> 
>> +
>> +      reg:
>> +        items:
>> +          - description: Gunyah capability ID of the TX message queue
>> +          - description: Gunyah capability ID of the RX message queue
>> +
>> +      interrupts:
>> +        items:
>> +          - description: Interrupt for the TX message queue
>> +          - description: Interrupt for the RX message queue
>> +
>> +    additionalProperties: false
>> +
>> +    required:
>> +      - compatible
>> +      - reg
>> +      - interrupts
>> +
>> +additionalProperties: false
>> +
>> +required:
>> +  - compatible
>> +  - "#address-cells"
>> +  - "#size-cells"
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
>> +
>> +    hypervisor {
>> +        #address-cells = <2>;
>> +        #size-cells = <0>;
>> +        compatible = "gunyah-hypervisor-1.0", "gunyah-hypervisor";
>> +
>> +        gunyah-resource-mgr@0 {
>> +            compatible = "gunyah-resource-manager-1-0", "gunyah-resource-manager";
>> +            interrupts = <GIC_SPI 3 IRQ_TYPE_EDGE_RISING>, /* TX full IRQ */
>> +                         <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>; /* RX empty IRQ */
>> +            reg = <0x00000000 0x00000000>, <0x00000000 0x00000001>;
>> +                  /* TX, RX cap ids */
>> +        };
>> +    };
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 91d00b00d91c..ef6de7599d98 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -8884,6 +8884,7 @@ M:	Elliot Berman <quic_eberman@quicinc.com>
>>   M:	Murali Nalajala <quic_mnalajal@quicinc.com>
>>   L:	linux-arm-msm@vger.kernel.org
>>   S:	Supported
>> +F:	Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>   F:	Documentation/virt/gunyah/
>>   
>>   HABANALABS PCI DRIVER
>> -- 
>> 2.25.1
>>
>>
Rob Herring Oct. 26, 2022, 9:16 p.m. UTC | #3
On Thu, Oct 13, 2022 at 6:59 PM Elliot Berman <quic_eberman@quicinc.com> wrote:
>
>
> On 10/12/2022 8:56 AM, Rob Herring wrote:
> > On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
> >> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
> >> Resource Manager applies a devicetree overlay describing the virtual
> >> platform configuration of the guest VM, such as the message queue
> >> capability IDs for communicating with the Resource Manager. This
> >> information is not otherwise discoverable by a VM: the Gunyah hypervisor
> >> core does not provide a direct interface to discover capability IDs nor
> >> a way to communicate with RM without having already known the
> >> corresponding message queue capability ID. Add the DT bindings that
> >> Gunyah adheres for the hypervisor node and message queues.
> >>
> >> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
> >> ---
> >>   .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
> >>   MAINTAINERS                                   |  1 +
> >>   2 files changed, 88 insertions(+)
> >>   create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> >>
> >> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> >> new file mode 100644
> >> index 000000000000..f0a14101e2fd
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
> >> @@ -0,0 +1,87 @@
> >> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
> >> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: Gunyah Hypervisor
> >> +
> >> +maintainers:
> >> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
> >> +  - Elliot Berman <quic_eberman@quicinc.com>
> >> +
> >> +description: |+
> >> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
> >
> > How you end up with the node (applying an overlay) is not relavent to
> > the binding.
> >
> >> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
> >> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
> >
> > Wrap at 80. That is the coding standard still though 100 is deemed
> > allowed. And yamllint only complains at 110 because I didn't care to fix
> > everyones lines over 100.
> >
> >> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
> >> +
> >> +properties:
> >> +  compatible:
> >> +    items:
> >> +      - const: gunyah-hypervisor-1.0
> >> +      - const: gunyah-hypervisor
> >
> > 2 compatibles implies a difference between the 2. What's the difference?
> > Where does '1.0' come from?
> >
>
> There's no difference. I thought the convention was to have
> device-specific compatible and the generic compatible. "device-specific"
> here would be specific to version of Gunyah since it's software.

No, that's just what people do because "vendor,new-soc",
"vendor,old-soc" seems to bother them for some reason. At the end of
the day, it's just a string identifier that means something. If
there's no difference in that 'something', then there is no point in
having more than one string.

You only need something specific enough to discover the rest from the
firmware. When that changes, then you add a new compatible. Of course,
if you want existing OSs to work, then better not change the
compatible.

> We do similar for firmware in the qcom,scm bindings and following that
> principle.

Always poor examples to follow...

Rob
Elliot Berman Oct. 27, 2022, 4:17 p.m. UTC | #4
Hi Rob,

On 10/26/2022 2:16 PM, Rob Herring wrote:
> On Thu, Oct 13, 2022 at 6:59 PM Elliot Berman <quic_eberman@quicinc.com> wrote:
>>
>>
>> On 10/12/2022 8:56 AM, Rob Herring wrote:
>>> On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
>>>> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
>>>> Resource Manager applies a devicetree overlay describing the virtual
>>>> platform configuration of the guest VM, such as the message queue
>>>> capability IDs for communicating with the Resource Manager. This
>>>> information is not otherwise discoverable by a VM: the Gunyah hypervisor
>>>> core does not provide a direct interface to discover capability IDs nor
>>>> a way to communicate with RM without having already known the
>>>> corresponding message queue capability ID. Add the DT bindings that
>>>> Gunyah adheres for the hypervisor node and message queues.
>>>>
>>>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>>>> ---
>>>>    .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>>>>    MAINTAINERS                                   |  1 +
>>>>    2 files changed, 88 insertions(+)
>>>>    create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>> new file mode 100644
>>>> index 000000000000..f0a14101e2fd
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>> @@ -0,0 +1,87 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>> +
>>>> +title: Gunyah Hypervisor
>>>> +
>>>> +maintainers:
>>>> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
>>>> +  - Elliot Berman <quic_eberman@quicinc.com>
>>>> +
>>>> +description: |+
>>>> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
>>>
>>> How you end up with the node (applying an overlay) is not relavent to
>>> the binding.
>>>
>>>> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
>>>> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
>>>
>>> Wrap at 80. That is the coding standard still though 100 is deemed
>>> allowed. And yamllint only complains at 110 because I didn't care to fix
>>> everyones lines over 100.
>>>
>>>> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
>>>> +
>>>> +properties:
>>>> +  compatible:
>>>> +    items:
>>>> +      - const: gunyah-hypervisor-1.0
>>>> +      - const: gunyah-hypervisor
>>>
>>> 2 compatibles implies a difference between the 2. What's the difference?
>>> Where does '1.0' come from?
>>>
>>
>> There's no difference. I thought the convention was to have
>> device-specific compatible and the generic compatible. "device-specific"
>> here would be specific to version of Gunyah since it's software.
> 
> No, that's just what people do because "vendor,new-soc",
> "vendor,old-soc" seems to bother them for some reason. At the end of
> the day, it's just a string identifier that means something. If
> there's no difference in that 'something', then there is no point in
> having more than one string.
> 
> You only need something specific enough to discover the rest from the
> firmware. When that changes, then you add a new compatible. Of course,
> if you want existing OSs to work, then better not change the
> compatible.
> 

Thanks for the info, I'll drop the "-1.0" suffix.
Krzysztof Kozlowski Oct. 27, 2022, 7:55 p.m. UTC | #5
On 27/10/2022 12:17, Elliot Berman wrote:
> Hi Rob,
> 
> On 10/26/2022 2:16 PM, Rob Herring wrote:
>> On Thu, Oct 13, 2022 at 6:59 PM Elliot Berman <quic_eberman@quicinc.com> wrote:
>>>
>>>
>>> On 10/12/2022 8:56 AM, Rob Herring wrote:
>>>> On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
>>>>> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
>>>>> Resource Manager applies a devicetree overlay describing the virtual
>>>>> platform configuration of the guest VM, such as the message queue
>>>>> capability IDs for communicating with the Resource Manager. This
>>>>> information is not otherwise discoverable by a VM: the Gunyah hypervisor
>>>>> core does not provide a direct interface to discover capability IDs nor
>>>>> a way to communicate with RM without having already known the
>>>>> corresponding message queue capability ID. Add the DT bindings that
>>>>> Gunyah adheres for the hypervisor node and message queues.
>>>>>
>>>>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>>>>> ---
>>>>>    .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>>>>>    MAINTAINERS                                   |  1 +
>>>>>    2 files changed, 88 insertions(+)
>>>>>    create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>
>>>>> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>> new file mode 100644
>>>>> index 000000000000..f0a14101e2fd
>>>>> --- /dev/null
>>>>> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>> @@ -0,0 +1,87 @@
>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>> +%YAML 1.2
>>>>> +---
>>>>> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
>>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>>> +
>>>>> +title: Gunyah Hypervisor
>>>>> +
>>>>> +maintainers:
>>>>> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
>>>>> +  - Elliot Berman <quic_eberman@quicinc.com>
>>>>> +
>>>>> +description: |+
>>>>> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
>>>>
>>>> How you end up with the node (applying an overlay) is not relavent to
>>>> the binding.
>>>>
>>>>> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
>>>>> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
>>>>
>>>> Wrap at 80. That is the coding standard still though 100 is deemed
>>>> allowed. And yamllint only complains at 110 because I didn't care to fix
>>>> everyones lines over 100.
>>>>
>>>>> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
>>>>> +
>>>>> +properties:
>>>>> +  compatible:
>>>>> +    items:
>>>>> +      - const: gunyah-hypervisor-1.0
>>>>> +      - const: gunyah-hypervisor
>>>>
>>>> 2 compatibles implies a difference between the 2. What's the difference?
>>>> Where does '1.0' come from?
>>>>
>>>
>>> There's no difference. I thought the convention was to have
>>> device-specific compatible and the generic compatible. "device-specific"
>>> here would be specific to version of Gunyah since it's software.
>>
>> No, that's just what people do because "vendor,new-soc",
>> "vendor,old-soc" seems to bother them for some reason. At the end of
>> the day, it's just a string identifier that means something. If
>> there's no difference in that 'something', then there is no point in
>> having more than one string.
>>
>> You only need something specific enough to discover the rest from the
>> firmware. When that changes, then you add a new compatible. Of course,
>> if you want existing OSs to work, then better not change the
>> compatible.
>>
> 
> Thanks for the info, I'll drop the "-1.0" suffix.

You still did not answer from where does 1.0 come from... Compatibles
are usually expected to be specific.

Best regards,
Krzysztof
Elliot Berman Nov. 1, 2022, 3:19 a.m. UTC | #6
On 10/27/2022 12:55 PM, Krzysztof Kozlowski wrote:
> On 27/10/2022 12:17, Elliot Berman wrote:
>> Hi Rob,
>>
>> On 10/26/2022 2:16 PM, Rob Herring wrote:
>>> On Thu, Oct 13, 2022 at 6:59 PM Elliot Berman <quic_eberman@quicinc.com> wrote:
>>>>
>>>>
>>>> On 10/12/2022 8:56 AM, Rob Herring wrote:
>>>>> On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
>>>>>> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
>>>>>> Resource Manager applies a devicetree overlay describing the virtual
>>>>>> platform configuration of the guest VM, such as the message queue
>>>>>> capability IDs for communicating with the Resource Manager. This
>>>>>> information is not otherwise discoverable by a VM: the Gunyah hypervisor
>>>>>> core does not provide a direct interface to discover capability IDs nor
>>>>>> a way to communicate with RM without having already known the
>>>>>> corresponding message queue capability ID. Add the DT bindings that
>>>>>> Gunyah adheres for the hypervisor node and message queues.
>>>>>>
>>>>>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>>>>>> ---
>>>>>>     .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>>>>>>     MAINTAINERS                                   |  1 +
>>>>>>     2 files changed, 88 insertions(+)
>>>>>>     create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>> new file mode 100644
>>>>>> index 000000000000..f0a14101e2fd
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>> @@ -0,0 +1,87 @@
>>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>>> +%YAML 1.2
>>>>>> +---
>>>>>> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
>>>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>>>> +
>>>>>> +title: Gunyah Hypervisor
>>>>>> +
>>>>>> +maintainers:
>>>>>> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
>>>>>> +  - Elliot Berman <quic_eberman@quicinc.com>
>>>>>> +
>>>>>> +description: |+
>>>>>> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
>>>>>
>>>>> How you end up with the node (applying an overlay) is not relavent to
>>>>> the binding.
>>>>>
>>>>>> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
>>>>>> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
>>>>>
>>>>> Wrap at 80. That is the coding standard still though 100 is deemed
>>>>> allowed. And yamllint only complains at 110 because I didn't care to fix
>>>>> everyones lines over 100.
>>>>>
>>>>>> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
>>>>>> +
>>>>>> +properties:
>>>>>> +  compatible:
>>>>>> +    items:
>>>>>> +      - const: gunyah-hypervisor-1.0
>>>>>> +      - const: gunyah-hypervisor
>>>>>
>>>>> 2 compatibles implies a difference between the 2. What's the difference?
>>>>> Where does '1.0' come from?
>>>>>
>>>>
>>>> There's no difference. I thought the convention was to have
>>>> device-specific compatible and the generic compatible. "device-specific"
>>>> here would be specific to version of Gunyah since it's software.
>>>
>>> No, that's just what people do because "vendor,new-soc",
>>> "vendor,old-soc" seems to bother them for some reason. At the end of
>>> the day, it's just a string identifier that means something. If
>>> there's no difference in that 'something', then there is no point in
>>> having more than one string.
>>>
>>> You only need something specific enough to discover the rest from the
>>> firmware. When that changes, then you add a new compatible. Of course,
>>> if you want existing OSs to work, then better not change the
>>> compatible.
>>>
>>
>> Thanks for the info, I'll drop the "-1.0" suffix.
> 
> You still did not answer from where does 1.0 come from... Compatibles
> are usually expected to be specific.
> 

The 1.0 comes from the Gunyah version. This is the same version returned 
by "hyp_identify" hypercall.
Krzysztof Kozlowski Nov. 2, 2022, 6:47 p.m. UTC | #7
On 31/10/2022 23:19, Elliot Berman wrote:
> 
> 
> On 10/27/2022 12:55 PM, Krzysztof Kozlowski wrote:
>> On 27/10/2022 12:17, Elliot Berman wrote:
>>> Hi Rob,
>>>
>>> On 10/26/2022 2:16 PM, Rob Herring wrote:
>>>> On Thu, Oct 13, 2022 at 6:59 PM Elliot Berman <quic_eberman@quicinc.com> wrote:
>>>>>
>>>>>
>>>>> On 10/12/2022 8:56 AM, Rob Herring wrote:
>>>>>> On Mon, Oct 10, 2022 at 05:08:29PM -0700, Elliot Berman wrote:
>>>>>>> When Linux is booted as a guest under the Gunyah hypervisor, the Gunyah
>>>>>>> Resource Manager applies a devicetree overlay describing the virtual
>>>>>>> platform configuration of the guest VM, such as the message queue
>>>>>>> capability IDs for communicating with the Resource Manager. This
>>>>>>> information is not otherwise discoverable by a VM: the Gunyah hypervisor
>>>>>>> core does not provide a direct interface to discover capability IDs nor
>>>>>>> a way to communicate with RM without having already known the
>>>>>>> corresponding message queue capability ID. Add the DT bindings that
>>>>>>> Gunyah adheres for the hypervisor node and message queues.
>>>>>>>
>>>>>>> Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
>>>>>>> ---
>>>>>>>     .../bindings/firmware/gunyah-hypervisor.yaml  | 87 +++++++++++++++++++
>>>>>>>     MAINTAINERS                                   |  1 +
>>>>>>>     2 files changed, 88 insertions(+)
>>>>>>>     create mode 100644 Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>>>
>>>>>>> diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>>> new file mode 100644
>>>>>>> index 000000000000..f0a14101e2fd
>>>>>>> --- /dev/null
>>>>>>> +++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
>>>>>>> @@ -0,0 +1,87 @@
>>>>>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>>>>>> +%YAML 1.2
>>>>>>> +---
>>>>>>> +$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
>>>>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>>>>> +
>>>>>>> +title: Gunyah Hypervisor
>>>>>>> +
>>>>>>> +maintainers:
>>>>>>> +  - Murali Nalajala <quic_mnalajal@quicinc.com>
>>>>>>> +  - Elliot Berman <quic_eberman@quicinc.com>
>>>>>>> +
>>>>>>> +description: |+
>>>>>>> +  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
>>>>>>
>>>>>> How you end up with the node (applying an overlay) is not relavent to
>>>>>> the binding.
>>>>>>
>>>>>>> +  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
>>>>>>> +  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
>>>>>>
>>>>>> Wrap at 80. That is the coding standard still though 100 is deemed
>>>>>> allowed. And yamllint only complains at 110 because I didn't care to fix
>>>>>> everyones lines over 100.
>>>>>>
>>>>>>> +  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
>>>>>>> +
>>>>>>> +properties:
>>>>>>> +  compatible:
>>>>>>> +    items:
>>>>>>> +      - const: gunyah-hypervisor-1.0
>>>>>>> +      - const: gunyah-hypervisor
>>>>>>
>>>>>> 2 compatibles implies a difference between the 2. What's the difference?
>>>>>> Where does '1.0' come from?
>>>>>>
>>>>>
>>>>> There's no difference. I thought the convention was to have
>>>>> device-specific compatible and the generic compatible. "device-specific"
>>>>> here would be specific to version of Gunyah since it's software.
>>>>
>>>> No, that's just what people do because "vendor,new-soc",
>>>> "vendor,old-soc" seems to bother them for some reason. At the end of
>>>> the day, it's just a string identifier that means something. If
>>>> there's no difference in that 'something', then there is no point in
>>>> having more than one string.
>>>>
>>>> You only need something specific enough to discover the rest from the
>>>> firmware. When that changes, then you add a new compatible. Of course,
>>>> if you want existing OSs to work, then better not change the
>>>> compatible.
>>>>
>>>
>>> Thanks for the info, I'll drop the "-1.0" suffix.
>>
>> You still did not answer from where does 1.0 come from... Compatibles
>> are usually expected to be specific.
>>
> 
> The 1.0 comes from the Gunyah version. This is the same version returned 
> by "hyp_identify" hypercall.

Then dropping 1.0 makes sense - your SW provides auto-detection.

Best regards,
Krzysztof
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
new file mode 100644
index 000000000000..f0a14101e2fd
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
@@ -0,0 +1,87 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/gunyah-hypervisor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Gunyah Hypervisor
+
+maintainers:
+  - Murali Nalajala <quic_mnalajal@quicinc.com>
+  - Elliot Berman <quic_eberman@quicinc.com>
+
+description: |+
+  On systems which support devicetree, Gunyah generates and overlays a deviceetree overlay which
+  describes the basic configuration of the hypervisor. Virtual machines use this information to determine
+  the capability IDs of the message queues used to communicate with the Gunyah Resource Manager.
+  See also: https://github.com/quic/gunyah-resource-manager/blob/develop/src/vm_creation/dto_construct.c
+
+properties:
+  compatible:
+    items:
+      - const: gunyah-hypervisor-1.0
+      - const: gunyah-hypervisor
+
+  "#address-cells":
+    description: Number of cells needed to represent 64-bit capability IDs.
+    const: 2
+
+  "#size-cells":
+    description: must be 0, because capability IDs are not memory address
+                  ranges and do not have a size.
+    const: 0
+
+patternProperties:
+  "^gunyah-resource-mgr(@.*)?":
+    type: object
+    description:
+      Resource Manager node which is required to communicate to Resource
+      Manager VM using Gunyah Message Queues.
+
+    properties:
+      compatible:
+        items:
+          - const: gunyah-resource-manager-1-0
+          - const: gunyah-resource-manager
+
+      reg:
+        items:
+          - description: Gunyah capability ID of the TX message queue
+          - description: Gunyah capability ID of the RX message queue
+
+      interrupts:
+        items:
+          - description: Interrupt for the TX message queue
+          - description: Interrupt for the RX message queue
+
+    additionalProperties: false
+
+    required:
+      - compatible
+      - reg
+      - interrupts
+
+additionalProperties: false
+
+required:
+  - compatible
+  - "#address-cells"
+  - "#size-cells"
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    hypervisor {
+        #address-cells = <2>;
+        #size-cells = <0>;
+        compatible = "gunyah-hypervisor-1.0", "gunyah-hypervisor";
+
+        gunyah-resource-mgr@0 {
+            compatible = "gunyah-resource-manager-1-0", "gunyah-resource-manager";
+            interrupts = <GIC_SPI 3 IRQ_TYPE_EDGE_RISING>, /* TX full IRQ */
+                         <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>; /* RX empty IRQ */
+            reg = <0x00000000 0x00000000>, <0x00000000 0x00000001>;
+                  /* TX, RX cap ids */
+        };
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index 91d00b00d91c..ef6de7599d98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8884,6 +8884,7 @@  M:	Elliot Berman <quic_eberman@quicinc.com>
 M:	Murali Nalajala <quic_mnalajal@quicinc.com>
 L:	linux-arm-msm@vger.kernel.org
 S:	Supported
+F:	Documentation/devicetree/bindings/firmware/gunyah-hypervisor.yaml
 F:	Documentation/virt/gunyah/
 
 HABANALABS PCI DRIVER