diff mbox series

[v4,58/59] acpi: Add more documentation for struct acpi_gpio

Message ID 20200922184544.2920969-27-sjg@chromium.org
State Accepted
Commit 1e4073b8559615509af45f2f826d157c39841fd0
Delegated to: Bin Meng
Headers show
Series dm: Add programatic generation of ACPI tables (part D) | expand

Commit Message

Simon Glass Sept. 22, 2020, 6:45 p.m. UTC
Add some documentation provided by Andy Shevchenko to describe how to
use struct acpi_gpio.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

Changes in v4:
- Add Andy's documentation to struct acpi_gpio

 include/acpi/acpi_device.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
diff mbox series

Patch

diff --git a/include/acpi/acpi_device.h b/include/acpi/acpi_device.h
index 1b838fcb857..007b7e7caf1 100644
--- a/include/acpi/acpi_device.h
+++ b/include/acpi/acpi_device.h
@@ -170,6 +170,28 @@  enum acpi_gpio_polarity {
  * @io_shared; true if GPIO is shared
  * @io_restrict: I/O restriction setting
  * @polarity: GPIO polarity
+ *
+ * Note that GpioIo doesn't have any means of Active Low / High setting, so a
+ * _DSD must be provided to mitigate this.
+ *
+ * GpioIo doesn't properly communicate the initial state of the output pin,
+ * thus Linux assumes the simple rule:
+ *
+ * Pull Bias       Polarity      Requested...
+ *
+ * Implicit        x             AS IS (assumed firmware configured for us)
+ * Explicit        x (no _DSD)   as Pull Bias (Up == High, Down == Low),
+ *                               assuming non-active (Polarity = !Pull Bias)
+ *
+ * Down            Low           as low, assuming active
+ * Down            High          as high, assuming non-active
+ * Up              Low           as high, assuming non-active
+ * Up              High          as high, assuming active
+ *
+ * GpioIo() can be used as interrupt and in this case the IoRestriction mustn't
+ * be OutputOnly. It also requires active_low flag from _DSD in cases where it's
+ * needed (better to always provide than rely on above assumption made on OS
+ * level).
  */
 struct acpi_gpio {
 	int pin_count;