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

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(-)

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)

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

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
>