Documentation/admin-guide/gpio/gpio-aggregator.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/gpio/gpio-aggregator.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/gpio/gpio-aggregator.rst
Extension
.rst
Size
8035 bytes
Lines
219
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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

Annotation

Implementation Notes