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 decriptor-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 - Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
  63   GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
  64   to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_add()
  65   of_mm_gpiochip_remove() from the kernel.
  66
  67 - Change all consumer drivers that #include <linux/of_gpio.h> to
  68   #include <linux/gpio/consumer.h> and stop doing custom parsing of the
  69   GPIO lines from the device tree. This can be tricky and often ivolves
  70   changing boardfiles, etc.
  71
  72 - Pull semantics for legacy device tree (OF) GPIO lookups into
  73   gpiolib-of.c: in some cases subsystems are doing custom flags and
  74   lookups for polarity inversion, open drain and what not. As we now
  75   handle this with generic OF bindings, pull all legacy handling into
  76   gpiolib so the library API becomes narrow and deep and handle all
  77   legacy bindings internally. (See e.g. commits 6953c57ab172,
  78   6a537d48461d etc)
  79
  80 - Delete <linux/of_gpio.h> when all the above is complete and everything
  81   uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.
  82
  83
  84 Get rid of <linux/gpio.h>
  85
  86 This legacy header is a one stop shop for anything GPIO is closely tied
  87 to the global GPIO numberspace. The endgame of the above refactorings will
  88 be the removal of <linux/gpio.h> and from that point only the specialized
  89 headers under <linux/gpio/*.h> will be used. This requires all the above to
  90 be completed and is expected to take a long time.
  91
  92
  93 Collect drivers
  94
  95 Collect GPIO drivers from arch/* and other places that should be placed
  96 in drivers/gpio/gpio-*. Augment platforms to create platform devices or
  97 similar and probe a proper driver in the gpiolib subsystem.
  98
  99 In some cases it makes sense to create a GPIO chip from the local driver
 100 for a few GPIOs. Those should stay where they are.
 101
 102
 103 Generic MMIO GPIO
 104
 105 The GPIO drivers can utilize the generic MMIO helper library in many
 106 cases, and the helper library should be as helpful as possible for MMIO
 107 drivers. (drivers/gpio/gpio-mmio.c)
 108
 109 Work items:
 110
 111 - Look over and identify any remaining easily converted drivers and
 112   dry-code conversions to MMIO GPIO for maintainers to test
 113
 114 - Expand the MMIO GPIO or write a new library for regmap-based I/O
 115   helpers for GPIO drivers on regmap that simply use offsets
 116   0..n in some register to drive GPIO lines
 117
 118 - Expand the MMIO GPIO or write a new library for port-mapped I/O
 119   helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
 120   this with dry-coding and sending to maintainers to test
 121
 122
 123 GPIOLIB irqchip
 124
 125 The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
 126 try to cover any generic kind of irqchip cascaded from a GPIO.
 127
 128 - Convert all the GPIOLIB_IRQCHIP users to pass an irqchip template,
 129   parent and flags before calling [devm_]gpiochip_add[_data]().
 130   Currently we set up the irqchip after setting up the gpiochip
 131   using gpiochip_irqchip_add() and gpiochip_set_[chained|nested]_irqchip().
 132   This is too complex, so convert all users over to just set up
 133   the irqchip before registering the gpio_chip, typical example:
 134
 135   /* Typical state container with dynamic irqchip */
 136   struct my_gpio {
 137       struct gpio_chip gc;
 138       struct irq_chip irq;
 139   };
 140
 141   int irq; /* from platform etc */
 142   struct my_gpio *g;
 143   struct gpio_irq_chip *girq;
 144
 145   /* Set up the irqchip dynamically */
 146   g->irq.name = "my_gpio_irq";
 147   g->irq.irq_ack = my_gpio_ack_irq;
 148   g->irq.irq_mask = my_gpio_mask_irq;
 149   g->irq.irq_unmask = my_gpio_unmask_irq;
 150   g->irq.irq_set_type = my_gpio_set_irq_type;
 151
 152   /* Get a pointer to the gpio_irq_chip */
 153   girq = &g->gc.irq;
 154   girq->chip = &g->irq;
 155   girq->parent_handler = ftgpio_gpio_irq_handler;
 156   girq->num_parents = 1;
 157   girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
 158                                GFP_KERNEL);
 159   if (!girq->parents)
 160       return -ENOMEM;
 161   girq->default_type = IRQ_TYPE_NONE;
 162   girq->handler = handle_bad_irq;
 163   girq->parents[0] = irq;
 164
 165   When this is done, we will delete the old APIs for instatiating
 166   GPIOLIB_IRQCHIP and simplify the code.
 167
 168 - Look over and identify any remaining easily converted drivers and
 169   dry-code conversions to gpiolib irqchip for maintainers to test
 170
 171 - Drop gpiochip_set_chained_irqchip() when all the chained irqchips
 172   have been converted to the above infrastructure.
 173
 174 - Add more infrastructure to make it possible to also pass a threaded
 175   irqchip in struct gpio_irq_chip.
 176
 177 - Drop gpiochip_irqchip_add_nested() when all the chained irqchips
 178   have been converted to the above infrastructure.
 179
 180
 181 Increase integration with pin control
 182
 183 There are already ways to use pin control as back-end for GPIO and
 184 it may make sense to bring these subsystems closer. One reason for
 185 creating pin control as its own subsystem was that we could avoid any
 186 use of the global GPIO numbers. Once the above is complete, it may
 187 make sense to simply join the subsystems into one and make pin
 188 multiplexing, pin configuration, GPIO, etc selectable options in one
 189 and the same pin control and GPIO subsystem.