[PATCH v4] Documentation: ACPI: explain how to use gpio-line-names

[PATCH v4] Documentation: ACPI: explain how to use gpio-line-names

[Flavio Suligoi]

The "gpio-line-names" declaration is not fully
documented, so can be useful to add some important
information and one more example.

This commit also fixes a trivial spelling mistake.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
---

v2: - fix commit spelling mistakes
    - add double back quotes to gpio-line-names
    - adjust documentation lines layout
    - add comma at the end of Package list names in the first example

v3: - add: Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

v4: - add: Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>

 .../firmware-guide/acpi/gpio-properties.rst   | 58 ++++++++++++++++++-
 1 file changed, 56 insertions(+), 2 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst
index bb6d74f23ee0..ae5396a1f092 100644
--- a/Documentation/firmware-guide/acpi/gpio-properties.rst
+++ b/Documentation/firmware-guide/acpi/gpio-properties.rst
@@ -107,7 +107,61 @@ Example::
 
 - gpio-line-names
 
-Example::
+The ``gpio-line-names`` declaration is a list of strings ("names"), which
+describes each line/pin of a GPIO controller/expander. This list, contained in
+a package, must be inserted inside the GPIO controller declaration of an ACPI
+table (typically inside the DSDT). The ``gpio-line-names`` list must respect the
+following rules (see also the examples):
+
+  - the first name in the list corresponds with the first line/pin of the GPIO
+    controller/expander
+  - the names inside the list must be consecutive (no "holes" are permitted)
+  - the list can be incomplete and can end before the last GPIO line: in
+    other words, it is not mandatory to fill all the GPIO lines
+  - empty names are allowed (two quotation marks ``""`` correspond to an empty
+    name)
+
+Example of a GPIO controller of 16 lines, with an incomplete list with two
+empty names::
+
+  Package () {
+      "gpio-line-names",
+      Package () {
+          "pin_0",
+          "pin_1",
+          "",
+          "",
+          "pin_3",
+          "pin_4_push_button",
+      }
+  }
+
+At runtime, the above declaration produces the following result (using the
+"libgpiod" tools)::
+
+  root@debian:~# gpioinfo gpiochip4
+  gpiochip4 - 16 lines:
+          line   0:      "pin_0"       unused   input  active-high
+          line   1:      "pin_1"       unused   input  active-high
+          line   2:      unnamed       unused   input  active-high
+          line   3:      unnamed       unused   input  active-high
+          line   4:      "pin_3"       unused   input  active-high
+          line   5: "pin_4_push_button" unused input active-high
+          line   6:      unnamed       unused   input  active-high
+          line   7       unnamed       unused   input  active-high
+          line   8:      unnamed       unused   input  active-high
+          line   9:      unnamed       unused   input  active-high
+          line  10:      unnamed       unused   input  active-high
+          line  11:      unnamed       unused   input  active-high
+          line  12:      unnamed       unused   input  active-high
+          line  13:      unnamed       unused   input  active-high
+          line  14:      unnamed       unused   input  active-high
+          line  15:      unnamed       unused   input  active-high
+  root@debian:~# gpiofind pin_4_push_button
+  gpiochip4 5
+  root@debian:~#
+
+Another example::
 
   Package () {
       "gpio-line-names",
@@ -191,7 +245,7 @@ The driver might expect to get the right GPIO when it does::
 but since there is no way to know the mapping between "reset" and
 the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT).
 
-The driver author can solve this by passing the mapping explictly
+The driver author can solve this by passing the mapping explicitly
 (the recommended way and documented in the above chapter).
 
 The ACPI GPIO mapping tables should not contaminate drivers that are not
-- 
2.25.1

Re: [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names

[Andy Shevchenko]

On Thu, Nov 12, 2020 at 02:15:45PM +0100, Flavio Suligoi wrote:
> The "gpio-line-names" declaration is not fully
> documented, so can be useful to add some important
> information and one more example.
> 
> This commit also fixes a trivial spelling mistake.

For the future contributions:

No need to resend each time you got a tag. Maintainers usually take them all at
once when applying (esp. taking into account plenty of scripts which help to do
this automatically).

Also, no need to resend so often. Give a chance to others to review (minimum
resend time is 24h)

-- 
With Best Regards,
Andy Shevchenko

RE: [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names

[Flavio Suligoi]

HI Andy,

> On Thu, Nov 12, 2020 at 02:15:45PM +0100, Flavio Suligoi wrote:
> > The "gpio-line-names" declaration is not fully
> > documented, so can be useful to add some important
> > information and one more example.
> >
> > This commit also fixes a trivial spelling mistake.
> 
> For the future contributions:
> 
> No need to resend each time you got a tag. Maintainers usually take them
> all at
> once when applying (esp. taking into account plenty of scripts which help
> to do
> this automatically).

ok

> 
> Also, no need to resend so often. Give a chance to others to review
> (minimum
> resend time is 24h)

ok, right!

> 
> --
> With Best Regards,
> Andy Shevchenko
> 

Regards,
Flavio

Re: [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names

[Rafael J. Wysocki]

On Thu, Nov 12, 2020 at 2:15 PM Flavio Suligoi <f.suligoi@asem.it> wrote:
>
> The "gpio-line-names" declaration is not fully
> documented, so can be useful to add some important
> information and one more example.
>
> This commit also fixes a trivial spelling mistake.

The spelling mistake has been fixed already, so I dropped this part of
the patch and applied the rest as 5.11 material.

Thanks!

> Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
> ---
>
> v2: - fix commit spelling mistakes
>     - add double back quotes to gpio-line-names
>     - adjust documentation lines layout
>     - add comma at the end of Package list names in the first example
>
> v3: - add: Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
>
> v4: - add: Reviewed-by: Mika Westerberg <mika.westerberg@linux.intel.com>
>
>  .../firmware-guide/acpi/gpio-properties.rst   | 58 ++++++++++++++++++-
>  1 file changed, 56 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst
> index bb6d74f23ee0..ae5396a1f092 100644
> --- a/Documentation/firmware-guide/acpi/gpio-properties.rst
> +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst
> @@ -107,7 +107,61 @@ Example::
>
>  - gpio-line-names
>
> -Example::
> +The ``gpio-line-names`` declaration is a list of strings ("names"), which
> +describes each line/pin of a GPIO controller/expander. This list, contained in
> +a package, must be inserted inside the GPIO controller declaration of an ACPI
> +table (typically inside the DSDT). The ``gpio-line-names`` list must respect the
> +following rules (see also the examples):
> +
> +  - the first name in the list corresponds with the first line/pin of the GPIO
> +    controller/expander
> +  - the names inside the list must be consecutive (no "holes" are permitted)
> +  - the list can be incomplete and can end before the last GPIO line: in
> +    other words, it is not mandatory to fill all the GPIO lines
> +  - empty names are allowed (two quotation marks ``""`` correspond to an empty
> +    name)
> +
> +Example of a GPIO controller of 16 lines, with an incomplete list with two
> +empty names::
> +
> +  Package () {
> +      "gpio-line-names",
> +      Package () {
> +          "pin_0",
> +          "pin_1",
> +          "",
> +          "",
> +          "pin_3",
> +          "pin_4_push_button",
> +      }
> +  }
> +
> +At runtime, the above declaration produces the following result (using the
> +"libgpiod" tools)::
> +
> +  root@debian:~# gpioinfo gpiochip4
> +  gpiochip4 - 16 lines:
> +          line   0:      "pin_0"       unused   input  active-high
> +          line   1:      "pin_1"       unused   input  active-high
> +          line   2:      unnamed       unused   input  active-high
> +          line   3:      unnamed       unused   input  active-high
> +          line   4:      "pin_3"       unused   input  active-high
> +          line   5: "pin_4_push_button" unused input active-high
> +          line   6:      unnamed       unused   input  active-high
> +          line   7       unnamed       unused   input  active-high
> +          line   8:      unnamed       unused   input  active-high
> +          line   9:      unnamed       unused   input  active-high
> +          line  10:      unnamed       unused   input  active-high
> +          line  11:      unnamed       unused   input  active-high
> +          line  12:      unnamed       unused   input  active-high
> +          line  13:      unnamed       unused   input  active-high
> +          line  14:      unnamed       unused   input  active-high
> +          line  15:      unnamed       unused   input  active-high
> +  root@debian:~# gpiofind pin_4_push_button
> +  gpiochip4 5
> +  root@debian:~#
> +
> +Another example::
>
>    Package () {
>        "gpio-line-names",
> @@ -191,7 +245,7 @@ The driver might expect to get the right GPIO when it does::
>  but since there is no way to know the mapping between "reset" and
>  the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT).
>
> -The driver author can solve this by passing the mapping explictly
> +The driver author can solve this by passing the mapping explicitly
>  (the recommended way and documented in the above chapter).
>
>  The ACPI GPIO mapping tables should not contaminate drivers that are not
> --
> 2.25.1
>