Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20201122092548.61979-1-gnurou@gmail.com> <CAAVeFuJ+j5qDq457h-LESmd5CY+rXUFQqGpn960S2Cz0d1O0Jw@mail.gmail.com>
In-Reply-To: <CAAVeFuJ+j5qDq457h-LESmd5CY+rXUFQqGpn960S2Cz0d1O0Jw@mail.gmail.com>
From:   Andy Shevchenko <andy.shevchenko@gmail.com>
Date:   Sun, 22 Nov 2020 23:48:52 +0200
Message-ID: <CAHp75Vf7OaaZZhsGg=PVQfVXCdfKozZzizdUBQOQ-YNXVySwXQ@mail.gmail.com>
Subject: Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section
To:     Alexandre Courbot <gnurou@gmail.com>
Cc:     Linus Walleij <linus.walleij@linaro.org>,
        Bartosz Golaszewski <bgolaszewski@baylibre.com>,
        Jonathan Corbet <corbet@lwn.net>,
        "open list:GPIO SUBSYSTEM" <linux-gpio@vger.kernel.org>,
        Linux Documentation List <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Sun, Nov 22, 2020 at 11:31 AM Alexandre Courbot <gnurou@gmail.com> wrote:
>
> On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot <gnurou@gmail.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@gmail.com>
>
> Realized after sending this should also have a
>
> Reported-by: Andy Shevchenko <andy.shevchenko@gmail.com>
>
> Apologies for the omission Andy!

NP

And perhaps
BugLink: https://stackoverflow.com/q/64455505/2511795

>
> > ---
> >  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
> >


-- 
With Best Regards,
Andy Shevchenko