Re: Is consumer documentation correct?

[Andy Shevchenko <andy.shevchenko@xxxxxxxxx>]

On Fri, Oct 30, 2020 at 4:16 PM Alexandre Courbot <gnurou@xxxxxxxxx> wrote:
>
> Hi! Sorry for the delayed reply.
>
> On Thu, Oct 29, 2020 at 10:50 PM Linus Walleij <linus.walleij@xxxxxxxxxx> wrote:
> >
> > On Wed, Oct 28, 2020 at 9:29 PM Andy Shevchenko
> > <andy.shevchenko@xxxxxxxxx> wrote:
> >
> > > The section titled "Interacting With the Legacy GPIO Subsystem"
> > > describes as far as I got it the interaction of gpio_to_desc() and
> > > desc_to_gpio() with new / legacy APIs along with their scope. But is
> > > that description correct after the above mentioned commit, i.e.
> > > 14e85c0e69d5 ("gpio: remove gpio_descs global array") when we lose the
> > > always-present data structure (if I'm not mistaken)?
> >
> > Yes I think it needs to be updated...
>
> Although there is no global array anymore, gpio_to_desc() should still
> perform as expected after 14e85c0e69d5 ("gpio: remove gpio_descs
> global array"), since it parses all the registered gpio chips and
> looks for the one which range includes the requested number.
>
> desc_to_gpio() is a bit simpler, as it simply returns the GPIO number
> corresponding to a valid descriptor. The descriptor must remain
> acquired as long as the GPIO is in use through its number. I think the
> misleading sentence is
>
> "The GPIO number returned by desc_to_gpio() can be safely used as long
> as the GPIO descriptor has not been freed."
>
> This has been written a long time ago, so maybe I am mistaken, but I
> suspect the intent was to say something along the lines of "... as the
> GPIO descriptor has not been *released* (using gpiod_put()).
>
> For gpio_to_desc(), the intent of "a GPIO number passed to
> gpio_to_desc() must have been properly acquired", is to say "...
> properly acquired using gpio_request()".
>
> As for "and usage of the returned GPIO descriptor is only possible
> after the GPIO number has been released", I am a bit puzzled. 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?

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?

-- 
With Best Regards,
Andy Shevchenko