From: Geert Uytterhoeven <geert+renesas@glider.be>
To: Linus Walleij <linus.walleij@linaro.org>,
Bartosz Golaszewski <bgolaszewski@baylibre.com>,
Jonathan Corbet <corbet@lwn.net>,
Harish Jenny K N <harish_kandiga@mentor.com>,
Eugeniu Rosca <erosca@de.adit-jv.com>
Cc: Alexander Graf <graf@amazon.com>,
Peter Maydell <peter.maydell@linaro.org>,
Paolo Bonzini <pbonzini@redhat.com>,
Phil Reid <preid@electromag.com.au>,
Marc Zyngier <marc.zyngier@arm.com>,
Christoffer Dall <christoffer.dall@arm.com>,
Magnus Damm <magnus.damm@gmail.com>,
Rob Herring <robh+dt@kernel.org>,
Mark Rutland <mark.rutland@arm.com>,
linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org,
linux-renesas-soc@vger.kernel.org, linux-kernel@vger.kernel.org,
qemu-devel@nongnu.org,
Geert Uytterhoeven <geert+renesas@glider.be>
Subject: [PATCH v4 4/5] docs: gpio: Add GPIO Aggregator documentation
Date: Wed, 15 Jan 2020 19:15:22 +0100 [thread overview]
Message-ID: <20200115181523.23556-5-geert+renesas@glider.be> (raw)
In-Reply-To: <20200115181523.23556-1-geert+renesas@glider.be>
Document the GPIO Aggregator, and the two typical use-cases.
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu>
---
v4:
- Add Reviewed-by,
- Drop controversial GPIO repeater,
- Clarify industrial control use case,
- Fix typo s/communicated/communicate/,
- Replace abstract frobnicator example by concrete door example with
gpio-line-names,
v3:
- New.
---
.../admin-guide/gpio/gpio-aggregator.rst | 102 ++++++++++++++++++
Documentation/admin-guide/gpio/index.rst | 1 +
2 files changed, 103 insertions(+)
create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst
diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
new file mode 100644
index 0000000000000000..954ed568b0b833b3
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst
@@ -0,0 +1,102 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+GPIO Aggregator
+===============
+
+The GPIO Aggregator allows to aggregate GPIOs, and expose them as a new
+gpio_chip. This supports the following use cases.
+
+
+Aggregating GPIOs using Sysfs
+-----------------------------
+
+GPIO controllers are exported to userspace using /dev/gpiochip* character
+devices. Access control to these devices is provided by standard UNIX file
+system permissions, on an all-or-nothing basis: either a GPIO controller is
+accessible for a user, or it is not.
+
+The GPIO Aggregator allows access control for individual GPIOs, by aggregating
+them into a new gpio_chip, which can be assigned to a group or user using
+standard UNIX file ownership and permissions. Furthermore, this simplifies and
+hardens exporting GPIOs to a virtual machine, as the VM can just grab the full
+GPIO controller, and no longer needs to care about which GPIOs to grab and
+which not, reducing the attack surface.
+
+Aggregated GPIO controllers are instantiated and destroyed by writing to
+write-only attribute files in sysfs.
+
+ /sys/bus/platform/drivers/gpio-aggregator/
+
+ "new_device" ...
+ Userspace may ask the kernel to instantiate an aggregated GPIO
+ controller by writing a string describing the GPIOs to
+ aggregate to the "new_device" file, using the format
+
+ .. code-block:: none
+
+ [<gpioA>] [<gpiochipB> <offsets>] ...
+
+ Where:
+
+ "<gpioA>" ...
+ is a GPIO line name,
+
+ "<gpiochipB>" ...
+ is a GPIO chip label or name, and
+
+ "<offsets>" ...
+ is a comma-separated list of GPIO offsets and/or
+ GPIO offset ranges denoted by dashes.
+
+ Example: Instantiate a new GPIO aggregator by aggregating GPIO
+ 19 of "e6052000.gpio" and GPIOs 20-21 of "gpiochip2" into a new
+ gpio_chip:
+
+ .. code-block:: bash
+
+ echo 'e6052000.gpio 19 gpiochip2 20-21' > new_device
+
+ "delete_device" ...
+ Userspace may ask the kernel to destroy an aggregated GPIO
+ controller after use by writing its device name to the
+ "delete_device" file.
+
+ Example: Destroy the previously-created aggregated GPIO
+ controller "gpio-aggregator.0":
+
+ .. code-block:: bash
+
+ echo gpio-aggregator.0 > delete_device
+
+
+Generic GPIO Driver
+-------------------
+
+The GPIO Aggregator can also be used as a generic driver for a simple
+GPIO-operated device described in DT, without a dedicated in-kernel driver.
+This is useful in industrial control, and is not unlike e.g. spidev, which
+allows to communicate with an SPI device from userspace.
+
+Binding a device to the GPIO Aggregator is performed either by modifying the
+gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
+
+Example: If "door" is a GPIO-operated device described in DT, using its own
+compatible value::
+
+ door {
+ compatible = "myvendor,mydoor";
+
+ gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,
+ <&gpio2 20 GPIO_ACTIVE_LOW>;
+ gpio-line-names = "open", "lock";
+ };
+
+it can be bound to the GPIO Aggregator by either:
+
+1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,
+2. Binding manually using "driver_override":
+
+.. code-block:: bash
+
+ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
+ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index a244ba4e87d5398a..ef2838638e967777 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -7,6 +7,7 @@ gpio
.. toctree::
:maxdepth: 1
+ gpio-aggregator
sysfs
.. only:: subproject and html
--
2.17.1
next prev parent reply other threads:[~2020-01-15 18:15 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-15 18:15 [PATCH v4 0/5] gpio: Add GPIO Aggregator Geert Uytterhoeven
2020-01-15 18:15 ` [PATCH v4 1/5] gpiolib: Add support for gpiochipN-based table lookup Geert Uytterhoeven
2020-01-15 18:15 ` [PATCH v4 2/5] gpiolib: Add support for GPIO line " Geert Uytterhoeven
2020-01-15 18:15 ` [PATCH v4 3/5] gpio: Add GPIO Aggregator Geert Uytterhoeven
2020-01-15 18:15 ` Geert Uytterhoeven [this message]
2020-01-15 18:15 ` [PATCH v4 5/5] MAINTAINERS: Add GPIO Aggregator section Geert Uytterhoeven
2020-01-20 13:26 ` [PATCH v4 0/5] gpio: Add GPIO Aggregator Eugeniu Rosca
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=20200115181523.23556-5-geert+renesas@glider.be \
--to=geert+renesas@glider.be \
--cc=bgolaszewski@baylibre.com \
--cc=christoffer.dall@arm.com \
--cc=corbet@lwn.net \
--cc=erosca@de.adit-jv.com \
--cc=graf@amazon.com \
--cc=harish_kandiga@mentor.com \
--cc=linus.walleij@linaro.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-gpio@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-renesas-soc@vger.kernel.org \
--cc=magnus.damm@gmail.com \
--cc=marc.zyngier@arm.com \
--cc=mark.rutland@arm.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=preid@electromag.com.au \
--cc=qemu-devel@nongnu.org \
--cc=robh+dt@kernel.org \
/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).