375 lines
17 KiB
Text
375 lines
17 KiB
Text
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.
|
|
|
|
RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
|
|
(like PM runtime) in its gpio_chip implementation (.get/.set and direction
|
|
control callbacks) if it is expected to call GPIO APIs from atomic context
|
|
on -RT (inside hard IRQ handlers and similar contexts). Normally this should
|
|
not be required.
|
|
|
|
|
|
GPIOs with open drain/source support
|
|
------------------------------------
|
|
|
|
Open drain (CMOS) or open collector (TTL) means the line is not actively driven
|
|
high: instead you provide the drain/collector as output, so when the transistor
|
|
is not open, it will present a high-impedance (tristate) to the external rail.
|
|
|
|
|
|
CMOS CONFIGURATION TTL CONFIGURATION
|
|
|
|
||--- out +--- out
|
|
in ----|| |/
|
|
||--+ in ----|
|
|
| |\
|
|
GND GND
|
|
|
|
This configuration is normally used as a way to achieve one of two things:
|
|
|
|
- Level-shifting: to reach a logical level higher than that of the silicon
|
|
where the output resides.
|
|
|
|
- inverse wire-OR on an I/O line, for example a GPIO line, making it possible
|
|
for any driving stage on the line to drive it low even if any other output
|
|
to the same line is simultaneously driving it high. A special case of this
|
|
is driving the SCL and SCA lines of an I2C bus, which is by definition a
|
|
wire-OR bus.
|
|
|
|
Both usecases require that the line be equipped with a pull-up resistor. This
|
|
resistor will make the line tend to high level unless one of the transistors on
|
|
the rail actively pulls it down.
|
|
|
|
The level on the line will go as high as the VDD on the pull-up resistor, which
|
|
may be higher than the level supported by the transistor, achieveing a
|
|
level-shift to the higher VDD.
|
|
|
|
Integrated electronics often have an output driver stage in the form of a CMOS
|
|
"totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
|
|
the line high and one of them drives the line low. This is called a push-pull
|
|
output. The "totem-pole" looks like so:
|
|
|
|
VDD
|
|
|
|
|
OD ||--+
|
|
+--/ ---o|| P-MOS-FET
|
|
| ||--+
|
|
IN --+ +----- out
|
|
| ||--+
|
|
+--/ ----|| N-MOS-FET
|
|
OS ||--+
|
|
|
|
|
GND
|
|
|
|
The desired output signal (e.g. coming directly from some GPIO output register)
|
|
arrives at IN. The switches named "OD" and "OS" are normally closed, creating
|
|
a push-pull circuit.
|
|
|
|
Consider the little "switches" named "OD" and "OS" that enable/disable the
|
|
P-MOS or N-MOS transistor right after the split of the input. As you can see,
|
|
either transistor will go totally numb if this switch is open. The totem-pole
|
|
is then halved and give high impedance instead of actively driving the line
|
|
high or low respectively. That is usually how software-controlled open
|
|
drain/source works.
|
|
|
|
Some GPIO hardware come in open drain / open source configuration. Some are
|
|
hard-wired lines that will only support open drain or open source no matter
|
|
what: there is only one transistor there. Some are software-configurable:
|
|
by flipping a bit in a register the output can be configured as open drain
|
|
or open source, in practice by flicking open the switches labeled "OD" and "OS"
|
|
in the drawing above.
|
|
|
|
By disabling the P-MOS transistor, the output can be driven between GND and
|
|
high impedance (open drain), and by disabling the N-MOS transistor, the output
|
|
can be driven between VDD and high impedance (open source). In the first case,
|
|
a pull-up resistor is needed on the outgoing rail to complete the circuit, and
|
|
in the second case, a pull-down resistor is needed on the rail.
|
|
|
|
Hardware that supports open drain or open source or both, can implement a
|
|
special callback in the gpio_chip: .set_single_ended() that takes an enum flag
|
|
telling whether to configure the line as open drain, open source or push-pull.
|
|
This will happen in response to the GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag
|
|
set in the machine file, or coming from other hardware descriptions.
|
|
|
|
If this state can not be configured in hardware, i.e. if the GPIO hardware does
|
|
not support open drain/open source in hardware, the GPIO library will instead
|
|
use a trick: when a line is set as output, if the line is flagged as open
|
|
drain, and the IN output value is low, it will be driven low as usual. But
|
|
if the IN output value is set to high, it will instead *NOT* be driven high,
|
|
instead it will be switched to input, as input mode is high impedance, thus
|
|
achieveing an "open drain emulation" of sorts: electrically the behaviour will
|
|
be identical, with the exception of possible hardware glitches when switching
|
|
the mode of the line.
|
|
|
|
For open source configuration the same principle is used, just that instead
|
|
of actively driving the line low, it is set to input.
|
|
|
|
|
|
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.
|
|
|
|
RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
|
|
(like PM runtime) as part of its irq_chip implementation on -RT.
|
|
- spinlock_t should be replaced with raw_spinlock_t [1].
|
|
- If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
|
|
and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks
|
|
on an irqchip. Create the callbacks if needed [2].
|
|
|
|
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.
|
|
|
|
RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT.
|
|
As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used
|
|
in chained IRQ handler.
|
|
if required (and if it can't be converted to the nested threaded GPIO irqchip)
|
|
- chained IRQ handler can be converted to generic irq handler and this way
|
|
it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT
|
|
(for example, see [3]).
|
|
Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,
|
|
so IRQ core will complain if it will be called from IRQ handler which is
|
|
forced thread. The "fake?" raw lock can be used to W/A this problem:
|
|
|
|
raw_spinlock_t wa_lock;
|
|
static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
|
|
unsigned long wa_lock_flags;
|
|
raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
|
|
generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit));
|
|
raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
|
|
|
|
* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",
|
|
but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
|
|
performed by generic IRQ handler which is configured using request_irq().
|
|
The GPIO irqchip will then end up calling something like this sequence in
|
|
its interrupt handler:
|
|
|
|
static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
|
|
for each detected GPIO IRQ
|
|
generic_handle_irq(...);
|
|
|
|
RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ
|
|
core will complain that generic_handle_irq() is called with IRQ enabled and
|
|
the same W/A as for "CHAINED GPIO irqchips" can be applied.
|
|
|
|
* 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
|
|
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)
|
|
|
|
If there is a need to exclude certain GPIOs from the IRQ domain, one can
|
|
set .irq_need_valid_mask of the gpiochip before gpiochip_add_data() is
|
|
called. This allocates .irq_valid_mask with as many bits set as there are
|
|
GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this
|
|
mask. The mask must be filled in before gpiochip_irqchip_add() is called.
|
|
|
|
* 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. This is also used
|
|
to set up a nested irqchip if NULL is passed as handler.
|
|
|
|
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.
|
|
|
|
- Nominally set all handlers to handle_bad_irq() in the setup call and pass
|
|
handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is
|
|
expected for GPIO driver that irqchip .set_type() callback have to be called
|
|
before using/enabling GPIO IRQ. 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.
|
|
|
|
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
|
|
to mark the GPIO as being used as an IRQ:
|
|
|
|
int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
|
|
|
This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
|
|
is released:
|
|
|
|
void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
|
|
|
When implementing an irqchip inside a GPIO driver, these two functions should
|
|
typically be called in the .startup() and .shutdown() callbacks from the
|
|
irqchip.
|
|
|
|
Real-Time compliance for GPIO IRQ chips
|
|
---------------------------------------
|
|
|
|
Any provider of irqchips needs to be carefully tailored to support Real Time
|
|
preemption. It is desirable that all irqchips in the GPIO subsystem keep this
|
|
in mind and does the proper testing to assure they are real time-enabled.
|
|
So, pay attention on above " RT_FULL:" notes, please.
|
|
The following is a checklist to follow when preparing a driver for real
|
|
time-compliance:
|
|
|
|
- ensure spinlock_t is not used as part irq_chip implementation;
|
|
- ensure that sleepable APIs are not used as part irq_chip implementation.
|
|
If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
|
|
and .irq_bus_unlock() callbacks;
|
|
- Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
|
|
from chained IRQ handler;
|
|
- Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
|
|
apply corresponding W/A;
|
|
- Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq
|
|
handler if possible :)
|
|
- regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for
|
|
GPIO IRQ chip implementation;
|
|
- Test your driver with the appropriate in-kernel real time test cases for both
|
|
level and edge IRQs.
|
|
|
|
|
|
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.
|
|
|
|
struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
|
|
const char *label)
|
|
|
|
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.
|
|
|
|
[1] http://www.spinics.net/lists/linux-omap/msg120425.html
|
|
[2] https://lkml.org/lkml/2015/9/25/494
|
|
[3] https://lkml.org/lkml/2015/9/25/495
|