0001 This is a place for planning the ongoing long-term work in the GPIO
0002 subsystem.
0003
0004
0005 GPIO descriptors
0006
0007 Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
0008 to move away from the global GPIO numberspace and toward a descriptor-based
0009 approach. This means that GPIO consumers, drivers and machine descriptions
0010 ideally have no use or idea of the global GPIO numberspace that has/was
0011 used in the inception of the GPIO subsystem.
0012
0013 The numberspace issue is the same as to why irq is moving away from irq
0014 numbers to IRQ descriptors.
0015
0016 The underlying motivation for this is that the GPIO numberspace has become
0017 unmanageable: machine board files tend to become full of macros trying to
0018 establish the numberspace at compile-time, making it hard to add any numbers
0019 in the middle (such as if you missed a pin on a chip) without the numberspace
0020 breaking.
0021
0022 Machine descriptions such as device tree or ACPI does not have a concept of the
0023 Linux GPIO number as those descriptions are external to the Linux kernel
0024 and treat GPIO lines as abstract entities.
0025
0026 The runtime-assigned GPIO numberspace (what you get if you assign the GPIO
0027 base as -1 in struct gpio_chip) has also became unpredictable due to factors
0028 such as probe ordering and the introduction of -EPROBE_DEFER making probe
0029 ordering of independent GPIO chips essentially unpredictable, as their base
0030 number will be assigned on a first come first serve basis.
0031
0032 The best way to get out of the problem is to make the global GPIO numbers
0033 unimportant by simply not using them. GPIO descriptors deal with this.
0034
0035 Work items:
0036
0037 - Convert all GPIO device drivers to only #include <linux/gpio/driver.h>
0038
0039 - Convert all consumer drivers to only #include <linux/gpio/consumer.h>
0040
0041 - Convert all machine descriptors in "boardfiles" to only
0042 #include <linux/gpio/machine.h>, the other option being to convert it
0043 to a machine description such as device tree, ACPI or fwnode that
0044 implicitly does not use global GPIO numbers.
0045
0046 - When this work is complete (will require some of the items in the
0047 following ongoing work as well) we can delete the old global
0048 numberspace accessors from <linux/gpio.h> and eventually delete
0049 <linux/gpio.h> altogether.
0050
0051
0052 Get rid of <linux/of_gpio.h>
0053
0054 This header and helpers appeared at one point when there was no proper
0055 driver infrastructure for doing simpler MMIO GPIO devices and there was
0056 no core support for parsing device tree GPIOs from the core library with
0057 the [devm_]gpiod_get() calls we have today that will implicitly go into
0058 the device tree back-end. It is legacy and should not be used in new code.
0059
0060 Work items:
0061
0062 - Get rid of struct of_mm_gpio_chip altogether: use the generic MMIO
0063 GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
0064 to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_add()
0065 of_mm_gpiochip_remove() from the kernel.
0066
0067 - Change all consumer drivers that #include <linux/of_gpio.h> to
0068 #include <linux/gpio/consumer.h> and stop doing custom parsing of the
0069 GPIO lines from the device tree. This can be tricky and often ivolves
0070 changing boardfiles, etc.
0071
0072 - Pull semantics for legacy device tree (OF) GPIO lookups into
0073 gpiolib-of.c: in some cases subsystems are doing custom flags and
0074 lookups for polarity inversion, open drain and what not. As we now
0075 handle this with generic OF bindings, pull all legacy handling into
0076 gpiolib so the library API becomes narrow and deep and handle all
0077 legacy bindings internally. (See e.g. commits 6953c57ab172,
0078 6a537d48461d etc)
0079
0080 - Delete <linux/of_gpio.h> when all the above is complete and everything
0081 uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.
0082
0083
0084 Get rid of <linux/gpio.h>
0085
0086 This legacy header is a one stop shop for anything GPIO is closely tied
0087 to the global GPIO numberspace. The endgame of the above refactorings will
0088 be the removal of <linux/gpio.h> and from that point only the specialized
0089 headers under <linux/gpio/*.h> will be used. This requires all the above to
0090 be completed and is expected to take a long time.
0091
0092
0093 Collect drivers
0094
0095 Collect GPIO drivers from arch/* and other places that should be placed
0096 in drivers/gpio/gpio-*. Augment platforms to create platform devices or
0097 similar and probe a proper driver in the gpiolib subsystem.
0098
0099 In some cases it makes sense to create a GPIO chip from the local driver
0100 for a few GPIOs. Those should stay where they are.
0101
0102 At the same time it makes sense to get rid of code duplication in existing or
0103 new coming drivers. For example, gpio-ml-ioh should be incorporated into
0104 gpio-pch.
0105
0106
0107 Generic MMIO GPIO
0108
0109 The GPIO drivers can utilize the generic MMIO helper library in many
0110 cases, and the helper library should be as helpful as possible for MMIO
0111 drivers. (drivers/gpio/gpio-mmio.c)
0112
0113 Work items:
0114
0115 - Look over and identify any remaining easily converted drivers and
0116 dry-code conversions to MMIO GPIO for maintainers to test
0117
0118 - Expand the MMIO GPIO or write a new library for regmap-based I/O
0119 helpers for GPIO drivers on regmap that simply use offsets
0120 0..n in some register to drive GPIO lines
0121
0122 - Expand the MMIO GPIO or write a new library for port-mapped I/O
0123 helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
0124 this with dry-coding and sending to maintainers to test
0125
0126
0127 GPIOLIB irqchip
0128
0129 The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
0130 try to cover any generic kind of irqchip cascaded from a GPIO.
0131
0132 - Look over and identify any remaining easily converted drivers and
0133 dry-code conversions to gpiolib irqchip for maintainers to test
0134
0135
0136 Increase integration with pin control
0137
0138 There are already ways to use pin control as back-end for GPIO and
0139 it may make sense to bring these subsystems closer. One reason for
0140 creating pin control as its own subsystem was that we could avoid any
0141 use of the global GPIO numbers. Once the above is complete, it may
0142 make sense to simply join the subsystems into one and make pin
0143 multiplexing, pin configuration, GPIO, etc selectable options in one
0144 and the same pin control and GPIO subsystem.
0145
0146
0147 Debugfs in place of sysfs
0148
0149 The old sysfs code that enables simple uses of GPIOs from the
0150 command line is still popular despite the existance of the proper
0151 character device. The reason is that it is simple to use on
0152 root filesystems where you only have a minimal set of tools such
0153 as "cat", "echo" etc.
0154
0155 The old sysfs still need to be strongly deprecated and removed
0156 as it relies on the global GPIO numberspace that assume a strict
0157 order of global GPIO numbers that do not change between boots
0158 and is independent of probe order.
0159
0160 To solve this and provide an ABI that people can use for hacks
0161 and development, implement a debugfs interface to manipulate
0162 GPIO lines that can do everything that sysfs can do today: one
0163 directory per gpiochip and one file entry per line:
0164
0165 /sys/kernel/debug/gpiochip/gpiochip0
0166 /sys/kernel/debug/gpiochip/gpiochip0/gpio0
0167 /sys/kernel/debug/gpiochip/gpiochip0/gpio1
0168 /sys/kernel/debug/gpiochip/gpiochip0/gpio2
0169 /sys/kernel/debug/gpiochip/gpiochip0/gpio3
0170 ...
0171 /sys/kernel/debug/gpiochip/gpiochip1
0172 /sys/kernel/debug/gpiochip/gpiochip1/gpio0
0173 /sys/kernel/debug/gpiochip/gpiochip1/gpio1
0174 ...
0175
0176 The exact files and design of the debugfs interface can be
0177 discussed but the idea is to provide a low-level access point
0178 for debugging and hacking and to expose all lines without the
0179 need of any exporting. Also provide ample ammunition to shoot
0180 oneself in the foot, because this is debugfs after all.
0181
0182
0183 Moving over to immutable irq_chip structures
0184
0185 Most of the gpio chips implementing interrupt support rely on gpiolib
0186 intercepting some of the irq_chip callbacks, preventing the structures
0187 from being made read-only and forcing duplication of structures that
0188 should otherwise be unique.
0189
0190 The solution is to call into the gpiolib code when needed (resource
0191 management, enable/disable or unmask/mask callbacks), and to let the
0192 core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
0193 the irq_chip structure. The irq_chip structure can then be made unique
0194 and const.
0195
0196 A small number of drivers have been converted (pl061, tegra186, msm,
0197 amd, apple), and can be used as examples of how to proceed with this
0198 conversion. Note that drivers using the generic irqchip framework
0199 cannot be converted yet, but watch this space!
