path: root/Documentation/gpio
diff options
Diffstat (limited to 'Documentation/gpio')
2 files changed, 95 insertions, 0 deletions
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index 0ff8eb072749..d8abfc31abbe 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -154,6 +154,7 @@ raw line value:
void gpiod_set_raw_value(struct gpio_desc *desc, int value)
int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
+ int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
The active-low state of a GPIO can also be queried using the following call:
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index 9da0bfa74781..fa9a0a8b3734 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -62,6 +62,96 @@ 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.
+GPIO irqchips usually fall in one of two categories:
+* CHAINED GPIO irqchips: these are usually the type that is embedded on
+ an SoC. This means that there is a fast IRQ handler for the GPIOs that
+ gets called in a chain from the parent IRQ handler, most typically the
+ system interrupt controller. This means the GPIO irqchip is registered
+ using irq_set_chained_handler() or the corresponding
+ gpiochip_set_chained_irqchip() helper function, and the GPIO irqchip
+ handler will be called immediately from the parent irqchip, while
+ holding the IRQs disabled. The GPIO irqchip will then end up calling
+ something like this sequence in its interrupt handler:
+ static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
+ chained_irq_enter(...);
+ generic_handle_irq(...);
+ chained_irq_exit(...);
+ Chained GPIO irqchips typically can NOT set the .can_sleep flag on
+ struct gpio_chip, as everything happens directly in the callbacks.
+* NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any
+ other GPIO irqchip residing on the other side of a sleeping bus. Of course
+ such drivers that need slow bus traffic to read out IRQ status and similar,
+ traffic which may in turn incur other IRQs to happen, cannot be handled
+ in a quick IRQ handler with IRQs disabled. Instead they need to spawn a
+ thread and then mask the parent IRQ line until the interrupt is handled
+ by the driver. The hallmark of this driver is to call something like
+ this in its interrupt handler:
+ static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
+ ...
+ handle_nested_irq(irq);
+ The hallmark of threaded GPIO irqchips is that they set the .can_sleep
+ flag on struct gpio_chip to true, indicating that this chip may sleep
+ when accessing the GPIOs.
+To help out in handling the set-up and management of GPIO irqchips and the
+associated irqdomain and resource allocation callbacks, the gpiolib has
+some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig
+* gpiochip_irqchip_add(): adds an irqchip to a gpiochip. It will pass
+ the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks
+ need to embed the gpio_chip in its state container and obtain a pointer
+ to the container using container_of().
+ (See Documentation/driver-model/design-patterns.txt)
+* gpiochip_set_chained_irqchip(): sets up a chained irq handler for a
+ gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler
+ data. (Notice handler data, since the irqchip data is likely used by the
+ parent irqchip!) This is for the chained type of chip.
+To use the helpers please keep the following in mind:
+- Make sure to assign all relevant members of the struct gpio_chip so that
+ the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
+ properly.
+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
+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
@@ -73,3 +163,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

Privacy Policy