lkml.org 
[lkml]   [2020]   [Nov]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    Date
    SubjectRe: [PATCH v4] Documentation: ACPI: explain how to use gpio-line-names
    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
    >

    \
     
     \ /
      Last update: 2020-11-16 19:39    [W:3.399 / U:0.308 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site