[PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Andy Shevchenko]

Currently the documentation for line names allows to use %u inside
the alternative name. This is broken in character device approach
from day 1 and being in use solely in sysfs.

Character device interface has a line number as a part of its address,
so the users better rely on it. Hence remove the misleading documentation.

On top of that, there are no in-kernel users (out of 6, if I'm correct)
for such names and moreover if one exists it won't help in distinguishing
lines with the same naming as '%u' will also be in them and we will get
a warning in gpiochip_set_desc_names() for such cases.

Signed-off-by: Andy Shevchenko <andy.shevchenko@gmail.com>
---
 include/linux/gpio/driver.h | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
index f8617eaf08ba..0032bb6e7d8f 100644
--- a/include/linux/gpio/driver.h
+++ b/include/linux/gpio/driver.h
@@ -376,9 +376,7 @@ struct gpio_irq_chip {
  * @names: if set, must be an array of strings to use as alternative
  *      names for the GPIOs in this chip. Any entry in the array
  *      may be NULL if there is no alias for the GPIO, however the
- *      array must be @ngpio entries long.  A name can include a single printk
- *      format specifier for an unsigned int.  It is substituted by the actual
- *      number of the gpio.
+ *      array must be @ngpio entries long.
  * @can_sleep: flag must be set iff get()/set() methods sleep, as they
  *	must while accessing GPIO expander chips over I2C or SPI. This
  *	implies that if the chip supports IRQs, these IRQs need to be threaded
-- 
2.45.0

Re: [PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Linus Walleij]

On Sun, May 5, 2024 at 4:14 PM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:

> Currently the documentation for line names allows to use %u inside
> the alternative name. This is broken in character device approach
> from day 1 and being in use solely in sysfs.
>
> Character device interface has a line number as a part of its address,
> so the users better rely on it. Hence remove the misleading documentation.
>
> On top of that, there are no in-kernel users (out of 6, if I'm correct)
> for such names and moreover if one exists it won't help in distinguishing
> lines with the same naming as '%u' will also be in them and we will get
> a warning in gpiochip_set_desc_names() for such cases.
>
> Signed-off-by: Andy Shevchenko <andy.shevchenko@gmail.com>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Andy Shevchenko]

On Mon, May 6, 2024 at 10:19 AM Linus Walleij <linus.walleij@linaro.org> wrote:
> On Sun, May 5, 2024 at 4:14 PM Andy Shevchenko
> <andy.shevchenko@gmail.com> wrote:
>
> > Currently the documentation for line names allows to use %u inside
> > the alternative name. This is broken in character device approach
> > from day 1 and being in use solely in sysfs.
> >
> > Character device interface has a line number as a part of its address,
> > so the users better rely on it. Hence remove the misleading documentation.
> >
> > On top of that, there are no in-kernel users (out of 6, if I'm correct)
> > for such names and moreover if one exists it won't help in distinguishing
> > lines with the same naming as '%u' will also be in them and we will get
> > a warning in gpiochip_set_desc_names() for such cases.
> >
> > Signed-off-by: Andy Shevchenko <andy.shevchenko@gmail.com>
>
> Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Thank you!

Meanwhile, Cc'ing to Kent as well.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Kent Gibson]

On Mon, May 06, 2024 at 01:39:05PM +0300, Andy Shevchenko wrote:
> On Mon, May 6, 2024 at 10:19 AM Linus Walleij <linus.walleij@linaro.org> wrote:
> > On Sun, May 5, 2024 at 4:14 PM Andy Shevchenko
> > <andy.shevchenko@gmail.com> wrote:
> >
> > > Currently the documentation for line names allows to use %u inside
> > > the alternative name. This is broken in character device approach
> > > from day 1 and being in use solely in sysfs.
> > >
> > > Character device interface has a line number as a part of its address,
> > > so the users better rely on it. Hence remove the misleading documentation.
> > >
> > > On top of that, there are no in-kernel users (out of 6, if I'm correct)
> > > for such names and moreover if one exists it won't help in distinguishing
> > > lines with the same naming as '%u' will also be in them and we will get
> > > a warning in gpiochip_set_desc_names() for such cases.
> > >
> > > Signed-off-by: Andy Shevchenko <andy.shevchenko@gmail.com>
> >
> > Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
>
> Thank you!
>
> Meanwhile, Cc'ing to Kent as well.
>

I saw it - makes total sense to me too.

Reviewed-by: Kent Gibson <warthog618@gmail.com>

Re: [PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Andy Shevchenko]

On Mon, May 6, 2024 at 1:39 PM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
> On Mon, May 6, 2024 at 10:19 AM Linus Walleij <linus.walleij@linaro.org> wrote:
> > On Sun, May 5, 2024 at 4:14 PM Andy Shevchenko
> > <andy.shevchenko@gmail.com> wrote:
> >
> > > Currently the documentation for line names allows to use %u inside
> > > the alternative name. This is broken in character device approach
> > > from day 1 and being in use solely in sysfs.
> > >
> > > Character device interface has a line number as a part of its address,
> > > so the users better rely on it. Hence remove the misleading documentation.
> > >
> > > On top of that, there are no in-kernel users (out of 6, if I'm correct)
> > > for such names and moreover if one exists it won't help in distinguishing
> > > lines with the same naming as '%u' will also be in them and we will get
> > > a warning in gpiochip_set_desc_names() for such cases.

Dunno if I need to elaborate this more, but just in case here is one:
Even if one puts '%u' to one line and avoids putting it into other:

 "gpio%u.foo"
 "gpioX.foo"

it means that it was already in mind to distinguish them beforehand,
diminishing the '%u' appearance in the first place. I.e. one may do

 "foo X"
 "foo Y"

to begin with. Besides that repetitive namings are discouraged and
most likely have no value but confusion.
For example,

"gpio%u.SPI CS"
"gpio%u.SPI CS"

would be rather

"SPI CS 0"
"SPI CS 1"

which is much more clearer to the user.

> > > Signed-off-by: Andy Shevchenko <andy.shevchenko@gmail.com>
> >
> > Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
>
> Thank you!
>
> Meanwhile, Cc'ing to Kent as well.
>
> --
> With Best Regards,
> Andy Shevchenko



-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] gpiolib: Discourage to use formatting strings in line names

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>


On Sun, 05 May 2024 17:14:20 +0300, Andy Shevchenko wrote:
> Currently the documentation for line names allows to use %u inside
> the alternative name. This is broken in character device approach
> from day 1 and being in use solely in sysfs.
> 
> Character device interface has a line number as a part of its address,
> so the users better rely on it. Hence remove the misleading documentation.
> 
> [...]

Applied, thanks!

[1/1] gpiolib: Discourage to use formatting strings in line names
      commit: 2b5ae9c7d9e5ef4bc52c932fdf10328feb5167c6

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>