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 <[email protected]>
---
.../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):
+
+ - 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
On Wed, Nov 11, 2020 at 3:07 PM Flavio Suligoi <[email protected]> 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 <[email protected]>
Also nit-picks below.
> Signed-off-by: Flavio Suligoi <[email protected]>
> ---
> .../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
>
--
With Best Regards,
Andy Shevchenko
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 <[email protected]> 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.
--
With Best Regards,
Andy Shevchenko
> > > 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