2013-11-16 12:34:21 +00:00
|
|
|
GPIO Descriptor Driver Interface
|
|
|
|
================================
|
|
|
|
|
|
|
|
This document serves as a guide for GPIO chip drivers writers. Note that it
|
|
|
|
describes the new descriptor-based interface. For a description of the
|
|
|
|
deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
|
|
|
|
|
|
|
|
Each GPIO controller driver needs to include the following header, which defines
|
|
|
|
the structures used to define a GPIO driver:
|
|
|
|
|
|
|
|
#include <linux/gpio/driver.h>
|
|
|
|
|
|
|
|
|
|
|
|
Internal Representation of GPIOs
|
|
|
|
================================
|
|
|
|
|
|
|
|
Inside a GPIO driver, individual GPIOs are identified by their hardware number,
|
|
|
|
which is a unique number between 0 and n, n being the number of GPIOs managed by
|
|
|
|
the chip. This number is purely internal: the hardware number of a particular
|
|
|
|
GPIO descriptor is never made visible outside of the driver.
|
|
|
|
|
|
|
|
On top of this internal number, each GPIO also need to have a global number in
|
|
|
|
the integer GPIO namespace so that it can be used with the legacy GPIO
|
|
|
|
interface. Each chip must thus have a "base" number (which can be automatically
|
|
|
|
assigned), and for each GPIO the global number will be (base + hardware number).
|
|
|
|
Although the integer representation is considered deprecated, it still has many
|
|
|
|
users and thus needs to be maintained.
|
|
|
|
|
|
|
|
So for example one platform could use numbers 32-159 for GPIOs, with a
|
|
|
|
controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
|
|
|
|
numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO
|
|
|
|
controller, and on one particular board 80-95 with an FPGA. The numbers need not
|
|
|
|
be contiguous; either of those platforms could also use numbers 2000-2063 to
|
|
|
|
identify GPIOs in a bank of I2C GPIO expanders.
|
|
|
|
|
|
|
|
|
|
|
|
Controller Drivers: gpio_chip
|
|
|
|
=============================
|
|
|
|
|
|
|
|
In the gpiolib framework each GPIO controller is packaged as a "struct
|
|
|
|
gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
|
|
|
|
common to each controller of that type:
|
|
|
|
|
|
|
|
- methods to establish GPIO direction
|
|
|
|
- methods used to access GPIO values
|
|
|
|
- method to return the IRQ number associated to a given GPIO
|
|
|
|
- flag saying whether calls to its methods may sleep
|
|
|
|
- optional debugfs dump method (showing extra state like pullup config)
|
|
|
|
- optional base number (will be automatically assigned if omitted)
|
|
|
|
- label for diagnostics and GPIOs mapping using platform data
|
|
|
|
|
|
|
|
The code implementing a gpio_chip should support multiple instances of the
|
|
|
|
controller, possibly using the driver model. That code will configure each
|
|
|
|
gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare;
|
|
|
|
use gpiochip_remove() when it is unavoidable.
|
|
|
|
|
|
|
|
Most often a gpio_chip is part of an instance-specific structure with state not
|
|
|
|
exposed by the GPIO interfaces, such as addressing, power management, and more.
|
|
|
|
Chips such as codecs will have complex non-GPIO state.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2014-01-22 14:00:55 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2014-04-09 12:36:32 +00:00
|
|
|
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.
|
|
|
|
|
2015-10-02 21:26:05 +00:00
|
|
|
NOTE: chained IRQ handlers are usually not good for real time. If you
|
|
|
|
are submitting a new driver or refactoring a driver for real time compliance,
|
|
|
|
consider using creating a nested/threaded irqchip instead, see below.
|
|
|
|
|
|
|
|
* NESTED THREADED GPIO irqchips: these are traditionally 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.
|
|
|
|
|
|
|
|
With the introduction of real time support in the Linux kernel, also other
|
|
|
|
GPIO irqchips are encouraged to use a nested and threaded IRQ handler.
|
|
|
|
Doing so makes the interrupts naturally preemptible on a real time
|
|
|
|
setup, which means the system can easily be configured for real time with
|
|
|
|
a (usually negligable) performance loss.
|
|
|
|
|
|
|
|
These drivers 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:
|
2014-04-09 12:36:32 +00:00
|
|
|
|
|
|
|
static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
|
|
|
|
...
|
|
|
|
handle_nested_irq(irq);
|
2015-10-02 21:26:05 +00:00
|
|
|
OR
|
|
|
|
generic_handle_irq(irq);
|
2014-04-09 12:36:32 +00:00
|
|
|
|
2015-10-02 21:26:05 +00:00
|
|
|
Threaded GPIO irqchips should set the .can_sleep flag on struct gpio_chip
|
|
|
|
to true if they are e.g. accessing the chip over I2C or SPI, indicating that
|
|
|
|
this chip may sleep when accessing the GPIOs. irqchips that are just made
|
|
|
|
threaded to be preemptible and thus real time compliant need not do this:
|
|
|
|
preemption is not sleeping.
|
2014-04-09 12:36:32 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
symbol:
|
|
|
|
|
|
|
|
* 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
|
2014-09-26 12:19:52 +00:00
|
|
|
parent irqchip!) This is for the chained type of chip. This is also used
|
2015-10-02 21:26:05 +00:00
|
|
|
to set up a threaded/nested irqchip if NULL is passed as handler.
|
2014-04-09 12:36:32 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2014-01-22 14:00:55 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2013-11-16 12:34:21 +00:00
|
|
|
Locking IRQ usage
|
|
|
|
-----------------
|
|
|
|
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
|
|
|
|
to mark the GPIO as being used as an IRQ:
|
|
|
|
|
2014-10-23 08:27:07 +00:00
|
|
|
int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
2013-11-16 12:34:21 +00:00
|
|
|
|
|
|
|
This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
|
|
|
|
is released:
|
|
|
|
|
2014-10-23 08:27:07 +00:00
|
|
|
void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
2014-01-22 14:00:55 +00:00
|
|
|
|
|
|
|
When implementing an irqchip inside a GPIO driver, these two functions should
|
|
|
|
typically be called in the .startup() and .shutdown() callbacks from the
|
|
|
|
irqchip.
|
2014-07-22 15:01:01 +00:00
|
|
|
|
|
|
|
|
2015-10-02 21:26:05 +00:00
|
|
|
Real-Time compliance for GPIO IRQ chips
|
|
|
|
---------------------------------------
|
|
|
|
|
|
|
|
Any provider of irqchips needs to be carefully tailored to support Real Time
|
|
|
|
preemption. It is desireable that all irqchips in the GPIO subsystem keep this
|
|
|
|
in mind and does the proper testing to assure they are real time-enabled. The
|
|
|
|
following is a checklist to follow when preparing a driver for real
|
|
|
|
time-compliance:
|
|
|
|
|
|
|
|
- Nominally use raw_spinlock_t in the IRQ context path of the IRQ handler as
|
|
|
|
we do not want these sections to be preempted.
|
|
|
|
|
|
|
|
- Do NOT use chained_irq_enter() or chained_irq_exit() in the IRQ handler,
|
|
|
|
as we want the hotpath to be preemptible.
|
|
|
|
|
|
|
|
- Instead use nested IRQs and generic handlers such as handle_bad_irq(),
|
|
|
|
handle_level_irq() and handle_edge_irq(). Consequentally the handler
|
|
|
|
argument of gpiochip_set_chained_irqchip() should be NULL when using the
|
|
|
|
gpiolib irqchip helpers.
|
|
|
|
|
|
|
|
- Nominally set all handlers to handle_bad_irq() in the setup call, then
|
|
|
|
set the handler to handle_level_irq() and/or handle_edge_irq() in the irqchip
|
|
|
|
.set_type() callback depending on what your controller supports.
|
|
|
|
|
|
|
|
- If you need to use the pm_runtime_get*()/pm_runtime_put*() callbacks in some
|
|
|
|
of the irqchip callbacks, these should be moved to the .irq_bus_lock()
|
|
|
|
and .irq_bus_unlock() callbacks respectively, as these are the only
|
|
|
|
slowpath callbacks on an irqchip. Create the callbacks if need be.
|
|
|
|
|
|
|
|
- Test your driver with the apropriate in-kernel real time test cases for both
|
|
|
|
level and edge IRQs.
|
|
|
|
|
|
|
|
|
2014-07-22 15:01:01 +00:00
|
|
|
Requesting self-owned GPIO pins
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
|
|
|
|
descriptors through the gpiolib API. Using gpio_request() for this purpose
|
|
|
|
does not help since it pins the module to the kernel forever (it calls
|
|
|
|
try_module_get()). A GPIO driver can use the following functions instead
|
|
|
|
to request and free descriptors without being pinned to the kernel forever.
|
|
|
|
|
2014-08-19 17:06:09 +00:00
|
|
|
struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
|
|
|
|
const char *label)
|
2014-07-22 15:01:01 +00:00
|
|
|
|
|
|
|
void gpiochip_free_own_desc(struct gpio_desc *desc)
|
|
|
|
|
|
|
|
Descriptors requested with gpiochip_request_own_desc() must be released with
|
|
|
|
gpiochip_free_own_desc().
|
|
|
|
|
|
|
|
These functions must be used with care since they do not affect module use
|
|
|
|
count. Do not use the functions to request gpio descriptors not owned by the
|
|
|
|
calling driver.
|