Merge branch 'ib-gpio-aggregator' into devel

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

.. toctree::

    :maxdepth: 1

    gpio-aggregator

    sysfs

.. only::  subproject and html

GPIOs are mapped by the means of tables of lookups, containing instances of the

gpiod_lookup structure. Two macros are defined to help declaring such mappings::

	GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)

	GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)

	GPIO_LOOKUP(key, chip_hwnum, con_id, flags)

	GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)

where

  - chip_label is the label of the gpiod_chip instance providing the GPIO

  - chip_hwnum is the hardware number of the GPIO within the chip

  - key is either the label of the gpiod_chip instance providing the GPIO, or

    the GPIO line name

  - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX

    to indicate that key is a GPIO line name

  - con_id is the name of the GPIO function from the device point of view. It

	can be NULL, in which case it will match any function.

  - idx is the index of the GPIO within the function.

In the future, these flags might be extended to support more properties.

Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.

Note that:

  1. GPIO line names are not guaranteed to be globally unique, so the first

     match found will be used.

  2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.

A lookup table can then be defined as follows, with an empty entry defining its

end. The 'dev_id' field of the table is the identifier of the device that will

F:	drivers/gpio/gpiolib-acpi.c

F:	drivers/gpio/gpiolib-acpi.h

GPIO AGGREGATOR

M:	Geert Uytterhoeven <geert+renesas@glider.be>

L:	linux-gpio@vger.kernel.org

S:	Supported

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

F:	drivers/gpio/gpio-aggregator.c

GPIO IR Transmitter

M:	Sean Young <sean@mess.org>

L:	linux-media@vger.kernel.org

endmenu

config GPIO_AGGREGATOR

	tristate "GPIO Aggregator"

	help

	  Say yes here to enable the GPIO Aggregator, which provides a way to

	  aggregate existing GPIO lines into a new virtual GPIO chip.

	  This can serve the following purposes:

	    - Assign permissions for a collection of GPIO lines to a user,

	    - Export a collection of GPIO lines to a virtual machine,

	    - Provide a generic driver for a GPIO-operated device in an

	      industrial control context, to be operated from userspace using

	      the GPIO chardev interface.

config GPIO_MOCKUP

	tristate "GPIO Testing Driver"

	select IRQ_SIM