| Message ID | 20231002-gpiodoc-v1-1-a8ec8376bbf1@linaro.org |
|---|---|
| State | Accepted |
| Commit | 7691ba064b71ffa03bbaefcb2af7ec1e2131eeed |
| Headers | show |
| Series | gpio: Further document optional GPIOLIB | expand |
On Mon, Oct 2, 2023 at 10:12 AM Linus Walleij <linus.walleij@linaro.org> wrote: > > Optional GPIOLIB as in not depended on or selected by a driver > should NOT use any *_optional() calls, this becomes paradoxical. > > Signed-off-by: Linus Walleij <linus.walleij@linaro.org> > --- > Documentation/driver-api/gpio/consumer.rst | 4 ++++ > 1 file changed, 4 insertions(+) > > diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst > index de6fc79ad6f0..3e588b9d678c 100644 > --- a/Documentation/driver-api/gpio/consumer.rst > +++ b/Documentation/driver-api/gpio/consumer.rst > @@ -29,6 +29,10 @@ warnings. These stubs are used for two use cases: > will use it under other compile-time configurations. In this case the > consumer must make sure not to call into these functions, or the user will > be met with console warnings that may be perceived as intimidating. > + Combining truly optional GPIOLIB usage with calls to > + ``[devm_]gpiod_get_optional()`` is a *bad idea*, and will result in weird > + error messages. Use the ordinary getter functions with optional GPIOLIB: > + some open coding of error handling should be expected when you do this. > > All the functions that work with the descriptor-based GPIO interface are > prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy > > --- > base-commit: 0bb80ecc33a8fb5a682236443c1e740d5c917d1d > change-id: 20231002-gpiodoc-cf9430641b91 > > Best regards, > -- > Linus Walleij <linus.walleij@linaro.org> > Applied, thanks! Bart
diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index de6fc79ad6f0..3e588b9d678c 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -29,6 +29,10 @@ warnings. These stubs are used for two use cases: will use it under other compile-time configurations. In this case the consumer must make sure not to call into these functions, or the user will be met with console warnings that may be perceived as intimidating. + Combining truly optional GPIOLIB usage with calls to + ``[devm_]gpiod_get_optional()`` is a *bad idea*, and will result in weird + error messages. Use the ordinary getter functions with optional GPIOLIB: + some open coding of error handling should be expected when you do this. All the functions that work with the descriptor-based GPIO interface are prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy
Optional GPIOLIB as in not depended on or selected by a driver should NOT use any *_optional() calls, this becomes paradoxical. Signed-off-by: Linus Walleij <linus.walleij@linaro.org> --- Documentation/driver-api/gpio/consumer.rst | 4 ++++ 1 file changed, 4 insertions(+) --- base-commit: 0bb80ecc33a8fb5a682236443c1e740d5c917d1d change-id: 20231002-gpiodoc-cf9430641b91 Best regards,