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 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. 194