1This is a place for planning the ongoing long-term work in the GPIO 2subsystem. 3 4=============================================================================== 5 6GPIO descriptors 7 8Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey 9to move away from the global GPIO numberspace and toward a descriptor-based 10approach. This means that GPIO consumers, drivers and machine descriptions 11ideally have no use or idea of the global GPIO numberspace that has/was 12used in the inception of the GPIO subsystem. 13 14The numberspace issue is the same as to why irq is moving away from irq 15numbers to IRQ descriptors. 16 17The underlying motivation for this is that the GPIO numberspace has become 18unmanageable: machine board files tend to become full of macros trying to 19establish the numberspace at compile-time, making it hard to add any numbers 20in the middle (such as if you missed a pin on a chip) without the numberspace 21breaking. 22 23Machine descriptions such as device tree or ACPI does not have a concept of the 24Linux GPIO number as those descriptions are external to the Linux kernel 25and treat GPIO lines as abstract entities. 26 27The runtime-assigned GPIO numberspace (what you get if you assign the GPIO 28base as -1 in struct gpio_chip) has also became unpredictable due to factors 29such as probe ordering and the introduction of -EPROBE_DEFER making probe 30ordering of independent GPIO chips essentially unpredictable, as their base 31number will be assigned on a first come first serve basis. 32 33The best way to get out of the problem is to make the global GPIO numbers 34unimportant by simply not using them. GPIO descriptors deal with this. 35 36Work items: 37 38- Convert all GPIO device drivers to only #include <linux/gpio/driver.h> 39 40- Convert all consumer drivers to only #include <linux/gpio/consumer.h> 41 42- Convert all machine descriptors in "boardfiles" to only 43 #include <linux/gpio/machine.h>, the other option being to convert it 44 to a machine description such as device tree, ACPI or fwnode that 45 implicitly does not use global GPIO numbers. 46 47- When this work is complete (will require some of the items in the 48 following ongoing work as well) we can delete the old global 49 numberspace accessors from <linux/gpio.h> and eventually delete 50 <linux/gpio.h> altogether. 51 52------------------------------------------------------------------------------- 53 54Get rid of <linux/of_gpio.h> 55 56This header and helpers appeared at one point when there was no proper 57driver infrastructure for doing simpler MMIO GPIO devices and there was 58no core support for parsing device tree GPIOs from the core library with 59the [devm_]gpiod_get() calls we have today that will implicitly go into 60the device tree back-end. It is legacy and should not be used in new code. 61 62Work items: 63 64- Change all consumer drivers that #include <linux/of_gpio.h> to 65 #include <linux/gpio/consumer.h> and stop doing custom parsing of the 66 GPIO lines from the device tree. This can be tricky and often involves 67 changing board files, etc. 68 69- Pull semantics for legacy device tree (OF) GPIO lookups into 70 gpiolib-of.c: in some cases subsystems are doing custom flags and 71 lookups for polarity inversion, open drain and what not. As we now 72 handle this with generic OF bindings, pull all legacy handling into 73 gpiolib so the library API becomes narrow and deep and handle all 74 legacy bindings internally. (See e.g. commits 6953c57ab172, 75 6a537d48461d etc) 76 77- Delete <linux/of_gpio.h> when all the above is complete and everything 78 uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead. 79 80------------------------------------------------------------------------------- 81 82Get rid of <linux/gpio/legacy-of-mm-gpiochip.h> 83 84Work items: 85 86- Get rid of struct of_mm_gpio_chip altogether: use the generic MMIO 87 GPIO for all current users (see below). Delete struct of_mm_gpio_chip, 88 to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_remove(), 89 CONFIG_OF_GPIO_MM_GPIOCHIP from the kernel. 90 91------------------------------------------------------------------------------- 92 93Collect drivers 94 95Collect GPIO drivers from arch/* and other places that should be placed 96in drivers/gpio/gpio-*. Augment platforms to create platform devices or 97similar and probe a proper driver in the gpiolib subsystem. 98 99In some cases it makes sense to create a GPIO chip from the local driver 100for a few GPIOs. Those should stay where they are. 101 102At the same time it makes sense to get rid of code duplication in existing or 103new coming drivers. For example, gpio-ml-ioh should be incorporated into 104gpio-pch. 105 106------------------------------------------------------------------------------- 107 108Generic MMIO GPIO 109 110The GPIO drivers can utilize the generic MMIO helper library in many 111cases, and the helper library should be as helpful as possible for MMIO 112drivers. (drivers/gpio/gpio-mmio.c) 113 114Work items: 115 116- Look over and identify any remaining easily converted drivers and 117 dry-code conversions to MMIO GPIO for maintainers to test 118 119- Expand the MMIO GPIO or write a new library for regmap-based I/O 120 helpers for GPIO drivers on regmap that simply use offsets 121 0..n in some register to drive GPIO lines 122 123- Expand the MMIO GPIO or write a new library for port-mapped I/O 124 helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use 125 this with dry-coding and sending to maintainers to test 126 127------------------------------------------------------------------------------- 128 129Generic regmap GPIO 130 131In the very similar way to Generic MMIO GPIO convert the users which can 132take advantage of using regmap over direct IO accessors. Note, even in 133MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c. 134 135------------------------------------------------------------------------------- 136 137GPIOLIB irqchip 138 139The GPIOLIB irqchip is a helper irqchip for "simple cases" that should 140try to cover any generic kind of irqchip cascaded from a GPIO. 141 142- Look over and identify any remaining easily converted drivers and 143 dry-code conversions to gpiolib irqchip for maintainers to test 144 145------------------------------------------------------------------------------- 146 147Moving over to immutable irq_chip structures 148 149Most of the gpio chips implementing interrupt support rely on gpiolib 150intercepting some of the irq_chip callbacks, preventing the structures 151from being made read-only and forcing duplication of structures that 152should otherwise be unique. 153 154The solution is to call into the gpiolib code when needed (resource 155management, enable/disable or unmask/mask callbacks), and to let the 156core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in 157the irq_chip structure. The irq_chip structure can then be made unique 158and const. 159 160A small number of drivers have been converted (pl061, tegra186, msm, 161amd, apple), and can be used as examples of how to proceed with this 162conversion. Note that drivers using the generic irqchip framework 163cannot be converted yet, but watch this space! 164 165------------------------------------------------------------------------------- 166 167Convert all GPIO chips to using the new, value returning line setters 168 169struct gpio_chip's set() and set_multiple() callbacks are now deprecated. They 170return void and thus do not allow drivers to indicate failure to set the line 171value back to the caller. 172 173We've now added new variants - set_rv() and set_multiple_rv() that return an 174integer. Let's convert all GPIO drivers treewide to use the new callbacks, 175remove the old ones and finally rename the new ones back to the old names. 176 177------------------------------------------------------------------------------- 178 179Extend the sysfs ABI to allow exporting lines by their HW offsets 180 181The need to support the sysfs GPIO class is one of the main obstacles to 182removing the global GPIO numberspace from the kernel. In order to wean users 183off using global numbers from user-space, extend the existing interface with 184new per-gpiochip export/unexport attributes that allow to refer to GPIOs using 185their hardware offsets within the chip. 186 187Encourage users to switch to using them and eventually remove the existing 188global export/unexport attribues. 189 190------------------------------------------------------------------------------- 191 192Remove GPIOD_FLAGS_BIT_NONEXCLUSIVE 193 194GPIOs in the linux kernel are meant to be an exclusive resource. This means 195that the GPIO descriptors (the software representation of the hardware concept) 196are not reference counted and - in general - only one user at a time can 197request a GPIO line and control its settings. The consumer API is designed 198around full control of the line's state as evidenced by the fact that, for 199instance, gpiod_set_value() does indeed drive the line as requested, instead 200of bumping an enable counter of some sort. 201 202A problematic use-case for GPIOs is when two consumers want to use the same 203descriptor independently. An example of such a user is the regulator subsystem 204which may instantiate several struct regulator_dev instances containing 205a struct device but using the same enable GPIO line. 206 207A workaround was introduced in the form of the GPIOD_FLAGS_BIT_NONEXCLUSIVE 208flag but its implementation is problematic: it does not provide any 209synchronization of usage nor did it introduce any enable count meaning the 210non-exclusive users of the same descriptor will in fact "fight" for the 211control over it. This flag should be removed and replaced with a better 212solution, possibly based on the new power sequencing subsystem. 213 214------------------------------------------------------------------------------- 215 216Remove devm_gpiod_unhinge() 217 218devm_gpiod_unhinge() is provided as a way to transfer the ownership of managed 219enable GPIOs to the regulator core. Rather than doing that however, we should 220make it possible for the regulator subsystem to deal with GPIO resources the 221lifetime of which it doesn't control as logically, a GPIO obtained by a caller 222should also be freed by it. 223