linux - drivers/gpio/TODO

174 lines · 7.6 KiB

1	This is a place for planning the ongoing long-term work in the GPIO
2	subsystem.
3
4	===============================================================================
5
6	GPIO descriptors
7
8	Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
9	to move away from the global GPIO numberspace and toward a descriptor-based
10	approach. This means that GPIO consumers, drivers and machine descriptions
11	ideally have no use or idea of the global GPIO numberspace that has/was
12	used in the inception of the GPIO subsystem.
13
14	The numberspace issue is the same as to why irq is moving away from irq
15	numbers to IRQ descriptors.
16
17	The underlying motivation for this is that the GPIO numberspace has become
18	unmanageable: machine board files tend to become full of macros trying to
19	establish the numberspace at compile-time, making it hard to add any numbers
20	in the middle (such as if you missed a pin on a chip) without the numberspace
21	breaking.
22
23	Machine descriptions such as device tree or ACPI does not have a concept of the
24	Linux GPIO number as those descriptions are external to the Linux kernel
25	and treat GPIO lines as abstract entities.
26
27	The runtime-assigned GPIO numberspace (what you get if you assign the GPIO
28	base as -1 in struct gpio_chip) has also became unpredictable due to factors
29	such as probe ordering and the introduction of -EPROBE_DEFER making probe
30	ordering of independent GPIO chips essentially unpredictable, as their base
31	number will be assigned on a first come first serve basis.
32
33	The best way to get out of the problem is to make the global GPIO numbers
34	unimportant by simply not using them. GPIO descriptors deal with this.
35
36	Work items:
37
38	- Convert all GPIO device drivers to only #include <linux/gpio/driver.h>
39
40	- Convert all consumer drivers to only #include <linux/gpio/consumer.h>
41
42	- Convert all machine descriptors in "boardfiles" to only
43	#include <linux/gpio/machine.h>, the other option being to convert it
44	to a machine description such as device tree, ACPI or fwnode that
45	implicitly does not use global GPIO numbers.
46
47	- Fix drivers to not read back struct gpio_chip::base. Some drivers do
48	that and would be broken by attempts to poison it or make it dynamic.
49	Example in AT91 pinctrl driver:
50	https://lore.kernel.org/all/[email protected]/
51	This particular driver is also DT-only, so with the above fixed, the
52	base can be made dynamic (set to -1) if CONFIG_GPIO_SYSFS is disabled.
53
54	- When this work is complete (will require some of the items in the
55	following ongoing work as well) we can delete the old global
56	numberspace accessors from <linux/gpio.h> and eventually delete
57	<linux/gpio.h> altogether.
58
59	-------------------------------------------------------------------------------
60
61	Collect drivers
62
63	Collect GPIO drivers from arch/* and other places that should be placed
64	in drivers/gpio/gpio-*. Augment platforms to create platform devices or
65	similar and probe a proper driver in the gpiolib subsystem.
66
67	In some cases it makes sense to create a GPIO chip from the local driver
68	for a few GPIOs. Those should stay where they are.
69
70	At the same time it makes sense to get rid of code duplication in existing or
71	new coming drivers. For example, gpio-ml-ioh should be incorporated into
72	gpio-pch.
73
74	-------------------------------------------------------------------------------
75
76	Generic MMIO GPIO
77
78	The GPIO drivers can utilize the generic MMIO helper library in many
79	cases, and the helper library should be as helpful as possible for MMIO
80	drivers. (drivers/gpio/gpio-mmio.c)
81
82	Work items:
83
84	- Look over and identify any remaining easily converted drivers and
85	dry-code conversions to MMIO GPIO for maintainers to test
86
87	- Expand the MMIO GPIO or write a new library for regmap-based I/O
88	helpers for GPIO drivers on regmap that simply use offsets
89	0..n in some register to drive GPIO lines
90
91	- Expand the MMIO GPIO or write a new library for port-mapped I/O
92	helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
93	this with dry-coding and sending to maintainers to test
94
95	-------------------------------------------------------------------------------
96
97	Generic regmap GPIO
98
99	In the very similar way to Generic MMIO GPIO convert the users which can
100	take advantage of using regmap over direct IO accessors. Note, even in
101	MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c.
102
103	-------------------------------------------------------------------------------
104
105	GPIOLIB irqchip
106
107	The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
108	try to cover any generic kind of irqchip cascaded from a GPIO.
109
110	- Look over and identify any remaining easily converted drivers and
111	dry-code conversions to gpiolib irqchip for maintainers to test
112
113	-------------------------------------------------------------------------------
114
115	Moving over to immutable irq_chip structures
116
117	Most of the gpio chips implementing interrupt support rely on gpiolib
118	intercepting some of the irq_chip callbacks, preventing the structures
119	from being made read-only and forcing duplication of structures that
120	should otherwise be unique.
121
122	The solution is to call into the gpiolib code when needed (resource
123	management, enable/disable or unmask/mask callbacks), and to let the
124	core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
125	the irq_chip structure. The irq_chip structure can then be made unique
126	and const.
127
128	A small number of drivers have been converted (pl061, tegra186, msm,
129	amd, apple), and can be used as examples of how to proceed with this
130	conversion. Note that drivers using the generic irqchip framework
131	cannot be converted yet, but watch this space!
132
133	-------------------------------------------------------------------------------
134
135	Remove legacy sysfs features
136
137	We have two parallel per-chip class devices and per-exported-line attribute
138	groups in sysfs. One is using the obsolete global GPIO numberspace and the
139	second relies on hardware offsets of pins within the chip. Remove the former
140	once user-space has switched to using the latter.
141
142	-------------------------------------------------------------------------------
143
144	Remove GPIOD_FLAGS_BIT_NONEXCLUSIVE
145
146	GPIOs in the linux kernel are meant to be an exclusive resource. This means
147	that the GPIO descriptors (the software representation of the hardware concept)
148	are not reference counted and - in general - only one user at a time can
149	request a GPIO line and control its settings. The consumer API is designed
150	around full control of the line's state as evidenced by the fact that, for
151	instance, gpiod_set_value() does indeed drive the line as requested, instead
152	of bumping an enable counter of some sort.
153
154	A problematic use-case for GPIOs is when two consumers want to use the same
155	descriptor independently. An example of such a user is the regulator subsystem
156	which may instantiate several struct regulator_dev instances containing
157	a struct device but using the same enable GPIO line.
158
159	A workaround was introduced in the form of the GPIOD_FLAGS_BIT_NONEXCLUSIVE
160	flag but its implementation is problematic: it does not provide any
161	synchronization of usage nor did it introduce any enable count meaning the
162	non-exclusive users of the same descriptor will in fact "fight" for the
163	control over it. This flag should be removed and replaced with a better
164	solution, possibly based on the new power sequencing subsystem.
165
166	-------------------------------------------------------------------------------
167
168	Remove devm_gpiod_unhinge()
169
170	devm_gpiod_unhinge() is provided as a way to transfer the ownership of managed
171	enable GPIOs to the regulator core. Rather than doing that however, we should
172	make it possible for the regulator subsystem to deal with GPIO resources the
173	lifetime of which it doesn't control as logically, a GPIO obtained by a caller
174	should also be freed by it.