[v2,1/3] dt-bindings: clocks: add binding for voltage-controlled-oscillators

Commit Message

Heiko Stuebner July 15, 2024, 11:02 a.m. UTC

In contrast to fixed clocks that are described as ungateable, boards
sometimes use additional oscillators for things like PCIe reference
clocks, that need actual supplies to get enabled and enable-gpios to be
toggled for them to work.

This adds a binding for such oscillators that are not configurable
themself, but need to handle supplies for them to work.

In schematics they often can be seen as

         ----------------
Enable - | 100MHz,3.3V, | - VDD
         |    3225      |
   GND - |              | - OUT
         ----------------

or similar. The enable pin might be separate but can also just be tied
to the vdd supply, hence it is optional in the binding.

Signed-off-by: Heiko Stuebner <[e-mail]>
---
 .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml

Comments

Dragan Simic July 15, 2024, 3:15 p.m. UTC | #1

Hello Heiko,

Please see some comments below.

On 2024-07-15 13:02, Heiko Stuebner wrote:
> In contrast to fixed clocks that are described as ungateable, boards
> sometimes use additional oscillators for things like PCIe reference
> clocks, that need actual supplies to get enabled and enable-gpios to be
> toggled for them to work.
> 
> This adds a binding for such oscillators that are not configurable
> themself, but need to handle supplies for them to work.
> 
> In schematics they often can be seen as
> 
>          ----------------
> Enable - | 100MHz,3.3V, | - VDD
>          |    3225      |
>    GND - |              | - OUT
>          ----------------
> 
> or similar. The enable pin might be separate but can also just be tied
> to the vdd supply, hence it is optional in the binding.
> 
> Signed-off-by: Heiko Stuebner <[e-mail]>
> ---
>  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>  1 file changed, 49 insertions(+)
>  create mode 100644
> Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> 
> diff --git
> a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> new file mode 100644
> index 0000000000000..8bff6b0fd582e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Voltage controlled oscillator

Frankly, I find the "voltage-oscillator" and "voltage controlled
oscillator" names awkward.  In general, "clock" is used throughout
the entire kernel, when it comes to naming files and defining
"compatible" strings.  Thus, I'd suggest that "clock" is used here
instead of "oscillator", because it's consistent and shorter.

How about using "gated-clock" for the "compatible" string, and
"Simple gated clock generator" instead of "voltage controlled
oscillator"?  Besides sounding awkward, "voltage controlled
oscillator" may suggest that the clock generator can be adjusted
or programmed somehow by applying the voltage, while it can only
be enabled or disabled that way, which is by definition clock
gating.  Thus, "gated-clock" and "Simple gated clock generator"
would fit very well.

> +maintainers:
> +  - Heiko Stuebner <[e-mail]>
> +
> +properties:
> +  compatible:
> +    const: voltage-oscillator
> +
> +  "#clock-cells":
> +    const: 0
> +
> +  clock-frequency: true
> +
> +  clock-output-names:
> +    maxItems: 1
> +
> +  enable-gpios:
> +    description:
> +      Contains a single GPIO specifier for the GPIO that enables and 
> disables
> +      the oscillator.
> +    maxItems: 1
> +
> +  vdd-supply:
> +    description: handle of the regulator that provides the supply 
> voltage
> +
> +required:
> +  - compatible
> +  - "#clock-cells"
> +  - clock-frequency
> +  - vdd-supply
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    voltage-oscillator {
> +      compatible = "voltage-oscillator";
> +      #clock-cells = <0>;
> +      clock-frequency = <1000000000>;
> +      vdd-supply = <&reg_vdd>;
> +    };
> +...

Heiko Stuebner July 15, 2024, 5:46 p.m. UTC | #2

Hi Dragan,

Am Montag, 15. Juli 2024, 17:15:45 CEST schrieb Dragan Simic:
> On 2024-07-15 13:02, Heiko Stuebner wrote:
> > In contrast to fixed clocks that are described as ungateable, boards
> > sometimes use additional oscillators for things like PCIe reference
> > clocks, that need actual supplies to get enabled and enable-gpios to be
> > toggled for them to work.
> > 
> > This adds a binding for such oscillators that are not configurable
> > themself, but need to handle supplies for them to work.
> > 
> > In schematics they often can be seen as
> > 
> >          ----------------
> > Enable - | 100MHz,3.3V, | - VDD
> >          |    3225      |
> >    GND - |              | - OUT
> >          ----------------
> > 
> > or similar. The enable pin might be separate but can also just be tied
> > to the vdd supply, hence it is optional in the binding.
> > 
> > Signed-off-by: Heiko Stuebner <[e-mail]>
> > ---
> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> >  1 file changed, 49 insertions(+)
> >  create mode 100644
> > Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > 
> > diff --git
> > a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > new file mode 100644
> > index 0000000000000..8bff6b0fd582e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > @@ -0,0 +1,49 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Voltage controlled oscillator
> 
> Frankly, I find the "voltage-oscillator" and "voltage controlled
> oscillator" names awkward.  In general, "clock" is used throughout
> the entire kernel, when it comes to naming files and defining
> "compatible" strings.  Thus, I'd suggest that "clock" is used here
> instead of "oscillator", because it's consistent and shorter.
>
> How about using "gated-clock" for the "compatible" string, and
> "Simple gated clock generator" instead of "voltage controlled
> oscillator"?  Besides sounding awkward, "voltage controlled
> oscillator" may suggest that the clock generator can be adjusted
> or programmed somehow by applying the voltage, while it can only
> be enabled or disabled that way, which is by definition clock
> gating.  Thus, "gated-clock" and "Simple gated clock generator"
> would fit very well.

The naming came from Stephen - one of the clock maintainers ;-)
See discussion in v1. Who also described these things as
"voltage-controlled-oscillators".

And from that discussion I also got the impression we should aim for
more specific naming - especially when talking about dt-bindings, for this
"usage in the Linux kernel" actually isn't a suitable metric and
"gated-clock" is probably way too generic I think.

Though I'm not attached to any specific naming, so we'll simply
wait for the clock- and dt-maintainers to weigh in ;-)


Heiko

Dragan Simic July 15, 2024, 6:01 p.m. UTC | #3

On 2024-07-15 19:46, Heiko Stübner wrote:
> Am Montag, 15. Juli 2024, 17:15:45 CEST schrieb Dragan Simic:
>> On 2024-07-15 13:02, Heiko Stuebner wrote:
>> > In contrast to fixed clocks that are described as ungateable, boards
>> > sometimes use additional oscillators for things like PCIe reference
>> > clocks, that need actual supplies to get enabled and enable-gpios to be
>> > toggled for them to work.
>> >
>> > This adds a binding for such oscillators that are not configurable
>> > themself, but need to handle supplies for them to work.
>> >
>> > In schematics they often can be seen as
>> >
>> >          ----------------
>> > Enable - | 100MHz,3.3V, | - VDD
>> >          |    3225      |
>> >    GND - |              | - OUT
>> >          ----------------
>> >
>> > or similar. The enable pin might be separate but can also just be tied
>> > to the vdd supply, hence it is optional in the binding.
>> >
>> > Signed-off-by: Heiko Stuebner <[e-mail]>
>> > ---
>> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>> >  1 file changed, 49 insertions(+)
>> >  create mode 100644
>> > Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >
>> > diff --git
>> > a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> > b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> > new file mode 100644
>> > index 0000000000000..8bff6b0fd582e
>> > --- /dev/null
>> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> > @@ -0,0 +1,49 @@
>> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> > +%YAML 1.2
>> > +---
>> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> > +
>> > +title: Voltage controlled oscillator
>> 
>> Frankly, I find the "voltage-oscillator" and "voltage controlled
>> oscillator" names awkward.  In general, "clock" is used throughout
>> the entire kernel, when it comes to naming files and defining
>> "compatible" strings.  Thus, I'd suggest that "clock" is used here
>> instead of "oscillator", because it's consistent and shorter.
>> 
>> How about using "gated-clock" for the "compatible" string, and
>> "Simple gated clock generator" instead of "voltage controlled
>> oscillator"?  Besides sounding awkward, "voltage controlled
>> oscillator" may suggest that the clock generator can be adjusted
>> or programmed somehow by applying the voltage, while it can only
>> be enabled or disabled that way, which is by definition clock
>> gating.  Thus, "gated-clock" and "Simple gated clock generator"
>> would fit very well.
> 
> The naming came from Stephen - one of the clock maintainers ;-)
> See discussion in v1. Who also described these things as
> "voltage-controlled-oscillators".
> 
> And from that discussion I also got the impression we should aim for
> more specific naming - especially when talking about dt-bindings, for 
> this
> "usage in the Linux kernel" actually isn't a suitable metric and
> "gated-clock" is probably way too generic I think.

I see, thanks for the clarification.  Though, the generic nature of
"gated-clock" as the name may actually make this driver a bit more
future-proof, by allowing some other features to be added to it at
some point in the future, avoiding that way the need for yet another
kernel driver.

> Though I'm not attached to any specific naming, so we'll simply
> wait for the clock- and dt-maintainers to weigh in ;-)

Heiko Stuebner July 15, 2024, 7:13 p.m. UTC | #4

Am Montag, 15. Juli 2024, 20:01:35 CEST schrieb Dragan Simic:
> On 2024-07-15 19:46, Heiko Stübner wrote:
> > Am Montag, 15. Juli 2024, 17:15:45 CEST schrieb Dragan Simic:
> >> On 2024-07-15 13:02, Heiko Stuebner wrote:
> >> > In contrast to fixed clocks that are described as ungateable, boards
> >> > sometimes use additional oscillators for things like PCIe reference
> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
> >> > toggled for them to work.
> >> >
> >> > This adds a binding for such oscillators that are not configurable
> >> > themself, but need to handle supplies for them to work.
> >> >
> >> > In schematics they often can be seen as
> >> >
> >> >          ----------------
> >> > Enable - | 100MHz,3.3V, | - VDD
> >> >          |    3225      |
> >> >    GND - |              | - OUT
> >> >          ----------------
> >> >
> >> > or similar. The enable pin might be separate but can also just be tied
> >> > to the vdd supply, hence it is optional in the binding.
> >> >
> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
> >> > ---
> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> >> >  1 file changed, 49 insertions(+)
> >> >  create mode 100644
> >> > Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> >
> >> > diff --git
> >> > a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> > b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> > new file mode 100644
> >> > index 0000000000000..8bff6b0fd582e
> >> > --- /dev/null
> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> > @@ -0,0 +1,49 @@
> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> > +%YAML 1.2
> >> > +---
> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> > +
> >> > +title: Voltage controlled oscillator
> >> 
> >> Frankly, I find the "voltage-oscillator" and "voltage controlled
> >> oscillator" names awkward.  In general, "clock" is used throughout
> >> the entire kernel, when it comes to naming files and defining
> >> "compatible" strings.  Thus, I'd suggest that "clock" is used here
> >> instead of "oscillator", because it's consistent and shorter.
> >> 
> >> How about using "gated-clock" for the "compatible" string, and
> >> "Simple gated clock generator" instead of "voltage controlled
> >> oscillator"?  Besides sounding awkward, "voltage controlled
> >> oscillator" may suggest that the clock generator can be adjusted
> >> or programmed somehow by applying the voltage, while it can only
> >> be enabled or disabled that way, which is by definition clock
> >> gating.  Thus, "gated-clock" and "Simple gated clock generator"
> >> would fit very well.
> > 
> > The naming came from Stephen - one of the clock maintainers ;-)
> > See discussion in v1. Who also described these things as
> > "voltage-controlled-oscillators".
> > 
> > And from that discussion I also got the impression we should aim for
> > more specific naming - especially when talking about dt-bindings, for 
> > this
> > "usage in the Linux kernel" actually isn't a suitable metric and
> > "gated-clock" is probably way too generic I think.
> 
> I see, thanks for the clarification.  Though, the generic nature of
> "gated-clock" as the name may actually make this driver a bit more
> future-proof, by allowing some other features to be added to it at
> some point in the future, avoiding that way the need for yet another
> kernel driver.

you're talking about the driver ... we're in the hardware-binding here.
Those are two completely different topics ;-) .

Devicetree is always about describing the hardware as best as possible,
so you don't want too many "generics" there, because we're always talking
about specific ICs soldered to some board.

I also "violated" that in my v1 by grouping in the the Diodes parts, which
as Stephen pointed out are quite different afterall.


Heiko

Conor Dooley July 16, 2024, 4:15 p.m. UTC | #5

On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
> In contrast to fixed clocks that are described as ungateable, boards
> sometimes use additional oscillators for things like PCIe reference
> clocks, that need actual supplies to get enabled and enable-gpios to be
> toggled for them to work.
> 
> This adds a binding for such oscillators that are not configurable
> themself, but need to handle supplies for them to work.
> 
> In schematics they often can be seen as
> 
>          ----------------
> Enable - | 100MHz,3.3V, | - VDD
>          |    3225      |
>    GND - |              | - OUT
>          ----------------
> 
> or similar. The enable pin might be separate but can also just be tied
> to the vdd supply, hence it is optional in the binding.
> 
> Signed-off-by: Heiko Stuebner <[e-mail]>
> ---
>  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>  1 file changed, 49 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> 
> diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> new file mode 100644
> index 0000000000000..8bff6b0fd582e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Voltage controlled oscillator

Voltage controlled oscillator? Really? That sounds far too similar to a
VCO to me, and the input voltage here (according to the description at
least) does not affect the frequency of oscillation.

Why the dedicated binding, rather than adding a supply and enable-gpio
to the existing "fixed-clock" binding? I suspect that a large portion of
"fixed-clock"s actually require a supply that is (effectively)
always-on.

Cheers,
Conor.

> +
> +maintainers:
> +  - Heiko Stuebner <[e-mail]>
> +
> +properties:
> +  compatible:
> +    const: voltage-oscillator
> +
> +  "#clock-cells":
> +    const: 0
> +
> +  clock-frequency: true
> +
> +  clock-output-names:
> +    maxItems: 1
> +
> +  enable-gpios:
> +    description:
> +      Contains a single GPIO specifier for the GPIO that enables and disables
> +      the oscillator.
> +    maxItems: 1
> +
> +  vdd-supply:
> +    description: handle of the regulator that provides the supply voltage
> +
> +required:
> +  - compatible
> +  - "#clock-cells"
> +  - clock-frequency
> +  - vdd-supply
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    voltage-oscillator {
> +      compatible = "voltage-oscillator";
> +      #clock-cells = <0>;
> +      clock-frequency = <1000000000>;
> +      vdd-supply = <&reg_vdd>;
> +    };
> +...
> -- 
> 2.39.2
>

Dragan Simic July 16, 2024, 5:54 p.m. UTC | #6

Hello Conor,

On 2024-07-16 18:15, Conor Dooley wrote:
> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
>> In contrast to fixed clocks that are described as ungateable, boards
>> sometimes use additional oscillators for things like PCIe reference
>> clocks, that need actual supplies to get enabled and enable-gpios to 
>> be
>> toggled for them to work.
>> 
>> This adds a binding for such oscillators that are not configurable
>> themself, but need to handle supplies for them to work.
>> 
>> In schematics they often can be seen as
>> 
>>          ----------------
>> Enable - | 100MHz,3.3V, | - VDD
>>          |    3225      |
>>    GND - |              | - OUT
>>          ----------------
>> 
>> or similar. The enable pin might be separate but can also just be tied
>> to the vdd supply, hence it is optional in the binding.
>> 
>> Signed-off-by: Heiko Stuebner <[e-mail]>
>> ---
>>  .../bindings/clock/voltage-oscillator.yaml    | 49 
>> +++++++++++++++++++
>>  1 file changed, 49 insertions(+)
>>  create mode 100644 
>> Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> 
>> diff --git 
>> a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml 
>> b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> new file mode 100644
>> index 0000000000000..8bff6b0fd582e
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> @@ -0,0 +1,49 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Voltage controlled oscillator
> 
> Voltage controlled oscillator? Really? That sounds far too similar to a
> VCO to me, and the input voltage here (according to the description at
> least) does not affect the frequency of oscillation.

Yup, "voltage controlled oscillator" really isn't the right choice for
the name, as I wrote about already. [1]

[1] 
https://lore.kernel.org/linux-rockchip/[e-mail]/

> Why the dedicated binding, rather than adding a supply and enable-gpio
> to the existing "fixed-clock" binding? I suspect that a large portion 
> of
> "fixed-clock"s actually require a supply that is (effectively)
> always-on.
> 
>> +
>> +maintainers:
>> +  - Heiko Stuebner <[e-mail]>
>> +
>> +properties:
>> +  compatible:
>> +    const: voltage-oscillator
>> +
>> +  "#clock-cells":
>> +    const: 0
>> +
>> +  clock-frequency: true
>> +
>> +  clock-output-names:
>> +    maxItems: 1
>> +
>> +  enable-gpios:
>> +    description:
>> +      Contains a single GPIO specifier for the GPIO that enables and 
>> disables
>> +      the oscillator.
>> +    maxItems: 1
>> +
>> +  vdd-supply:
>> +    description: handle of the regulator that provides the supply 
>> voltage
>> +
>> +required:
>> +  - compatible
>> +  - "#clock-cells"
>> +  - clock-frequency
>> +  - vdd-supply
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    voltage-oscillator {
>> +      compatible = "voltage-oscillator";
>> +      #clock-cells = <0>;
>> +      clock-frequency = <1000000000>;
>> +      vdd-supply = <&reg_vdd>;
>> +    };
>> +...
>> --
>> 2.39.2
>> 
> 
> _______________________________________________
> Linux-rockchip mailing list
> [e-mail]
> http://lists.infradead.org/mailman/listinfo/linux-rockchip

Dragan Simic July 16, 2024, 8:11 p.m. UTC | #7

Hello Heiko,

On 2024-07-15 21:13, Heiko Stübner wrote:
> Am Montag, 15. Juli 2024, 20:01:35 CEST schrieb Dragan Simic:
>> On 2024-07-15 19:46, Heiko Stübner wrote:
>> > Am Montag, 15. Juli 2024, 17:15:45 CEST schrieb Dragan Simic:
>> >> On 2024-07-15 13:02, Heiko Stuebner wrote:
>> >> > In contrast to fixed clocks that are described as ungateable, boards
>> >> > sometimes use additional oscillators for things like PCIe reference
>> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
>> >> > toggled for them to work.
>> >> >
>> >> > This adds a binding for such oscillators that are not configurable
>> >> > themself, but need to handle supplies for them to work.
>> >> >
>> >> > In schematics they often can be seen as
>> >> >
>> >> >          ----------------
>> >> > Enable - | 100MHz,3.3V, | - VDD
>> >> >          |    3225      |
>> >> >    GND - |              | - OUT
>> >> >          ----------------
>> >> >
>> >> > or similar. The enable pin might be separate but can also just be tied
>> >> > to the vdd supply, hence it is optional in the binding.
>> >> >
>> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
>> >> > ---
>> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>> >> >  1 file changed, 49 insertions(+)
>> >> >  create mode 100644
>> >> > Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> >
>> >> > diff --git
>> >> > a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> > b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> > new file mode 100644
>> >> > index 0000000000000..8bff6b0fd582e
>> >> > --- /dev/null
>> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> > @@ -0,0 +1,49 @@
>> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> >> > +%YAML 1.2
>> >> > +---
>> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> >> > +
>> >> > +title: Voltage controlled oscillator
>> >>
>> >> Frankly, I find the "voltage-oscillator" and "voltage controlled
>> >> oscillator" names awkward.  In general, "clock" is used throughout
>> >> the entire kernel, when it comes to naming files and defining
>> >> "compatible" strings.  Thus, I'd suggest that "clock" is used here
>> >> instead of "oscillator", because it's consistent and shorter.
>> >>
>> >> How about using "gated-clock" for the "compatible" string, and
>> >> "Simple gated clock generator" instead of "voltage controlled
>> >> oscillator"?  Besides sounding awkward, "voltage controlled
>> >> oscillator" may suggest that the clock generator can be adjusted
>> >> or programmed somehow by applying the voltage, while it can only
>> >> be enabled or disabled that way, which is by definition clock
>> >> gating.  Thus, "gated-clock" and "Simple gated clock generator"
>> >> would fit very well.
>> >
>> > The naming came from Stephen - one of the clock maintainers ;-)
>> > See discussion in v1. Who also described these things as
>> > "voltage-controlled-oscillators".
>> >
>> > And from that discussion I also got the impression we should aim for
>> > more specific naming - especially when talking about dt-bindings, for
>> > this
>> > "usage in the Linux kernel" actually isn't a suitable metric and
>> > "gated-clock" is probably way too generic I think.
>> 
>> I see, thanks for the clarification.  Though, the generic nature of
>> "gated-clock" as the name may actually make this driver a bit more
>> future-proof, by allowing some other features to be added to it at
>> some point in the future, avoiding that way the need for yet another
>> kernel driver.
> 
> you're talking about the driver ... we're in the hardware-binding here.
> Those are two completely different topics ;-) .
> 
> Devicetree is always about describing the hardware as best as possible,
> so you don't want too many "generics" there, because we're always 
> talking
> about specific ICs soldered to some board.
> 
> I also "violated" that in my v1 by grouping in the the Diodes parts, 
> which
> as Stephen pointed out are quite different afterall.

I'll make sure to go through the v1 discussion in detail ASAP.  After
that, I'll come back with some more thoughts.

Heiko Stuebner July 18, 2024, 9:25 a.m. UTC | #8

Hi Conor,

Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
> > In contrast to fixed clocks that are described as ungateable, boards
> > sometimes use additional oscillators for things like PCIe reference
> > clocks, that need actual supplies to get enabled and enable-gpios to be
> > toggled for them to work.
> > 
> > This adds a binding for such oscillators that are not configurable
> > themself, but need to handle supplies for them to work.
> > 
> > In schematics they often can be seen as
> > 
> >          ----------------
> > Enable - | 100MHz,3.3V, | - VDD
> >          |    3225      |
> >    GND - |              | - OUT
> >          ----------------
> > 
> > or similar. The enable pin might be separate but can also just be tied
> > to the vdd supply, hence it is optional in the binding.
> > 
> > Signed-off-by: Heiko Stuebner <[e-mail]>
> > ---
> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> >  1 file changed, 49 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > new file mode 100644
> > index 0000000000000..8bff6b0fd582e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > @@ -0,0 +1,49 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Voltage controlled oscillator
> 
> Voltage controlled oscillator? Really? That sounds far too similar to a
> VCO to me, and the input voltage here (according to the description at
> least) does not affect the frequency of oscillation.

That naming was suggested by Stephen in v1 [0] .

Of course the schematics for the board I have only describe it as
"100MHz,3.3V,3225" , thumbing through some mouser parts matching that
only mentions "supply voltage" in their datasheets but not a dependency
between rate and voltage.

[0] https://lore.kernel.org/linux-arm-kernel/[e-mail]/

> Why the dedicated binding, rather than adding a supply and enable-gpio
> to the existing "fixed-clock" binding? I suspect that a large portion of
> "fixed-clock"s actually require a supply that is (effectively)
> always-on.

I guess there are three aspects:
- I do remember discussions in the past about not extending generic
  bindings with device-specific stuff. I think generic power-sequences
  were the topic back then, though that might have changed over time?
- There are places that describe "fixed-clock" as
  "basic fixed-rate clock that cannot gate" [1]
- Stephen also suggested a separate binding [2]

With the fixed-clock being sort of the root for everything else on most
systems, I opted to leave it alone. I guess if the consenus really is that
this should go there, I can move it, but discussion in v1 

Interestingly the fixed clock had a gpios property 10 years ago [3] :-) .

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
[2] https://lore.kernel.org/linux-arm-kernel/[e-mail]/
[3] https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t


Heiko


> > +
> > +maintainers:
> > +  - Heiko Stuebner <[e-mail]>
> > +
> > +properties:
> > +  compatible:
> > +    const: voltage-oscillator
> > +
> > +  "#clock-cells":
> > +    const: 0
> > +
> > +  clock-frequency: true
> > +
> > +  clock-output-names:
> > +    maxItems: 1
> > +
> > +  enable-gpios:
> > +    description:
> > +      Contains a single GPIO specifier for the GPIO that enables and disables
> > +      the oscillator.
> > +    maxItems: 1
> > +
> > +  vdd-supply:
> > +    description: handle of the regulator that provides the supply voltage
> > +
> > +required:
> > +  - compatible
> > +  - "#clock-cells"
> > +  - clock-frequency
> > +  - vdd-supply
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    voltage-oscillator {
> > +      compatible = "voltage-oscillator";
> > +      #clock-cells = <0>;
> > +      clock-frequency = <1000000000>;
> > +      vdd-supply = <&reg_vdd>;
> > +    };
> > +...
>

Dragan Simic July 18, 2024, 10:53 a.m. UTC | #9

Hello all,

On 2024-07-18 11:25, Heiko Stübner wrote:
> Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
>> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
>> > In contrast to fixed clocks that are described as ungateable, boards
>> > sometimes use additional oscillators for things like PCIe reference
>> > clocks, that need actual supplies to get enabled and enable-gpios to be
>> > toggled for them to work.
>> >
>> > This adds a binding for such oscillators that are not configurable
>> > themself, but need to handle supplies for them to work.
>> >
>> > In schematics they often can be seen as
>> >
>> >          ----------------
>> > Enable - | 100MHz,3.3V, | - VDD
>> >          |    3225      |
>> >    GND - |              | - OUT
>> >          ----------------
>> >
>> > or similar. The enable pin might be separate but can also just be tied
>> > to the vdd supply, hence it is optional in the binding.
>> >
>> > Signed-off-by: Heiko Stuebner <[e-mail]>
>> > ---
>> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>> >  1 file changed, 49 insertions(+)
>> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >
>> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> > new file mode 100644
>> > index 0000000000000..8bff6b0fd582e
>> > --- /dev/null
>> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> > @@ -0,0 +1,49 @@
>> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> > +%YAML 1.2
>> > +---
>> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> > +
>> > +title: Voltage controlled oscillator
>> 
>> Voltage controlled oscillator? Really? That sounds far too similar to 
>> a
>> VCO to me, and the input voltage here (according to the description at
>> least) does not affect the frequency of oscillation.
> 
> That naming was suggested by Stephen in v1 [0] .
> 
> Of course the schematics for the board I have only describe it as
> "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
> only mentions "supply voltage" in their datasheets but not a dependency
> between rate and voltage.
> 
> [0] 
> https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> 
>> Why the dedicated binding, rather than adding a supply and enable-gpio
>> to the existing "fixed-clock" binding? I suspect that a large portion 
>> of
>> "fixed-clock"s actually require a supply that is (effectively)
>> always-on.
> 
> I guess there are three aspects:
> - I do remember discussions in the past about not extending generic
>   bindings with device-specific stuff. I think generic power-sequences
>   were the topic back then, though that might have changed over time?
> - There are places that describe "fixed-clock" as
>   "basic fixed-rate clock that cannot gate" [1]
> - Stephen also suggested a separate binding [2]
> 
> With the fixed-clock being sort of the root for everything else on most
> systems, I opted to leave it alone. I guess if the consenus really is 
> that
> this should go there, I can move it, but discussion in v1
> 
> Interestingly the fixed clock had a gpios property 10 years ago [3] :-) 
> .
> 
> [1] 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
> [2] 
> https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> [3] 
> https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t

After finally going through the v1 discussion [4] in detail,
here are my further thoughts:

- I agree with dropping the Diodes stuff, [5] because I see
   no need for that at this point;  though, am I missing
   something, where are they actually used?

- I agree that "enable-gpios" and "vdd-supply" should be
   required in the binding, [5] because that's the basis for
   something to be actually represented this way

- I agree that it should be better not to touch fixed-clock
   at this point, simply because it's used in very many places,
   and because in this case we need more than it requires (see
   the bullet point above)

- As I wrote already, [6] I highly disagree with this being
   called voltage-controlled oscillator (VCO), [7] simply
   because it isn't a VCO, but a clock that can be gated;
   though, looking forward to what the last bullet point
   asks to be clarified further

- I still think that gated-clock is the best choice for the
   name, because it uses "clock" that's used throughout the
   entire codebase, and uses "gated" to reflect the nature
   of the clock generator

- Maybe we could actually use fixed-gated-clock as the name,
   which would make more sense from the stanpoint of possibly
   merging it into fixed-clock at some point, but I'd like
   to hear first what's actually going on with the Diodes
   stuff that was deleted in v2, which I already asked about
   in the first bullet point

[4] 
https://lore.kernel.org/linux-rockchip/[e-mail]/T/#u
[5] 
https://lore.kernel.org/linux-rockchip/[e-mail]/
[6] 
https://lore.kernel.org/linux-rockchip/[e-mail]/
[7] 
https://lore.kernel.org/linux-rockchip/[e-mail]/

>> > +
>> > +maintainers:
>> > +  - Heiko Stuebner <[e-mail]>
>> > +
>> > +properties:
>> > +  compatible:
>> > +    const: voltage-oscillator
>> > +
>> > +  "#clock-cells":
>> > +    const: 0
>> > +
>> > +  clock-frequency: true
>> > +
>> > +  clock-output-names:
>> > +    maxItems: 1
>> > +
>> > +  enable-gpios:
>> > +    description:
>> > +      Contains a single GPIO specifier for the GPIO that enables and disables
>> > +      the oscillator.
>> > +    maxItems: 1
>> > +
>> > +  vdd-supply:
>> > +    description: handle of the regulator that provides the supply voltage
>> > +
>> > +required:
>> > +  - compatible
>> > +  - "#clock-cells"
>> > +  - clock-frequency
>> > +  - vdd-supply
>> > +
>> > +additionalProperties: false
>> > +
>> > +examples:
>> > +  - |
>> > +    voltage-oscillator {
>> > +      compatible = "voltage-oscillator";
>> > +      #clock-cells = <0>;
>> > +      clock-frequency = <1000000000>;
>> > +      vdd-supply = <&reg_vdd>;
>> > +    };
>> > +...

Heiko Stuebner July 18, 2024, 11:30 a.m. UTC | #10

Hi Dragan,

Am Donnerstag, 18. Juli 2024, 12:53:07 CEST schrieb Dragan Simic:
> On 2024-07-18 11:25, Heiko Stübner wrote:
> > Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
> >> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
> >> > In contrast to fixed clocks that are described as ungateable, boards
> >> > sometimes use additional oscillators for things like PCIe reference
> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
> >> > toggled for them to work.
> >> >
> >> > This adds a binding for such oscillators that are not configurable
> >> > themself, but need to handle supplies for them to work.
> >> >
> >> > In schematics they often can be seen as
> >> >
> >> >          ----------------
> >> > Enable - | 100MHz,3.3V, | - VDD
> >> >          |    3225      |
> >> >    GND - |              | - OUT
> >> >          ----------------
> >> >
> >> > or similar. The enable pin might be separate but can also just be tied
> >> > to the vdd supply, hence it is optional in the binding.
> >> >
> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
> >> > ---
> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> >> >  1 file changed, 49 insertions(+)
> >> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> >
> >> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> > new file mode 100644
> >> > index 0000000000000..8bff6b0fd582e
> >> > --- /dev/null
> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> > @@ -0,0 +1,49 @@
> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> > +%YAML 1.2
> >> > +---
> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> > +
> >> > +title: Voltage controlled oscillator
> >> 
> >> Voltage controlled oscillator? Really? That sounds far too similar to 
> >> a
> >> VCO to me, and the input voltage here (according to the description at
> >> least) does not affect the frequency of oscillation.
> > 
> > That naming was suggested by Stephen in v1 [0] .
> > 
> > Of course the schematics for the board I have only describe it as
> > "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
> > only mentions "supply voltage" in their datasheets but not a dependency
> > between rate and voltage.
> > 
> > [0] 
> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> > 
> >> Why the dedicated binding, rather than adding a supply and enable-gpio
> >> to the existing "fixed-clock" binding? I suspect that a large portion 
> >> of
> >> "fixed-clock"s actually require a supply that is (effectively)
> >> always-on.
> > 
> > I guess there are three aspects:
> > - I do remember discussions in the past about not extending generic
> >   bindings with device-specific stuff. I think generic power-sequences
> >   were the topic back then, though that might have changed over time?
> > - There are places that describe "fixed-clock" as
> >   "basic fixed-rate clock that cannot gate" [1]
> > - Stephen also suggested a separate binding [2]
> > 
> > With the fixed-clock being sort of the root for everything else on most
> > systems, I opted to leave it alone. I guess if the consenus really is 
> > that
> > this should go there, I can move it, but discussion in v1
> > 
> > Interestingly the fixed clock had a gpios property 10 years ago [3] :-) 
> > .
> > 
> > [1] 
> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
> > [2] 
> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> > [3] 
> > https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t
> 
> After finally going through the v1 discussion [4] in detail,
> here are my further thoughts:
> 
> - I agree with dropping the Diodes stuff, [5] because I see
>    no need for that at this point;  though, am I missing
>    something, where are they actually used?

On the Rock5 ITX that 100MHz clock comes the one single oscillator thing.

The Diodes parts are not root sources for their clocks but instead sort
PLLs or something, though their manual describes them as
"clock generator supporting PCI Express and Ethernet requirements" [8]

So they generate the 100MHz (frequency actually is
selected by input pins of the chip) from a separate 25MHz source clock.

One example are the Theobroma/Cherry embedded boards changed in v1 where
they currently are described via existing generic things (no schematics).

Another user is the rk3568-rock3b for example, where the diodes part
is enabled by the same rail as the port itself, so in contrast to the
Rock 5 ITX, it works "by accident" on the rock 3b [9]


The interesting part of the Diodes ICs is that they actually allow
configuration of the generated frequency via their S0 + S1 pins,
though they might be statically set in the board layout without
being user configurable. (Rock3b does it this way for example)


> - I agree that "enable-gpios" and "vdd-supply" should be
>    required in the binding, [5] because that's the basis for
>    something to be actually represented this way

I would only require the vdd supply though.

On the Rock 5 ITX, the chip does have an enable-gpio input, but that is
tied directly to the voltage rail and is not user controllable.


> - I agree that it should be better not to touch fixed-clock
>    at this point, simply because it's used in very many places,
>    and because in this case we need more than it requires (see
>    the bullet point above)
> 
> - As I wrote already, [6] I highly disagree with this being
>    called voltage-controlled oscillator (VCO), [7] simply
>    because it isn't a VCO, but a clock that can be gated;
>    though, looking forward to what the last bullet point
>    asks to be clarified further
> 
> - I still think that gated-clock is the best choice for the
>    name, because it uses "clock" that's used throughout the
>    entire codebase, and uses "gated" to reflect the nature
>    of the clock generator

"gated-oscillator" perhaps? 

This would make it more explicit that we're talking about a root
for clock signals. "gated-clock" can be anything, in the middle
of a clock tree. Having a very generic name, also invites misuse.


> - Maybe we could actually use fixed-gated-clock as the name,
>    which would make more sense from the stanpoint of possibly
>    merging it into fixed-clock at some point, but I'd like
>    to hear first what's actually going on with the Diodes
>    stuff that was deleted in v2, which I already asked about
>    in the first bullet point
> 
> [4] 
> https://lore.kernel.org/linux-rockchip/[e-mail]/T/#u
> [5] 
> https://lore.kernel.org/linux-rockchip/[e-mail]/
> [6] 
> https://lore.kernel.org/linux-rockchip/[e-mail]/
> [7] 
> https://lore.kernel.org/linux-rockchip/[e-mail]/

[8] https://www.diodes.com/assets/Datasheets/PI6C557-03.pdf
[9] https://dl.radxa.com/rock3/docs/hw/3b/Radxa_ROCK_3B_V1.51_SCH.pdf
    page 31, bottom left of the page


> >> > +
> >> > +maintainers:
> >> > +  - Heiko Stuebner <[e-mail]>
> >> > +
> >> > +properties:
> >> > +  compatible:
> >> > +    const: voltage-oscillator
> >> > +
> >> > +  "#clock-cells":
> >> > +    const: 0
> >> > +
> >> > +  clock-frequency: true
> >> > +
> >> > +  clock-output-names:
> >> > +    maxItems: 1
> >> > +
> >> > +  enable-gpios:
> >> > +    description:
> >> > +      Contains a single GPIO specifier for the GPIO that enables and disables
> >> > +      the oscillator.
> >> > +    maxItems: 1
> >> > +
> >> > +  vdd-supply:
> >> > +    description: handle of the regulator that provides the supply voltage
> >> > +
> >> > +required:
> >> > +  - compatible
> >> > +  - "#clock-cells"
> >> > +  - clock-frequency
> >> > +  - vdd-supply
> >> > +
> >> > +additionalProperties: false
> >> > +
> >> > +examples:
> >> > +  - |
> >> > +    voltage-oscillator {
> >> > +      compatible = "voltage-oscillator";
> >> > +      #clock-cells = <0>;
> >> > +      clock-frequency = <1000000000>;
> >> > +      vdd-supply = <&reg_vdd>;
> >> > +    };
> >> > +...
>

Dragan Simic July 18, 2024, 1 p.m. UTC | #11

Hello Heiko,

On 2024-07-18 13:30, Heiko Stübner wrote:
> Am Donnerstag, 18. Juli 2024, 12:53:07 CEST schrieb Dragan Simic:
>> On 2024-07-18 11:25, Heiko Stübner wrote:
>> > Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
>> >> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
>> >> > In contrast to fixed clocks that are described as ungateable, boards
>> >> > sometimes use additional oscillators for things like PCIe reference
>> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
>> >> > toggled for them to work.
>> >> >
>> >> > This adds a binding for such oscillators that are not configurable
>> >> > themself, but need to handle supplies for them to work.
>> >> >
>> >> > In schematics they often can be seen as
>> >> >
>> >> >          ----------------
>> >> > Enable - | 100MHz,3.3V, | - VDD
>> >> >          |    3225      |
>> >> >    GND - |              | - OUT
>> >> >          ----------------
>> >> >
>> >> > or similar. The enable pin might be separate but can also just be tied
>> >> > to the vdd supply, hence it is optional in the binding.
>> >> >
>> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
>> >> > ---
>> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>> >> >  1 file changed, 49 insertions(+)
>> >> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> >
>> >> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> > new file mode 100644
>> >> > index 0000000000000..8bff6b0fd582e
>> >> > --- /dev/null
>> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> > @@ -0,0 +1,49 @@
>> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> >> > +%YAML 1.2
>> >> > +---
>> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> >> > +
>> >> > +title: Voltage controlled oscillator
>> >>
>> >> Voltage controlled oscillator? Really? That sounds far too similar to
>> >> a
>> >> VCO to me, and the input voltage here (according to the description at
>> >> least) does not affect the frequency of oscillation.
>> >
>> > That naming was suggested by Stephen in v1 [0] .
>> >
>> > Of course the schematics for the board I have only describe it as
>> > "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
>> > only mentions "supply voltage" in their datasheets but not a dependency
>> > between rate and voltage.
>> >
>> > [0]
>> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
>> >
>> >> Why the dedicated binding, rather than adding a supply and enable-gpio
>> >> to the existing "fixed-clock" binding? I suspect that a large portion
>> >> of
>> >> "fixed-clock"s actually require a supply that is (effectively)
>> >> always-on.
>> >
>> > I guess there are three aspects:
>> > - I do remember discussions in the past about not extending generic
>> >   bindings with device-specific stuff. I think generic power-sequences
>> >   were the topic back then, though that might have changed over time?
>> > - There are places that describe "fixed-clock" as
>> >   "basic fixed-rate clock that cannot gate" [1]
>> > - Stephen also suggested a separate binding [2]
>> >
>> > With the fixed-clock being sort of the root for everything else on most
>> > systems, I opted to leave it alone. I guess if the consenus really is
>> > that
>> > this should go there, I can move it, but discussion in v1
>> >
>> > Interestingly the fixed clock had a gpios property 10 years ago [3] :-)
>> > .
>> >
>> > [1]
>> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
>> > [2]
>> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
>> > [3]
>> > https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t
>> 
>> After finally going through the v1 discussion [4] in detail,
>> here are my further thoughts:
>> 
>> - I agree with dropping the Diodes stuff, [5] because I see
>>    no need for that at this point;  though, am I missing
>>    something, where are they actually used?
> 
> On the Rock5 ITX that 100MHz clock comes the one single oscillator 
> thing.
> 
> The Diodes parts are not root sources for their clocks but instead sort
> PLLs or something, though their manual describes them as
> "clock generator supporting PCI Express and Ethernet requirements" [8]
> 
> So they generate the 100MHz (frequency actually is
> selected by input pins of the chip) from a separate 25MHz source clock.
> 
> One example are the Theobroma/Cherry embedded boards changed in v1 
> where
> they currently are described via existing generic things (no 
> schematics).
> 
> Another user is the rk3568-rock3b for example, where the diodes part
> is enabled by the same rail as the port itself, so in contrast to the
> Rock 5 ITX, it works "by accident" on the rock 3b [9]

Ah, I see now, thanks for the clarification.  The way Diodes PI6C557
is used on the ROCK 3B, together with its 25 MHz "passive" crystal,
is pretty much the same as the way Aurasemi AU5426 is used on the
ROCK 5 ITX, together with its 100 MHz "active" clock generator.  All
that from the software standpoint, of course.

To explain it further, the PI6C577 and the AU5426 are the components
that actually generate the clocks for the PCIe interfaces.  Thus,
technically we should describe two components per board in their DTs:

- ROCK 5 ITX:
     - 100 MHz clock generator (which goes to the AU5426),
       i.e. the "100MHz,3.3V,3225"
     - clock buffer that fans the 100 MHz clock out to the
       PCIe interfaces, i.e. the Aurasemi AU5426

- ROCK 3B:
     - 25 MHz "passive" crystal (which goes to the PI6C557)
     - clock generator that uses the 25 MHz crystal to generate
       100 MHz and fan it out to the PCIe interfaces, i.e. the
       Diodes PI6C557

(The "passive" 25 MHz crystal is very similar to the main 24 MHz
crystal used by the SoC, also known as xin24m.)

However, simplifying and abstracting the things out a bit should
be fine, to end up with the following:

- ROCK 5 ITX:
     - "black box" that generates fixed 100 MHz clocks for the
        PCIe interfaces, which can be gated

- ROCK 3B:
     - "black box" that generates fixed 100 MHz clocks for the
        PCIe interfaces, which can be gated

... and that's our, hopefully, gated-clock. :)

> The interesting part of the Diodes ICs is that they actually allow
> configuration of the generated frequency via their S0 + S1 pins,
> though they might be statically set in the board layout without
> being user configurable. (Rock3b does it this way for example)

The Aurasemi AU5426 also has a few tricks up its sleeve. :)  For
example, it can also use a "passive" crystal instead of using an
external clock generator, i.e. it can be configured to work in
the same "big picture" layout as the PI6C577.

>> - I agree that "enable-gpios" and "vdd-supply" should be
>>    required in the binding, [5] because that's the basis for
>>    something to be actually represented this way
> 
> I would only require the vdd supply though.
> 
> On the Rock 5 ITX, the chip does have an enable-gpio input, but that is
> tied directly to the voltage rail and is not user controllable.

Isn't that voltage rail (VCC3V3_PI6C_05, provided by the U90099 
regulator,
which is an RT9193) actually enabled by GPIO1_A4_d (see pages 14 and 35
in the ROCK 5 ITX schematic and follow PCIE30x_PWREN_H)?

Unless I'm missing something, that's the source of all troubles, because
we basically also need to enable PCIE30x_PWREN_H when only the other M.2
slot is in use, or when it's enumerated first.  Thus, we need 
enable-gpios
to be able to enable the VCC3V3_PI6C_05 independently.

>> - I agree that it should be better not to touch fixed-clock
>>    at this point, simply because it's used in very many places,
>>    and because in this case we need more than it requires (see
>>    the bullet point above)
>> 
>> - As I wrote already, [6] I highly disagree with this being
>>    called voltage-controlled oscillator (VCO), [7] simply
>>    because it isn't a VCO, but a clock that can be gated;
>>    though, looking forward to what the last bullet point
>>    asks to be clarified further
>> 
>> - I still think that gated-clock is the best choice for the
>>    name, because it uses "clock" that's used throughout the
>>    entire codebase, and uses "gated" to reflect the nature
>>    of the clock generator
> 
> "gated-oscillator" perhaps?

But what's the output of an oscillator, which we actually care about?
It's nothing more but a clock. :)

> This would make it more explicit that we're talking about a root
> for clock signals. "gated-clock" can be anything, in the middle
> of a clock tree. Having a very generic name, also invites misuse.

I can't escape wondering why doesn't "fixed-clock", which is also
a very generic name, invite abuse?

Speaking about the root of clock signals, the above-mentioned xin24m,
which is represented in DTs as a fixed-clock, is the root of pretty
much everything.  Also, it technically isn't a clock, it's a crystal.
That's another example of the above-mentioned abstraction, in which
we care about the way sotware sees it, which is a clock.

>> - Maybe we could actually use fixed-gated-clock as the name,
>>    which would make more sense from the stanpoint of possibly
>>    merging it into fixed-clock at some point, but I'd like
>>    to hear first what's actually going on with the Diodes
>>    stuff that was deleted in v2, which I already asked about
>>    in the first bullet point
>> 
>> [4]
>> https://lore.kernel.org/linux-rockchip/[e-mail]/T/#u
>> [5]
>> https://lore.kernel.org/linux-rockchip/[e-mail]/
>> [6]
>> https://lore.kernel.org/linux-rockchip/[e-mail]/
>> [7]
>> https://lore.kernel.org/linux-rockchip/[e-mail]/
> 
> [8] https://www.diodes.com/assets/Datasheets/PI6C557-03.pdf
> [9] https://dl.radxa.com/rock3/docs/hw/3b/Radxa_ROCK_3B_V1.51_SCH.pdf
>     page 31, bottom left of the page
> 
> 
>> >> > +
>> >> > +maintainers:
>> >> > +  - Heiko Stuebner <[e-mail]>
>> >> > +
>> >> > +properties:
>> >> > +  compatible:
>> >> > +    const: voltage-oscillator
>> >> > +
>> >> > +  "#clock-cells":
>> >> > +    const: 0
>> >> > +
>> >> > +  clock-frequency: true
>> >> > +
>> >> > +  clock-output-names:
>> >> > +    maxItems: 1
>> >> > +
>> >> > +  enable-gpios:
>> >> > +    description:
>> >> > +      Contains a single GPIO specifier for the GPIO that enables and disables
>> >> > +      the oscillator.
>> >> > +    maxItems: 1
>> >> > +
>> >> > +  vdd-supply:
>> >> > +    description: handle of the regulator that provides the supply voltage
>> >> > +
>> >> > +required:
>> >> > +  - compatible
>> >> > +  - "#clock-cells"
>> >> > +  - clock-frequency
>> >> > +  - vdd-supply
>> >> > +
>> >> > +additionalProperties: false
>> >> > +
>> >> > +examples:
>> >> > +  - |
>> >> > +    voltage-oscillator {
>> >> > +      compatible = "voltage-oscillator";
>> >> > +      #clock-cells = <0>;
>> >> > +      clock-frequency = <1000000000>;
>> >> > +      vdd-supply = <&reg_vdd>;
>> >> > +    };
>> >> > +...

Heiko Stuebner July 18, 2024, 1:50 p.m. UTC | #12

Hi Dragan,

Am Donnerstag, 18. Juli 2024, 15:00:57 CEST schrieb Dragan Simic:
> On 2024-07-18 13:30, Heiko Stübner wrote:
> > Am Donnerstag, 18. Juli 2024, 12:53:07 CEST schrieb Dragan Simic:
> >> On 2024-07-18 11:25, Heiko Stübner wrote:
> >> > Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
> >> >> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
> >> >> > In contrast to fixed clocks that are described as ungateable, boards
> >> >> > sometimes use additional oscillators for things like PCIe reference
> >> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
> >> >> > toggled for them to work.
> >> >> >
> >> >> > This adds a binding for such oscillators that are not configurable
> >> >> > themself, but need to handle supplies for them to work.
> >> >> >
> >> >> > In schematics they often can be seen as
> >> >> >
> >> >> >          ----------------
> >> >> > Enable - | 100MHz,3.3V, | - VDD
> >> >> >          |    3225      |
> >> >> >    GND - |              | - OUT
> >> >> >          ----------------
> >> >> >
> >> >> > or similar. The enable pin might be separate but can also just be tied
> >> >> > to the vdd supply, hence it is optional in the binding.
> >> >> >
> >> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
> >> >> > ---
> >> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> >> >> >  1 file changed, 49 insertions(+)
> >> >> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> >> >
> >> >> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> >> > new file mode 100644
> >> >> > index 0000000000000..8bff6b0fd582e
> >> >> > --- /dev/null
> >> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> >> >> > @@ -0,0 +1,49 @@
> >> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> >> > +%YAML 1.2
> >> >> > +---
> >> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> >> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> >> > +
> >> >> > +title: Voltage controlled oscillator
> >> >>
> >> >> Voltage controlled oscillator? Really? That sounds far too similar to
> >> >> a
> >> >> VCO to me, and the input voltage here (according to the description at
> >> >> least) does not affect the frequency of oscillation.
> >> >
> >> > That naming was suggested by Stephen in v1 [0] .
> >> >
> >> > Of course the schematics for the board I have only describe it as
> >> > "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
> >> > only mentions "supply voltage" in their datasheets but not a dependency
> >> > between rate and voltage.
> >> >
> >> > [0]
> >> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> >> >
> >> >> Why the dedicated binding, rather than adding a supply and enable-gpio
> >> >> to the existing "fixed-clock" binding? I suspect that a large portion
> >> >> of
> >> >> "fixed-clock"s actually require a supply that is (effectively)
> >> >> always-on.
> >> >
> >> > I guess there are three aspects:
> >> > - I do remember discussions in the past about not extending generic
> >> >   bindings with device-specific stuff. I think generic power-sequences
> >> >   were the topic back then, though that might have changed over time?
> >> > - There are places that describe "fixed-clock" as
> >> >   "basic fixed-rate clock that cannot gate" [1]
> >> > - Stephen also suggested a separate binding [2]
> >> >
> >> > With the fixed-clock being sort of the root for everything else on most
> >> > systems, I opted to leave it alone. I guess if the consenus really is
> >> > that
> >> > this should go there, I can move it, but discussion in v1
> >> >
> >> > Interestingly the fixed clock had a gpios property 10 years ago [3] :-)
> >> > .
> >> >
> >> > [1]
> >> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
> >> > [2]
> >> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> >> > [3]
> >> > https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t
> >> 
> >> After finally going through the v1 discussion [4] in detail,
> >> here are my further thoughts:
> >> 
> >> - I agree with dropping the Diodes stuff, [5] because I see
> >>    no need for that at this point;  though, am I missing
> >>    something, where are they actually used?
> > 
> > On the Rock5 ITX that 100MHz clock comes the one single oscillator 
> > thing.
> > 
> > The Diodes parts are not root sources for their clocks but instead sort
> > PLLs or something, though their manual describes them as
> > "clock generator supporting PCI Express and Ethernet requirements" [8]
> > 
> > So they generate the 100MHz (frequency actually is
> > selected by input pins of the chip) from a separate 25MHz source clock.
> > 
> > One example are the Theobroma/Cherry embedded boards changed in v1 
> > where
> > they currently are described via existing generic things (no 
> > schematics).
> > 
> > Another user is the rk3568-rock3b for example, where the diodes part
> > is enabled by the same rail as the port itself, so in contrast to the
> > Rock 5 ITX, it works "by accident" on the rock 3b [9]
> 
> Ah, I see now, thanks for the clarification.  The way Diodes PI6C557
> is used on the ROCK 3B, together with its 25 MHz "passive" crystal,
> is pretty much the same as the way Aurasemi AU5426 is used on the
> ROCK 5 ITX, together with its 100 MHz "active" clock generator.  All
> that from the software standpoint, of course.
> 
> To explain it further, the PI6C577 and the AU5426 are the components
> that actually generate the clocks for the PCIe interfaces.  Thus,
> technically we should describe two components per board in their DTs:
> 
> - ROCK 5 ITX:
>      - 100 MHz clock generator (which goes to the AU5426),
>        i.e. the "100MHz,3.3V,3225"
>      - clock buffer that fans the 100 MHz clock out to the
>        PCIe interfaces, i.e. the Aurasemi AU5426
> 
> - ROCK 3B:
>      - 25 MHz "passive" crystal (which goes to the PI6C557)
>      - clock generator that uses the 25 MHz crystal to generate
>        100 MHz and fan it out to the PCIe interfaces, i.e. the
>        Diodes PI6C557
> 
> (The "passive" 25 MHz crystal is very similar to the main 24 MHz
> crystal used by the SoC, also known as xin24m.)
> 
> However, simplifying and abstracting the things out a bit should
> be fine, to end up with the following:
> 
> - ROCK 5 ITX:
>      - "black box" that generates fixed 100 MHz clocks for the
>         PCIe interfaces, which can be gated
> 
> - ROCK 3B:
>      - "black box" that generates fixed 100 MHz clocks for the
>         PCIe interfaces, which can be gated
> 
> ... and that's our, hopefully, gated-clock. :)

I don't think we want too many black-boxes. Devicetree's purpose is to
describe the hardware as best as possible, the OS can make of it what it
wants afterwards ;-) .

That was also Stephen's point in v1 when he wanted to distinguish
between the input-less oscillator and the Diodes things that needs an
input clock.


> > The interesting part of the Diodes ICs is that they actually allow
> > configuration of the generated frequency via their S0 + S1 pins,
> > though they might be statically set in the board layout without
> > being user configurable. (Rock3b does it this way for example)
> 
> The Aurasemi AU5426 also has a few tricks up its sleeve. :)  For
> example, it can also use a "passive" crystal instead of using an
> external clock generator, i.e. it can be configured to work in
> the same "big picture" layout as the PI6C577.
> 
> >> - I agree that "enable-gpios" and "vdd-supply" should be
> >>    required in the binding, [5] because that's the basis for
> >>    something to be actually represented this way
> > 
> > I would only require the vdd supply though.
> > 
> > On the Rock 5 ITX, the chip does have an enable-gpio input, but that is
> > tied directly to the voltage rail and is not user controllable.
> 
> Isn't that voltage rail (VCC3V3_PI6C_05, provided by the U90099 
> regulator,
> which is an RT9193) actually enabled by GPIO1_A4_d (see pages 14 and 35
> in the ROCK 5 ITX schematic and follow PCIE30x_PWREN_H)?
> 
> Unless I'm missing something, that's the source of all troubles, because
> we basically also need to enable PCIE30x_PWREN_H when only the other M.2
> slot is in use, or when it's enumerated first.  Thus, we need 
> enable-gpios
> to be able to enable the VCC3V3_PI6C_05 independently.

And you correctly described the problem I faced and that got me on that
journey (sata-pcie-controller probing before M.2 attached controller).

PCIE30x4_PWREN_H actually drives two separate regulators though,
U90098 and U90099 . 

U90098 creates VCC3V3_MKEY which is the supply for the main M.2 slot
U90099 creates VCC3V3_PI6C_05 which is the oscillator and Au5426 supply

PCIE30x4_PWREN_H definitly belongs to a regulator node in the devicetree
that then either the M.2 slot or the oscillator can enable first.


> >> - I agree that it should be better not to touch fixed-clock
> >>    at this point, simply because it's used in very many places,
> >>    and because in this case we need more than it requires (see
> >>    the bullet point above)
> >> 
> >> - As I wrote already, [6] I highly disagree with this being
> >>    called voltage-controlled oscillator (VCO), [7] simply
> >>    because it isn't a VCO, but a clock that can be gated;
> >>    though, looking forward to what the last bullet point
> >>    asks to be clarified further
> >> 
> >> - I still think that gated-clock is the best choice for the
> >>    name, because it uses "clock" that's used throughout the
> >>    entire codebase, and uses "gated" to reflect the nature
> >>    of the clock generator
> > 
> > "gated-oscillator" perhaps?
> 
> But what's the output of an oscillator, which we actually care about?
> It's nothing more but a clock. :)
> 
> > This would make it more explicit that we're talking about a root
> > for clock signals. "gated-clock" can be anything, in the middle
> > of a clock tree. Having a very generic name, also invites misuse.
> 
> I can't escape wondering why doesn't "fixed-clock", which is also
> a very generic name, invite abuse?

I guess it does - see the misuse in the rk3588 tiger and jaguar boards.
But it is sort of grandfathered I guess. It is still from a time more than
12 years ago, when architectures (like sunxi) tried to model their clock-
controllers via individual interconnected dt-nodes.


> Speaking about the root of clock signals, the above-mentioned xin24m,
> which is represented in DTs as a fixed-clock, is the root of pretty
> much everything.  Also, it technically isn't a clock, it's a crystal.
> That's another example of the above-mentioned abstraction, in which
> we care about the way sotware sees it, which is a clock.

At this point I think we should dt-people weigh in more on which
direction to take ;-) .

Because as a lot of dt-binding review in the past mentioned, the
"software-perspective" doesn't matter for the binding.


Heiko

> >> - Maybe we could actually use fixed-gated-clock as the name,
> >>    which would make more sense from the stanpoint of possibly
> >>    merging it into fixed-clock at some point, but I'd like
> >>    to hear first what's actually going on with the Diodes
> >>    stuff that was deleted in v2, which I already asked about
> >>    in the first bullet point
> >> 
> >> [4]
> >> https://lore.kernel.org/linux-rockchip/[e-mail]/T/#u
> >> [5]
> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
> >> [6]
> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
> >> [7]
> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
> > 
> > [8] https://www.diodes.com/assets/Datasheets/PI6C557-03.pdf
> > [9] https://dl.radxa.com/rock3/docs/hw/3b/Radxa_ROCK_3B_V1.51_SCH.pdf
> >     page 31, bottom left of the page
> > 
> > 
> >> >> > +
> >> >> > +maintainers:
> >> >> > +  - Heiko Stuebner <[e-mail]>
> >> >> > +
> >> >> > +properties:
> >> >> > +  compatible:
> >> >> > +    const: voltage-oscillator
> >> >> > +
> >> >> > +  "#clock-cells":
> >> >> > +    const: 0
> >> >> > +
> >> >> > +  clock-frequency: true
> >> >> > +
> >> >> > +  clock-output-names:
> >> >> > +    maxItems: 1
> >> >> > +
> >> >> > +  enable-gpios:
> >> >> > +    description:
> >> >> > +      Contains a single GPIO specifier for the GPIO that enables and disables
> >> >> > +      the oscillator.
> >> >> > +    maxItems: 1
> >> >> > +
> >> >> > +  vdd-supply:
> >> >> > +    description: handle of the regulator that provides the supply voltage
> >> >> > +
> >> >> > +required:
> >> >> > +  - compatible
> >> >> > +  - "#clock-cells"
> >> >> > +  - clock-frequency
> >> >> > +  - vdd-supply
> >> >> > +
> >> >> > +additionalProperties: false
> >> >> > +
> >> >> > +examples:
> >> >> > +  - |
> >> >> > +    voltage-oscillator {
> >> >> > +      compatible = "voltage-oscillator";
> >> >> > +      #clock-cells = <0>;
> >> >> > +      clock-frequency = <1000000000>;
> >> >> > +      vdd-supply = <&reg_vdd>;
> >> >> > +    };
> >> >> > +...
>

Dragan Simic July 18, 2024, 2:24 p.m. UTC | #13

Hello Heiko,

On 2024-07-18 15:50, Heiko Stübner wrote:
> Am Donnerstag, 18. Juli 2024, 15:00:57 CEST schrieb Dragan Simic:
>> On 2024-07-18 13:30, Heiko Stübner wrote:
>> > Am Donnerstag, 18. Juli 2024, 12:53:07 CEST schrieb Dragan Simic:
>> >> On 2024-07-18 11:25, Heiko Stübner wrote:
>> >> > Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
>> >> >> On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
>> >> >> > In contrast to fixed clocks that are described as ungateable, boards
>> >> >> > sometimes use additional oscillators for things like PCIe reference
>> >> >> > clocks, that need actual supplies to get enabled and enable-gpios to be
>> >> >> > toggled for them to work.
>> >> >> >
>> >> >> > This adds a binding for such oscillators that are not configurable
>> >> >> > themself, but need to handle supplies for them to work.
>> >> >> >
>> >> >> > In schematics they often can be seen as
>> >> >> >
>> >> >> >          ----------------
>> >> >> > Enable - | 100MHz,3.3V, | - VDD
>> >> >> >          |    3225      |
>> >> >> >    GND - |              | - OUT
>> >> >> >          ----------------
>> >> >> >
>> >> >> > or similar. The enable pin might be separate but can also just be tied
>> >> >> > to the vdd supply, hence it is optional in the binding.
>> >> >> >
>> >> >> > Signed-off-by: Heiko Stuebner <[e-mail]>
>> >> >> > ---
>> >> >> >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
>> >> >> >  1 file changed, 49 insertions(+)
>> >> >> >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> >> >
>> >> >> > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> >> > new file mode 100644
>> >> >> > index 0000000000000..8bff6b0fd582e
>> >> >> > --- /dev/null
>> >> >> > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
>> >> >> > @@ -0,0 +1,49 @@
>> >> >> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> >> >> > +%YAML 1.2
>> >> >> > +---
>> >> >> > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
>> >> >> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> >> >> > +
>> >> >> > +title: Voltage controlled oscillator
>> >> >>
>> >> >> Voltage controlled oscillator? Really? That sounds far too similar to
>> >> >> a
>> >> >> VCO to me, and the input voltage here (according to the description at
>> >> >> least) does not affect the frequency of oscillation.
>> >> >
>> >> > That naming was suggested by Stephen in v1 [0] .
>> >> >
>> >> > Of course the schematics for the board I have only describe it as
>> >> > "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
>> >> > only mentions "supply voltage" in their datasheets but not a dependency
>> >> > between rate and voltage.
>> >> >
>> >> > [0]
>> >> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
>> >> >
>> >> >> Why the dedicated binding, rather than adding a supply and enable-gpio
>> >> >> to the existing "fixed-clock" binding? I suspect that a large portion
>> >> >> of
>> >> >> "fixed-clock"s actually require a supply that is (effectively)
>> >> >> always-on.
>> >> >
>> >> > I guess there are three aspects:
>> >> > - I do remember discussions in the past about not extending generic
>> >> >   bindings with device-specific stuff. I think generic power-sequences
>> >> >   were the topic back then, though that might have changed over time?
>> >> > - There are places that describe "fixed-clock" as
>> >> >   "basic fixed-rate clock that cannot gate" [1]
>> >> > - Stephen also suggested a separate binding [2]
>> >> >
>> >> > With the fixed-clock being sort of the root for everything else on most
>> >> > systems, I opted to leave it alone. I guess if the consenus really is
>> >> > that
>> >> > this should go there, I can move it, but discussion in v1
>> >> >
>> >> > Interestingly the fixed clock had a gpios property 10 years ago [3] :-)
>> >> > .
>> >> >
>> >> > [1]
>> >> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
>> >> > [2]
>> >> > https://lore.kernel.org/linux-arm-kernel/[e-mail]/
>> >> > [3]
>> >> > https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t
>> >>
>> >> After finally going through the v1 discussion [4] in detail,
>> >> here are my further thoughts:
>> >>
>> >> - I agree with dropping the Diodes stuff, [5] because I see
>> >>    no need for that at this point;  though, am I missing
>> >>    something, where are they actually used?
>> >
>> > On the Rock5 ITX that 100MHz clock comes the one single oscillator
>> > thing.
>> >
>> > The Diodes parts are not root sources for their clocks but instead sort
>> > PLLs or something, though their manual describes them as
>> > "clock generator supporting PCI Express and Ethernet requirements" [8]
>> >
>> > So they generate the 100MHz (frequency actually is
>> > selected by input pins of the chip) from a separate 25MHz source clock.
>> >
>> > One example are the Theobroma/Cherry embedded boards changed in v1
>> > where
>> > they currently are described via existing generic things (no
>> > schematics).
>> >
>> > Another user is the rk3568-rock3b for example, where the diodes part
>> > is enabled by the same rail as the port itself, so in contrast to the
>> > Rock 5 ITX, it works "by accident" on the rock 3b [9]
>> 
>> Ah, I see now, thanks for the clarification.  The way Diodes PI6C557
>> is used on the ROCK 3B, together with its 25 MHz "passive" crystal,
>> is pretty much the same as the way Aurasemi AU5426 is used on the
>> ROCK 5 ITX, together with its 100 MHz "active" clock generator.  All
>> that from the software standpoint, of course.
>> 
>> To explain it further, the PI6C577 and the AU5426 are the components
>> that actually generate the clocks for the PCIe interfaces.  Thus,
>> technically we should describe two components per board in their DTs:
>> 
>> - ROCK 5 ITX:
>>      - 100 MHz clock generator (which goes to the AU5426),
>>        i.e. the "100MHz,3.3V,3225"
>>      - clock buffer that fans the 100 MHz clock out to the
>>        PCIe interfaces, i.e. the Aurasemi AU5426
>> 
>> - ROCK 3B:
>>      - 25 MHz "passive" crystal (which goes to the PI6C557)
>>      - clock generator that uses the 25 MHz crystal to generate
>>        100 MHz and fan it out to the PCIe interfaces, i.e. the
>>        Diodes PI6C557
>> 
>> (The "passive" 25 MHz crystal is very similar to the main 24 MHz
>> crystal used by the SoC, also known as xin24m.)
>> 
>> However, simplifying and abstracting the things out a bit should
>> be fine, to end up with the following:
>> 
>> - ROCK 5 ITX:
>>      - "black box" that generates fixed 100 MHz clocks for the
>>         PCIe interfaces, which can be gated
>> 
>> - ROCK 3B:
>>      - "black box" that generates fixed 100 MHz clocks for the
>>         PCIe interfaces, which can be gated
>> 
>> ... and that's our, hopefully, gated-clock. :)
> 
> I don't think we want too many black-boxes. Devicetree's purpose is to
> describe the hardware as best as possible, the OS can make of it what 
> it
> wants afterwards ;-) .
> 
> That was also Stephen's point in v1 when he wanted to distinguish
> between the input-less oscillator and the Diodes things that needs an
> input clock.

I can agree with that for sure, but in that case, we'd need much
more than just one "black box" per board dtb, namely, and by reusing
and expanding a bit one of the earlier lists:

- ROCK 5 ITX:
      - gated-clock
        (100 MHz clock generator (which goes to the AU5426),
        i.e. the "100MHz,3.3V,3225")
        - clock-fanout
          (clock buffer that fans the 100 MHz clock out to the
          PCIe interfaces, i.e. the Aurasemi AU5426)

- ROCK 3B:
      - fixed-clock
        (25 MHz "passive" crystal (which goes to the PI6C557))
        - clock-fanout
          (clock generator that uses the 25 MHz crystal to generate
          100 MHz and fan it out to the PCIe interfaces, i.e. the
          Diodes PI6C557)

Actually, I'd be happy to see such a precise hardware definition
in these (and some other) board dts files. :)

>> > The interesting part of the Diodes ICs is that they actually allow
>> > configuration of the generated frequency via their S0 + S1 pins,
>> > though they might be statically set in the board layout without
>> > being user configurable. (Rock3b does it this way for example)
>> 
>> The Aurasemi AU5426 also has a few tricks up its sleeve. :)  For
>> example, it can also use a "passive" crystal instead of using an
>> external clock generator, i.e. it can be configured to work in
>> the same "big picture" layout as the PI6C577.
>> 
>> >> - I agree that "enable-gpios" and "vdd-supply" should be
>> >>    required in the binding, [5] because that's the basis for
>> >>    something to be actually represented this way
>> >
>> > I would only require the vdd supply though.
>> >
>> > On the Rock 5 ITX, the chip does have an enable-gpio input, but that is
>> > tied directly to the voltage rail and is not user controllable.
>> 
>> Isn't that voltage rail (VCC3V3_PI6C_05, provided by the U90099
>> regulator,
>> which is an RT9193) actually enabled by GPIO1_A4_d (see pages 14 and 
>> 35
>> in the ROCK 5 ITX schematic and follow PCIE30x_PWREN_H)?
>> 
>> Unless I'm missing something, that's the source of all troubles, 
>> because
>> we basically also need to enable PCIE30x_PWREN_H when only the other 
>> M.2
>> slot is in use, or when it's enumerated first.  Thus, we need
>> enable-gpios
>> to be able to enable the VCC3V3_PI6C_05 independently.
> 
> And you correctly described the problem I faced and that got me on that
> journey (sata-pcie-controller probing before M.2 attached controller).
> 
> PCIE30x4_PWREN_H actually drives two separate regulators though,
> U90098 and U90099 .
> 
> U90098 creates VCC3V3_MKEY which is the supply for the main M.2 slot
> U90099 creates VCC3V3_PI6C_05 which is the oscillator and Au5426 supply
> 
> PCIE30x4_PWREN_H definitly belongs to a regulator node in the 
> devicetree
> that then either the M.2 slot or the oscillator can enable first.

Exactly, PCIE30x4_PWREN_H basically plays a double role, so it needs
to be enabled idenpendently in each of its roles, for the observed
problem to be resolved.

>> >> - I agree that it should be better not to touch fixed-clock
>> >>    at this point, simply because it's used in very many places,
>> >>    and because in this case we need more than it requires (see
>> >>    the bullet point above)
>> >>
>> >> - As I wrote already, [6] I highly disagree with this being
>> >>    called voltage-controlled oscillator (VCO), [7] simply
>> >>    because it isn't a VCO, but a clock that can be gated;
>> >>    though, looking forward to what the last bullet point
>> >>    asks to be clarified further
>> >>
>> >> - I still think that gated-clock is the best choice for the
>> >>    name, because it uses "clock" that's used throughout the
>> >>    entire codebase, and uses "gated" to reflect the nature
>> >>    of the clock generator
>> >
>> > "gated-oscillator" perhaps?
>> 
>> But what's the output of an oscillator, which we actually care about?
>> It's nothing more but a clock. :)
>> 
>> > This would make it more explicit that we're talking about a root
>> > for clock signals. "gated-clock" can be anything, in the middle
>> > of a clock tree. Having a very generic name, also invites misuse.
>> 
>> I can't escape wondering why doesn't "fixed-clock", which is also
>> a very generic name, invite abuse?
> 
> I guess it does - see the misuse in the rk3588 tiger and jaguar boards.
> But it is sort of grandfathered I guess. It is still from a time more 
> than
> 12 years ago, when architectures (like sunxi) tried to model their 
> clock-
> controllers via individual interconnected dt-nodes.

Perhaps, but again, "clock" became the universally used term
throughout the entire codebase.

>> Speaking about the root of clock signals, the above-mentioned xin24m,
>> which is represented in DTs as a fixed-clock, is the root of pretty
>> much everything.  Also, it technically isn't a clock, it's a crystal.
>> That's another example of the above-mentioned abstraction, in which
>> we care about the way sotware sees it, which is a clock.
> 
> At this point I think we should dt-people weigh in more on which
> direction to take ;-) .
> 
> Because as a lot of dt-binding review in the past mentioned, the
> "software-perspective" doesn't matter for the binding.

Looking forward to hearing more opinions. :)

>> >> - Maybe we could actually use fixed-gated-clock as the name,
>> >>    which would make more sense from the stanpoint of possibly
>> >>    merging it into fixed-clock at some point, but I'd like
>> >>    to hear first what's actually going on with the Diodes
>> >>    stuff that was deleted in v2, which I already asked about
>> >>    in the first bullet point
>> >>
>> >> [4]
>> >> https://lore.kernel.org/linux-rockchip/[e-mail]/T/#u
>> >> [5]
>> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
>> >> [6]
>> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
>> >> [7]
>> >> https://lore.kernel.org/linux-rockchip/[e-mail]/
>> >
>> > [8] https://www.diodes.com/assets/Datasheets/PI6C557-03.pdf
>> > [9] https://dl.radxa.com/rock3/docs/hw/3b/Radxa_ROCK_3B_V1.51_SCH.pdf
>> >     page 31, bottom left of the page
>> >
>> >
>> >> >> > +
>> >> >> > +maintainers:
>> >> >> > +  - Heiko Stuebner <[e-mail]>
>> >> >> > +
>> >> >> > +properties:
>> >> >> > +  compatible:
>> >> >> > +    const: voltage-oscillator
>> >> >> > +
>> >> >> > +  "#clock-cells":
>> >> >> > +    const: 0
>> >> >> > +
>> >> >> > +  clock-frequency: true
>> >> >> > +
>> >> >> > +  clock-output-names:
>> >> >> > +    maxItems: 1
>> >> >> > +
>> >> >> > +  enable-gpios:
>> >> >> > +    description:
>> >> >> > +      Contains a single GPIO specifier for the GPIO that enables and disables
>> >> >> > +      the oscillator.
>> >> >> > +    maxItems: 1
>> >> >> > +
>> >> >> > +  vdd-supply:
>> >> >> > +    description: handle of the regulator that provides the supply voltage
>> >> >> > +
>> >> >> > +required:
>> >> >> > +  - compatible
>> >> >> > +  - "#clock-cells"
>> >> >> > +  - clock-frequency
>> >> >> > +  - vdd-supply
>> >> >> > +
>> >> >> > +additionalProperties: false
>> >> >> > +
>> >> >> > +examples:
>> >> >> > +  - |
>> >> >> > +    voltage-oscillator {
>> >> >> > +      compatible = "voltage-oscillator";
>> >> >> > +      #clock-cells = <0>;
>> >> >> > +      clock-frequency = <1000000000>;
>> >> >> > +      vdd-supply = <&reg_vdd>;
>> >> >> > +    };
>> >> >> > +...

Conor Dooley July 18, 2024, 3:59 p.m. UTC | #14

On Thu, Jul 18, 2024 at 11:25:28AM +0200, Heiko Stübner wrote:
> Hi Conor,
> 
> Am Dienstag, 16. Juli 2024, 18:15:08 CEST schrieb Conor Dooley:
> > On Mon, Jul 15, 2024 at 01:02:49PM +0200, Heiko Stuebner wrote:
> > > In contrast to fixed clocks that are described as ungateable, boards
> > > sometimes use additional oscillators for things like PCIe reference
> > > clocks, that need actual supplies to get enabled and enable-gpios to be
> > > toggled for them to work.
> > > 
> > > This adds a binding for such oscillators that are not configurable
> > > themself, but need to handle supplies for them to work.
> > > 
> > > In schematics they often can be seen as
> > > 
> > >          ----------------
> > > Enable - | 100MHz,3.3V, | - VDD
> > >          |    3225      |
> > >    GND - |              | - OUT
> > >          ----------------
> > > 
> > > or similar. The enable pin might be separate but can also just be tied
> > > to the vdd supply, hence it is optional in the binding.
> > > 
> > > Signed-off-by: Heiko Stuebner <[e-mail]>
> > > ---
> > >  .../bindings/clock/voltage-oscillator.yaml    | 49 +++++++++++++++++++
> > >  1 file changed, 49 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > > 
> > > diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > > new file mode 100644
> > > index 0000000000000..8bff6b0fd582e
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
> > > @@ -0,0 +1,49 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Voltage controlled oscillator
> > 
> > Voltage controlled oscillator? Really? That sounds far too similar to a
> > VCO to me, and the input voltage here (according to the description at
> > least) does not affect the frequency of oscillation.
> 
> That naming was suggested by Stephen in v1 [0] .

I think "voltage-oscillator" is a confusing name, and having "voltage
controlled oscillator" in the title doubly so as this isn't a binding
for a VCO.
A VCO is a more general case of the sort of device that you're talking
about here, so a part of me can see it - but I think specific
compatibles would be required for actual VCOs, since the "transfer
function" would vary per device.

> Of course the schematics for the board I have only describe it as
> "100MHz,3.3V,3225" , thumbing through some mouser parts matching that
> only mentions "supply voltage" in their datasheets but not a dependency
> between rate and voltage.
> 
> [0] https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> 
> > Why the dedicated binding, rather than adding a supply and enable-gpio
> > to the existing "fixed-clock" binding? I suspect that a large portion of
> > "fixed-clock"s actually require a supply that is (effectively)
> > always-on.
> 
> I guess there are three aspects:
> - I do remember discussions in the past about not extending generic
>   bindings with device-specific stuff.

FWIW, I wouldn't classify this as device-specific. "enable-gpios" and
"vdd-supply" are pretty generic and I think the latter is missing from
the vast majority of real* "fixed-clocks". I would expect that devices
where the datasheet would call

* Real because there's plenty of "fixed-clocks" (both in and out of tree)
that are used to work around the lack of a clock-controller driver for an
SoC.

> I think generic power-sequences
>   were the topic back then, though that might have changed over time?
> - There are places that describe "fixed-clock" as
>   "basic fixed-rate clock that cannot gate" [1]

I think that that is something that could be changed, it's "just" a
comment in some code! Sounds like Stephen disagrees though :)

> - Stephen also suggested a separate binding [2]

I liked your "gated-oscillator" suggestion in another reply, but
"gated-fixed-clock" might be a better "thematic" fit since this is a
special case of fixed-clocks?

Cheers,
Conor.

> With the fixed-clock being sort of the root for everything else on most
> systems, I opted to leave it alone. I guess if the consenus really is that
> this should go there, I can move it, but discussion in v1 
> 
> Interestingly the fixed clock had a gpios property 10 years ago [3] :-) .

heh!

> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/clk-fixed-rate.c#n18
> [2] https://lore.kernel.org/linux-arm-kernel/[e-mail]/
> [3] https://lore.kernel.org/linux-kernel//20140515064420.9521.47383@quantum/T/#t

Stephen Boyd July 26, 2024, 10:21 p.m. UTC | #15

Quoting Conor Dooley (2024-07-18 08:59:50)
> 
> FWIW, I wouldn't classify this as device-specific. "enable-gpios" and
> "vdd-supply" are pretty generic and I think the latter is missing from
> the vast majority of real* "fixed-clocks". I would expect that devices
> where the datasheet would call
> 
> * Real because there's plenty of "fixed-clocks" (both in and out of tree)
> that are used to work around the lack of a clock-controller driver for an
> SoC.

I agree!

> 
> > I think generic power-sequences
> >   were the topic back then, though that might have changed over time?
> > - There are places that describe "fixed-clock" as
> >   "basic fixed-rate clock that cannot gate" [1]
> 
> I think that that is something that could be changed, it's "just" a
> comment in some code! Sounds like Stephen disagrees though :)

It's more about making a clear break from the fixed-clock binding so
that the extra properties are required.

> 
> > - Stephen also suggested a separate binding [2]
> 
> I liked your "gated-oscillator" suggestion in another reply, but
> "gated-fixed-clock" might be a better "thematic" fit since this is a
> special case of fixed-clocks?
> 

It looks to me like we've arrived at the hardest problem in computer
science, i.e. naming. Any of these names is fine. I'd look to see what
those parts on mouser are called and use that to drive the compatible
name decision if you can't decide. The description section in the
binding could be verbose and link to some parts/pdfs if that helps too.
In the past I've seen EEs call these things clock buffers. I'm not a
classically trained EE myself but it usually helps to use similar names
from the schematic in DT because DT authors are sorta translating
schematics to DT.

Heiko Stuebner July 27, 2024, 11:25 a.m. UTC | #16

Am Samstag, 27. Juli 2024, 00:21:44 CEST schrieb Stephen Boyd:
> Quoting Conor Dooley (2024-07-18 08:59:50)
> > 
> > FWIW, I wouldn't classify this as device-specific. "enable-gpios" and
> > "vdd-supply" are pretty generic and I think the latter is missing from
> > the vast majority of real* "fixed-clocks". I would expect that devices
> > where the datasheet would call
> > 
> > * Real because there's plenty of "fixed-clocks" (both in and out of tree)
> > that are used to work around the lack of a clock-controller driver for an
> > SoC.
> 
> I agree!
> 
> > 
> > > I think generic power-sequences
> > >   were the topic back then, though that might have changed over time?
> > > - There are places that describe "fixed-clock" as
> > >   "basic fixed-rate clock that cannot gate" [1]
> > 
> > I think that that is something that could be changed, it's "just" a
> > comment in some code! Sounds like Stephen disagrees though :)
> 
> It's more about making a clear break from the fixed-clock binding so
> that the extra properties are required.
> 
> > 
> > > - Stephen also suggested a separate binding [2]
> > 
> > I liked your "gated-oscillator" suggestion in another reply, but
> > "gated-fixed-clock" might be a better "thematic" fit since this is a
> > special case of fixed-clocks?
> > 
> 
> It looks to me like we've arrived at the hardest problem in computer
> science, i.e. naming. Any of these names is fine. I'd look to see what
> those parts on mouser are called and use that to drive the compatible
> name decision if you can't decide. The description section in the
> binding could be verbose and link to some parts/pdfs if that helps too.
> In the past I've seen EEs call these things clock buffers. I'm not a
> classically trained EE myself but it usually helps to use similar names
> from the schematic in DT because DT authors are sorta translating
> schematics to DT.

TL;DR: I'm fine with both "gated-oscillator" or "gated-fixed-clock" .
Some tiny part in the back of my head wants to name things in the most
specific way aka "gated-oscillator", but I guess "gated-fixed-clock" will
possibly spare us the naming dance in the future :-)

So I guess if nobody objects anymore, I'll go with "gated-fixed-clock".

--------- 8< --------
Some background stuff for the oscillator / clock-buffer difference,
which are actually both used on the Rock 5 ITX in question:

[my ASCII-art may not survive mail readers]
                                        ------------
VCC3v3_PI6C (to both VDD + Enable) -----| VCC*     | - CLKoutA - to PCIe
  |                                     |          |
--------------------                    |          | - CLKoutB - to PCIe
| 100MHz,3.3V,3225 |-------XTAL_IN_OUT -| Au5426   |
--------------------                    |          | - REFout (unconnected)
                                        ------------

Just asking Google for that "100MHz,3.3V,3225" brings me to
"100 MHz Standard Clock Oscillators" on Mouser.

The Au5426 from Aurasemi is a "4 Differential and 1 LVCMOS Output Ultra
Low Jitter High Performance Buffer" - aka a clock-buffer.

In the Rock-5-ITX patch, I opted to ignore it, because on _that_ board
it is transparent to the system, enabled by the same sources as the
crystal and statically configured.

On the other hand, the Au5426 actually _has_ input pins to select
its working mode: 
- select between different clock sources
- enable/disable the output of the input clock as refclk
- configure the clock buffer type (lvpecl, lvds, hcsl, hiz)

So I didn't want to conjure a binding for that stuff out of thin air :-)


Heiko

Dragan Simic July 27, 2024, 5:26 p.m. UTC | #17

Hello Stephen,

On 2024-07-27 00:21, Stephen Boyd wrote:
> Quoting Conor Dooley (2024-07-18 08:59:50)
>> 
>> FWIW, I wouldn't classify this as device-specific. "enable-gpios" and
>> "vdd-supply" are pretty generic and I think the latter is missing from
>> the vast majority of real* "fixed-clocks". I would expect that devices
>> where the datasheet would call
>> 
>> * Real because there's plenty of "fixed-clocks" (both in and out of 
>> tree)
>> that are used to work around the lack of a clock-controller driver for 
>> an
>> SoC.
> 
> I agree!
> 
>> > I think generic power-sequences
>> >   were the topic back then, though that might have changed over time?
>> > - There are places that describe "fixed-clock" as
>> >   "basic fixed-rate clock that cannot gate" [1]
>> 
>> I think that that is something that could be changed, it's "just" a
>> comment in some code! Sounds like Stephen disagrees though :)
> 
> It's more about making a clear break from the fixed-clock binding so
> that the extra properties are required.
>> 
>> > - Stephen also suggested a separate binding [2]
>> 
>> I liked your "gated-oscillator" suggestion in another reply, but
>> "gated-fixed-clock" might be a better "thematic" fit since this is a
>> special case of fixed-clocks?
> 
> It looks to me like we've arrived at the hardest problem in computer
> science, i.e. naming. Any of these names is fine. I'd look to see what
> those parts on mouser are called and use that to drive the compatible
> name decision if you can't decide. The description section in the
> binding could be verbose and link to some parts/pdfs if that helps too.
> In the past I've seen EEs call these things clock buffers. I'm not a
> classically trained EE myself but it usually helps to use similar names
> from the schematic in DT because DT authors are sorta translating
> schematics to DT.

Please note that the hardware components modeled by these DT bindings
are definitely not clock buffers.  Those are simply clock generators,
which can be gated, hense the proposal to use "gated-fixed-clock".

If we were to additionally model Aurasemi AU5426 or Diodes PI6C557 into
new DT bindings and into the board dts file(s), which I'd support 
because
of accuracy, those should actually be called "clock-buffer".

Patch

diff --git a/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
new file mode 100644
index 0000000000000..8bff6b0fd582e
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/voltage-oscillator.yaml
@@ -0,0 +1,49 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/voltage-oscillator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Voltage controlled oscillator
+
+maintainers:
+  - Heiko Stuebner <[e-mail]>
+
+properties:
+  compatible:
+    const: voltage-oscillator
+
+  "#clock-cells":
+    const: 0
+
+  clock-frequency: true
+
+  clock-output-names:
+    maxItems: 1
+
+  enable-gpios:
+    description:
+      Contains a single GPIO specifier for the GPIO that enables and disables
+      the oscillator.
+    maxItems: 1
+
+  vdd-supply:
+    description: handle of the regulator that provides the supply voltage
+
+required:
+  - compatible
+  - "#clock-cells"
+  - clock-frequency
+  - vdd-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    voltage-oscillator {
+      compatible = "voltage-oscillator";
+      #clock-cells = <0>;
+      clock-frequency = <1000000000>;
+      vdd-supply = <&reg_vdd>;
+    };
+...