Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section
On Sun, Nov 22, 2020 at 10:26 AM Alexandre Courbot 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 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
Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section
On Sun, Nov 22, 2020 at 11:31 AM Alexandre Courbot wrote: > > On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot 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 > > Realized after sending this should also have a > > Reported-by: Andy Shevchenko > > 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 > > -- With Best Regards, Andy Shevchenko
Re: [PATCH] Documentation: gpio: fix typo and unclear legacy API section
On Sun, Nov 22, 2020 at 6:25 PM Alexandre Courbot 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 Realized after sending this should also have a Reported-by: Andy Shevchenko 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 >
[PATCH] 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. Signed-off-by: Alexandre Courbot --- 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
