[v1] 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 fix a trivial syntax error.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---
 .../firmware-guide/acpi/gpio-properties.rst   | 58 ++++++++++++++++++-
 1 file changed, 56 insertions(+), 2 deletions(-)

On Wed, Nov 11, 2020 at 3:07 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 fix a trivial syntax error.

fix -> fixes
syntax error -> spelling mistake

Taking into account this done from the experience, it's a very good job, thanks!

Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

Also nit-picks below.

> Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
> ---
>  .../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..a9f4dfa932cc 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):

Since it's rest, I would expect gpio-line-names in above paragraphs to
be a term, something like
``gpio-line-names`` (double back quotes on each side). Yes, I know
that there are other places which need to be amended, but I believe
it's out of scope of this patch.

Also no need to have each sentence to be started from a new line, it
will be rendered as it has one white space in between.

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

``""`` but better to check the resulting (rendered) file. You may use
rst2pdf script for that.

> +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"

+ comma at the end here as well.

> +      }
> +  }
> +
> +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
>

Hi Andy,

> > This commit also fix a trivial syntax error.
> 
> fix -> fixes
> syntax error -> spelling mistake

ok

> > -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):
> 
> Since it's rest, I would expect gpio-line-names in above paragraphs to
> be a term, something like
> ``gpio-line-names`` (double back quotes on each side). Yes, I know
> that there are other places which need to be amended, but I believe
> it's out of scope of this patch.

Ok, I'll use the backquotes for code samples, right!
If you want, when this patch will be concluded, I can check all the ACPI
documentation to put all code samples into backquotes.

> 
> Also no need to have each sentence to be started from a new line, it
> will be rendered as it has one white space in between.

ok

> > +    other words, it is not mandatory to fill all the GPIO lines
> > +  - empty names are allowed (two quotation marks "" correspond to an
> empty name)
> 
> ``""`` but better to check the resulting (rendered) file. You may use
> rst2pdf script for that.

OK for the``""``.
I check the rendered HTML using the usual "make htmldocs". Is it enough?

> --
> With Best Regards,
> Andy Shevchenko

Regards,
Flavio

On Wed, Nov 11, 2020 at 4:53 PM Flavio Suligoi <f.suligoi@asem.it> wrote:

...

> > Since it's rest, I would expect gpio-line-names in above paragraphs to
> > be a term, something like
> > ``gpio-line-names`` (double back quotes on each side). Yes, I know
> > that there are other places which need to be amended, but I believe
> > it's out of scope of this patch.
>
> Ok, I'll use the backquotes for code samples, right!
> If you want, when this patch will be concluded, I can check all the ACPI
> documentation to put all code samples into backquotes.

I'm not sure I understand what you meant under 'code samples'. The
code excerpts like below are fine, what I'm talking about is the
reference to properties in the text.

...

> > ``""`` but better to check the resulting (rendered) file. You may use
> > rst2pdf script for that.
>
> OK for the``""``.
> I check the rendered HTML using the usual "make htmldocs". Is it enough?

Ideally it's not enough. html, pdf and man all should be checked.

> > > Since it's rest, I would expect gpio-line-names in above paragraphs to
> > > be a term, something like
> > > ``gpio-line-names`` (double back quotes on each side). Yes, I know
> > > that there are other places which need to be amended, but I believe
> > > it's out of scope of this patch.
> >
> > Ok, I'll use the backquotes for code samples, right!
> > If you want, when this patch will be concluded, I can check all the ACPI
> > documentation to put all code samples into backquotes.
> 
> I'm not sure I understand what you meant under 'code samples'. The
> code excerpts like below are fine, what I'm talking about is the
> reference to properties in the text.

ok, now it's clearer!

> 
> ...
> 
> > > ``""`` but better to check the resulting (rendered) file. You may use
> > > rst2pdf script for that.
> >
> > OK for the``""``.
> > I check the rendered HTML using the usual "make htmldocs". Is it enough?
> 
> Ideally it's not enough. html, pdf and man all should be checked.

ok, I'll check all of them

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

Regards,
Flavio