linux-kernel - Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAAVeFuJ+j5qDq457h-LESmd5CY+rXUFQqGpn960S2Cz0d1O0Jw@mail.gmail.com>
Date:   Sun, 22 Nov 2020 18:31:05 +0900
From:   Alexandre Courbot <gnurou@...il.com>
To:     Linus Walleij <linus.walleij@...aro.org>,
        Bartosz Golaszewski <bgolaszewski@...libre.com>,
        Jonathan Corbet <corbet@....net>,
        Andy Shevchenko <andy.shevchenko@...il.com>
Cc:     "open list:GPIO SUBSYSTEM" <linux-gpio@...r.kernel.org>,
        linux-doc@...r.kernel.org,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section

On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot <gnurou@...il.com> wrote:
>
> The "Interacting With the Legacy GPIO Subsystem" of the documentation
> was unclear at best, and even included a sentence that seems to say the
> opposite of what it should say about the lifetime of the return value of
> the conversion functions.
>
> Try to clarify things a bit and hopefully make that section more
> readable.
>
> Signed-off-by: Alexandre Courbot <gnurou@...il.com>

Realized after sending this should also have a

Reported-by: Andy Shevchenko <andy.shevchenko@...il.com>

Apologies for the omission Andy!

> ---
>  Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst
> index 423492d125b9..173e4c7b037d 100644
> --- a/Documentation/driver-api/gpio/consumer.rst
> +++ b/Documentation/driver-api/gpio/consumer.rst
> @@ -440,18 +440,20 @@ For details refer to Documentation/firmware-guide/acpi/gpio-properties.rst
>
>  Interacting With the Legacy GPIO Subsystem
>  ==========================================
> -Many kernel subsystems still handle GPIOs using the legacy integer-based
> -interface. Although it is strongly encouraged to upgrade them to the safer
> -descriptor-based API, the following two functions allow you to convert a GPIO
> -descriptor into the GPIO integer namespace and vice-versa::
> +Many kernel subsystems and drivers still handle GPIOs using the legacy
> +integer-based interface. It is strongly recommended to update these to the new
> +gpiod interface. For cases where both interfaces need to be used, the following
> +two functions allow to convert a GPIO descriptor into the GPIO integer namespace
> +and vice-versa::
>
>         int desc_to_gpio(const struct gpio_desc *desc)
>         struct gpio_desc *gpio_to_desc(unsigned gpio)
>
> -The GPIO number returned by desc_to_gpio() can be safely used as long as the
> -GPIO descriptor has not been freed. All the same, a GPIO number passed to
> -gpio_to_desc() must have been properly acquired, and usage of the returned GPIO
> -descriptor is only possible after the GPIO number has been released.
> +The GPIO number returned by desc_to_gpio() can safely be used as a parameter of
> +the gpio\_*() functions for as long as the GPIO descriptor `desc` is not freed.
> +All the same, a GPIO number passed to gpio_to_desc() must first be properly
> +acquired using e.g. gpio_request_one(), and the returned GPIO descriptor is only
> +considered valid until that GPIO number is released using gpio_free().
>
>  Freeing a GPIO obtained by one API with the other API is forbidden and an
>  unchecked error.
> --
> 2.29.2
>