Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a621c99a authored by Linus Walleij's avatar Linus Walleij
Browse files

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: default avatarLinus Walleij <linus.walleij@linaro.org>
parent aa5c2a88

Documentation/gpio/consumer.txt

+19 −3
Original line number Diff line number Diff line
@@ -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