1This is a place for planning the ongoing long-term work in the GPIO
  2subsystem.
  3
  4
  5GPIO descriptors
  6
  7Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
  8to move away from the global GPIO numberspace and toward a decriptor-based
  9approach. This means that GPIO consumers, drivers and machine descriptions
 10ideally have no use or idea of the global GPIO numberspace that has/was
 11used in the inception of the GPIO subsystem.
 12
 13Work items:
 14
 15- Convert all GPIO device drivers to only #include <linux/gpio/driver.h>
 16
 17- Convert all consumer drivers to only #include <linux/gpio/consumer.h>
 18
 19- Convert all machine descriptors in "boardfiles" to only
 20  #include <linux/gpio/machine.h>, the other option being to convert it
 21  to a machine description such as device tree, ACPI or fwnode that
 22  implicitly does not use global GPIO numbers.
 23
 24- When this work is complete (will require some of the items in the
 25  following ongoing work as well) we can delete the old global
 26  numberspace accessors from <linux/gpio.h> and eventually delete
 27  <linux/gpio.h> altogether.
 28
 29
 30Get rid of <linux/of_gpio.h>
 31
 32This header and helpers appeared at one point when there was no proper
 33driver infrastructure for doing simpler MMIO GPIO devices and there was
 34no core support for parsing device tree GPIOs from the core library with
 35the [devm_]gpiod_get() calls we have today that will implicitly go into
 36the device tree back-end.
 37
 38Work items:
 39
 40- Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
 41  GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
 42  to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_add()
 43  of_mm_gpiochip_remove() from the kernel.
 44
 45- Change all consumer drivers that #include <linux/of_gpio.h> to
 46  #include <linux/gpio/consumer.h> and stop doing custom parsing of the
 47  GPIO lines from the device tree. This can be tricky and often ivolves
 48  changing boardfiles, etc.
 49
 50- Pull semantics for legacy device tree (OF) GPIO lookups into
 51  gpiolib-of.c: in some cases subsystems are doing custom flags and
 52  lookups for polarity inversion, open drain and what not. As we now
 53  handle this with generic OF bindings, pull all legacy handling into
 54  gpiolib so the library API becomes narrow and deep and handle all
 55  legacy bindings internally. (See e.g. commits 6953c57ab172,
 56  6a537d48461d etc)
 57
 58- Delete <linux/of_gpio.h> when all the above is complete and everything
 59  uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.
 60
 61
 62Collect drivers
 63
 64Collect GPIO drivers from arch/* and other places that should be placed
 65in drivers/gpio/gpio-*. Augment platforms to create platform devices or
 66similar and probe a proper driver in the gpiolib subsystem.
 67
 68In some cases it makes sense to create a GPIO chip from the local driver
 69for a few GPIOs. Those should stay where they are.
 70
 71
 72Generic MMIO GPIO
 73
 74The GPIO drivers can utilize the generic MMIO helper library in many
 75cases, and the helper library should be as helpful as possible for MMIO
 76drivers. (drivers/gpio/gpio-mmio.c)
 77
 78Work items:
 79
 80- Look over and identify any remaining easily converted drivers and
 81  dry-code conversions to MMIO GPIO for maintainers to test
 82
 83- Expand the MMIO GPIO or write a new library for port-mapped I/O
 84  helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
 85  this with dry-coding and sending to maintainers to test
 86
 87
 88GPIOLIB irqchip
 89
 90The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
 91try to cover any generic kind of irqchip cascaded from a GPIO.
 92
 93- Convert all the GPIOLIB_IRQCHIP users to pass an irqchip template,
 94  parent and flags before calling [devm_]gpiochip_add[_data]().
 95  Currently we set up the irqchip after setting up the gpiochip
 96  using gpiochip_irqchip_add() and gpiochip_set_[chained|nested]_irqchip().
 97  This is too complex, so convert all users over to just set up
 98  the irqchip before registering the gpio_chip, typical example:
 99
100  /* Typical state container with dynamic irqchip */
101  struct my_gpio {
102      struct gpio_chip gc;
103      struct irq_chip irq;
104  };
105
106  int irq; /* from platform etc */
107  struct my_gpio *g;
108  struct gpio_irq_chip *girq
109
110  /* Set up the irqchip dynamically */
111  g->irq.name = "my_gpio_irq";
112  g->irq.irq_ack = my_gpio_ack_irq;
113  g->irq.irq_mask = my_gpio_mask_irq;
114  g->irq.irq_unmask = my_gpio_unmask_irq;
115  g->irq.irq_set_type = my_gpio_set_irq_type;
116
117  /* Get a pointer to the gpio_irq_chip */
118  girq = &g->gc.irq;
119  girq->chip = &g->irq;
120  girq->parent_handler = ftgpio_gpio_irq_handler;
121  girq->num_parents = 1;
122  girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
123                               GFP_KERNEL);
124  if (!girq->parents)
125      return -ENOMEM;
126  girq->default_type = IRQ_TYPE_NONE;
127  girq->handler = handle_bad_irq;
128  girq->parents[0] = irq;
129
130  When this is done, we will delete the old APIs for instatiating
131  GPIOLIB_IRQCHIP and simplify the code.
132
133- Look over and identify any remaining easily converted drivers and
134  dry-code conversions to gpiolib irqchip for maintainers to test
135
136- Support generic hierarchical GPIO interrupts: these are for the
137  non-cascading case where there is one IRQ per GPIO line, there is
138  currently no common infrastructure for this.
139
140
141Increase integration with pin control
142
143There are already ways to use pin control as back-end for GPIO and
144it may make sense to bring these subsystems closer. One reason for
145creating pin control as its own subsystem was that we could avoid any
146use of the global GPIO numbers. Once the above is complete, it may
147make sense to simply join the subsystems into one and make pin
148multiplexing, pin configuration, GPIO, etc selectable options in one
149and the same pin control and GPIO subsystem.