summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLinus Walleij <linus.walleij@linaro.org>2017-09-12 09:32:34 +0200
committerLinus Walleij <linus.walleij@linaro.org>2017-09-19 09:39:24 +0200
commita621c99a96e64e3d6d5d47745a5e832262ac8f7c (patch)
treea1e8ee98059dcb1b676688eb04b2ca65dc9be3e0
parentaa5c2a88bb1d1116a4de3046e7adb9e864f1c9e5 (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.txt22
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