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- Change all consumer drivers that #include <linux/of_gpio.h> to
 63  #include <linux/gpio/consumer.h> and stop doing custom parsing of the
 64  GPIO lines from the device tree. This can be tricky and often ivolves
 65  changing boardfiles, etc.
 66
 67- Pull semantics for legacy device tree (OF) GPIO lookups into
 68  gpiolib-of.c: in some cases subsystems are doing custom flags and
 69  lookups for polarity inversion, open drain and what not. As we now
 70  handle this with generic OF bindings, pull all legacy handling into
 71  gpiolib so the library API becomes narrow and deep and handle all
 72  legacy bindings internally. (See e.g. commits 6953c57ab172,
 73  6a537d48461d etc)
 74
 75- Delete <linux/of_gpio.h> when all the above is complete and everything
 76  uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.
 77
 78
 79Get rid of <linux/gpio/legacy-of-mm-gpiochip.h>
 80
 81Work items:
 82
 83- Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
 84  GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
 85  to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_remove(),
 86  CONFIG_OF_GPIO_MM_GPIOCHIP from the kernel.
 87
 88
 89Get rid of <linux/gpio.h>
 90
 91This legacy header is a one stop shop for anything GPIO is closely tied
 92to the global GPIO numberspace. The endgame of the above refactorings will
 93be the removal of <linux/gpio.h> and from that point only the specialized
 94headers under <linux/gpio/*.h> will be used. This requires all the above to
 95be completed and is expected to take a long time.
 96
 97
 98Collect drivers
 99
100Collect GPIO drivers from arch/* and other places that should be placed
101in drivers/gpio/gpio-*. Augment platforms to create platform devices or
102similar and probe a proper driver in the gpiolib subsystem.
103
104In some cases it makes sense to create a GPIO chip from the local driver
105for a few GPIOs. Those should stay where they are.
106
107At the same time it makes sense to get rid of code duplication in existing or
108new coming drivers. For example, gpio-ml-ioh should be incorporated into
109gpio-pch.
110
111
112Generic MMIO GPIO
113
114The GPIO drivers can utilize the generic MMIO helper library in many
115cases, and the helper library should be as helpful as possible for MMIO
116drivers. (drivers/gpio/gpio-mmio.c)
117
118Work items:
119
120- Look over and identify any remaining easily converted drivers and
121  dry-code conversions to MMIO GPIO for maintainers to test
122
123- Expand the MMIO GPIO or write a new library for regmap-based I/O
124  helpers for GPIO drivers on regmap that simply use offsets
125  0..n in some register to drive GPIO lines
126
127- Expand the MMIO GPIO or write a new library for port-mapped I/O
128  helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
129  this with dry-coding and sending to maintainers to test
130
131
132Generic regmap GPIO
133
134In the very similar way to Generic MMIO GPIO convert the users which can
135take advantage of using regmap over direct IO accessors. Note, even in
136MMIO case the regmap MMIO with gpio-regmap.c is preferable over gpio-mmio.c.
137
138
139GPIOLIB irqchip
140
141The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
142try to cover any generic kind of irqchip cascaded from a GPIO.
143
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
144- Look over and identify any remaining easily converted drivers and
145  dry-code conversions to gpiolib irqchip for maintainers to test
146
 
 
 
 
 
 
 
 
 
147
148Increase integration with pin control
149
150There are already ways to use pin control as back-end for GPIO and
151it may make sense to bring these subsystems closer. One reason for
152creating pin control as its own subsystem was that we could avoid any
153use of the global GPIO numbers. Once the above is complete, it may
154make sense to simply join the subsystems into one and make pin
155multiplexing, pin configuration, GPIO, etc selectable options in one
156and the same pin control and GPIO subsystem.
157
158
159Debugfs in place of sysfs
160
161The old sysfs code that enables simple uses of GPIOs from the
162command line is still popular despite the existance of the proper
163character device. The reason is that it is simple to use on
164root filesystems where you only have a minimal set of tools such
165as "cat", "echo" etc.
166
167The old sysfs still need to be strongly deprecated and removed
168as it relies on the global GPIO numberspace that assume a strict
169order of global GPIO numbers that do not change between boots
170and is independent of probe order.
171
172To solve this and provide an ABI that people can use for hacks
173and development, implement a debugfs interface to manipulate
174GPIO lines that can do everything that sysfs can do today: one
175directory per gpiochip and one file entry per line:
176
177/sys/kernel/debug/gpiochip/gpiochip0
178/sys/kernel/debug/gpiochip/gpiochip0/gpio0
179/sys/kernel/debug/gpiochip/gpiochip0/gpio1
180/sys/kernel/debug/gpiochip/gpiochip0/gpio2
181/sys/kernel/debug/gpiochip/gpiochip0/gpio3
182...
183/sys/kernel/debug/gpiochip/gpiochip1
184/sys/kernel/debug/gpiochip/gpiochip1/gpio0
185/sys/kernel/debug/gpiochip/gpiochip1/gpio1
186...
187
188The exact files and design of the debugfs interface can be
189discussed but the idea is to provide a low-level access point
190for debugging and hacking and to expose all lines without the
191need of any exporting. Also provide ample ammunition to shoot
192oneself in the foot, because this is debugfs after all.
193
194
195Moving over to immutable irq_chip structures
196
197Most of the gpio chips implementing interrupt support rely on gpiolib
198intercepting some of the irq_chip callbacks, preventing the structures
199from being made read-only and forcing duplication of structures that
200should otherwise be unique.
201
202The solution is to call into the gpiolib code when needed (resource
203management, enable/disable or unmask/mask callbacks), and to let the
204core code know about that by exposing a flag (IRQCHIP_IMMUTABLE) in
205the irq_chip structure. The irq_chip structure can then be made unique
206and const.
207
208A small number of drivers have been converted (pl061, tegra186, msm,
209amd, apple), and can be used as examples of how to proceed with this
210conversion. Note that drivers using the generic irqchip framework
211cannot 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 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. In similar way gpio-intel-mid into gpio-pxa.
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
 
 
 
 
 
 
 
127GPIOLIB irqchip
128
129The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
130try to cover any generic kind of irqchip cascaded from a GPIO.
131
132- Convert all the GPIOLIB_IRQCHIP users to pass an irqchip template,
133  parent and flags before calling [devm_]gpiochip_add[_data]().
134  Currently we set up the irqchip after setting up the gpiochip
135  using gpiochip_irqchip_add() and gpiochip_set_[chained|nested]_irqchip().
136  This is too complex, so convert all users over to just set up
137  the irqchip before registering the gpio_chip, typical example:
138
139  /* Typical state container with dynamic irqchip */
140  struct my_gpio {
141      struct gpio_chip gc;
142      struct irq_chip irq;
143  };
144
145  int irq; /* from platform etc */
146  struct my_gpio *g;
147  struct gpio_irq_chip *girq;
148
149  /* Set up the irqchip dynamically */
150  g->irq.name = "my_gpio_irq";
151  g->irq.irq_ack = my_gpio_ack_irq;
152  g->irq.irq_mask = my_gpio_mask_irq;
153  g->irq.irq_unmask = my_gpio_unmask_irq;
154  g->irq.irq_set_type = my_gpio_set_irq_type;
155
156  /* Get a pointer to the gpio_irq_chip */
157  girq = &g->gc.irq;
158  girq->chip = &g->irq;
159  girq->parent_handler = ftgpio_gpio_irq_handler;
160  girq->num_parents = 1;
161  girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
162                               GFP_KERNEL);
163  if (!girq->parents)
164      return -ENOMEM;
165  girq->default_type = IRQ_TYPE_NONE;
166  girq->handler = handle_bad_irq;
167  girq->parents[0] = irq;
168
169  When this is done, we will delete the old APIs for instatiating
170  GPIOLIB_IRQCHIP and simplify the code.
171
172- Look over and identify any remaining easily converted drivers and
173  dry-code conversions to gpiolib irqchip for maintainers to test
174
175- Drop gpiochip_set_chained_irqchip() when all the chained irqchips
176  have been converted to the above infrastructure.
177
178- Add more infrastructure to make it possible to also pass a threaded
179  irqchip in struct gpio_irq_chip.
180
181- Drop gpiochip_irqchip_add_nested() when all the chained irqchips
182  have been converted to the above infrastructure.
183
184
185Increase integration with pin control
186
187There are already ways to use pin control as back-end for GPIO and
188it may make sense to bring these subsystems closer. One reason for
189creating pin control as its own subsystem was that we could avoid any
190use of the global GPIO numbers. Once the above is complete, it may
191make sense to simply join the subsystems into one and make pin
192multiplexing, pin configuration, GPIO, etc selectable options in one
193and the same pin control and GPIO subsystem.