gpio: document how to make combined GPIO+irqchip drivers

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 gpiod_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

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.