From: "Rafael J. Wysocki" <rafael@kernel.org>
To: Flavio Suligoi <f.suligoi@asem.it>
Cc: Mika Westerberg <mika.westerberg@linux.intel.com>,
Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
"Rafael J . Wysocki" <rjw@rjwysocki.net>,
Len Brown <lenb@kernel.org>,
linux-gpio@vger.kernel.org,
ACPI Devel Maling List <linux-acpi@vger.kernel.org>,
Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names
Date: Mon, 16 Nov 2020 19:37:53 +0100 [thread overview]
Message-ID: <CAJZ5v0gZxWJdNjRVqznhcNqO-Ofc6dGGES4CKhuk3w-jBhdaKw@mail.gmail.com> (raw)
In-Reply-To: <20201112131545.62628-1-f.suligoi@asem.it>
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
>
prev parent reply other threads:[~2020-11-16 18:38 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-12 13:15 [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names Flavio Suligoi
2020-11-12 13:40 ` Andy Shevchenko
2020-11-12 13:50 ` Flavio Suligoi
2020-11-16 18:37 ` Rafael J. Wysocki [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAJZ5v0gZxWJdNjRVqznhcNqO-Ofc6dGGES4CKhuk3w-jBhdaKw@mail.gmail.com \
--to=rafael@kernel.org \
--cc=andriy.shevchenko@linux.intel.com \
--cc=f.suligoi@asem.it \
--cc=lenb@kernel.org \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-gpio@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mika.westerberg@linux.intel.com \
--cc=rjw@rjwysocki.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).