| Message ID | 20201122092548.61979-1-gnurou@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | Documentation: gpio: fix typo and unclear legacy API section | expand |
On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot <gnurou@gmail.com> wrote: > > 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. > > Signed-off-by: Alexandre Courbot <gnurou@gmail.com> Realized after sending this should also have a Reported-by: Andy Shevchenko <andy.shevchenko@gmail.com> Apologies for the omission Andy! > --- > Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++-------- > 1 file 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. > -- > 2.29.2 >
On Sun, Nov 22, 2020 at 11:31 AM Alexandre Courbot <gnurou@gmail.com> wrote: > > On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot <gnurou@gmail.com> wrote: > > > > 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. > > > > Signed-off-by: Alexandre Courbot <gnurou@gmail.com> > > Realized after sending this should also have a > > Reported-by: Andy Shevchenko <andy.shevchenko@gmail.com> > > Apologies for the omission Andy! NP And perhaps BugLink: https://stackoverflow.com/q/64455505/2511795 > > > --- > > Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++-------- > > 1 file 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. > > -- > > 2.29.2 > >
On Sun, Nov 22, 2020 at 10:26 AM Alexandre Courbot <gnurou@gmail.com> wrote: > 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. > > Signed-off-by: Alexandre Courbot <gnurou@gmail.com> 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
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.
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. Signed-off-by: Alexandre Courbot <gnurou@gmail.com> --- Documentation/driver-api/gpio/consumer.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)