[PATCH RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[PATCH RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[Uwe Kleine-König]

From: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>

For active low lines the semantic of output-low and output-high is hard
to grasp because there is a double negation involved and so output-low
is actually a request to drive the line high (aka inactive).

So introduce output-inactive and output-active with the same semantic as
output-low and output-high have respectively today, but with a more
sensible name.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
Hello,

no code changes yet. Just asking for feedback if you consider this
sensible.

I don't like explaining that double inversion any more ...

Best regards
Uwe

 Documentation/devicetree/bindings/gpio/gpio.txt | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index a8895d339bfe..af2d3bd9412c 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -196,11 +196,16 @@ Only one of the following properties scanned in the order shown below.
 This means that when multiple properties are present they will be searched
 in the order presented below and the first match is taken as the intended
 configuration.
-- input:      A property specifying to set the GPIO direction as input.
-- output-low  A property specifying to set the GPIO direction as output with
-	      the value low.
-- output-high A property specifying to set the GPIO direction as output with
-	      the value high.
+- input:            A property specifying to set the GPIO direction as input.
+- output-inactive:  A property specifying to set the GPIO direction as output with
+		    the inactive value (depending on the line's polarity, which
+		    is active-high by default)
+- output-active:    A property specifying to set the GPIO direction as output with
+		    the active value.
+
+For backwards compatibility "output-low" and "output-high" should be supported
+as aliases for "output-inactive" and "output-active" respectively. Their usage is
+misleading for active-low outputs, so their use is discouraged.
 
 Optional properties:
 - line-name:  The GPIO label name. If not present the node name is used.
-- 
2.27.0

Re: [PATCH RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[Linus Walleij]

On Thu, Jul 9, 2020 at 8:39 AM Uwe Kleine-König <uwe@kleine-koenig.org> wrote:

> From: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
>
> For active low lines the semantic of output-low and output-high is hard
> to grasp because there is a double negation involved and so output-low
> is actually a request to drive the line high (aka inactive).
>
> So introduce output-inactive and output-active with the same semantic as
> output-low and output-high have respectively today, but with a more
> sensible name.
>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
> Hello,
>
> no code changes yet. Just asking for feedback if you consider this
> sensible.

It makes sense, and it is in line with earlier inversion problems that
people have had.

Could you use the properties:
output-asserted
output-deasserted
?

(The anglo-saxon can maybe comment on whether it should be
"deasserted" or "unasserted", sorry for bikeshedding.)

This was the terminology we discussed wrt changing the prototypes
of gpiod_set_value() from:

void gpiod_set_value(struct gpio_desc *desc, int value);

to:

void gpiod_set_value(struct gpio_desc *desc, bool asserted);

This latter simple semantic change over the entire kernel is
something "someone should do" possibly with a script or
Cocinelle.

Yours,
Linus Walleij

[PATCH v2] [RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[Uwe Kleine-König]

For active low lines the semantic of output-low and output-high is hard
to grasp because there is a double negation involved and so output-low
is actually a request to drive the line high (aka inactive).

So introduce output-inactive and output-active with the same semantic as
output-low and output-high respectively have today, but with a more
sensible name.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
Hello,

compared to (implicit) v1, changed to ..asserted from ...active as Linus
Walleij suggested.

Best regards
Uwe

 Documentation/devicetree/bindings/gpio/gpio.txt | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index a8895d339bfe..1061c346a619 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -196,11 +196,16 @@ Only one of the following properties scanned in the order shown below.
 This means that when multiple properties are present they will be searched
 in the order presented below and the first match is taken as the intended
 configuration.
-- input:      A property specifying to set the GPIO direction as input.
-- output-low  A property specifying to set the GPIO direction as output with
-	      the value low.
-- output-high A property specifying to set the GPIO direction as output with
-	      the value high.
+- input:             A property specifying to set the GPIO direction as input.
+- output-deasserted: A property specifying to set the GPIO direction as output
+		     with the inactive value (depending on the line's polarity,
+		     which is active-high by default)
+- output-asserted:   A property specifying to set the GPIO direction as output
+		     with the active value.
+
+For backwards compatibility "output-low" and "output-high" should be supported
+as aliases for "output-deasserted" and "output-asserted" respectively. Their
+usage is misleading for active-low outputs, so their use is discouraged.
 
 Optional properties:
 - line-name:  The GPIO label name. If not present the node name is used.
-- 
2.27.0

Re: [PATCH v2] [RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[Andy Shevchenko]

On Sat, Jul 11, 2020 at 7:57 AM Uwe Kleine-König
<u.kleine-koenig@pengutronix.de> wrote:
>
> For active low lines the semantic of output-low and output-high is hard
> to grasp because there is a double negation involved and so output-low
> is actually a request to drive the line high (aka inactive).
>
> So introduce output-inactive and output-active with the same semantic as
> output-low and output-high respectively have today, but with a more
> sensible name.

I guess someone needs to proofread the GPIO in-kernel documentation
and update it accordingly. We have a lot of references to logical vs.
physical state AFAIR.


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2] [RFC] dt-bindings: gpio: introduce hog properties with less ambiguity

[Linus Walleij]

On Sat, Jul 11, 2020 at 6:54 AM Uwe Kleine-König
<u.kleine-koenig@pengutronix.de> wrote:

> For active low lines the semantic of output-low and output-high is hard
> to grasp because there is a double negation involved and so output-low
> is actually a request to drive the line high (aka inactive).
>
> So introduce output-inactive and output-active with the same semantic as
> output-low and output-high respectively have today, but with a more
> sensible name.
>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
> Hello,
>
> compared to (implicit) v1, changed to ..asserted from ...active as Linus
> Walleij suggested.

I'm fine to apply this but would prefer if I can apply it back-to-back
with a patch adding support to the kernel.

I know the bindings and the OS should be decoupled in theory
but ... feels better for me.

Yours,
Linus Walleij