diff options
| author | Linus Walleij | 2017-09-12 09:32:34 +0200 |
|---|---|---|
| committer | Linus Walleij | 2017-09-19 09:39:24 +0200 |
| commit | a621c99a96e64e3d6d5d47745a5e832262ac8f7c (patch) | |
| tree | a1e8ee98059dcb1b676688eb04b2ca65dc9be3e0 | |
| parent | aa5c2a88bb1d1116a4de3046e7adb9e864f1c9e5 (diff) | |
gpio: Clarify consumer stubs use-cases
After discussion we add a few blurbs to clarify how the stubs
in the consumer API are supposed to be used.
Cc: Florian Fainelli <f.fainelli@gmail.com>
Cc: Sergei Shtylyov <sergei.shtylyov@cogentembedded.com>
Cc: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
| -rw-r--r-- | Documentation/gpio/consumer.txt | 22 |
1 files changed, 19 insertions, 3 deletions
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 912568baabb9..ddbfa775a78a 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -10,14 +10,30 @@ Guidelines for GPIOs consumers ============================== Drivers that can't work without standard GPIO calls should have Kconfig entries -that depend on GPIOLIB. The functions that allow a driver to obtain and use -GPIOs are available by including the following file: +that depend on GPIOLIB or select GPIOLIB. The functions that allow a driver to +obtain and use GPIOs are available by including the following file: #include <linux/gpio/consumer.h> +There are static inline stubs for all functions in the header file in the case +where GPIOLIB is disabled. When these stubs are called they will emit +warnings. These stubs are used for two use cases: + +- Simple compile coverage with e.g. COMPILE_TEST - it does not matter that + the current platform does not enable or select GPIOLIB because we are not + going to execute the system anyway. + +- Truly optional GPIOLIB support - where the driver does not really make use + of the GPIOs on certain compile-time configurations for certain systems, but + 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. + All the functions that work with the descriptor-based GPIO interface are prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No -other function in the kernel should use these prefixes. +other function in the kernel should use these prefixes. The use of the legacy +functions is strongly discouraged, new code should use <linux/gpio/consumer.h> +and descriptors exclusively. Obtaining and Disposing GPIOs |