[PATCH v3 0/2] gs101 oriole: UART clock fixes

[PATCH v3 0/2] gs101 oriole: UART clock fixes

[André Draszik]

Hi,

This series fixes two issues in the gs101 clocking / uart handling & related
device tree binding:
1) the binding omitted specifying the required number of clocks for the UART
2) an incorrect work-around in the gs101 clock driver

The 2nd point is essentially the last remaining patch [1] with all review
comments addressed, from the series [2] that was sent earlier this year, see
lore links below.

As requested, I'm also documenting (in the binding) the hand-over issue
between earlycon and (real) console driver that we have on gs101, see [3].
While doing that, I noticed the omission mentioned in point 1) above, hence
this series.

To avoid confusion, I'm marking this whole series as v3 because the patch to
clk-gs101.c had been sent as v2 previously, and this supersedes it.

Signed-off-by: André Draszik <andre.draszik@linaro.org>

[1] https://lore.kernel.org/all/20240130093812.1746512-6-andre.draszik@linaro.org/
[2] https://lore.kernel.org/all/20240130093812.1746512-1-andre.draszik@linaro.org/
[3] https://lore.kernel.org/all/d45de3b2bb6b48653842cf1f74e58889ed6783ae.camel@linaro.org/

---
André Draszik (2):
      dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements
      clk: samsung: gs101: don't mark non-essential (UART) clocks critical

 Documentation/devicetree/bindings/serial/samsung_uart.yaml | 14 ++++++++++++++
 drivers/clk/samsung/clk-gs101.c                            |  6 ++----
 2 files changed, 16 insertions(+), 4 deletions(-)
---
base-commit: 523b23f0bee3014a7a752c9bb9f5c54f0eddae88
change-id: 20240430-gs101-non-essential-clocks-2-6a3280fa1be8

Best regards,
-- 
André Draszik <andre.draszik@linaro.org>

[PATCH v3 1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements

[André Draszik]

While gs101 needs exactly two clocks for the UART, the schema doesn't
currently limit the maximum number to this and instead the default of
five from this schema is applied.

Update the schema accordingly.

Also, as pointed out in [1] before, the hand-over between earlycon and
serial console is fragile due to clocking issues, at least on Google
Tensor gs101. Therefore, document the clocking requirements for
earlycon in the description for posterity, so the information is not
lost.

Link: https://lore.kernel.org/all/d45de3b2bb6b48653842cf1f74e58889ed6783ae.camel@linaro.org/ [1]
Signed-off-by: André Draszik <andre.draszik@linaro.org>
---
 Documentation/devicetree/bindings/serial/samsung_uart.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
index 0f0131026911..2435c3d92158 100644
--- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml
+++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
@@ -145,6 +145,20 @@ allOf:
         - samsung,uart-fifosize
       properties:
         reg-io-width: false
+        clocks:
+          description: |
+            Note that for earlycon to work, the respective ipclk and pclk need
+            to be running! The bootloader normally leaves them enabled, but the
+            serial driver will start handling those clocks before the console
+            driver takes over from earlycon, breaking earlycon. If earlycon is
+            required, please revert the patch "clk: samsung: gs101: don't mark
+            non-essential (UART) clocks critical" locally first to mark them
+            CLK_IS_CRITICAL and avoid this problem.
+          maxItems: 2
+        clock-names:
+          items:
+            - const: uart
+            - const: clk_uart_baud0
 
 unevaluatedProperties: false
 

-- 
2.45.2.803.g4e1b14247a-goog

Re: [PATCH v3 1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements

[Rob Herring]

On Wed, Jul 10, 2024 at 7:29 AM André Draszik <andre.draszik@linaro.org> wrote:
>
> While gs101 needs exactly two clocks for the UART, the schema doesn't
> currently limit the maximum number to this and instead the default of
> five from this schema is applied.
>
> Update the schema accordingly.
>
> Also, as pointed out in [1] before, the hand-over between earlycon and
> serial console is fragile due to clocking issues, at least on Google
> Tensor gs101. Therefore, document the clocking requirements for
> earlycon in the description for posterity, so the information is not
> lost.
>
> Link: https://lore.kernel.org/all/d45de3b2bb6b48653842cf1f74e58889ed6783ae.camel@linaro.org/ [1]
> Signed-off-by: André Draszik <andre.draszik@linaro.org>
> ---
>  Documentation/devicetree/bindings/serial/samsung_uart.yaml | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> index 0f0131026911..2435c3d92158 100644
> --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> @@ -145,6 +145,20 @@ allOf:
>          - samsung,uart-fifosize
>        properties:
>          reg-io-width: false

blank line between properties

> +        clocks:
> +          description: |
> +            Note that for earlycon to work, the respective ipclk and pclk need
> +            to be running! The bootloader normally leaves them enabled, but the
> +            serial driver will start handling those clocks before the console
> +            driver takes over from earlycon, breaking earlycon. If earlycon is
> +            required, please revert the patch "clk: samsung: gs101: don't mark
> +            non-essential (UART) clocks critical" locally first to mark them
> +            CLK_IS_CRITICAL and avoid this problem.

That's a whole bunch of details that are Linux specific which have
little to do with the binding.

> +          maxItems: 2
> +        clock-names:
> +          items:
> +            - const: uart
> +            - const: clk_uart_baud0

Which clock is pclk and ipclk? 'baud' would be sufficient for the
name. 'clk_' and 'uart' are redundant because it's all clocks and they
are all for the uart.

Rob

Re: [PATCH v3 1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements

[André Draszik]

Hi Rob,

On Thu, 2024-07-11 at 09:51 -0600, Rob Herring wrote:
> On Wed, Jul 10, 2024 at 7:29 AM André Draszik <andre.draszik@linaro.org> wrote:
> > --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > @@ -145,6 +145,20 @@ allOf:
> >          - samsung,uart-fifosize
> >        properties:
> >          reg-io-width: false
> 
> blank line between properties

Do mean before clocks: below and before clock-names: below? We don't do that normally,
at least none of the bindings I looked at do that. Or did I misunderstand?

> > +        clocks:
> > +          description: |
> > +            Note that for earlycon to work, the respective ipclk and pclk need
> > +            to be running! The bootloader normally leaves them enabled, but the
> > +            serial driver will start handling those clocks before the console
> > +            driver takes over from earlycon, breaking earlycon. If earlycon is
> > +            required, please revert the patch "clk: samsung: gs101: don't mark
> > +            non-essential (UART) clocks critical" locally first to mark them
> > +            CLK_IS_CRITICAL and avoid this problem.
> 
> That's a whole bunch of details that are Linux specific which have
> little to do with the binding.

You're right - I had been asked to add this to the binding and didn't consider
that. I think I found a much better alternative in the meantime and this
description can go away.

> > +          maxItems: 2
> > +        clock-names:
> > +          items:
> > +            - const: uart
> > +            - const: clk_uart_baud0
> 
> Which clock is pclk and ipclk?

uart is pclk, clk_uart_baud0 is ipclk.

> 'baud' would be sufficient for the
> name. 'clk_' and 'uart' are redundant because it's all clocks and they
> are all for the uart.

TBH, this patch is just following the existing style & names as already exist for
various other SoCs in this same file. Furthermore, up until this patch the default
from this file applies, which is:

  clock-names:
    description: N = 0 is allowed for SoCs without internal baud clock mux.
    minItems: 2
    items:
      - const: uart
      - pattern: '^clk_uart_baud[0-3]$'
      - pattern: '^clk_uart_baud[0-3]$'
      - pattern: '^clk_uart_baud[0-3]$'
      - pattern: '^clk_uart_baud[0-3]$'

so of course the existing gs101 DTs had followed this scheme. Other SoCs that are
described in this same binding also keep the name as per the default in case
they limit the maximum number like this patch does.

Changing the name now would be a bit disruptive and make gs101 differ from other
Exynos SoCs in this respect, I'd rather not :-)


Cheers,
Andre'

Re: [PATCH v3 1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements

[Rob Herring]

On Thu, Jul 11, 2024 at 05:09:50PM +0100, André Draszik wrote:
> Hi Rob,
> 
> On Thu, 2024-07-11 at 09:51 -0600, Rob Herring wrote:
> > On Wed, Jul 10, 2024 at 7:29 AM André Draszik <andre.draszik@linaro.org> wrote:
> > > --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > > +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > > @@ -145,6 +145,20 @@ allOf:
> > >          - samsung,uart-fifosize
> > >        properties:
> > >          reg-io-width: false
> > 
> > blank line between properties
> 
> Do mean before clocks: below and before clock-names: below? 

Yes.

> We don't do that normally,
> at least none of the bindings I looked at do that. Or did I misunderstand?

That style is pretty universal. If in doubt, look at example-schema.yaml 
for best practices. The exception is only for cases like this:

  foo: true
  bar: true

> > > +        clocks:
> > > +          description: |
> > > +            Note that for earlycon to work, the respective ipclk and pclk need
> > > +            to be running! The bootloader normally leaves them enabled, but the
> > > +            serial driver will start handling those clocks before the console
> > > +            driver takes over from earlycon, breaking earlycon. If earlycon is
> > > +            required, please revert the patch "clk: samsung: gs101: don't mark
> > > +            non-essential (UART) clocks critical" locally first to mark them
> > > +            CLK_IS_CRITICAL and avoid this problem.
> > 
> > That's a whole bunch of details that are Linux specific which have
> > little to do with the binding.
> 
> You're right - I had been asked to add this to the binding and didn't consider
> that. I think I found a much better alternative in the meantime and this
> description can go away.

I hope so because asking someone to revert a patch to use earlycon is 
not a great experience. I wouldn't want to use that platform.

> 
> > > +          maxItems: 2
> > > +        clock-names:
> > > +          items:
> > > +            - const: uart
> > > +            - const: clk_uart_baud0
> > 
> > Which clock is pclk and ipclk?
> 
> uart is pclk, clk_uart_baud0 is ipclk.
> 
> > 'baud' would be sufficient for the
> > name. 'clk_' and 'uart' are redundant because it's all clocks and they
> > are all for the uart.
> 
> TBH, this patch is just following the existing style & names as already exist for
> various other SoCs in this same file. Furthermore, up until this patch the default
> from this file applies, which is:
> 
>   clock-names:
>     description: N = 0 is allowed for SoCs without internal baud clock mux.
>     minItems: 2
>     items:
>       - const: uart
>       - pattern: '^clk_uart_baud[0-3]$'
>       - pattern: '^clk_uart_baud[0-3]$'
>       - pattern: '^clk_uart_baud[0-3]$'
>       - pattern: '^clk_uart_baud[0-3]$'

Then don't duplicate it. Ideally, the names are defined at the top level 
and the conditional schema just limits the number of clocks, and this is 
an example of why we want it that way. I have no context to see if this 
is consistent or not.

> 
> so of course the existing gs101 DTs had followed this scheme. Other SoCs that are
> described in this same binding also keep the name as per the default in case
> they limit the maximum number like this patch does.
> 
> Changing the name now would be a bit disruptive and make gs101 differ from other
> Exynos SoCs in this respect, I'd rather not :-)

Agreed.

Rob

Re: [PATCH v3 1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements

[André Draszik]

Hi Rob,

On Thu, 2024-07-11 at 15:23 -0600, Rob Herring wrote:
> On Thu, Jul 11, 2024 at 05:09:50PM +0100, André Draszik wrote:
> > Hi Rob,
> > 
> > On Thu, 2024-07-11 at 09:51 -0600, Rob Herring wrote:
> > > On Wed, Jul 10, 2024 at 7:29 AM André Draszik <andre.draszik@linaro.org> wrote:
> > > > --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > > > +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml
> > > > @@ -145,6 +145,20 @@ allOf:
> > > >          - samsung,uart-fifosize
> > > >        properties:
> > > >          reg-io-width: false
> > > 
> > > blank line between properties
> > 
> > Do mean before clocks: below and before clock-names: below? 
> 
> Yes.
> 
> > We don't do that normally,
> > at least none of the bindings I looked at do that. Or did I misunderstand?
> 
> That style is pretty universal. If in doubt, look at example-schema.yaml 
> for best practices. The exception is only for cases like this:
> 
>   foo: true
>   bar: true

example-schema.yaml doesn't have an example for that, so I suspect that's why
many (Samsung?) bindings ended up without the blank line. I have fixed it for
this schema in the next version in
https://lore.kernel.org/all/20240712-gs101-uart-binding-v4-1-24e9f8d4bdcb@linaro.org/

> > > 
> > > > +          maxItems: 2
> > > > +        clock-names:
> > > > +          items:
> > > > +            - const: uart
> > > > +            - const: clk_uart_baud0
> > > 
> > > Which clock is pclk and ipclk?
> > 
> > uart is pclk, clk_uart_baud0 is ipclk.
> > 
> > > 'baud' would be sufficient for the
> > > name. 'clk_' and 'uart' are redundant because it's all clocks and they
> > > are all for the uart.
> > 
> > TBH, this patch is just following the existing style & names as already exist for
> > various other SoCs in this same file. Furthermore, up until this patch the default
> > from this file applies, which is:
> > 
> >   clock-names:
> >     description: N = 0 is allowed for SoCs without internal baud clock mux.
> >     minItems: 2
> >     items:
> >       - const: uart
> >       - pattern: '^clk_uart_baud[0-3]$'
> >       - pattern: '^clk_uart_baud[0-3]$'
> >       - pattern: '^clk_uart_baud[0-3]$'
> >       - pattern: '^clk_uart_baud[0-3]$'
> 
> Then don't duplicate it. Ideally, the names are defined at the top level 
> and the conditional schema just limits the number of clocks, and this is 
> an example of why we want it that way. I have no context to see if this 
> is consistent or not.

I've fixed it in https://lore.kernel.org/all/20240712-gs101-uart-binding-v4-1-24e9f8d4bdcb@linaro.org/

Hopefully you'll that's more acceptable :-)

Cheers,
Andre'

[PATCH v3 2/2] clk: samsung: gs101: don't mark non-essential (UART) clocks critical

[André Draszik]

The peric0_top1_ipclk_0 and peric0_top1_pclk_0 are the clocks going to
peric0/uart_usi, with pclk being the bus clock. Without pclk running,
any bus access will hang.
Unfortunately, in commit d97b6c902a40 ("arm64: dts: exynos: gs101:
update USI UART to use peric0 clocks") the gs101 DT ended up specifying
an incorrect pclk in the respective node and instead the two clocks
here were marked as critical.

Since then, the DT has been updated to use the correct clock in
commit 21e4e8807bfc ("arm64: dts: exynos: gs101: use correct clocks for
usi_uart") and the driver here should be corrected and the work-around
removed.

Note that this commit has the side-effect of causing earlycon to stop
to work sometime into the boot for two reasons:
    * peric0_top1_ipclk_0 requires its parent gout_cmu_peric0_ip to be
      running, but because earlycon doesn't deal with clocks that
      parent will be disabled when none of the other drivers that
      actually deal with clocks correctly require it to be running and
      the real serial driver (which does deal with clocks) hasn't taken
      over yet
    * hand-over between earlycon and serial driver appears to be
      fragile and clocks get enabled and disabled a few times, which
      also causes register access to hang while earlycon is still
      active
(A wordier explanation can also be found in [1])

Nonetheless we shouldn't keep these clocks running unconditionally just
for earlycon. Clocks should be disabled where possible. If earlycon is
required in the future, e.g. for debug, this commit can simply be
reverted (locally!).

Link: https://lore.kernel.org/all/d45de3b2bb6b48653842cf1f74e58889ed6783ae.camel@linaro.org/ [1]
Fixes: 893f133a040b ("clk: samsung: gs101: add support for cmu_peric0")
Signed-off-by: André Draszik <andre.draszik@linaro.org>
Reviewed-by: Tudor Ambarus <tudor.ambarus@linaro.org>
Reviewed-by: Sam Protsenko <semen.protsenko@linaro.org>

---
v3:
- add git commit SHA1s (Krzysztof)
- add link to wordier description of earlycon issue

v2:
- commit message typo fixed
- collect Reviewed-by: tags
---
 drivers/clk/samsung/clk-gs101.c | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/drivers/clk/samsung/clk-gs101.c b/drivers/clk/samsung/clk-gs101.c
index 85098c61c15e..9769c00b6ca8 100644
--- a/drivers/clk/samsung/clk-gs101.c
+++ b/drivers/clk/samsung/clk-gs101.c
@@ -3946,20 +3946,18 @@ static const struct samsung_gate_clock peric0_gate_clks[] __initconst = {
 	     "gout_peric0_peric0_top0_pclk_9", "mout_peric0_bus_user",
 	     CLK_CON_GAT_GOUT_BLK_PERIC0_UID_PERIC0_TOP0_IPCLKPORT_PCLK_9,
 	     21, 0, 0),
-	/* Disabling this clock makes the system hang. Mark the clock as critical. */
 	GATE(CLK_GOUT_PERIC0_PERIC0_TOP1_IPCLK_0,
 	     "gout_peric0_peric0_top1_ipclk_0", "dout_peric0_usi0_uart",
 	     CLK_CON_GAT_GOUT_BLK_PERIC0_UID_PERIC0_TOP1_IPCLKPORT_IPCLK_0,
-	     21, CLK_IS_CRITICAL, 0),
+	     21, 0, 0),
 	GATE(CLK_GOUT_PERIC0_PERIC0_TOP1_IPCLK_2,
 	     "gout_peric0_peric0_top1_ipclk_2", "dout_peric0_usi14_usi",
 	     CLK_CON_GAT_GOUT_BLK_PERIC0_UID_PERIC0_TOP1_IPCLKPORT_IPCLK_2,
 	     21, CLK_SET_RATE_PARENT, 0),
-	/* Disabling this clock makes the system hang. Mark the clock as critical. */
 	GATE(CLK_GOUT_PERIC0_PERIC0_TOP1_PCLK_0,
 	     "gout_peric0_peric0_top1_pclk_0", "mout_peric0_bus_user",
 	     CLK_CON_GAT_GOUT_BLK_PERIC0_UID_PERIC0_TOP1_IPCLKPORT_PCLK_0,
-	     21, CLK_IS_CRITICAL, 0),
+	     21, 0, 0),
 	GATE(CLK_GOUT_PERIC0_PERIC0_TOP1_PCLK_2,
 	     "gout_peric0_peric0_top1_pclk_2", "mout_peric0_bus_user",
 	     CLK_CON_GAT_GOUT_BLK_PERIC0_UID_PERIC0_TOP1_IPCLKPORT_PCLK_2,

-- 
2.45.2.803.g4e1b14247a-goog

Re: [PATCH v3 2/2] clk: samsung: gs101: don't mark non-essential (UART) clocks critical

[Marek Szyprowski]

On 10.07.2024 15:29, André Draszik wrote:
> The peric0_top1_ipclk_0 and peric0_top1_pclk_0 are the clocks going to
> peric0/uart_usi, with pclk being the bus clock. Without pclk running,
> any bus access will hang.
> Unfortunately, in commit d97b6c902a40 ("arm64: dts: exynos: gs101:
> update USI UART to use peric0 clocks") the gs101 DT ended up specifying
> an incorrect pclk in the respective node and instead the two clocks
> here were marked as critical.
>
> Since then, the DT has been updated to use the correct clock in
> commit 21e4e8807bfc ("arm64: dts: exynos: gs101: use correct clocks for
> usi_uart") and the driver here should be corrected and the work-around
> removed.
>
> Note that this commit has the side-effect of causing earlycon to stop
> to work sometime into the boot for two reasons:
>      * peric0_top1_ipclk_0 requires its parent gout_cmu_peric0_ip to be
>        running, but because earlycon doesn't deal with clocks that
>        parent will be disabled when none of the other drivers that
>        actually deal with clocks correctly require it to be running and
>        the real serial driver (which does deal with clocks) hasn't taken
>        over yet
>      * hand-over between earlycon and serial driver appears to be
>        fragile and clocks get enabled and disabled a few times, which
>        also causes register access to hang while earlycon is still
>        active
> (A wordier explanation can also be found in [1])
>
> Nonetheless we shouldn't keep these clocks running unconditionally just
> for earlycon. Clocks should be disabled where possible. If earlycon is
> required in the future, e.g. for debug, this commit can simply be
> reverted (locally!).
>
> Link: https://lore.kernel.org/all/d45de3b2bb6b48653842cf1f74e58889ed6783ae.camel@linaro.org/ [1]
> Fixes: 893f133a040b ("clk: samsung: gs101: add support for cmu_peric0")
> Signed-off-by: André Draszik <andre.draszik@linaro.org>
> Reviewed-by: Tudor Ambarus <tudor.ambarus@linaro.org>
> Reviewed-by: Sam Protsenko <semen.protsenko@linaro.org>

Frankly speaking I'm not sure that anyone will find this comment and do 
local reverts before getting angry that earlycon doesn't work for his 
device and wasting his time.

I think that it would be much better to check if earlycon is specified 
in kernel's cmdline and if so, simply mark those problematic clocks 
critical in this driver. Make this code hidden under 
IS_ENABLED(CONFIG_SERIAL_EARLYCON) to avoid polluting release builds. 
Any comments?

Best regards
-- 
Marek Szyprowski, PhD
Samsung R&D Institute Poland

Re: [PATCH v3 2/2] clk: samsung: gs101: don't mark non-essential (UART) clocks critical

[André Draszik]

On Wed, 2024-07-10 at 16:35 +0200, Marek Szyprowski wrote:
> I think that it would be much better to check if earlycon is specified 
> in kernel's cmdline and if so, simply mark those problematic clocks 
> critical in this driver. Make this code hidden under 
> IS_ENABLED(CONFIG_SERIAL_EARLYCON) to avoid polluting release builds. 
> Any comments?

Good idea, I've found that i.MX appears to suffer from a similar problem,
and I'm testing something similar now:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/clk/imx/clk.c#n157


Cheers,
Andre'