[PATCH] regulator: fixed: Use more standard GPIO binding

[PATCH] regulator: fixed: Use more standard GPIO binding

[Linus Walleij]

The fixed regulator uses "gpio" (singularis) for the GPIO line
but the standard GPIO bindings recommend "gpios" (pluralis).

We have augmented the Linux kernel to handle both, so recommend
the best practice and deprecate the singularis variant.

Cc: devicetree@vger.kernel.org
Cc: Leonard Crestez <leonard.crestez@nxp.com>
Suggested-by: Leonard Crestez <leonard.crestez@nxp.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 .../devicetree/bindings/regulator/fixed-regulator.txt     | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt b/Documentation/devicetree/bindings/regulator/fixed-regulator.txt
index 0c2a6c8a1536..a0d7f15ef5ca 100644
--- a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt
+++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.txt
@@ -5,7 +5,7 @@ Required properties:
 - regulator-name: Defined in regulator.txt as optional, but required here.
 
 Optional properties:
-- gpio: gpio to use for enable control
+- gpios: gpio to use for enable control
 - startup-delay-us: startup time in microseconds
 - enable-active-high: Polarity of GPIO is Active high
 If this property is missing, the default assumed is Active low.
@@ -13,6 +13,10 @@ If this property is missing, the default assumed is Active low.
   If this property is missing then default assumption is false.
 -vin-supply: Input supply name.
 
+Deprecated properties:
+- gpio: singularis variant of "gpios" is allowed in accordance with the
+  GPIO bindings specification, but not recommended.
+
 Any property defined as part of the core regulator
 binding, defined in regulator.txt, can also be used.
 However a fixed voltage regulator is expected to have the
@@ -26,7 +30,7 @@ Example:
 		regulator-name = "fixed-supply";
 		regulator-min-microvolt = <1800000>;
 		regulator-max-microvolt = <1800000>;
-		gpio = <&gpio1 16 0>;
+		gpios = <&gpio1 16 0>;
 		startup-delay-us = <70000>;
 		enable-active-high;
 		regulator-boot-on;
-- 
2.17.1

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Mark Brown]

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

On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:

>  Optional properties:
> -- gpio: gpio to use for enable control
> +- gpios: gpio to use for enable control

Are we supposed to be able to have just plain gpios as a standards
conforming property or would best practice be to call it enable-gpios or
something?

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

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Linus Walleij]

On Thu, Oct 4, 2018 at 12:50 PM Mark Brown <broonie@kernel.org> wrote:
> On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:
>
> >  Optional properties:
> > -- gpio: gpio to use for enable control
> > +- gpios: gpio to use for enable control
>
> Are we supposed to be able to have just plain gpios as a standards
> conforming property or would best practice be to call it enable-gpios or
> something?

Oh I didn't think of that really. The gpio-regulator indeed uses
enable-gpio for the same thing. But it complicates things codewise,
as the GPIO line is also optional. I'm a bit uncertain, I tend
to think just "gpios" is fine when the usage is unambigous. but
I don't know what the DT maintainers think.

Yours,
Linus Walleij

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Linus Walleij]

On Thu, Oct 4, 2018 at 12:50 PM Mark Brown <broonie@kernel.org> wrote:
> On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:
>
> >  Optional properties:
> > -- gpio: gpio to use for enable control
> > +- gpios: gpio to use for enable control
>
> Are we supposed to be able to have just plain gpios as a standards
> conforming property or would best practice be to call it enable-gpios or
> something?

Oh I didn't think of that really. The gpio-regulator indeed uses
enable-gpio for the same thing. But it complicates things codewise,
as the GPIO line is also optional. I'm a bit uncertain, I tend
to think just "gpios" is fine when the usage is unambigous. but
I don't know what the DT maintainers think.

Yours,
Linus Walleij

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Mark Brown]

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

On Thu, Oct 04, 2018 at 01:32:13PM +0200, Linus Walleij wrote:
> On Thu, Oct 4, 2018 at 12:50 PM Mark Brown <broonie@kernel.org> wrote:
> > On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:

> > >  Optional properties:
> > > -- gpio: gpio to use for enable control
> > > +- gpios: gpio to use for enable control

> > Are we supposed to be able to have just plain gpios as a standards
> > conforming property or would best practice be to call it enable-gpios or
> > something?

> Oh I didn't think of that really. The gpio-regulator indeed uses
> enable-gpio for the same thing. But it complicates things codewise,
> as the GPIO line is also optional. I'm a bit uncertain, I tend
> to think just "gpios" is fine when the usage is unambigous. but
> I don't know what the DT maintainers think.

Right, well from my point of view -gpio is perfectly fine also so... :)
Rob?

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

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Mark Brown]

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

On Thu, Oct 04, 2018 at 01:32:13PM +0200, Linus Walleij wrote:
> On Thu, Oct 4, 2018 at 12:50 PM Mark Brown <broonie@kernel.org> wrote:
> > On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:

> > >  Optional properties:
> > > -- gpio: gpio to use for enable control
> > > +- gpios: gpio to use for enable control

> > Are we supposed to be able to have just plain gpios as a standards
> > conforming property or would best practice be to call it enable-gpios or
> > something?

> Oh I didn't think of that really. The gpio-regulator indeed uses
> enable-gpio for the same thing. But it complicates things codewise,
> as the GPIO line is also optional. I'm a bit uncertain, I tend
> to think just "gpios" is fine when the usage is unambigous. but
> I don't know what the DT maintainers think.

Right, well from my point of view -gpio is perfectly fine also so... :)
Rob?

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

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Rob Herring]

On Thu, Oct 4, 2018 at 8:54 AM Mark Brown <broonie@kernel.org> wrote:
>
> On Thu, Oct 04, 2018 at 01:32:13PM +0200, Linus Walleij wrote:
> > On Thu, Oct 4, 2018 at 12:50 PM Mark Brown <broonie@kernel.org> wrote:
> > > On Thu, Oct 04, 2018 at 11:06:54AM +0200, Linus Walleij wrote:
>
> > > >  Optional properties:
> > > > -- gpio: gpio to use for enable control
> > > > +- gpios: gpio to use for enable control
>
> > > Are we supposed to be able to have just plain gpios as a standards
> > > conforming property or would best practice be to call it enable-gpios or
> > > something?
>
> > Oh I didn't think of that really. The gpio-regulator indeed uses
> > enable-gpio for the same thing. But it complicates things codewise,
> > as the GPIO line is also optional. I'm a bit uncertain, I tend
> > to think just "gpios" is fine when the usage is unambigous. but
> > I don't know what the DT maintainers think.
>
> Right, well from my point of view -gpio is perfectly fine also so... :)
> Rob?

Just 'gpios' is fine generally when there's only one (or one group).

Ideally, gpio-regulator would be a superset of fixed-regulator. The
difference would essentially be the voltage control gpios and state
properties. Changing the names though will break forwards
compatibility if dts files are updated and these are widely used. So
probably not worth trying to change unless you want to carry code to
handle both. That applies to gpio -> gpios too if dts files are
updated and older kernels don't handle both cases. But updating just
the documentation should be fine.

BTW, 'enable-active-high' is also a bit strange as that should just be
encoded into 'enable-gpio' flags. We should really deprecate that.

Rob

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Linus Walleij]

On Fri, Oct 5, 2018 at 10:17 PM Rob Herring <robh@kernel.org> wrote:

> BTW, 'enable-active-high' is also a bit strange as that should just be
> encoded into 'enable-gpio' flags. We should really deprecate that.

I have been struggling with this (and similar flags in other subsystems)
and the current plan is to contain them in current state, but push them
into the gpiolib-of.c to get it out of the respective subsystem.

The problem is that is "enable-active-high" is negative: if it is NOT
present the line is assumes to active low, which is NOT the case
for normal GPIOs (flag zero means active high).

Therefore the binding becomes ambigous: if the "enable-active-high"
is NOT present, and the gpio flag says it is active high, right
now it should result in active low behavior, and we have no way
of telling if a certain device tree want modern semantics instead,
specifying active high in the flag.

Hmmm...

We COULD enforce normal behaviour on a NEW property
"enable-gpios" though.

Let me think about that. That should be a clean migration path.

Yours,
Linus Walleij

Re: [PATCH] regulator: fixed: Use more standard GPIO binding

[Linus Walleij]

On Fri, Oct 5, 2018 at 10:17 PM Rob Herring <robh@kernel.org> wrote:

> BTW, 'enable-active-high' is also a bit strange as that should just be
> encoded into 'enable-gpio' flags. We should really deprecate that.

I have been struggling with this (and similar flags in other subsystems)
and the current plan is to contain them in current state, but push them
into the gpiolib-of.c to get it out of the respective subsystem.

The problem is that is "enable-active-high" is negative: if it is NOT
present the line is assumes to active low, which is NOT the case
for normal GPIOs (flag zero means active high).

Therefore the binding becomes ambigous: if the "enable-active-high"
is NOT present, and the gpio flag says it is active high, right
now it should result in active low behavior, and we have no way
of telling if a certain device tree want modern semantics instead,
specifying active high in the flag.

Hmmm...

We COULD enforce normal behaviour on a NEW property
"enable-gpios" though.

Let me think about that. That should be a clean migration path.

Yours,
Linus Walleij