Skip to contentSkip to conversation

dt-bindings: clk: Make example a bit clearer

PATCH In review Alexander Dahl 3 participants 6 messages Aug 23, 2019 – Nov 8, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 dt-bindings: clk: Make example a bit clearer

From: Uwe Kleine-König <[email protected]>

Previously the example used <&pll 2> in two places which made it harder than necessary to understand why this clock gets the parent of <&clkcon 0>. Also describe why <&pll 2> isn't reparented and <&clkcon 0> gets no rate assigned.

---

Notes:
v2:
Add additional explaining text to following paragraph and strip mail headers from commit message.

 .../devicetree/bindings/clock/clock-bindings.txt     | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/devicetree/bindings/clock/clock-bindings.txt +7 -5
index b646bbcf7f92..1d4942380918 100644
@@ -150,16 +150,18 @@ set to 0, or can be omitted if it is not followed by any non-zero entry.
         compatible = "fsl,imx-uart";
         reg = <0xa000 0x1000>;
         ...
-        clocks = <&osc 0>, <&pll 1>;
-        clock-names = "baud", "register";
+        clocks = ...
+        clock-names = ...
 
         assigned-clocks = <&clkcon 0>, <&pll 2>;
-        assigned-clock-parents = <&pll 2>;
+        assigned-clock-parents = <&pll 1>;
         assigned-clock-rates = <0>, <460800>;
     };
 
-In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
-the <&pll 2> clock is assigned a frequency value of 460800 Hz.
+In this example the <&pll 1> clock is set as parent of clock <&clkcon 0> and
+the <&pll 2> clock is assigned a frequency value of 460800 Hz.  A parent
+setting for <&pll 2> is omitted (end of list) and rate setting for <&clkcon 0>
+is skipped because set to <0>.
 
 Configuring a clock's parent and rate through the device node that consumes
 the clock can be done only for clocks that have a single user. Specifying
Signature · 1 line
2.20.1
maintainer
#1 lore raw

Quoting Alexander Dahl (2019-08-23 03:03:15)

Quoted 2 lines

---

You need to Cc Rob and devicetree list on binding changes.

Quoted 14 lines

Notes:
v2:
Add additional explaining text to following paragraph and strip mail headers from commit message.

 .../devicetree/bindings/clock/clock-bindings.txt     | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/devicetree/bindings/clock/clock-bindings.txt +0 -0
index b646bbcf7f92..1d4942380918 100644

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 154

Quoted 7 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +2 -2
@@ -150,16 +150,18 @@ set to 0, or can be omitted if it is not followed by any non-zero entry.
         compatible = "fsl,imx-uart";
         reg = <0xa000 0x1000>;
...
-        clocks = <&osc 0>, <&pll 1>;
-        clock-names = "baud", "register";
+        clocks = ...
+        clock-names = ...

I don't see the need for this change.

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 164

Quoted 13 lines
 
         assigned-clocks = <&clkcon 0>, <&pll 2>;
Documentation/devicetree/bindings/clock/clock-bindings.txt +5 -3
-        assigned-clock-parents = <&pll 2>;
+        assigned-clock-parents = <&pll 1>;
         assigned-clock-rates = <0>, <460800>;
     };
 
-In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
-the <&pll 2> clock is assigned a frequency value of 460800 Hz.
+In this example the <&pll 1> clock is set as parent of clock <&clkcon 0> and
+the <&pll 2> clock is assigned a frequency value of 460800 Hz.  A parent
+setting for <&pll 2> is omitted (end of list) and rate setting for <&clkcon 0>
+is skipped because set to <0>.

Maybe you can comment that the "clocks" and "clock-names" properties don't matter for assigned clk rates and parents.

#2 lore raw

Hello,

Quoted 6 lines · Stephen Boyd
Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +0 -0
index b646bbcf7f92..1d4942380918 100644
@@ -150,16 +150,18 @@ set to 0, or can be omitted if it is not followed by any non-zero entry.
         compatible = "fsl,imx-uart";
Quoted 8 lines

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 154

Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +2 -2
         reg = <0xa000 0x1000>;
...
-        clocks = <&osc 0>, <&pll 1>;
-        clock-names = "baud", "register";
+        clocks = ...
+        clock-names = ...

I don't see the need for this change.

<&pll 1> is mentioned below. But it is not this instance that is relevant. So I suggested to get rid of it to not be a source of confusion. (But I guess you understood that.)

Quoted 6 lines
Quoted 6 lines
         assigned-clocks = <&clkcon 0>, <&pll 2>;
Documentation/devicetree/bindings/clock/clock-bindings.txt +1 -1
-        assigned-clock-parents = <&pll 2>;
+        assigned-clock-parents = <&pll 1>;
         assigned-clock-rates = <0>, <460800>;
     };
Quoted 9 lines

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 164

Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +4 -2
-In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
-the <&pll 2> clock is assigned a frequency value of 460800 Hz.
+In this example the <&pll 1> clock is set as parent of clock <&clkcon 0> and
+the <&pll 2> clock is assigned a frequency value of 460800 Hz.  A parent
+setting for <&pll 2> is omitted (end of list) and rate setting for <&clkcon 0>
+is skipped because set to <0>.

Maybe you can comment that the "clocks" and "clock-names" properties don't matter for assigned clk rates and parents.

Sure, a long text can explain this, but a maximal simple example is very beneficial, too.

Best regards
Uwe

Signature · 2 lines
Pengutronix e.K.                           | Uwe Kleine-K�nig            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
maintainer
#3 lore raw

(Sorry my MUA fails at utf8 encoding emails)

Quoted 16 lines · Stephen Boyd
Quoted 6 lines
Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +0 -0
index b646bbcf7f92..1d4942380918 100644
@@ -150,16 +150,18 @@ set to 0, or can be omitted if it is not followed by any non-zero entry.
         compatible = "fsl,imx-uart";
Quoted 8 lines

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 154

Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +2 -2
         reg = <0xa000 0x1000>;
...
-        clocks = <&osc 0>, <&pll 1>;
-        clock-names = "baud", "register";
+        clocks = ...
+        clock-names = ...

I don't see the need for this change.

Quoted 3 lines

<&pll 1> is mentioned below. But it is not this instance that is relevant. So I suggested to get rid of it to not be a source of confusion. (But I guess you understood that.)

Yes.

Quoted 17 lines
Quoted 7 lines
Quoted 7 lines
         assigned-clocks = <&clkcon 0>, <&pll 2>;
Documentation/devicetree/bindings/clock/clock-bindings.txt +1 -1
-        assigned-clock-parents = <&pll 2>;
+        assigned-clock-parents = <&pll 1>;
         assigned-clock-rates = <0>, <460800>;
     };
Quoted 9 lines

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 164

Quoted 6 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +4 -2
-In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and
-the <&pll 2> clock is assigned a frequency value of 460800 Hz.
+In this example the <&pll 1> clock is set as parent of clock <&clkcon 0> and
+the <&pll 2> clock is assigned a frequency value of 460800 Hz.  A parent
+setting for <&pll 2> is omitted (end of list) and rate setting for <&clkcon 0>
+is skipped because set to <0>.

Maybe you can comment that the "clocks" and "clock-names" properties don't matter for assigned clk rates and parents.

Quoted 3 lines

Sure, a long text can explain this, but a maximal simple example is very beneficial, too.

The paragraph at the start of "Assigned clock parents and rates" already explains how these properties work. This patch isn't going to help if the reader hasn't read that paragraph, so reordering things isn't providing more clarity. If anything, I would clarify the description of the example by indicating what parts of the example we're talking about when explaining, i.e.

In this example the <&pll 2> clock is set as parent of the <&clkcon 0> clock because the first clock specifier in the assigned-clocks property is <&clkcon 0> and that matches the first clock specifier in the assigned-clock-parents property. Similarly the <&pll 2> clock is assigned a frequency value of 460800 Hz because the second frequency in the assigned-clock-rates property is 460800 Hz and that matches the second clock specifier in the assigned-clocks property <&pll 2>.

#4 lore raw

Hello Stephen,

I took some minutes to look at this again, because I was the one who had difficulties understanding the documentation here in the first place.

Note: this patch/discussion is not about changing the dt-binding, but about improving the documentation on the properties 'assigned-clocks', 'assigned- clock-parents', and 'assigned-clock-rates'. See below:

Am Montag, 16. September 2019, 13:13:16 CEST schrieb Stephen Boyd:

Quoted 22 lines

(Sorry my MUA fails at utf8 encoding emails)

Quoted 20 lines · Stephen Boyd
Quoted 18 lines
Quoted 12 lines

diff --git a/Documentation/devicetree/bindings/clock/clock-bindings.txt b/Documentation/devicetree/bindings/clock/clock-bindings.txt index b646bbcf7f92..1d4942380918 100644

Documentation/devicetree/bindings/clock/clock-bindings.txt +0 -0
@@ -150,16 +150,18 @@ set to 0, or can be omitted if it is not

followed by any non-zero entry.> > >

         compatible = "fsl,imx-uart";
         reg = <0xa000 0x1000>;
         ...

Documentation/devicetree/bindings/clock/clock-bindings.txt set to 0, or can be omitted if it is not followed by any non-zero entry. · line 154

Quoted 4 lines
Documentation/devicetree/bindings/clock/clock-bindings.txt +2 -2
-        clocks = <&osc 0>, <&pll 1>;
-        clock-names = "baud", "register";
+        clocks = ...
+        clock-names = ...

I don't see the need for this change.

Quoted 5 lines
Quoted 3 lines

<&pll 1> is mentioned below. But it is not this instance that is relevant. So I suggested to get rid of it to not be a source of confusion. (But I guess you understood that.)

Yes.

This was indeed one source of confusion for me. This obfuscation of Uwe would have helped me, because it hides distracting information, which is irrelevant for explaining assigned clock parents and might lead to false conclusions on how those things work.

Quoted 20 lines
Quoted 20 lines
Quoted 19 lines
Quoted 10 lines
         assigned-clocks = <&clkcon 0>, <&pll 2>;
Documentation/devicetree/bindings/clock/clock-bindings.txt +1 -2
-        assigned-clock-parents = <&pll 2>;
+        assigned-clock-parents = <&pll 1>;
 
         assigned-clock-rates = <0>, <460800>;
 
     };
 
-In this example the <&pll 2> clock is set as parent of clock <&clkcon
Quoted 6 lines

0> and -the <&pll 2> clock is assigned a frequency value of 460800 Hz.
+In this example the <&pll 1> clock is set as parent of clock <&clkcon 0> and +the <&pll 2> clock is assigned a frequency value of 460800 Hz. A parent +setting for <&pll 2> is omitted (end of list) and rate setting for <&clkcon 0> +is skipped because set to <0>.

Maybe you can comment that the "clocks" and "clock-names" properties don't matter for assigned clk rates and parents.

Quoted 7 lines
Quoted 2 lines

Sure, a long text can explain this, but a maximal simple example is very beneficial, too.

The paragraph at the start of "Assigned clock parents and rates" already explains how these properties work. This patch isn't going to help if the reader hasn't read that paragraph, so reordering things isn't providing more clarity.

Reordering might not help. What helps on understanding things is describing the same topic in a different way again. This is somewhat redundant, but someone who does not fully understand explanation A might understand explanation B better.

Quoted 4 lines

If anything, I would clarify the description of
the example by indicating what parts of the example we're talking about when explaining, i.e.

Quoted 8 lines

In this example the <&pll 2> clock is set as parent of the <&clkcon 0> clock because the first clock specifier in the assigned-clocks property is <&clkcon 0> and that matches the first clock specifier in the assigned-clock-parents property. Similarly the <&pll 2> clock is assigned a frequency value of 460800 Hz because the second frequency in the assigned-clock-rates property is 460800 Hz and that matches the second clock specifier in the assigned-clocks property <&pll 2>.

I could go with that and send a v3 with the obfuscation from above (I'd like to keep that) and this paragraph of yours?

Greets
Alex

maintainer
#5 lore raw

Quoting Alexander Dahl (2019-10-10 07:16:00)

Quoted 14 lines
Quoted 5 lines

If anything, I would clarify the description of
the example by indicating what parts of the example we're talking about when explaining, i.e.

Quoted 8 lines

In this example the <&pll 2> clock is set as parent of the <&clkcon 0> clock because the first clock specifier in the assigned-clocks property is <&clkcon 0> and that matches the first clock specifier in the assigned-clock-parents property. Similarly the <&pll 2> clock is assigned a frequency value of 460800 Hz because the second frequency in the assigned-clock-rates property is 460800 Hz and that matches the second clock specifier in the assigned-clocks property <&pll 2>.

Quoted 3 lines

I could go with that and send a v3 with the obfuscation from above (I'd like to keep that) and this paragraph of yours?

Sure. Please resend.