[PATCH] regulator: Document "regulator-boot-on" binding more thoroughly

[PATCH] regulator: Document "regulator-boot-on" binding more thoroughly

[Douglas Anderson]

The description of "regulator-boot-on" was a little unclear, at least
to me.  Did this property mean that we should turn the regulator on at
boot?  Or perhaps it was intended only to be used for regulators where
we couldn't read the state at bootup to indicate what state we should
assume?  The answer, it turns out, is both [1].

Let's document this.

[1] https://lore.kernel.org/r/20190923181431.GU2036@sirena.org.uk

Signed-off-by: Douglas Anderson <dianders@chromium.org>
---

 Documentation/devicetree/bindings/regulator/regulator.yaml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml
index 02c3043ce419..4e67fb41db6b 100644
--- a/Documentation/devicetree/bindings/regulator/regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/regulator.yaml
@@ -38,7 +38,12 @@ properties:
     type: boolean
 
   regulator-boot-on:
-    description: bootloader/firmware enabled regulator
+    description: bootloader/firmware enabled regulator.
+      It's expected that this regulator was left on by the bootloader.
+      If the bootloader didn't leave it on then OS should turn it on
+      at boot but shouldn't prevent it from being turned off later.
+      This property is intended to only be used for regulators where
+      Linux cannot read the state of the regulator at bootup.
     type: boolean
 
   regulator-allow-bypass:
-- 
2.23.0.444.g18eeb5a265-goog

Re: [PATCH] regulator: Document "regulator-boot-on" binding more thoroughly

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 861 bytes --]

On Thu, Sep 26, 2019 at 12:41:18PM -0700, Douglas Anderson wrote:

> -    description: bootloader/firmware enabled regulator
> +    description: bootloader/firmware enabled regulator.
> +      It's expected that this regulator was left on by the bootloader.
> +      If the bootloader didn't leave it on then OS should turn it on
> +      at boot but shouldn't prevent it from being turned off later.

This is good...

> +      This property is intended to only be used for regulators where
> +      Linux cannot read the state of the regulator at bootup.

...but we shouldn't say "Linux" here since the DT binding is for all
OSs, not just Linux.  I'd say "software" instead.  Really the
expectation is that things wouldn't support readback at all, though it's
possible there's some weird hardware out there that will support
readback some of the time I guess.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] regulator: Document "regulator-boot-on" binding more thoroughly

[Doug Anderson]

Hi,

On Tue, Oct 1, 2019 at 10:41 AM Mark Brown <broonie@kernel.org> wrote:
>
> On Thu, Sep 26, 2019 at 12:41:18PM -0700, Douglas Anderson wrote:
>
> > -    description: bootloader/firmware enabled regulator
> > +    description: bootloader/firmware enabled regulator.
> > +      It's expected that this regulator was left on by the bootloader.
> > +      If the bootloader didn't leave it on then OS should turn it on
> > +      at boot but shouldn't prevent it from being turned off later.
>
> This is good...
>
> > +      This property is intended to only be used for regulators where
> > +      Linux cannot read the state of the regulator at bootup.
>
> ...but we shouldn't say "Linux" here since the DT binding is for all
> OSs, not just Linux.  I'd say "software" instead.  Really the
> expectation is that things wouldn't support readback at all, though it's
> possible there's some weird hardware out there that will support
> readback some of the time I guess.

Argh.  I knew not to mention "Linux" and kept it in mind to write the
first part.  ...but then I must have just spaced.  I also removed the
"at bootup" part since it seemed better.

-Doug