[PATCH] gpio: document how to make combined GPIO+irqchip drivers

[PATCH] gpio: document how to make combined GPIO+irqchip drivers

[Linus Walleij]

Write a few words on how GPIO drivers supplying an irqchip should
be written.

Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 Documentation/gpio/driver.txt | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index 9da0bfa74781..9818b2055197 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -62,6 +62,36 @@ Any debugfs dump method should normally ignore signals which haven't been
 requested as GPIOs. They can use gpiochip_is_requested(), which returns either
 NULL or the label associated with that GPIO when it was requested.
 
+GPIO drivers providing IRQs
+---------------------------
+It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
+most often cascaded off a parent interrupt controller, and in some special
+cases the GPIO logic is melded with a SoC:s primary interrupt controller.
+
+The IRQ portions of the GPIO block are implemented using an irqchip, using
+the header <linux/irq.h>. So basically such a driver is utilizing two sub-
+systems simultaneously: gpio and irq.
+
+It is legal for any IRQ consumer to request an IRQ from any irqchip no matter
+if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
+irq_chip are orthogonal, and offering their services independent of each
+other.
+
+gpiod_to_irq() is just a convenience function to figure out the IRQ for a
+certain GPIO line and should not be relied upon to have been called before
+the IRQ is used.
+
+So always prepare the hardware and make it ready for action in respective
+callbacks from the GPIO and irqchip APIs. Do not rely on gpio_to_irq() having
+been called first.
+
+This orthogonality leads to ambiguities that we need to solve: if there is
+competition inside the subsystem which side is using the resource (a certain
+GPIO line and register for example) it needs to deny certain operations and
+keep track of usage inside of the gpiolib subsystem. This is why the API
+below exists.
+
+
 Locking IRQ usage
 -----------------
 Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
@@ -73,3 +103,7 @@ This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
 is released:
 
 	void gpiod_unlock_as_irq(struct gpio_desc *desc)
+
+When implementing an irqchip inside a GPIO driver, these two functions should
+typically be called in the .startup() and .shutdown() callbacks from the
+irqchip.
-- 
1.8.4.2

Re: [PATCH] gpio: document how to make combined GPIO+irqchip drivers

[Gerhard Sittig]

On Wed, Jan 22, 2014 at 15:03 +0100, Linus Walleij wrote:
> 
> --- a/Documentation/gpio/driver.txt
> +++ b/Documentation/gpio/driver.txt
> @@ -62,6 +62,36 @@ Any debugfs dump method should normally ignore signals which haven't been
>  requested as GPIOs. They can use gpiochip_is_requested(), which returns either
>  NULL or the label associated with that GPIO when it was requested.
>  
> +GPIO drivers providing IRQs
> +---------------------------
> +It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
> +most often cascaded off a parent interrupt controller, and in some special
> +cases the GPIO logic is melded with a SoC:s primary interrupt controller.

... with a SoC's primary ... (apostroph instead of colon)

> +gpiod_to_irq() is just a convenience function to figure out the IRQ for a
> +certain GPIO line and should not be relied upon to have been called before
> +the IRQ is used.
> +
> +So always prepare the hardware and make it ready for action in respective
> +callbacks from the GPIO and irqchip APIs. Do not rely on gpio_to_irq() having
> +been called first.

The two paragraphs refer to different routines (gpiod_to_irq()
and gpio_to_irq()) -- is this intentional?  (one might be the
equivalent of the other, just using different handles which
perfectly map to each other in any direction, haven't checked the
details)


virtually yours
Gerhard Sittig
-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80  Email: office@denx.de

Re: [PATCH] gpio: document how to make combined GPIO+irqchip drivers

[Linus Walleij]

On Wed, Jan 22, 2014 at 7:51 PM, Gerhard Sittig <gsi@denx.de> wrote:

> ... with a SoC's primary ... (apostroph instead of colon)

OK

> The two paragraphs refer to different routines (gpiod_to_irq()
> and gpio_to_irq()) -- is this intentional?

No :-)

Fixed up both in the commit in my tree, THANKS!

Yours,
Linus Walleij