acpi: Add more documentation for struct acpi_gpio
Add some documentation provided by Andy Shevchenko to describe how to
use struct acpi_gpio.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/include/acpi/acpi_device.h b/include/acpi/acpi_device.h
index 1b838fc..007b7e7 100644
--- a/include/acpi/acpi_device.h
+++ b/include/acpi/acpi_device.h
@@ -170,6 +170,28 @@
* @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;