Commit 5645f805 authored by Linus Walleij's avatar Linus Walleij Committed by Bartosz Golaszewski
Browse files

gpio: Document line value semantics 



It is not clearly documented that the GPIO driver API expect the
driver to get/set the physical level of the GPIO line and the
consumer API will get/set the logic level. Document this in
relevant places.

Reported-by: default avatarDavid Jander <david@protonic.nl>
Signed-off-by: default avatarLinus Walleij <linusw@kernel.org>
Link: https://patch.msgid.link/20260306-gpio-doc-levels-v1-1-19928739e400@kernel.org


Signed-off-by: default avatarBartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>
parent 3671411e

Documentation/driver-api/gpio/driver.rst

+27 −0
Original line number Diff line number Diff line
@@ -87,6 +87,33 @@ atomic context on realtime kernels (inside hard IRQ handlers and similar 
contexts). Normally this should not be required.





GPIO level semantics

--------------------



The gpip_chip .get/set[_multiple]() line values are clamped to the boolean

space [0, 1], low level or high level.



Low and high values are defined as physical low on the line in/out to the

connector such as a physical pad, pin or rail.



The GPIO library has internal logic to handle lines that are active low, such

as indicated by overstrike or #name in a schematic, and the driver should not

try to second-guess the logic value of a line.



The way GPIO values are handled by the consumers is that the library present

the *logical* value to the consumer. A line is *asserted* if its *logical*

value is 1, and *de-asserted* if its logical value is 0. If inversion is

required, this is handled by gpiolib and configured using hardware descriptions

such as device tree or ACPI that can clearly indicate if a line is active

high or low.



Since electronics commonly insert inverters as driving stages or protection

buffers in front of a GPIO line it is necessary that this semantic is part

of the hardware description, so that consumers such as kernel drivers need

not worry about this, and can for example assert a RESET line tied to a GPIO

pin by setting it to logic 1 even if it is physically active low.





GPIO electrical configuration

-----------------------------

include/linux/gpio/driver.h

+8 −2
Original line number Diff line number Diff line
@@ -343,11 +343,17 @@ struct gpio_irq_chip { 
 * @direction_output: configures signal "offset" as output, returns 0 on

 *	success or a negative error number. This can be omitted on input-only

 *	or output-only gpio chips.

 * @get: returns value for signal "offset", 0=low, 1=high, or negative error

 * @get: returns value for signal "offset", 0=low, 1=high, or negative error.

 *	the low and high values are defined as physical low on the line

 *	in/out to the connector such as a physical pad, pin or rail. The GPIO

 *	library has internal logic to handle lines that are active low, such

 *	as indicated by overstrike or #name in a schematic, and the driver

 *	should not try to second-guess the logic value of a line.

 * @get_multiple: reads values for multiple signals defined by "mask" and

 *	stores them in "bits", returns 0 on success or negative error

 * @set: assigns output value for signal "offset", returns 0 on success or

 *       negative error value

 *	negative error value. The output value follows the same semantic

 *	rules as for @get.

 * @set_multiple: assigns output values for multiple signals defined by

 *                "mask", returns 0 on success or negative error value

 * @set_config: optional hook for all kinds of settings. Uses the same