Received-SPF: pass (google.com: domain of linux-kernel+bounces-61253-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Precedence: bulk
MIME-Version: 1.0
References: <20240211101421.166779-1-warthog618@gmail.com> <CAHp75VeSLvrxMOARDBHBJ5VGVR-Jv-7saxjJiN-NOPMyTwit3Q@mail.gmail.com>
 <20240211231321.GA4748@rigel> <CAHp75VddjcLaRqugKuk+eejYx_0AHVL4SjYcdh7zUKDj8SpcQw@mail.gmail.com>
In-Reply-To: <CAHp75VddjcLaRqugKuk+eejYx_0AHVL4SjYcdh7zUKDj8SpcQw@mail.gmail.com>
From: Andy Shevchenko <andy.shevchenko@gmail.com>
Date: Mon, 12 Feb 2024 11:44:02 +0200
Message-ID: <CAHp75VcjsVasfaZe25fWzzV-5vv7m7O0-v4j=pcvtWQGKtY5BQ@mail.gmail.com>
Subject: Re: [PATCH] gpio: uapi: clarify default_values being logical
To: Kent Gibson <warthog618@gmail.com>
Cc: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, brgl@bgdev.pl, 
	linus.walleij@linaro.org, andy@kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Mon, Feb 12, 2024 at 11:28=E2=80=AFAM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
>
> On Mon, Feb 12, 2024 at 1:13=E2=80=AFAM Kent Gibson <warthog618@gmail.com=
> wrote:
> > On Sun, Feb 11, 2024 at 06:58:14PM +0200, Andy Shevchenko wrote:
> > > On Sun, Feb 11, 2024 at 12:14=E2=80=AFPM Kent Gibson <warthog618@gmai=
l.com> wrote:
> > > >
> > > > The documentation for default_values mentions high/low which can be
> > > > confusing, particularly when the ACTIVE_LOW flag is set.
> > > >
> > > > Replace high/low with active/inactive to clarify that the values ar=
e
> > > > logical not physical.
> > > >
> > > > Similarly, clarify the interpretation of values in struct gpiohandl=
e_data.
> > >
> > > I'm not against this particular change, but I want the entire GPIO
> > > documentation to be aligned in the terminology aspect. Is this the
> > > case after this patch? I.o.w. have we replaced all leftovers?
> >
> > Agreed. Those are the last remnants of the low/high terminolgy that I a=
m
> > aware of, certainly the last in gpio.h.
> >
> > Having a closer look to double check...
> >
> > Ah - it is still used in Documentation/userspace-api/gpio/sysfs.rst -
> > not somewhere I go very often.
> > Would you like that updated in a separate patch?
>
> Yes, please. For this one
> Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

Also
"The values are boolean, zero for low, nonzero for high."
https://docs.kernel.org/driver-api/gpio/consumer.html

And there as well
"With this, all the gpiod_set_(array)_value_xxx() functions interpret
the parameter "value" as "asserted" ("1") or "de-asserted" ("0")."
So, should we use asserted-deasserted?


On https://docs.kernel.org/driver-api/gpio/
"get
returns value for signal "offset", 0=3Dlow, 1=3Dhigh, or negative error

..

reg_set
output set register (out=3Dhigh) for generic GPIO

reg_clr
output clear register (out=3Dlow) for generic GPIO"
(Not sure about the last two, though)

https://docs.kernel.org/driver-api/gpio/intro.html
"Output values are writable (high=3D1, low=3D0)."


A-ha, here is the section about this:
https://docs.kernel.org/driver-api/gpio/intro.html#active-high-and-active-l=
ow.


On https://docs.kernel.org/driver-api/gpio/drivers-on-gpio.html
"ledtrig-gpio: drivers/leds/trigger/ledtrig-gpio.c will provide a LED
trigger, i.e. a LED will turn on/off in response to a GPIO line going
high or low (and that LED may in turn use the leds-gpio as per
above)."

So, can you re-read all of it for high/low asserted/deasserted,
active/inactive and amend accordingly?

--=20
With Best Regards,
Andy Shevchenko