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: David Jander <david@protonic.nl>
Signed-off-by: Linus Walleij <linusw@kernel.org>
Link: https://patch.msgid.link/20260306-gpio-doc-levels-v1-1-19928739e400@kernel.org
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 85d86f92c41ba739b2af6e814948ea680343e35c..a4f160b950892e22bb32eed4b126ca2e06ed2249 100644 (file)
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -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
 -----------------------------
 

diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
index 5f5ddcbfa44593ad8d47d11d2ba265b3f51dccb2..17511434ed077dde8807bd7630c342e146e5230b 100644 (file)
--- a/include/linux/gpio/driver.h
+++ b/include/linux/gpio/driver.h
@@ -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