Skip to contentSkip to conversation

Documentation: gpio: fix typo and unclear legacy API section

PATCH In review Alexandre Courbot 3 participants 4 messages Nov 22, 2020 – Dec 4, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

---
 Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/driver-api/gpio/consumer.rst +10 -8
index 423492d125b9..173e4c7b037d 100644
@@ -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.
Signature · 1 line
2.29.2
#1 lore raw
Quoted 10 lines · Alexandre Courbot

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.

Realized after sending this should also have a

Apologies for the omission Andy!

Quoted 40 lines
---
 Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/driver-api/gpio/consumer.rst +10 -9
index 423492d125b9..173e4c7b037d 100644
@@ -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.
--

2.29.2

#2 lore raw
Quoted 11 lines · Alexandre Courbot
Quoted 9 lines · Alexandre Courbot

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.

Quoted 7 lines
Quoted 1 line

Realized after sending this should also have a

Apologies for the omission Andy!

NP

And perhaps

Quoted 41 lines
Quoted 41 lines
---
 Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/driver-api/gpio/consumer.rst +10 -9
index 423492d125b9..173e4c7b037d 100644
@@ -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.
--

2.29.2

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#3 lore raw
In reply to Alexandre Courbot
Quoted 9 lines · Alexandre Courbot

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.

Patch applied!

Thanks for fixing this up and thanks to Andy for coordinating with the fine folks over at StackOverflow. I added the BugLink and Andy's Reported-by.

Yours,
Linus Walleij