This is a place for planning the ongoing long-term work in the GPIO
subsystem.

===============================================================================

GPIO descriptors

Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
to move away from the global GPIO numberspace and toward a descriptor-based
approach. This means that GPIO consumers, drivers and machine descriptions
ideally have no use or idea of the global GPIO numberspace that has/was
used in the inception of the GPIO subsystem.

The numberspace issue is the same as to why irq is moving away from irq
numbers to IRQ descriptors.

The underlying motivation for this is that the GPIO numberspace has become
unmanageable: machine board files tend to become full of macros trying to
establish the numberspace at compile-time, making it hard to add any numbers
in the middle (such as if you missed a pin on a chip) without the numberspace
breaking.

Machine descriptions such as device tree or ACPI does not have a concept of the
Linux GPIO number as those descriptions are external to the Linux kernel
and treat GPIO lines as abstract entities.

The runtime-assigned GPIO numberspace (what you get if you assign the GPIO
base as -1 in struct gpio_chip) has also became unpredictable due to factors
such as probe ordering and the introduction of -EPROBE_DEFER making probe
ordering of independent GPIO chips essentially unpredictable, as their base
number will be assigned on a first come first serve basis.

The best way to get out of the problem is to make the global GPIO numbers
unimportant by simply not using them. GPIO descriptors deal with this.

Work items:

- Convert all GPIO device drivers to only #include <linux/gpio/driver.h>

- Convert all consumer drivers to only #include <linux/gpio/consumer.h>

- Convert all machine descriptors in "boardfiles" to only
  #include <linux/gpio/machine.h>, the other option being to convert it
  to a machine description such as device tree, ACPI or fwnode that
  implicitly does not use global GPIO numbers.

- Fix drivers to not read back struct gpio_chip::base. Some drivers do
  that and would be broken by attempts to poison it or make it dynamic.
  Example in AT91 pinctrl driver:
  https://lore.kernel.org/all/1d00c056-3d61-4c22-bedd-3bae0bf1ddc4@pengutronix.de/
  This particular driver is also DT-only, so with the above fixed, the
  base can be made dynamic (set to -1) if CONFIG_GPIO_SYSFS is disabled.

- When this work is complete (will require some of the items in the
  following ongoing work as well) we can delete the old global
  numberspace accessors from <linux/gpio.h> and eventually delete
  <linux/gpio.h> altogether.

-------------------------------------------------------------------------------

Get rid of <linux/of_gpio.h>

This header and helpers appeared at one point when there was no proper
driver infrastructure for doing simpler MMIO GPIO devices and there was
no core support for parsing device tree GPIOs from the core library with
the [devm_]gpiod_get() calls we have today that will implicitly go into
the device tree back-end. It is legacy and should not be used in new code.

Work items:

- Change all consumer drivers that #include <linux/of_gpio.h> to
  #include <linux/gpio/consumer.h> and stop doing custom parsing of the
  GPIO lines from the device tree. This can be tricky and often involves
  changing board files, etc.

- Pull semantics for legacy device tree (OF) GPIO lookups into
  gpiolib-of.c: in some cases subsystems are doing custom flags and
  lookups for polarity inversion, open drain and what not. As we now
  handle this with generic OF bindings, pull all legacy handling into
  gpiolib so the library API becomes narrow and deep and handle all
  legacy bindings internally. (See e.g. commits 6953c57ab172,
  6a537d48461d etc)

- Delete <linux/of_gpio.h> when all the above is complete and everything
  uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.

-------------------------------------------------------------------------------

Get rid of <linux/gpio/legacy-of-mm-gpiochip.h>

Work items:

- Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
  GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
  to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_remove(),
  CONFIG_OF_GPIO_MM_GPIOCHIP from the kernel.

-------------------------------------------------------------------------------

Collect drivers

Collect GPIO drivers from arch/* and other places that should be placed
in drivers/gpio/gpio-*. Augment platforms to create platform devices or
similar and probe a proper driver in the gpiolib subsystem.

In some cases it makes sense to create a GPIO chip from the local driver
for a few GPIOs. Those should stay where they are.

At the same time it makes sense to get rid of code duplication in existing or
new coming drivers. For example, gpio-ml-ioh should be incorporated into
gpio-pch.

-------------------------------------------------------------------------------

Generic MMIO GPIO

The GPIO drivers can utilize the generic MMIO helper library in many
cases, and the helper library should be as helpful as possible for MMIO
drivers. (drivers/gpio/gpio-mmio.c)

Work items:

- Look over and identify any remaining easily converted drivers and
  dry-code conversions to MMIO GPIO for maintainers to test

- Expand the MMIO GPIO or write a new library for regmap-based I/O
  helpers for GPIO drivers on regmap that simply use offsets
  0..n in some register to drive GPIO lines

- Expand the MMIO GPIO or write a new library for port-mapped I/O
  helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
  this with dry-coding and sending to maintainers to test

- Move the MMIO GPIO specific fields out of struct gpio_chip into a
  dedicated structure. Currently every GPIO chip has them if gpio-mmio is
  enabled in Kconfig even if it itself doesn't register with the helper
  library.

-------------------------------------------------------------------------------

Generic regmap GPIO

In the very similar way to Generic MMIO GPIO convert the users which can
take advantage of using regmap over direct IO accessors. Note, even in
MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c.

-------------------------------------------------------------------------------

GPIOLIB irqchip

The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
try to cover any generic kind of irqchip cascaded from a GPIO.

- Look over and identify any remaining easily converted drivers and
  dry-code conversions to gpiolib irqchip for maintainers to test

-------------------------------------------------------------------------------

Moving over to immutable irq_chip structures

Most of the gpio chips implementing interrupt support rely on gpiolib
intercepting some of the irq_chip callbacks, preventing the structures
from being made read-only and forcing duplication of structures that
should otherwise be unique.

The solution is to call into the gpiolib code when needed (resource
management, enable/disable or unmask/mask callbacks), and to let the
core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
the irq_chip structure. The irq_chip structure can then be made unique
and const.

A small number of drivers have been converted (pl061, tegra186, msm,
amd, apple), and can be used as examples of how to proceed with this
conversion. Note that drivers using the generic irqchip framework
cannot be converted yet, but watch this space!

-------------------------------------------------------------------------------

Convert all GPIO chips to using the new, value returning line setters

struct gpio_chip's set() and set_multiple() callbacks are now deprecated. They
return void and thus do not allow drivers to indicate failure to set the line
value back to the caller.

We've now added new variants - set_rv() and set_multiple_rv() that return an
integer. Let's convert all GPIO drivers treewide to use the new callbacks,
remove the old ones and finally rename the new ones back to the old names.

-------------------------------------------------------------------------------

Remove legacy sysfs features

We have two parallel per-chip class devices and per-exported-line attribute
groups in sysfs. One is using the obsolete global GPIO numberspace and the
second relies on hardware offsets of pins within the chip. Remove the former
once user-space has switched to using the latter.

-------------------------------------------------------------------------------

Remove GPIOD_FLAGS_BIT_NONEXCLUSIVE

GPIOs in the linux kernel are meant to be an exclusive resource. This means
that the GPIO descriptors (the software representation of the hardware concept)
are not reference counted and - in general - only one user at a time can
request a GPIO line and control its settings. The consumer API is designed
around full control of the line's state as evidenced by the fact that, for
instance, gpiod_set_value() does indeed drive the line as requested, instead
of bumping an enable counter of some sort.

A problematic use-case for GPIOs is when two consumers want to use the same
descriptor independently. An example of such a user is the regulator subsystem
which may instantiate several struct regulator_dev instances containing
a struct device but using the same enable GPIO line.

A workaround was introduced in the form of the GPIOD_FLAGS_BIT_NONEXCLUSIVE
flag but its implementation is problematic: it does not provide any
synchronization of usage nor did it introduce any enable count meaning the
non-exclusive users of the same descriptor will in fact "fight" for the
control over it. This flag should be removed and replaced with a better
solution, possibly based on the new power sequencing subsystem.

-------------------------------------------------------------------------------

Remove devm_gpiod_unhinge()

devm_gpiod_unhinge() is provided as a way to transfer the ownership of managed
enable GPIOs to the regulator core. Rather than doing that however, we should
make it possible for the regulator subsystem to deal with GPIO resources the
lifetime of which it doesn't control as logically, a GPIO obtained by a caller
should also be freed by it.