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- Fix drivers to not read back struct gpio_chip::base. Some drivers do 48 that and would be broken by attempts to poison it or make it dynamic. 49 Example in AT91 pinctrl driver: 50 https://lore.kernel.org/all/1d00c056-3d61-4c22-bedd-3bae0bf1ddc4@pengutronix.de/ 51 This particular driver is also DT-only, so with the above fixed, the 52 base can be made dynamic (set to -1) if CONFIG_GPIO_SYSFS is disabled. 53 54- When this work is complete (will require some of the items in the 55 following ongoing work as well) we can delete the old global 56 numberspace accessors from <linux/gpio.h> and eventually delete 57 <linux/gpio.h> altogether. 58 59------------------------------------------------------------------------------- 60 61Collect drivers 62 63Collect GPIO drivers from arch/* and other places that should be placed 64in drivers/gpio/gpio-*. Augment platforms to create platform devices or 65similar and probe a proper driver in the gpiolib subsystem. 66 67In some cases it makes sense to create a GPIO chip from the local driver 68for a few GPIOs. Those should stay where they are. 69 70At the same time it makes sense to get rid of code duplication in existing or 71new coming drivers. For example, gpio-ml-ioh should be incorporated into 72gpio-pch. 73 74------------------------------------------------------------------------------- 75 76Generic MMIO GPIO 77 78The GPIO drivers can utilize the generic MMIO helper library in many 79cases, and the helper library should be as helpful as possible for MMIO 80drivers. (drivers/gpio/gpio-mmio.c) 81 82Work items: 83 84- Look over and identify any remaining easily converted drivers and 85 dry-code conversions to MMIO GPIO for maintainers to test 86 87- Expand the MMIO GPIO or write a new library for regmap-based I/O 88 helpers for GPIO drivers on regmap that simply use offsets 89 0..n in some register to drive GPIO lines 90 91- Expand the MMIO GPIO or write a new library for port-mapped I/O 92 helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use 93 this with dry-coding and sending to maintainers to test 94 95------------------------------------------------------------------------------- 96 97Generic regmap GPIO 98 99In the very similar way to Generic MMIO GPIO convert the users which can 100take advantage of using regmap over direct IO accessors. Note, even in 101MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c. 102 103------------------------------------------------------------------------------- 104 105GPIOLIB irqchip 106 107The GPIOLIB irqchip is a helper irqchip for "simple cases" that should 108try to cover any generic kind of irqchip cascaded from a GPIO. 109 110- Look over and identify any remaining easily converted drivers and 111 dry-code conversions to gpiolib irqchip for maintainers to test 112 113------------------------------------------------------------------------------- 114 115Moving over to immutable irq_chip structures 116 117Most of the gpio chips implementing interrupt support rely on gpiolib 118intercepting some of the irq_chip callbacks, preventing the structures 119from being made read-only and forcing duplication of structures that 120should otherwise be unique. 121 122The solution is to call into the gpiolib code when needed (resource 123management, enable/disable or unmask/mask callbacks), and to let the 124core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in 125the irq_chip structure. The irq_chip structure can then be made unique 126and const. 127 128A small number of drivers have been converted (pl061, tegra186, msm, 129amd, apple), and can be used as examples of how to proceed with this 130conversion. Note that drivers using the generic irqchip framework 131cannot be converted yet, but watch this space! 132 133------------------------------------------------------------------------------- 134 135Remove legacy sysfs features 136 137We have two parallel per-chip class devices and per-exported-line attribute 138groups in sysfs. One is using the obsolete global GPIO numberspace and the 139second relies on hardware offsets of pins within the chip. Remove the former 140once user-space has switched to using the latter. 141 142------------------------------------------------------------------------------- 143 144Remove GPIOD_FLAGS_BIT_NONEXCLUSIVE 145 146GPIOs in the linux kernel are meant to be an exclusive resource. This means 147that the GPIO descriptors (the software representation of the hardware concept) 148are not reference counted and - in general - only one user at a time can 149request a GPIO line and control its settings. The consumer API is designed 150around full control of the line's state as evidenced by the fact that, for 151instance, gpiod_set_value() does indeed drive the line as requested, instead 152of bumping an enable counter of some sort. 153 154A problematic use-case for GPIOs is when two consumers want to use the same 155descriptor independently. An example of such a user is the regulator subsystem 156which may instantiate several struct regulator_dev instances containing 157a struct device but using the same enable GPIO line. 158 159A workaround was introduced in the form of the GPIOD_FLAGS_BIT_NONEXCLUSIVE 160flag but its implementation is problematic: it does not provide any 161synchronization of usage nor did it introduce any enable count meaning the 162non-exclusive users of the same descriptor will in fact "fight" for the 163control over it. This flag should be removed and replaced with a better 164solution, possibly based on the new power sequencing subsystem. 165 166------------------------------------------------------------------------------- 167 168Remove devm_gpiod_unhinge() 169 170devm_gpiod_unhinge() is provided as a way to transfer the ownership of managed 171enable GPIOs to the regulator core. Rather than doing that however, we should 172make it possible for the regulator subsystem to deal with GPIO resources the 173lifetime of which it doesn't control as logically, a GPIO obtained by a caller 174should also be freed by it. 175