[PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[Mika Westerberg]

With ACPI 5.1 _DSD (Device Specific Data) it is now possible to name
functions just like Device Tree is doing. Make sure that the documentation
mentions _DSD as the recommended way to describe GPIOs in ACPI systems.

Reported-by: Darren Hart <dvhart@linux.intel.com>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---
v2: Corrected text according what Darren suggested

 Documentation/gpio/board.txt | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt
index 8b35f51fe7b6..b80606de545a 100644
--- a/Documentation/gpio/board.txt
+++ b/Documentation/gpio/board.txt
@@ -50,10 +50,43 @@ gpiod_is_active_low(power) will be true).
 
 ACPI
 ----
-ACPI does not support function names for GPIOs. Therefore, only the "idx"
-argument of gpiod_get_index() is useful to discriminate between GPIOs assigned
-to a device. The "con_id" argument can still be set for debugging purposes (it
-will appear under error messages as well as debug and sysfs nodes).
+ACPI also supports function names for GPIOs in a similar fashion to DT.
+The above DT example can be converted to an equivalent ACPI description
+with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
+
+	Device (FOO) {
+		Name (_CRS, ResourceTemplate () {
+			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
+				"\\_SB.GPI0") {15} // red
+			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
+				"\\_SB.GPI0") {16} // green
+			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
+				"\\_SB.GPI0") {17} // blue
+			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
+				"\\_SB.GPI0") {1} // power
+		})
+
+		Name (_DSD, Package () {
+			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+			Package () {
+				Package () {
+					"led-gpios",
+					Package () {
+						^FOO, 0, 0, 1,
+						^FOO, 1, 0, 1,
+						^FOO, 2, 0, 1,
+					}
+				},
+				Package () {
+					"power-gpios",
+					Package () {^FOO, 3, 0, 0},
+				},
+			}
+		})
+	}
+
+For more information about the ACPI GPIO bindings see
+Documentation/acpi/gpio-properties.txt.
 
 Platform Data
 -------------
-- 
2.1.4

Re: [PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[Rafael J. Wysocki]

On Wednesday, April 01, 2015 11:13:16 AM Mika Westerberg wrote:
> With ACPI 5.1 _DSD (Device Specific Data) it is now possible to name
> functions just like Device Tree is doing. Make sure that the documentation
> mentions _DSD as the recommended way to describe GPIOs in ACPI systems.
> 
> Reported-by: Darren Hart <dvhart@linux.intel.com>
> Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>

Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

> ---
> v2: Corrected text according what Darren suggested
> 
>  Documentation/gpio/board.txt | 41 +++++++++++++++++++++++++++++++++++++----
>  1 file changed, 37 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt
> index 8b35f51fe7b6..b80606de545a 100644
> --- a/Documentation/gpio/board.txt
> +++ b/Documentation/gpio/board.txt
> @@ -50,10 +50,43 @@ gpiod_is_active_low(power) will be true).
>  
>  ACPI
>  ----
> -ACPI does not support function names for GPIOs. Therefore, only the "idx"
> -argument of gpiod_get_index() is useful to discriminate between GPIOs assigned
> -to a device. The "con_id" argument can still be set for debugging purposes (it
> -will appear under error messages as well as debug and sysfs nodes).
> +ACPI also supports function names for GPIOs in a similar fashion to DT.
> +The above DT example can be converted to an equivalent ACPI description
> +with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
> +
> +	Device (FOO) {
> +		Name (_CRS, ResourceTemplate () {
> +			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
> +				"\\_SB.GPI0") {15} // red
> +			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
> +				"\\_SB.GPI0") {16} // green
> +			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
> +				"\\_SB.GPI0") {17} // blue
> +			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
> +				"\\_SB.GPI0") {1} // power
> +		})
> +
> +		Name (_DSD, Package () {
> +			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
> +			Package () {
> +				Package () {
> +					"led-gpios",
> +					Package () {
> +						^FOO, 0, 0, 1,
> +						^FOO, 1, 0, 1,
> +						^FOO, 2, 0, 1,
> +					}
> +				},
> +				Package () {
> +					"power-gpios",
> +					Package () {^FOO, 3, 0, 0},
> +				},
> +			}
> +		})
> +	}
> +
> +For more information about the ACPI GPIO bindings see
> +Documentation/acpi/gpio-properties.txt.
>  
>  Platform Data
>  -------------
> 

-- 
I speak only for myself.
Rafael J. Wysocki, Intel Open Source Technology Center.

Re: [PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[Darren Hart]

On 4/1/15, 1:13 AM, "Mika Westerberg" <mika.westerberg@linux.intel.com>
wrote:

>With ACPI 5.1 _DSD (Device Specific Data) it is now possible to name
>functions just like Device Tree is doing. Make sure that the documentation
>mentions _DSD as the recommended way to describe GPIOs in ACPI systems.
>
>Reported-by: Darren Hart <dvhart@linux.intel.com>
>Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
>---
>v2: Corrected text according what Darren suggested

Thanks Mika,

Reviewed-by: Darren Hart <dvhart@linux.intel.com>

-- 
Darren Hart
Intel Open Source Technology Center

Re: [PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[Jonathan Corbet]

On Wed,  1 Apr 2015 11:13:16 +0300
Mika Westerberg <mika.westerberg@linux.intel.com> wrote:

> With ACPI 5.1 _DSD (Device Specific Data) it is now possible to name
> functions just like Device Tree is doing. Make sure that the documentation
> mentions _DSD as the recommended way to describe GPIOs in ACPI systems.

OK, I've applied this to the docs tree, thanks.

jon

Re: [PATCH v2] Documentation: gpio: Update ACPI part of the document to mention _DSD

[Linus Walleij]

On Sat, Apr 4, 2015 at 11:27 AM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed,  1 Apr 2015 11:13:16 +0300
> Mika Westerberg <mika.westerberg@linux.intel.com> wrote:
>
>> With ACPI 5.1 _DSD (Device Specific Data) it is now possible to name
>> functions just like Device Tree is doing. Make sure that the documentation
>> mentions _DSD as the recommended way to describe GPIOs in ACPI systems.
>
> OK, I've applied this to the docs tree, thanks.

Aha Jon takes it, thx, Acked-by.

Yours,
Linus Walleij