| Message ID | 20240710-gs101-non-essential-clocks-2-v3-1-5dcb8d040d1c@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | [v3,1/2] dt-bindings: serial: samsung: fix maxItems for gs101 & document earlycon requirements | expand |
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
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'
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
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'
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
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(+)