leandrof/linux
1
0
Fork 0
forked from Minki/linux
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation: gpio: fix typo and unclear legacy API section

Browse Source 
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.

Reported-by: Andy Shevchenko <andy.shevchenko@gmail.com>
BugLink: https://stackoverflow.com/q/64455505/2511795
Signed-off-by: Alexandre Courbot <gnurou@gmail.com>
Link: https://lore.kernel.org/r/20201122092548.61979-1-gnurou@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
This commit is contained in:
Alexandre Courbot 2020-11-22 18:25:48 +09:00 committed by Linus Walleij
parent 105e051f1a
commit a0de695819
1 changed files with 10 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Documentation/driver-api/gpio/consumer.rst
View File

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