diff options
| author | Alexandre Courbot <gnurou@gmail.com> | 2020-11-22 18:25:48 +0900 |
|---|---|---|
| committer | Linus Walleij <linus.walleij@linaro.org> | 2020-12-05 20:23:34 +0100 |
| commit | a0de695819f63b02645e0c1c8d493324c02b0eb0 (patch) | |
| tree | 3fac9c01cc3cf7d271c8f9bae2f27641ff104683 /Documentation/driver-api/gpio | |
| parent | 105e051f1ae4cf1e94110a834987fdc78673f0c8 (diff) | |
Documentation: gpio: fix typo and unclear legacy API section
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>
Diffstat (limited to 'Documentation/driver-api/gpio')
| -rw-r--r-- | Documentation/driver-api/gpio/consumer.rst | 18 |
1 files 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. |