xref: /openbmc/linux/drivers/gpio/TODO (revision a080a92a) 
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
13The numberspace issue is the same as to why irq is moving away from irq
14numbers to IRQ descriptors.
15
16The underlying motivation for this is that the GPIO numberspace has become
17unmanageable: machine board files tend to become full of macros trying to
18establish the numberspace at compile-time, making it hard to add any numbers
19in the middle (such as if you missed a pin on a chip) without the numberspace
20breaking.
21
22Machine descriptions such as device tree or ACPI does not have a concept of the
23Linux GPIO number as those descriptions are external to the Linux kernel
24and treat GPIO lines as abstract entities.
25
26The runtime-assigned GPIO numberspace (what you get if you assign the GPIO
27base as -1 in struct gpio_chip) has also became unpredictable due to factors
28such as probe ordering and the introduction of -EPROBE_DEFER making probe
29ordering of independent GPIO chips essentially unpredictable, as their base
30number will be assigned on a first come first serve basis.
31
32The best way to get out of the problem is to make the global GPIO numbers
33unimportant by simply not using them. GPIO descriptors deal with this.
34
35Work 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
52Get rid of <linux/of_gpio.h>
53
54This header and helpers appeared at one point when there was no proper
55driver infrastructure for doing simpler MMIO GPIO devices and there was
56no core support for parsing device tree GPIOs from the core library with
57the [devm_]gpiod_get() calls we have today that will implicitly go into
58the device tree back-end. It is legacy and should not be used in new code.
59
60Work 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
84Get rid of <linux/gpio.h>
85
86This legacy header is a one stop shop for anything GPIO is closely tied
87to the global GPIO numberspace. The endgame of the above refactorings will
88be the removal of <linux/gpio.h> and from that point only the specialized
89headers under <linux/gpio/*.h> will be used. This requires all the above to
90be completed and is expected to take a long time.
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
102
103Generic MMIO GPIO
104
105The GPIO drivers can utilize the generic MMIO helper library in many
106cases, and the helper library should be as helpful as possible for MMIO
107drivers. (drivers/gpio/gpio-mmio.c)
108
109Work 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
123GPIOLIB irqchip
124
125The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
126try 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
181Increase integration with pin control
182
183There are already ways to use pin control as back-end for GPIO and
184it may make sense to bring these subsystems closer. One reason for
185creating pin control as its own subsystem was that we could avoid any
186use of the global GPIO numbers. Once the above is complete, it may
187make sense to simply join the subsystems into one and make pin
188multiplexing, pin configuration, GPIO, etc selectable options in one
189and the same pin control and GPIO subsystem.
190