drivers/gpio/TODO

   1 This is a place for planning the ongoing long-term work in the GPIO
   2 subsystem.
   3
   4
   5 GPIO descriptors
   6
   7 Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
   8 to move away from the global GPIO numberspace and toward a descriptor-based
   9 approach. This means that GPIO consumers, drivers and machine descriptions
  10 ideally have no use or idea of the global GPIO numberspace that has/was
  11 used in the inception of the GPIO subsystem.
  12
  13 The numberspace issue is the same as to why irq is moving away from irq
  14 numbers to IRQ descriptors.
  15
  16 The underlying motivation for this is that the GPIO numberspace has become
  17 unmanageable: machine board files tend to become full of macros trying to
  18 establish the numberspace at compile-time, making it hard to add any numbers
  19 in the middle (such as if you missed a pin on a chip) without the numberspace
  20 breaking.
  21
  22 Machine descriptions such as device tree or ACPI does not have a concept of the
  23 Linux GPIO number as those descriptions are external to the Linux kernel
  24 and treat GPIO lines as abstract entities.
  25
  26 The runtime-assigned GPIO numberspace (what you get if you assign the GPIO
  27 base as -1 in struct gpio_chip) has also became unpredictable due to factors
  28 such as probe ordering and the introduction of -EPROBE_DEFER making probe
  29 ordering of independent GPIO chips essentially unpredictable, as their base
  30 number will be assigned on a first come first serve basis.
  31
  32 The best way to get out of the problem is to make the global GPIO numbers
  33 unimportant by simply not using them. GPIO descriptors deal with this.
  34
  35 Work items:
  36
  37 - Convert all GPIO device drivers to only #include <linux/gpio/driver.h>
  38
  39 - Convert all consumer drivers to only #include <linux/gpio/consumer.h>
  40
  41 - Convert all machine descriptors in "boardfiles" to only
  42   #include <linux/gpio/machine.h>, the other option being to convert it
  43   to a machine description such as device tree, ACPI or fwnode that
  44   implicitly does not use global GPIO numbers.
  45
  46 - When this work is complete (will require some of the items in the
  47   following ongoing work as well) we can delete the old global
  48   numberspace accessors from <linux/gpio.h> and eventually delete
  49   <linux/gpio.h> altogether.
  50
  51
  52 Get rid of <linux/of_gpio.h>
  53
  54 This header and helpers appeared at one point when there was no proper
  55 driver infrastructure for doing simpler MMIO GPIO devices and there was
  56 no core support for parsing device tree GPIOs from the core library with
  57 the [devm_]gpiod_get() calls we have today that will implicitly go into
  58 the device tree back-end. It is legacy and should not be used in new code.
  59
  60 Work items:
  61
  62 - Change all consumer drivers that #include <linux/of_gpio.h> to
  63   #include <linux/gpio/consumer.h> and stop doing custom parsing of the
  64   GPIO lines from the device tree. This can be tricky and often ivolves
  65   changing boardfiles, etc.
  66
  67 - Pull semantics for legacy device tree (OF) GPIO lookups into
  68   gpiolib-of.c: in some cases subsystems are doing custom flags and
  69   lookups for polarity inversion, open drain and what not. As we now
  70   handle this with generic OF bindings, pull all legacy handling into
  71   gpiolib so the library API becomes narrow and deep and handle all
  72   legacy bindings internally. (See e.g. commits 6953c57ab172,
  73   6a537d48461d etc)
  74
  75 - Delete <linux/of_gpio.h> when all the above is complete and everything
  76   uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.
  77
  78
  79 Get rid of <linux/gpio/legacy-of-mm-gpiochip.h>
  80
  81 Work items:
  82
  83 - Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
  84   GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
  85   to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_remove(),
  86   CONFIG_OF_GPIO_MM_GPIOCHIP from the kernel.
  87
  88
  89 Get rid of <linux/gpio.h>
  90
  91 This legacy header is a one stop shop for anything GPIO is closely tied
  92 to the global GPIO numberspace. The endgame of the above refactorings will
  93 be the removal of <linux/gpio.h> and from that point only the specialized
  94 headers under <linux/gpio/*.h> will be used. This requires all the above to
  95 be completed and is expected to take a long time.
  96
  97
  98 Collect drivers
  99
 100 Collect GPIO drivers from arch/* and other places that should be placed
 101 in drivers/gpio/gpio-*. Augment platforms to create platform devices or
 102 similar and probe a proper driver in the gpiolib subsystem.
 103
 104 In some cases it makes sense to create a GPIO chip from the local driver
 105 for a few GPIOs. Those should stay where they are.
 106
 107 At the same time it makes sense to get rid of code duplication in existing or
 108 new coming drivers. For example, gpio-ml-ioh should be incorporated into
 109 gpio-pch.
 110
 111
 112 Generic MMIO GPIO
 113
 114 The GPIO drivers can utilize the generic MMIO helper library in many
 115 cases, and the helper library should be as helpful as possible for MMIO
 116 drivers. (drivers/gpio/gpio-mmio.c)
 117
 118 Work items:
 119
 120 - Look over and identify any remaining easily converted drivers and
 121   dry-code conversions to MMIO GPIO for maintainers to test
 122
 123 - Expand the MMIO GPIO or write a new library for regmap-based I/O
 124   helpers for GPIO drivers on regmap that simply use offsets
 125   0..n in some register to drive GPIO lines
 126
 127 - Expand the MMIO GPIO or write a new library for port-mapped I/O
 128   helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
 129   this with dry-coding and sending to maintainers to test
 130
 131
 132 Generic regmap GPIO
 133
 134 In the very similar way to Generic MMIO GPIO convert the users which can
 135 take advantage of using regmap over direct IO accessors. Note, even in
 136 MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c.
 137
 138
 139 GPIOLIB irqchip
 140
 141 The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
 142 try to cover any generic kind of irqchip cascaded from a GPIO.
 143
 144 - Look over and identify any remaining easily converted drivers and
 145   dry-code conversions to gpiolib irqchip for maintainers to test
 146
 147
 148 Increase integration with pin control
 149
 150 There are already ways to use pin control as back-end for GPIO and
 151 it may make sense to bring these subsystems closer. One reason for
 152 creating pin control as its own subsystem was that we could avoid any
 153 use of the global GPIO numbers. Once the above is complete, it may
 154 make sense to simply join the subsystems into one and make pin
 155 multiplexing, pin configuration, GPIO, etc selectable options in one
 156 and the same pin control and GPIO subsystem.
 157
 158
 159 Debugfs in place of sysfs
 160
 161 The old sysfs code that enables simple uses of GPIOs from the
 162 command line is still popular despite the existance of the proper
 163 character device. The reason is that it is simple to use on
 164 root filesystems where you only have a minimal set of tools such
 165 as "cat", "echo" etc.
 166
 167 The old sysfs still need to be strongly deprecated and removed
 168 as it relies on the global GPIO numberspace that assume a strict
 169 order of global GPIO numbers that do not change between boots
 170 and is independent of probe order.
 171
 172 To solve this and provide an ABI that people can use for hacks
 173 and development, implement a debugfs interface to manipulate
 174 GPIO lines that can do everything that sysfs can do today: one
 175 directory per gpiochip and one file entry per line:
 176
 177 /sys/kernel/debug/gpiochip/gpiochip0
 178 /sys/kernel/debug/gpiochip/gpiochip0/gpio0
 179 /sys/kernel/debug/gpiochip/gpiochip0/gpio1
 180 /sys/kernel/debug/gpiochip/gpiochip0/gpio2
 181 /sys/kernel/debug/gpiochip/gpiochip0/gpio3
 182 ...
 183 /sys/kernel/debug/gpiochip/gpiochip1
 184 /sys/kernel/debug/gpiochip/gpiochip1/gpio0
 185 /sys/kernel/debug/gpiochip/gpiochip1/gpio1
 186 ...
 187
 188 The exact files and design of the debugfs interface can be
 189 discussed but the idea is to provide a low-level access point
 190 for debugging and hacking and to expose all lines without the
 191 need of any exporting. Also provide ample ammunition to shoot
 192 oneself in the foot, because this is debugfs after all.
 193
 194
 195 Moving over to immutable irq_chip structures
 196
 197 Most of the gpio chips implementing interrupt support rely on gpiolib
 198 intercepting some of the irq_chip callbacks, preventing the structures
 199 from being made read-only and forcing duplication of structures that
 200 should otherwise be unique.
 201
 202 The solution is to call into the gpiolib code when needed (resource
 203 management, enable/disable or unmask/mask callbacks), and to let the
 204 core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
 205 the irq_chip structure. The irq_chip structure can then be made unique
 206 and const.
 207
 208 A small number of drivers have been converted (pl061, tegra186, msm,
 209 amd, apple), and can be used as examples of how to proceed with this
 210 conversion. Note that drivers using the generic irqchip framework
 211 cannot be converted yet, but watch this space!