Skip to contentSkip to conversation

clk: vc5: Add bindings for output configurations

RFC In review Adam Ford 3 participants 7 messages Mar 26, 2020 – Apr 6, 2020

Subsystems (2)
lore
Share & tools
lore

Adam Ford

author
#0 lore raw

RFC 1/1 clk: vc5: Add bindings for output configurations

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +28 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
 		- 5p49v5933 and
 		- 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+		  - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+		  - CMOS
+		  - HCSL 
+		  - LVDS: Low voltage differential signal
+
+- voltage-level:  can be one of the following microvolts
+		  - 1800000
+		  - 2500000
+		  - 3300000
+-  slew: Percent of normal, can be one of 
+		  - P80 
+		  - P85
+		  - P90
+		  - P100 
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
+#include <dt-bindings/versaclock.h>
+
 /* 25MHz reference crystal */
 ref25: ref25m {
 	compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
 		/* Connect XIN input to 25MHz reference */
 		clocks = <&ref25m>;
 		clock-names = "xin";
+
+		ports@1 {
+			reg = <1>;
+			mode = <CMOS>;
+			pwr_sel = <1800000>;
+			slew = <P80>;
+		};
 	};
 };
 
Signature · 1 line
2.25.1
#1 lore raw

Hi Adam,

CC Marek

Quoted 24 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +7 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
                - 5p49v5933 and
                - 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+                 - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+                 - CMOS
+                 - HCSL
+                 - LVDS: Low voltage differential signal

Documentation/devicetree/bindings/clock/idt,versaclock5.txt Required properties: · line 49

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +10 -0
+
+- voltage-level:  can be one of the following microvolts
+                 - 1800000
+                 - 2500000
+                 - 3300000
+-  slew: Percent of normal, can be one of
+                 - P80
+                 - P85
+                 - P90
+                 - P100

Why the P prefixes? Can't you just use integer values?
After the conversion to json-schema, these values can be validated, too.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt clock specifier, the following mapping applies: · line 84

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +3 -0
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
+#include <dt-bindings/versaclock.h>

Does not exist?

Quoted 7 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+
 /* 25MHz reference crystal */
 ref25: ref25m {
        compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
                /* Connect XIN input to 25MHz reference */
                clocks = <&ref25m>;

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 112

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +7 -0
                clock-names = "xin";
+
+               ports@1 {
+                       reg = <1>;
+                       mode = <CMOS>;
+                       pwr_sel = <1800000>;
+                       slew = <P80>;
+               };
        };
 };

Gr{oetje,eeting}s,

Geert

Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
author
#2 lore raw
Quoted 48 lines · Geert Uytterhoeven

Hi Adam,

CC Marek

Quoted 24 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +7 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
                - 5p49v5933 and
                - 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+                 - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+                 - CMOS
+                 - HCSL
+                 - LVDS: Low voltage differential signal

Documentation/devicetree/bindings/clock/idt,versaclock5.txt Required properties: · line 49

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +10 -0
+
+- voltage-level:  can be one of the following microvolts
+                 - 1800000
+                 - 2500000
+                 - 3300000
+-  slew: Percent of normal, can be one of
+                 - P80
+                 - P85
+                 - P90
+                 - P100

Why the P prefixes? Can't you just use integer values?
After the conversion to json-schema, these values can be validated, too.

Quoted 4 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+
+
 ==Mapping between clock specifier and physical pins==
 
Quoted 8 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt clock specifier, the following mapping applies: · line 84

Quoted 6 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
+#include <dt-bindings/versaclock.h>

Does not exist?

Not yet. Before actually coding anything, I wanted to get feedback on how the bindings should look. In this file would be definitions of terms like P80, CMOS, and the other items that are defined for mode and slew.

Quoted 29 lines
Quoted 8 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+
 /* 25MHz reference crystal */
 ref25: ref25m {
        compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
                /* Connect XIN input to 25MHz reference */
                clocks = <&ref25m>;

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 112

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +7 -0
                clock-names = "xin";
+
+               ports@1 {
+                       reg = <1>;
+                       mode = <CMOS>;
+                       pwr_sel = <1800000>;
+                       slew = <P80>;
+               };
        };
 };

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds

author
#3 lore raw
Quoted 37 lines · Adam Ford
Quoted 35 lines · Geert Uytterhoeven

Hi Adam,

CC Marek

Quoted 29 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +12 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
                - 5p49v5933 and
                - 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+                 - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+                 - CMOS
+                 - HCSL
+                 - LVDS: Low voltage differential signal
+
+- voltage-level:  can be one of the following microvolts
+                 - 1800000
+                 - 2500000
+                 - 3300000
Quoted 8 lines
Quoted 8 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt Required properties: · line 49

Quoted 5 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +5 -0
+-  slew: Percent of normal, can be one of
+                 - P80
+                 - P85
+                 - P90
+                 - P100

Why the P prefixes? Can't you just use integer values?
After the conversion to json-schema, these values can be validated, too.

That makes sense. We can just use numbers.

Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
Quoted 8 lines
Quoted 3 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt clock specifier, the following mapping applies: · line 84

Quoted 1 line
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+#include <dt-bindings/versaclock.h>

Does not exist?

Not yet. Before actually coding anything, I wanted to get feedback on how the bindings should look. In this file would be definitions of terms like P80, CMOS, and the other items that are defined for mode and slew.

The intent was to create this file and define a sensible translation between the arbitrary the numbers 0 to 7 and the acronyms for "output type". Would it be better to just use strings for output type (and not create this header file)? I think I've seen something like that in a TI driver. I hesitate to put a bunch of string compares in a driver. Is there another way? Could we use properties and only allow one?

Quoted 30 lines
Quoted 30 lines
Quoted 9 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+
 /* 25MHz reference crystal */
 ref25: ref25m {
        compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
                /* Connect XIN input to 25MHz reference */
                clocks = <&ref25m>;

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 112

Quoted 10 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +7 -0
                clock-names = "xin";
+
+               ports@1 {
+                       reg = <1>;
+                       mode = <CMOS>;
+                       pwr_sel = <1800000>;
+                       slew = <P80>;
+               };
        };
 };

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds

maintainer
#4 lore raw
In reply to Adam Ford
Quoted 49 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +21 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
 		- 5p49v5933 and
 		- 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+		  - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+		  - CMOS
+		  - HCSL 
+		  - LVDS: Low voltage differential signal
+
+- voltage-level:  can be one of the following microvolts
+		  - 1800000
+		  - 2500000
+		  - 3300000
+-  slew: Percent of normal, can be one of 
+		  - P80 
+		  - P85
+		  - P90
+		  - P100 
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
+#include <dt-bindings/versaclock.h>
+
 /* 25MHz reference crystal */
 ref25: ref25m {
 	compatible = "fixed-clock";

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 105

Quoted 5 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
@@ -80,6 +101,13 @@ i2c-master-node {
 		/* Connect XIN input to 25MHz reference */
 		clocks = <&ref25m>;
 		clock-names = "xin";
+
+		ports@1 {

'ports' is already taken as a node name.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 106

Quoted 1 line
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+			reg = <1>;

What do the reg value signify?

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 108

Quoted 2 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+			mode = <CMOS>;
+			pwr_sel = <1800000>;

Not documented. Don't use '-' in property names.

Quoted 8 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+			slew = <P80>;
+		};
 	};
 };
 
Signature · 1 line
2.25.1
author
#5 lore raw
Quoted 45 lines · Rob Herring
Quoted 43 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +19 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
              - 5p49v5933 and
              - 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+               - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+               - CMOS
+               - HCSL
+               - LVDS: Low voltage differential signal
+
+- voltage-level:  can be one of the following microvolts
+               - 1800000
+               - 2500000
+               - 3300000
+-  slew: Percent of normal, can be one of
+               - P80
+               - P85
+               - P90
+               - P100
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
Quoted 13 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 105

Quoted 11 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +4 -0
+#include <dt-bindings/versaclock.h>
+
 /* 25MHz reference crystal */
 ref25: ref25m {
      compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
              /* Connect XIN input to 25MHz reference */
              clocks = <&ref25m>;
              clock-names = "xin";
+
+             ports@1 {

'ports' is already taken as a node name.

Rob,

The clock chip can drive multiple clocks and each output is independent of the rest. The idea is that port@1 would represent output 1, port@2 would represent output 2, etc.
Is there a name you'd think we should use to represent each output? Different variations of this chip can have different number of outputs.

Quoted 4 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 106

Quoted 2 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+                     reg = <1>;

What do the reg value signify?

I am fine if we drop we drop it. I was under the assumption that reg =<1> had to correspond to the port@1 and that it was required since other devices with port sub-nodes use the reg entry.

Quoted 5 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 108

Quoted 3 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+                     mode = <CMOS>;
+                     pwr_sel = <1800000>;

Not documented. Don't use '-' in property names.

Do you have a preference to what name or convention you want us to use?

Quoted 1 line

Thanks for the review.

adam

Quoted 8 lines
Quoted 8 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -1
+                     slew = <P80>;
+             };
      };
 };
 
--

2.25.1

maintainer
#6 lore raw
Quoted 60 lines · Adam Ford
Quoted 45 lines · Rob Herring
Quoted 43 lines · Adam Ford

The Versaclock can be purchased in a non-programmed configuration. If that is the case, the driver needs to configure the chip to output the correct signal type, voltage and slew.

This RFC is proposing an additional binding to allow non-programmed chips to be configured beyond their default configuration.

Documentation/devicetree/bindings/clock/idt,versaclock5.txt +19 -0
index 05a245c9df08..4bc46ed9ba4a 100644
@@ -30,6 +30,25 @@ Required properties:
              - 5p49v5933 and
              - 5p49v5935: (optional) property not present or "clkin".
 
+For all output ports, an option child node can be used to specify:
+
+- mode: can be one of
+               - LVPECL: Low-voltage positive/psuedo emitter-coupled logic
+               - CMOS
+               - HCSL
+               - LVDS: Low voltage differential signal
+
+- voltage-level:  can be one of the following microvolts
+               - 1800000
+               - 2500000
+               - 3300000
+-  slew: Percent of normal, can be one of
+               - P80
+               - P85
+               - P90
+               - P100
+
+
 ==Mapping between clock specifier and physical pins==
 
 When referencing the provided clock in the DT using phandle and
@@ -62,6 +81,8 @@ clock specifier, the following mapping applies:
 
 ==Example==
 
Quoted 13 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 105

Quoted 11 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +4 -0
+#include <dt-bindings/versaclock.h>
+
 /* 25MHz reference crystal */
 ref25: ref25m {
      compatible = "fixed-clock";
@@ -80,6 +101,13 @@ i2c-master-node {
              /* Connect XIN input to 25MHz reference */
              clocks = <&ref25m>;
              clock-names = "xin";
+
+             ports@1 {

'ports' is already taken as a node name.

Quoted 6 lines

Rob,

The clock chip can drive multiple clocks and each output is independent of the rest. The idea is that port@1 would represent output 1, port@2 would represent output 2, etc.
Is there a name you'd think we should use to represent each output?

clock-output@...?

Quoted 11 lines

Different variations of this chip can have different number of outputs.

Quoted 4 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 106

Quoted 2 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +1 -0
+                     reg = <1>;

What do the reg value signify?

I am fine if we drop we drop it. I was under the assumption that reg =<1> had to correspond to the port@1 and that it was required since other devices with port sub-nodes use the reg entry.

I wasn't suggesting dropping it. Just what 0, 1, 2, etc. corresponds to as you explained above. Just put that into the 'reg' description.

Quoted 6 lines
Quoted 4 lines

Documentation/devicetree/bindings/clock/idt,versaclock5.txt i2c-master-node { · line 108

Quoted 2 lines
Documentation/devicetree/bindings/clock/idt,versaclock5.txt +2 -0
+                     mode = <CMOS>;
+                     pwr_sel = <1800000>;

Not documented. Don't use '-' in property names.

Do you have a preference to what name or convention you want us to use?

Errr, that was supposed to say '_'. Using hyphens is fine.

Also, needs a vendor prefix and if that's in microvolts needs a unit suffix.

Rob