Re: Is consumer documentation correct?

[Alexandre Courbot <gnurou@xxxxxxxxx>]

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?