Loading...
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 descriptor-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
102At the same time it makes sense to get rid of code duplication in existing or
103new coming drivers. For example, gpio-ml-ioh should be incorporated into
104gpio-pch.
105
106
107Generic MMIO GPIO
108
109The GPIO drivers can utilize the generic MMIO helper library in many
110cases, and the helper library should be as helpful as possible for MMIO
111drivers. (drivers/gpio/gpio-mmio.c)
112
113Work items:
114
115- Look over and identify any remaining easily converted drivers and
116 dry-code conversions to MMIO GPIO for maintainers to test
117
118- Expand the MMIO GPIO or write a new library for regmap-based I/O
119 helpers for GPIO drivers on regmap that simply use offsets
120 0..n in some register to drive GPIO lines
121
122- Expand the MMIO GPIO or write a new library for port-mapped I/O
123 helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
124 this with dry-coding and sending to maintainers to test
125
126
127Generic regmap GPIO
128
129In the very similar way to Generic MMIO GPIO convert the users which can
130take advantage of using regmap over direct IO accessors. Note, even in
131MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c.
132
133
134GPIOLIB irqchip
135
136The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
137try to cover any generic kind of irqchip cascaded from a GPIO.
138
139- Look over and identify any remaining easily converted drivers and
140 dry-code conversions to gpiolib irqchip for maintainers to test
141
142
143Increase integration with pin control
144
145There are already ways to use pin control as back-end for GPIO and
146it may make sense to bring these subsystems closer. One reason for
147creating pin control as its own subsystem was that we could avoid any
148use of the global GPIO numbers. Once the above is complete, it may
149make sense to simply join the subsystems into one and make pin
150multiplexing, pin configuration, GPIO, etc selectable options in one
151and the same pin control and GPIO subsystem.
152
153
154Debugfs in place of sysfs
155
156The old sysfs code that enables simple uses of GPIOs from the
157command line is still popular despite the existance of the proper
158character device. The reason is that it is simple to use on
159root filesystems where you only have a minimal set of tools such
160as "cat", "echo" etc.
161
162The old sysfs still need to be strongly deprecated and removed
163as it relies on the global GPIO numberspace that assume a strict
164order of global GPIO numbers that do not change between boots
165and is independent of probe order.
166
167To solve this and provide an ABI that people can use for hacks
168and development, implement a debugfs interface to manipulate
169GPIO lines that can do everything that sysfs can do today: one
170directory per gpiochip and one file entry per line:
171
172/sys/kernel/debug/gpiochip/gpiochip0
173/sys/kernel/debug/gpiochip/gpiochip0/gpio0
174/sys/kernel/debug/gpiochip/gpiochip0/gpio1
175/sys/kernel/debug/gpiochip/gpiochip0/gpio2
176/sys/kernel/debug/gpiochip/gpiochip0/gpio3
177...
178/sys/kernel/debug/gpiochip/gpiochip1
179/sys/kernel/debug/gpiochip/gpiochip1/gpio0
180/sys/kernel/debug/gpiochip/gpiochip1/gpio1
181...
182
183The exact files and design of the debugfs interface can be
184discussed but the idea is to provide a low-level access point
185for debugging and hacking and to expose all lines without the
186need of any exporting. Also provide ample ammunition to shoot
187oneself in the foot, because this is debugfs after all.
188
189
190Moving over to immutable irq_chip structures
191
192Most of the gpio chips implementing interrupt support rely on gpiolib
193intercepting some of the irq_chip callbacks, preventing the structures
194from being made read-only and forcing duplication of structures that
195should otherwise be unique.
196
197The solution is to call into the gpiolib code when needed (resource
198management, enable/disable or unmask/mask callbacks), and to let the
199core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
200the irq_chip structure. The irq_chip structure can then be made unique
201and const.
202
203A small number of drivers have been converted (pl061, tegra186, msm,
204amd, apple), and can be used as examples of how to proceed with this
205conversion. Note that drivers using the generic irqchip framework
206cannot be converted yet, but watch this space!
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.