summaryrefslogtreecommitdiff
path: root/Documentation/admin-guide
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-06-06 00:00:30 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2020-06-06 00:00:30 +0300
commit3f7e82379fc91102d82ed89822bd4242c83e40d5 (patch)
treef0be8a42c4de8009b4d9d37f401b5087d999a147 /Documentation/admin-guide
parent1f2dc7f5b6c1fffdb24e776b9d3529bd9414aa2c (diff)
parent74910e15ab25f95f162bc4d4a634d029186543ce (diff)
downloadlinux-3f7e82379fc91102d82ed89822bd4242c83e40d5.tar.xz
Merge tag 'gpio-v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull GPIO updates from Linus Walleij: "This is the bulk of GPIO changes for the v5.8 kernel cycle. Core changes: - A new GPIO aggregator driver has been merged: this can join a few select GPIO lines into a new aggregated GPIO chip. This can be used for security: a process can be granted access to only these lines, for example for industrial control. Another way to use this is to reexpose certain select lines to a virtual machine or container. - Warn if the gpio-line-names is too long in he DT parser core. - GPIO lines can now be looked up by line name in addition to being looked up by offset. New drivers: - A new generic regmap GPIO driver has been merged. Too many regmap drivers are starting to look like each other so we need to create some common ground and try to move drivers over to using that. - The F7188X driver now supports F81865. Driver improvements: - Large improvements to the PCA953x expander, get multiple lines and several cleanups. - Large improvements to the DesignWare DWAPB driver, and Sergey Semin has volunteered to maintain it. - PL061 can now be built as a module, this is part of a bigger effort to make the ARM platforms more modular" * tag 'gpio-v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (77 commits) gpio: pca953x: Drop unneeded ACPI_PTR() MAINTAINERS: Add gpio regmap section gpio: add a reusable generic gpio_chip using regmap gpiolib: Introduce gpiochip_irqchip_add_domain() gpio: gpiolib: Allow GPIO IRQs to lazy disable gpiolib: Separate GPIO_GET_LINEINFO_WATCH_IOCTL conditional gpio: rcar: Fix runtime PM imbalance on error gpio: pca935x: Allow IRQ support for driver built as a module gpio: pxa: Add COMPILE_TEST support dt-bindings: gpio: Add renesas,em-gio bindings MAINTAINERS: Fix file name for DesignWare GPIO DT schema gpio: dwapb: Remove unneeded has_irq member in struct dwapb_port_property gpio: dwapb: Don't use IRQ 0 as valid Linux interrupt gpio: dwapb: avoid error message for optional IRQ gpio: dwapb: Call acpi_gpiochip_free_interrupts() on GPIO chip de-registration gpio: max730x: bring gpiochip_add_data after port config MAINTAINERS: Add GPIO Aggregator section docs: gpio: Add GPIO Aggregator documentation gpio: Add GPIO Aggregator gpiolib: Add support for GPIO lookup by line name ...
Diffstat (limited to 'Documentation/admin-guide')
-rw-r--r--Documentation/admin-guide/gpio/gpio-aggregator.rst111
-rw-r--r--Documentation/admin-guide/gpio/index.rst1
2 files changed, 112 insertions, 0 deletions
diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
new file mode 100644
index 000000000000..5cd1e7221756
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+GPIO Aggregator
+===============
+
+The GPIO Aggregator provides a mechanism 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 provides access control for a set of one or more 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, 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
+ line 19 of "e6052000.gpio" and GPIO lines 20-21 of
+ "e6050000.gpio" into a new gpio_chip:
+
+ .. code-block:: sh
+
+ $ echo 'e6052000.gpio 19 e6050000.gpio 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, assumed to be "gpio-aggregator.0":
+
+ .. code-block:: sh
+
+ $ 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 the user 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:: sh
+
+ $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
+ $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
+
+After that, a new gpiochip "door" has been created:
+
+.. code-block:: sh
+
+ $ gpioinfo door
+ gpiochip12 - 2 lines:
+ line 0: "open" unused input active-high
+ line 1: "lock" unused input active-high
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index a244ba4e87d5..ef2838638e96 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