Re: Is consumer documentation correct?

[Alexandre Courbot <gnurou@xxxxxxxxx>]

On Fri, Oct 30, 2020 at 11:29 PM Andy Shevchenko
<andy.shevchenko@xxxxxxxxx> wrote:
>
> On Fri, Oct 30, 2020 at 4:26 PM Andy Shevchenko
> <andy.shevchenko@xxxxxxxxx> wrote:
> > On Fri, Oct 30, 2020 at 4:16 PM Alexandre Courbot <gnurou@xxxxxxxxx> wrote:
> > > On Thu, Oct 29, 2020 at 10:50 PM Linus Walleij <linus.walleij@xxxxxxxxxx> wrote:
>
> ...
>
> > > As for "and usage of the returned GPIO descriptor is only possible
> > > after the GPIO number has been released", I am a bit puzzled.
>
> So does the OP of [1].
> Have you had a chance to read that?
>
> > My
> > > understanding is that the descriptor is only guaranteed to be valid
> > > between calls to gpio_request() and gpio_free(), so that's probably a
> > > mistake here?
>
> Sounds like this and my investigation tells me that this mistake is a
> result of the global array removal w/o updating documentation part.

I have written a reply to the SO post:
https://stackoverflow.com/a/64610316/251248

The important thing here is that gpio_acquire() and gpio_free() call
gpiod_request() and gpiod_free() under the hood. So all the lifetimes
are ultimately managed through GPIO descriptors. This means that when
gpio_acquire() is called, the descriptor's refcount is increased by
one, and thus it is safe to use it until the refcount is decreased by
the corresponding call to gpio_free() (which will call gpiod_free()).

For the opposite operation, desc_to_gpio(), the same logic applies:
the descriptor has been acquired using gpiod_get(), and so legacy
gpio_*() functions, which ultimately use that descriptor, can be
called safely as long as you know the magic number and until
gpiod_put() is called on the descriptor.

So yeah the documentation (which I have written as far as I can
remember) looks a bit clumsy at best and I probably should amend it a
bit. Now I don't want to give the impression that these functions
should be used as they absolutely should not. :)

>
> > Funny thing is that it is you who is the author of fd8e198cfcaa
> > ("Documentation: gpiolib: document new interface"). Or am I mistaken?
> >
> > Perhaps you can send a follow up to amend that chapter?
>
> [1]: https://stackoverflow.com/q/64455505/2511795
>
> --
> With Best Regards,
> Andy Shevchenko