[mirror_ubuntu-focal-kernel.git] / drivers / gpio / TODO

This is a place for planning the ongoing long-term work in the GPIO
subsystem.


GPIO descriptors

Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
to move away from the global GPIO numberspace and toward a decriptor-based
approach. This means that GPIO consumers, drivers and machine descriptions
ideally have no use or idea of the global GPIO numberspace that has/was
used in the inception of the GPIO subsystem.

Work items:

- Convert all GPIO device drivers to only #include <linux/gpio/driver.h>

- Convert all consumer drivers to only #include <linux/gpio/consumer.h>

- Convert all machine descriptors in "boardfiles" to only
  #include <linux/gpio/machine.h>, the other option being to convert it
  to a machine description such as device tree, ACPI or fwnode that
  implicitly does not use global GPIO numbers.

- When this work is complete (will require some of the items in the
  following ongoing work as well) we can delete the old global
  numberspace accessors from <linux/gpio.h> and eventually delete
  <linux/gpio.h> altogether.


Get rid of <linux/of_gpio.h>

This header and helpers appeared at one point when there was no proper
driver infrastructure for doing simpler MMIO GPIO devices and there was
no core support for parsing device tree GPIOs from the core library with
the [devm_]gpiod_get() calls we have today that will implicitly go into
the device tree back-end.

Work items:

- Get rid of struct of_mm_gpio_chip altogether: use the generic  MMIO
  GPIO for all current users (see below). Delete struct of_mm_gpio_chip,
  to_of_mm_gpio_chip(), of_mm_gpiochip_add_data(), of_mm_gpiochip_add()
  of_mm_gpiochip_remove() from the kernel.

- Change all consumer drivers that #include <linux/of_gpio.h> to
  #include <linux/gpio/consumer.h> and stop doing custom parsing of the
  GPIO lines from the device tree. This can be tricky and often ivolves
  changing boardfiles, etc.

- Pull semantics for legacy device tree (OF) GPIO lookups into
  gpiolib-of.c: in some cases subsystems are doing custom flags and
  lookups for polarity inversion, open drain and what not. As we now
  handle this with generic OF bindings, pull all legacy handling into
  gpiolib so the library API becomes narrow and deep and handle all
  legacy bindings internally. (See e.g. commits 6953c57ab172,
  6a537d48461d etc)

- Delete <linux/of_gpio.h> when all the above is complete and everything
  uses <linux/gpio/consumer.h> or <linux/gpio/driver.h> instead.


Collect drivers

Collect GPIO drivers from arch/* and other places that should be placed
in drivers/gpio/gpio-*. Augment platforms to create platform devices or
similar and probe a proper driver in the gpiolib subsystem.

In some cases it makes sense to create a GPIO chip from the local driver
for a few GPIOs. Those should stay where they are.


Generic MMIO GPIO

The GPIO drivers can utilize the generic MMIO helper library in many
cases, and the helper library should be as helpful as possible for MMIO
drivers. (drivers/gpio/gpio-mmio.c)

Work items:

- Look over and identify any remaining easily converted drivers and
  dry-code conversions to MMIO GPIO for maintainers to test

- Expand the MMIO GPIO or write a new library for port-mapped I/O
  helpers (x86 inb()/outb()) and convert port-mapped I/O drivers to use
  this with dry-coding and sending to maintainers to test


GPIOLIB irqchip

The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
try to cover any generic kind of irqchip cascaded from a GPIO.

- Convert all the GPIOLIB_IRQCHIP users to pass an irqchip template,
  parent and flags before calling [devm_]gpiochip_add[_data]().
  Currently we set up the irqchip after setting up the gpiochip
  using gpiochip_irqchip_add() and gpiochip_set_[chained|nested]_irqchip().
  This is too complex, so convert all users over to just set up
  the irqchip before registering the gpio_chip, typical example:

  /* Typical state container with dynamic irqchip */
  struct my_gpio {
      struct gpio_chip gc;
      struct irq_chip irq;
  };

  int irq; /* from platform etc */
  struct my_gpio *g;
  struct gpio_irq_chip *girq

  /* Set up the irqchip dynamically */
  g->irq.name = "my_gpio_irq";
  g->irq.irq_ack = my_gpio_ack_irq;
  g->irq.irq_mask = my_gpio_mask_irq;
  g->irq.irq_unmask = my_gpio_unmask_irq;
  g->irq.irq_set_type = my_gpio_set_irq_type;

  /* Get a pointer to the gpio_irq_chip */
  girq = &g->gc.irq;
  girq->chip = &g->irq;
  girq->parent_handler = ftgpio_gpio_irq_handler;
  girq->num_parents = 1;
  girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
                               GFP_KERNEL);
  if (!girq->parents)
      return -ENOMEM;
  girq->default_type = IRQ_TYPE_NONE;
  girq->handler = handle_bad_irq;
  girq->parents[0] = irq;

  When this is done, we will delete the old APIs for instatiating
  GPIOLIB_IRQCHIP and simplify the code.

- Look over and identify any remaining easily converted drivers and
  dry-code conversions to gpiolib irqchip for maintainers to test

- Support generic hierarchical GPIO interrupts: these are for the
  non-cascading case where there is one IRQ per GPIO line, there is
  currently no common infrastructure for this.


Increase integration with pin control

There are already ways to use pin control as back-end for GPIO and
it may make sense to bring these subsystems closer. One reason for
creating pin control as its own subsystem was that we could avoid any
use of the global GPIO numbers. Once the above is complete, it may
make sense to simply join the subsystems into one and make pin
multiplexing, pin configuration, GPIO, etc selectable options in one
and the same pin control and GPIO subsystem.
Commit	Line	Data
2646b90d LW	1	This is a place for planning the ongoing long-term work in the GPIO
	2	subsystem.
	3
	4
	5	GPIO descriptors
	6
	7	Starting with commit 79a9becda894 the GPIO subsystem embarked on a journey
	8	to move away from the global GPIO numberspace and toward a decriptor-based
	9	approach. This means that GPIO consumers, drivers and machine descriptions
	10	ideally have no use or idea of the global GPIO numberspace that has/was
	11	used in the inception of the GPIO subsystem.
	12
	13	Work 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
	30	Get rid of <linux/of_gpio.h>
	31
	32	This header and helpers appeared at one point when there was no proper
	33	driver infrastructure for doing simpler MMIO GPIO devices and there was
	34	no core support for parsing device tree GPIOs from the core library with
	35	the [devm_]gpiod_get() calls we have today that will implicitly go into
	36	the device tree back-end.
	37
	38	Work 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
	62	Collect drivers
	63
	64	Collect GPIO drivers from arch/* and other places that should be placed
65	in drivers/gpio/gpio-*. Augment platforms to create platform devices or
66	similar and probe a proper driver in the gpiolib subsystem.
67
68	In some cases it makes sense to create a GPIO chip from the local driver
69	for a few GPIOs. Those should stay where they are.
70
71
72	Generic MMIO GPIO
73
74	The GPIO drivers can utilize the generic MMIO helper library in many
75	cases, and the helper library should be as helpful as possible for MMIO
76	drivers. (drivers/gpio/gpio-mmio.c)
77
78	Work 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
88	GPIOLIB irqchip
89
90	The GPIOLIB irqchip is a helper irqchip for "simple cases" that should
91	try to cover any generic kind of irqchip cascaded from a GPIO.
92
9a82ee69 LW	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
2646b90d LW	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
	141	Increase integration with pin control
	142
	143	There are already ways to use pin control as back-end for GPIO and
	144	it may make sense to bring these subsystems closer. One reason for
	145	creating pin control as its own subsystem was that we could avoid any
	146	use of the global GPIO numbers. Once the above is complete, it may
	147	make sense to simply join the subsystems into one and make pin
	148	multiplexing, pin configuration, GPIO, etc selectable options in one
	149	and the same pin control and GPIO subsystem.