| Message ID | 20250203031213.399914-11-koichiro.den@canonical.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Introduce configfs-based interface for gpio-aggregator | expand |
Hi Den-san. On Mon, 3 Feb 2025 at 04:14, Koichiro Den <koichiro.den@canonical.com> wrote: > Add documentation for the newly added configfs-based interface for GPIO > aggregator. > > Signed-off-by: Koichiro Den <koichiro.den@canonical.com> Thanks for your patch! > --- a/Documentation/admin-guide/gpio/gpio-aggregator.rst > +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst > @@ -69,6 +69,99 @@ write-only attribute files in sysfs. > $ echo gpio-aggregator.0 > delete_device > > > +Aggregating GPIOs using Configfs > +-------------------------------- > + > +**Group:** ``/config/gpio-aggregator`` > + > + This is the root directory of the gpio-aggregator configfs tree. > + > +**Group:** ``/config/gpio-aggregator/<example-name>`` > + > + This directory represents a GPIO aggregator device. You can assign any > + name to ``<example-name>`` (e.g., ``agg0``), except names starting with > + ``_auto`` prefix, which are reserved for auto-generated configfs > + entries corresponding to devices created via Sysfs. > + > +**Attribute:** ``/config/gpio-aggregator/<example-name>/live`` > + > + The ``live`` attribute allows to trigger the actual creation of the device > + once it's fully configured. The accepted values are: ``1`` to enable the > + virtual device and ``0`` to disable and tear it down. As the code uses kstrtobool(), it accepts variants of yes/true/on/no/false/off, too. > + > +**Attribute:** ``/config/gpio-aggregator/<example-name>/dev_name`` > + > + The read-only ``dev_name`` attribute exposes the name of the device as it > + will appear in the system on the platform bus (e.g. ``gpio-aggregator.0``). > + This is useful for identifying a character device for the newly created > + aggregator. If it's ``gpio-aggregator.0``, > + ``/sys/devices/platform/gpio-aggregator.0/gpiochipX`` path tells you that the > + GPIO device id is ``X``. > + > +You must create subdirectories for each virtual line you want to > +instantiate, named exactly as ``line0``, ``line1``, ..., ``lineY``, when > +you want to instantiate ``Y+1`` (Y >= 0) lines. Configure all lines before > +activating the device by setting ``live`` to 1. > + > +**Group:** ``/config/gpio-aggregator/<example-name>/<lineY>/`` > + > + This directory represents a GPIO line to include in the aggregator. > + > +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/key`` > + > +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/offset`` > + > + If ``offset`` is >= 0: > + * ``key`` specifies the name of the chip this GPIO belongs to > + * ``offset`` specifies the line offset within that chip. > + If ``offset`` is <0: Missing space before 0. Please add "(default)", so the user knows he can skip writing to this file when specifying a GPIO line name. > + * ``key`` needs to specify the GPIO line name. Gr{oetje,eeting}s, Geert
On Wed, Feb 12, 2025 at 04:55:24PM GMT, Geert Uytterhoeven wrote: > Hi Den-san. > > On Mon, 3 Feb 2025 at 04:14, Koichiro Den <koichiro.den@canonical.com> wrote: > > Add documentation for the newly added configfs-based interface for GPIO > > aggregator. > > > > Signed-off-by: Koichiro Den <koichiro.den@canonical.com> > > Thanks for your patch! > > > --- a/Documentation/admin-guide/gpio/gpio-aggregator.rst > > +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst > > @@ -69,6 +69,99 @@ write-only attribute files in sysfs. > > $ echo gpio-aggregator.0 > delete_device > > > > > > +Aggregating GPIOs using Configfs > > +-------------------------------- > > + > > +**Group:** ``/config/gpio-aggregator`` > > + > > + This is the root directory of the gpio-aggregator configfs tree. > > + > > +**Group:** ``/config/gpio-aggregator/<example-name>`` > > + > > + This directory represents a GPIO aggregator device. You can assign any > > + name to ``<example-name>`` (e.g., ``agg0``), except names starting with > > + ``_auto`` prefix, which are reserved for auto-generated configfs > > + entries corresponding to devices created via Sysfs. > > + > > +**Attribute:** ``/config/gpio-aggregator/<example-name>/live`` > > + > > + The ``live`` attribute allows to trigger the actual creation of the device > > + once it's fully configured. The accepted values are: ``1`` to enable the > > + virtual device and ``0`` to disable and tear it down. > > As the code uses kstrtobool(), it accepts variants of > yes/true/on/no/false/off, too. Thanks for pointing that out. I'll modify this part. > > > + > > +**Attribute:** ``/config/gpio-aggregator/<example-name>/dev_name`` > > + > > + The read-only ``dev_name`` attribute exposes the name of the device as it > > + will appear in the system on the platform bus (e.g. ``gpio-aggregator.0``). > > + This is useful for identifying a character device for the newly created > > + aggregator. If it's ``gpio-aggregator.0``, > > + ``/sys/devices/platform/gpio-aggregator.0/gpiochipX`` path tells you that the > > + GPIO device id is ``X``. > > + > > +You must create subdirectories for each virtual line you want to > > +instantiate, named exactly as ``line0``, ``line1``, ..., ``lineY``, when > > +you want to instantiate ``Y+1`` (Y >= 0) lines. Configure all lines before > > +activating the device by setting ``live`` to 1. > > + > > +**Group:** ``/config/gpio-aggregator/<example-name>/<lineY>/`` > > + > > + This directory represents a GPIO line to include in the aggregator. > > + > > +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/key`` > > + > > +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/offset`` > > + > > + If ``offset`` is >= 0: > > + * ``key`` specifies the name of the chip this GPIO belongs to > > + * ``offset`` specifies the line offset within that chip. > > + If ``offset`` is <0: > > Missing space before 0. > Please add "(default)", so the user knows he can skip writing to this > file when specifying a GPIO line name. That makes sense. Thanks for the review! Koichiro > > > + * ``key`` needs to specify the GPIO line name. > > Gr{oetje,eeting}s, > > Geert > > -- > Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org > > In personal conversations with technical people, I call myself a hacker. But > when I'm talking to journalists I just say "programmer" or something like that. > -- Linus Torvalds
diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst index 5cd1e7221756..e753f3dc4ae6 100644 --- a/Documentation/admin-guide/gpio/gpio-aggregator.rst +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst @@ -69,6 +69,99 @@ write-only attribute files in sysfs. $ echo gpio-aggregator.0 > delete_device +Aggregating GPIOs using Configfs +-------------------------------- + +**Group:** ``/config/gpio-aggregator`` + + This is the root directory of the gpio-aggregator configfs tree. + +**Group:** ``/config/gpio-aggregator/<example-name>`` + + This directory represents a GPIO aggregator device. You can assign any + name to ``<example-name>`` (e.g., ``agg0``), except names starting with + ``_auto`` prefix, which are reserved for auto-generated configfs + entries corresponding to devices created via Sysfs. + +**Attribute:** ``/config/gpio-aggregator/<example-name>/live`` + + The ``live`` attribute allows to trigger the actual creation of the device + once it's fully configured. The accepted values are: ``1`` to enable the + virtual device and ``0`` to disable and tear it down. + +**Attribute:** ``/config/gpio-aggregator/<example-name>/dev_name`` + + The read-only ``dev_name`` attribute exposes the name of the device as it + will appear in the system on the platform bus (e.g. ``gpio-aggregator.0``). + This is useful for identifying a character device for the newly created + aggregator. If it's ``gpio-aggregator.0``, + ``/sys/devices/platform/gpio-aggregator.0/gpiochipX`` path tells you that the + GPIO device id is ``X``. + +You must create subdirectories for each virtual line you want to +instantiate, named exactly as ``line0``, ``line1``, ..., ``lineY``, when +you want to instantiate ``Y+1`` (Y >= 0) lines. Configure all lines before +activating the device by setting ``live`` to 1. + +**Group:** ``/config/gpio-aggregator/<example-name>/<lineY>/`` + + This directory represents a GPIO line to include in the aggregator. + +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/key`` + +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/offset`` + + If ``offset`` is >= 0: + * ``key`` specifies the name of the chip this GPIO belongs to + * ``offset`` specifies the line offset within that chip. + If ``offset`` is <0: + * ``key`` needs to specify the GPIO line name. + +**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/name`` + + The ``name`` attribute sets a custom name for lineY. If left unset, the + line will remain unnamed. + +Once the configuration is done, the ``'live'`` attribute must be set to 1 +in order to instantiate the aggregator device. It can be set back to 0 to +destroy the virtual device. The module will synchronously wait for the new +aggregator device to be successfully probed and if this doesn't happen, writing +to ``'live'`` will result in an error. This is a different behaviour from the +case when you create it using sysfs ``new_device`` interface. + +.. note:: + + For aggregators created via Sysfs, the configfs entries are + auto-generated and appear as ``/config/gpio-aggregator/_auto.<N>/``. You + cannot add or remove line directories with mkdir(2)/rmdir(2). To modify + lines, you must use the "delete_device" interface to tear down the + existing device and reconfigure it from scratch. However, you can still + toggle the aggregator with the ``live`` attribute and adjust the + ``key``, ``offset``, and ``name`` attributes for each line when ``live`` + is set to 0 by hand (i.e. it's not waiting for deferred probe). + +Sample configuration commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: sh + + # Create a directory for an aggregator device + $ mkdir /sys/kernel/config/gpio-aggregator/agg0 + + # Configure each line + $ mkdir /sys/kernel/config/gpio-aggregator/agg0/line0 + $ echo gpiochip0 > /sys/kernel/config/gpio-aggregator/agg0/line0/key + $ echo 6 > /sys/kernel/config/gpio-aggregator/agg0/line0/offset + $ echo test0 > /sys/kernel/config/gpio-aggregator/agg0/line0/name + $ mkdir /sys/kernel/config/gpio-aggregator/agg0/line1 + $ echo gpiochip0 > /sys/kernel/config/gpio-aggregator/agg0/line1/key + $ echo 7 > /sys/kernel/config/gpio-aggregator/agg0/line1/offset + $ echo test1 > /sys/kernel/config/gpio-aggregator/agg0/line1/name + + # Activate the aggregator device + $ echo 1 > /sys/kernel/config/gpio-aggregator/agg0/live + + Generic GPIO Driver -------------------
Add documentation for the newly added configfs-based interface for GPIO aggregator. Signed-off-by: Koichiro Den <koichiro.den@canonical.com> --- .../admin-guide/gpio/gpio-aggregator.rst | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+)