driver-api/gpio/driver.rst

26 between 0 and n-1, n being the number of GPIOs managed by the chip.
29 example if a system uses a memory-mapped set of I/O-registers where 32 GPIO
30 lines are handled by one bit per line in a 32-bit register, it makes sense to
44 So for example one platform could use global numbers 32-159 for GPIOs, with a
46 global numbers 0..63 with one set of GPIO controllers, 64-79 with another type
47 of GPIO controller, and on one particular board 80-95 with an FPGA. The legacy
49 2000-2063 to identify GPIO lines in a bank of I2C GPIO expanders.
60  - methods to establish GPIO line direction
61  - methods used to access GPIO line values
62  - method to set electrical configuration for a given GPIO line
63  - method to return the IRQ number associated to a given GPIO line
64  - flag saying whether calls to its methods may sleep
65  - optional line names array to identify lines
66  - optional debugfs dump method (showing extra state information)
67  - optional base number (will be automatically assigned if omitted)
68  - optional label for diagnostics and GPIO chip mapping using platform data
75 Often a gpio_chip is part of an instance-specific structure with states not
77 Chips such as audio codecs will have complex non-GPIO states.
86 atomic context on realtime kernels (inside hard IRQ handlers and similar
91 -----------------------------
96 - Debouncing
97 - Single-ended modes (open drain/open source)
98 - Pull up and pull down resistor enablement
106 ending up in the pin control back-end "behind" the GPIO controller, usually
110 If a pin controller back-end is used, the GPIO controller or hardware
112 numbers on the pin controller so they can properly cross-reference each other.
116 --------------------------------
133 -----------------------------------------
137 is not open, it will present a high-impedance (tristate) to the external rail::
142             ||--- out              +--- out
143      in ----||                   |/
144             ||--+         in ----|
150 - Level-shifting: to reach a logical level higher than that of the silicon
153 - Inverse wire-OR on an I/O line, for example a GPIO line, making it possible
157   wire-OR bus.
159 Both use cases require that the line be equipped with a pull-up resistor. This
163 The level on the line will go as high as the VDD on the pull-up resistor, which
165 level-shift to the higher VDD.
168 "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
169 the line high and one of them drives the line low. This is called a push-pull
170 output. The "totem-pole" looks like so::
174             OD    ||--+
175          +--/ ---o||     P-MOS-FET
176          |        ||--+
177     IN --+            +----- out
178          |        ||--+
179          +--/ ----||     N-MOS-FET
180             OS    ||--+
186 a push-pull circuit.
189 P-MOS or N-MOS transistor right after the split of the input. As you can see,
190 either transistor will go totally numb if this switch is open. The totem-pole
192 high or low respectively. That is usually how software-controlled open
196 hard-wired lines that will only support open drain or open source no matter
197 what: there is only one transistor there. Some are software-configurable:
202 By disabling the P-MOS transistor, the output can be driven between GND and
203 high impedance (open drain), and by disabling the N-MOS transistor, the output
205 a pull-up resistor is needed on the outgoing rail to complete the circuit, and
206 in the second case, a pull-down resistor is needed on the rail.
211 open source or push-pull. This will happen in response to the
229 GPIO lines with pull up/down resistor support
230 ---------------------------------------------
232 A GPIO line can support pull-up/down using the .set_config() callback. This
233 means that a pull up or pull-down resistor is available on the output of the
236 In discrete designs, a pull-up or pull-down resistor is simply soldered on
241 The .set_config() callback can only turn pull up or down on and off, and will
243 switch a bit in a register enabling or disabling pull-up or pull-down.
246 pull-up or pull-down resistor, the GPIO chip callback .set_config() will not
250 different pull-up or pull-down resistance values.
260 The IRQ portions of the GPIO block are implemented using an irq_chip, using
261 the header <linux/irq.h>. So this combined driver is utilizing two sub-
262 systems simultaneously: gpio and irq.
264 It is legal for any IRQ consumer to request an IRQ from any irqchip even if it
265 is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
269 gpiod_to_irq() is just a convenience function to figure out the IRQ for a
271 the IRQ is used.
279 - CASCADED INTERRUPT CHIPS: this means that the GPIO chip has one common
292 - HIERARCHICAL INTERRUPT CHIPS: this means that each GPIO line has a dedicated
293   irq line to a parent interrupt controller one level up. There is no need
302 - spinlock_t should be replaced with raw_spinlock_t.[1]
303 - If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
309 ----------------------
313 - CHAINED CASCADED GPIO IRQCHIPS: these are usually the type that is embedded on
314   an SoC. This means that there is a fast IRQ flow handler for the GPIOs that
315   gets called in a chain from the parent IRQ handler, most typically the
321     static irqreturn_t foo_gpio_irq(int irq, void *data)
330   Realtime considerations: Note that chained IRQ handlers will not be forced
331   threaded on -RT. As a result, spinlock_t or any sleepable APIs (like PM
332   runtime) can't be used in a chained IRQ handler.
335   see below) a chained IRQ handler can be converted to generic irq handler and
336   this way it will become a threaded IRQ handler on -RT and a hard IRQ handler
337   on non-RT (for example, see [3]).
339   The generic_handle_irq() is expected to be called with IRQ disabled,
340   so the IRQ core will complain if it is called from an IRQ handler which is
345     static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
347         raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
348         generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));
349         raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
351 - GENERIC CHAINED GPIO IRQCHIPS: these are the same as "CHAINED GPIO irqchips",
352   but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
353   performed by generic IRQ handler which is configured using request_irq().
357     static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
358         for each detected GPIO IRQ
361   Realtime considerations: this kind of handlers will be forced threaded on -RT,
362   and as result the IRQ core will complain that generic_handle_irq() is called
363   with IRQ enabled and the same work-around as for "CHAINED GPIO irqchips" can
366 - NESTED THREADED GPIO IRQCHIPS: these are off-chip GPIO expanders and any
370   Of course such drivers that need slow bus traffic to read out IRQ status and
372   handled in a quick IRQ handler with IRQs disabled. Instead they need to spawn
373   a thread and then mask the parent IRQ line until the interrupt is handled
377     static irqreturn_t foo_gpio_irq(int irq, void *data)
379         handle_nested_irq(irq);
390 ----------------------------------------
392 To help out in handling the set-up and management of GPIO irqchips and the
397 under the assumption that your interrupts are 1-to-1-mapped to the
400 .. csv-table::
401     :header: GPIO line offset, Hardware IRQ
407     ngpio-1, ngpio-1
422 .. code-block:: c
474   int irq; /* from platform etc */
479   girq = &g->gc.irq;
481   girq->parent_handler = ftgpio_gpio_irq_handler;
482   girq->num_parents = 1;
483   girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
485   if (!girq->parents)
486       return -ENOMEM;
487   girq->default_type = IRQ_TYPE_NONE;
488   girq->handler = handle_bad_irq;
489   girq->parents[0] = irq;
491   return devm_gpiochip_add_data(dev, &g->gc, g);
496 .. code-block:: c
548   int irq; /* from platform etc */
552   ret = devm_request_threaded_irq(dev, irq, NULL, irq_thread_fn,
553                                   IRQF_ONESHOT, "my-chip", g);
558   girq = &g->gc.irq;
560   /* This will let us handle the parent IRQ in the driver */
561   girq->parent_handler = NULL;
562   girq->num_parents = 0;
563   girq->parents = NULL;
564   girq->default_type = IRQ_TYPE_NONE;
565   girq->handler = handle_bad_irq;
567   return devm_gpiochip_add_data(dev, &g->gc, g);
570 In this case the typical set-up will look like this:
572 .. code-block:: c
632   girq = &g->gc.irq;
634   girq->default_type = IRQ_TYPE_NONE;
635   girq->handler = handle_bad_irq;
636   girq->fwnode = g->fwnode;
637   girq->parent_domain = parent;
638   girq->child_to_parent_hwirq = my_gpio_child_to_parent_hwirq;
640   return devm_gpiochip_add_data(dev, &g->gc, g);
643 the IRQ, instead a parent irqdomain, an fwnode for the hardware and
645 the parent hardware irq from a child (i.e. this gpio chip) hardware irq.
649 If there is a need to exclude certain GPIO lines from the IRQ domain handled by
650 these helpers, we can set .irq.need_valid_mask of the gpiochip before
652 .irq.valid_mask with as many bits set as there are GPIO lines in the chip, each
653 bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits
659 - Make sure to assign all relevant members of the struct gpio_chip so that
663 - Nominally set gpio_irq_chip.handler to handle_bad_irq. Then, if your irqchip
669 Locking IRQ usage
670 -----------------
680 Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
681 to mark the GPIO as being used as an IRQ::
685 This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
699 ---------------------------
706 When a GPIO is used as an IRQ signal, then gpiolib also needs to know if
707 the IRQ is enabled or disabled. In order to inform gpiolib about this,
712 This allows drivers to drive the GPIO as an output while the IRQ is
713 disabled. When the IRQ is enabled again, a driver should call::
726 Real-Time compliance for GPIO IRQ chips
727 ---------------------------------------
729 Any provider of irqchips needs to be carefully tailored to support Real-Time
731 in mind and do the proper testing to assure they are real time-enabled.
735 The following is a checklist to follow when preparing a driver for real-time
738 - ensure spinlock_t is not used as part irq_chip implementation
739 - ensure that sleepable APIs are not used as part irq_chip implementation
742 - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
743   from the chained IRQ handler
744 - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
745   apply corresponding work-around
746 - Chained GPIO irqchips: get rid of the chained IRQ handler and use generic irq
748 - regmap_mmio: it is possible to disable internal locking in regmap by setting
750 - Test your driver with the appropriate in-kernel real-time test cases for both
753 * [1] http://www.spinics.net/lists/linux-omap/msg120425.html
754 * [2] https://lore.kernel.org/r/1443209283-20781-2-git-send-email-grygorii.strashko@ti.com
755 * [3] https://lore.kernel.org/r/1443209283-20781-3-git-send-email-grygorii.strashko@ti.com
758 Requesting self-owned GPIO pins