Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 1 | GPIO Descriptor Driver Interface |
| 2 | ================================ |
| 3 | |
| 4 | This document serves as a guide for GPIO chip drivers writers. Note that it |
| 5 | describes the new descriptor-based interface. For a description of the |
| 6 | deprecated integer-based GPIO interface please refer to gpio-legacy.txt. |
| 7 | |
| 8 | Each GPIO controller driver needs to include the following header, which defines |
| 9 | the structures used to define a GPIO driver: |
| 10 | |
| 11 | #include <linux/gpio/driver.h> |
| 12 | |
| 13 | |
| 14 | Internal Representation of GPIOs |
| 15 | ================================ |
| 16 | |
| 17 | Inside a GPIO driver, individual GPIOs are identified by their hardware number, |
| 18 | which is a unique number between 0 and n, n being the number of GPIOs managed by |
| 19 | the chip. This number is purely internal: the hardware number of a particular |
| 20 | GPIO descriptor is never made visible outside of the driver. |
| 21 | |
| 22 | On top of this internal number, each GPIO also need to have a global number in |
| 23 | the integer GPIO namespace so that it can be used with the legacy GPIO |
| 24 | interface. Each chip must thus have a "base" number (which can be automatically |
| 25 | assigned), and for each GPIO the global number will be (base + hardware number). |
| 26 | Although the integer representation is considered deprecated, it still has many |
| 27 | users and thus needs to be maintained. |
| 28 | |
| 29 | So for example one platform could use numbers 32-159 for GPIOs, with a |
| 30 | controller defining 128 GPIOs at a "base" of 32 ; while another platform uses |
| 31 | numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO |
| 32 | controller, and on one particular board 80-95 with an FPGA. The numbers need not |
| 33 | be contiguous; either of those platforms could also use numbers 2000-2063 to |
| 34 | identify GPIOs in a bank of I2C GPIO expanders. |
| 35 | |
| 36 | |
| 37 | Controller Drivers: gpio_chip |
| 38 | ============================= |
| 39 | |
| 40 | In the gpiolib framework each GPIO controller is packaged as a "struct |
| 41 | gpio_chip" (see linux/gpio/driver.h for its complete definition) with members |
| 42 | common to each controller of that type: |
| 43 | |
| 44 | - methods to establish GPIO direction |
| 45 | - methods used to access GPIO values |
| 46 | - method to return the IRQ number associated to a given GPIO |
| 47 | - flag saying whether calls to its methods may sleep |
| 48 | - optional debugfs dump method (showing extra state like pullup config) |
| 49 | - optional base number (will be automatically assigned if omitted) |
| 50 | - label for diagnostics and GPIOs mapping using platform data |
| 51 | |
| 52 | The code implementing a gpio_chip should support multiple instances of the |
| 53 | controller, possibly using the driver model. That code will configure each |
| 54 | gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare; |
| 55 | use gpiochip_remove() when it is unavoidable. |
| 56 | |
| 57 | Most often a gpio_chip is part of an instance-specific structure with state not |
| 58 | exposed by the GPIO interfaces, such as addressing, power management, and more. |
| 59 | Chips such as codecs will have complex non-GPIO state. |
| 60 | |
| 61 | Any debugfs dump method should normally ignore signals which haven't been |
| 62 | requested as GPIOs. They can use gpiochip_is_requested(), which returns either |
| 63 | NULL or the label associated with that GPIO when it was requested. |
| 64 | |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 65 | RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs |
| 66 | (like PM runtime) in its gpio_chip implementation (.get/.set and direction |
| 67 | control callbacks) if it is expected to call GPIO APIs from atomic context |
| 68 | on -RT (inside hard IRQ handlers and similar contexts). Normally this should |
| 69 | not be required. |
Linus Walleij | 99adc05 | 2014-01-22 15:00:55 +0100 | [diff] [blame] | 70 | |
| 71 | GPIO drivers providing IRQs |
| 72 | --------------------------- |
| 73 | It is custom that GPIO drivers (GPIO chips) are also providing interrupts, |
| 74 | most often cascaded off a parent interrupt controller, and in some special |
| 75 | cases the GPIO logic is melded with a SoC's primary interrupt controller. |
| 76 | |
| 77 | The IRQ portions of the GPIO block are implemented using an irqchip, using |
| 78 | the header <linux/irq.h>. So basically such a driver is utilizing two sub- |
| 79 | systems simultaneously: gpio and irq. |
| 80 | |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 81 | RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs |
| 82 | (like PM runtime) as part of its irq_chip implementation on -RT. |
| 83 | - spinlock_t should be replaced with raw_spinlock_t [1]. |
| 84 | - If sleepable APIs have to be used, these can be done from the .irq_bus_lock() |
| 85 | and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks |
| 86 | on an irqchip. Create the callbacks if needed [2]. |
| 87 | |
Linus Walleij | 90887db | 2014-04-09 14:36:32 +0200 | [diff] [blame] | 88 | GPIO irqchips usually fall in one of two categories: |
| 89 | |
| 90 | * CHAINED GPIO irqchips: these are usually the type that is embedded on |
| 91 | an SoC. This means that there is a fast IRQ handler for the GPIOs that |
| 92 | gets called in a chain from the parent IRQ handler, most typically the |
| 93 | system interrupt controller. This means the GPIO irqchip is registered |
| 94 | using irq_set_chained_handler() or the corresponding |
| 95 | gpiochip_set_chained_irqchip() helper function, and the GPIO irqchip |
| 96 | handler will be called immediately from the parent irqchip, while |
| 97 | holding the IRQs disabled. The GPIO irqchip will then end up calling |
| 98 | something like this sequence in its interrupt handler: |
| 99 | |
| 100 | static irqreturn_t tc3589x_gpio_irq(int irq, void *data) |
| 101 | chained_irq_enter(...); |
| 102 | generic_handle_irq(...); |
| 103 | chained_irq_exit(...); |
| 104 | |
| 105 | Chained GPIO irqchips typically can NOT set the .can_sleep flag on |
| 106 | struct gpio_chip, as everything happens directly in the callbacks. |
| 107 | |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 108 | RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT. |
| 109 | As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used |
| 110 | in chained IRQ handler. |
| 111 | if required (and if it can't be converted to the nested threaded GPIO irqchip) |
| 112 | - chained IRQ handler can be converted to generic irq handler and this way |
| 113 | it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT |
| 114 | (for example, see [3]). |
| 115 | Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled, |
| 116 | so IRQ core will complain if it will be called from IRQ handler wich is forced |
| 117 | thread. The "fake?" raw lock can be used to W/A this problem: |
| 118 | |
| 119 | raw_spinlock_t wa_lock; |
| 120 | static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) |
| 121 | unsigned long wa_lock_flags; |
| 122 | raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags); |
| 123 | generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit)); |
| 124 | raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags); |
| 125 | |
| 126 | * GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips", |
| 127 | but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is |
| 128 | performed by generic IRQ handler which is configured using request_irq(). |
| 129 | The GPIO irqchip will then end up calling something like this sequence in |
| 130 | its interrupt handler: |
| 131 | |
| 132 | static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id) |
| 133 | for each detected GPIO IRQ |
| 134 | generic_handle_irq(...); |
| 135 | |
| 136 | RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ |
| 137 | core will complain that generic_handle_irq() is called with IRQ enabled and |
| 138 | the same W/A as for "CHAINED GPIO irqchips" can be applied. |
| 139 | |
Linus Walleij | 4aa50b8 | 2015-10-27 11:13:18 +0100 | [diff] [blame] | 140 | * NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any |
| 141 | other GPIO irqchip residing on the other side of a sleeping bus. Of course |
| 142 | such drivers that need slow bus traffic to read out IRQ status and similar, |
| 143 | traffic which may in turn incur other IRQs to happen, cannot be handled |
| 144 | in a quick IRQ handler with IRQs disabled. Instead they need to spawn a |
| 145 | thread and then mask the parent IRQ line until the interrupt is handled |
| 146 | by the driver. The hallmark of this driver is to call something like |
| 147 | this in its interrupt handler: |
Linus Walleij | 90887db | 2014-04-09 14:36:32 +0200 | [diff] [blame] | 148 | |
| 149 | static irqreturn_t tc3589x_gpio_irq(int irq, void *data) |
| 150 | ... |
| 151 | handle_nested_irq(irq); |
| 152 | |
Linus Walleij | 4aa50b8 | 2015-10-27 11:13:18 +0100 | [diff] [blame] | 153 | The hallmark of threaded GPIO irqchips is that they set the .can_sleep |
| 154 | flag on struct gpio_chip to true, indicating that this chip may sleep |
| 155 | when accessing the GPIOs. |
Linus Walleij | 90887db | 2014-04-09 14:36:32 +0200 | [diff] [blame] | 156 | |
| 157 | To help out in handling the set-up and management of GPIO irqchips and the |
| 158 | associated irqdomain and resource allocation callbacks, the gpiolib has |
| 159 | some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig |
| 160 | symbol: |
| 161 | |
| 162 | * gpiochip_irqchip_add(): adds an irqchip to a gpiochip. It will pass |
| 163 | the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks |
| 164 | need to embed the gpio_chip in its state container and obtain a pointer |
| 165 | to the container using container_of(). |
| 166 | (See Documentation/driver-model/design-patterns.txt) |
| 167 | |
| 168 | * gpiochip_set_chained_irqchip(): sets up a chained irq handler for a |
| 169 | gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler |
| 170 | data. (Notice handler data, since the irqchip data is likely used by the |
Linus Walleij | 3f97d5fc | 2014-09-26 14:19:52 +0200 | [diff] [blame] | 171 | parent irqchip!) This is for the chained type of chip. This is also used |
Linus Walleij | 4aa50b8 | 2015-10-27 11:13:18 +0100 | [diff] [blame] | 172 | to set up a nested irqchip if NULL is passed as handler. |
Linus Walleij | 90887db | 2014-04-09 14:36:32 +0200 | [diff] [blame] | 173 | |
| 174 | To use the helpers please keep the following in mind: |
| 175 | |
| 176 | - Make sure to assign all relevant members of the struct gpio_chip so that |
| 177 | the irqchip can initialize. E.g. .dev and .can_sleep shall be set up |
| 178 | properly. |
| 179 | |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 180 | - Nominally set all handlers to handle_bad_irq() in the setup call and pass |
| 181 | handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is |
| 182 | expected for GPIO driver that irqchip .set_type() callback have to be called |
| 183 | before using/enabling GPIO IRQ. Then set the handler to handle_level_irq() |
| 184 | and/or handle_edge_irq() in the irqchip .set_type() callback depending on |
| 185 | what your controller supports. |
| 186 | |
Linus Walleij | 99adc05 | 2014-01-22 15:00:55 +0100 | [diff] [blame] | 187 | It is legal for any IRQ consumer to request an IRQ from any irqchip no matter |
| 188 | if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and |
| 189 | irq_chip are orthogonal, and offering their services independent of each |
| 190 | other. |
| 191 | |
| 192 | gpiod_to_irq() is just a convenience function to figure out the IRQ for a |
| 193 | certain GPIO line and should not be relied upon to have been called before |
| 194 | the IRQ is used. |
| 195 | |
| 196 | So always prepare the hardware and make it ready for action in respective |
| 197 | callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having |
| 198 | been called first. |
| 199 | |
| 200 | This orthogonality leads to ambiguities that we need to solve: if there is |
| 201 | competition inside the subsystem which side is using the resource (a certain |
| 202 | GPIO line and register for example) it needs to deny certain operations and |
| 203 | keep track of usage inside of the gpiolib subsystem. This is why the API |
| 204 | below exists. |
| 205 | |
| 206 | |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 207 | Locking IRQ usage |
| 208 | ----------------- |
| 209 | Input GPIOs can be used as IRQ signals. When this happens, a driver is requested |
| 210 | to mark the GPIO as being used as an IRQ: |
| 211 | |
Alexandre Courbot | e3a2e87 | 2014-10-23 17:27:07 +0900 | [diff] [blame] | 212 | int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 213 | |
| 214 | This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock |
| 215 | is released: |
| 216 | |
Alexandre Courbot | e3a2e87 | 2014-10-23 17:27:07 +0900 | [diff] [blame] | 217 | void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) |
Linus Walleij | 99adc05 | 2014-01-22 15:00:55 +0100 | [diff] [blame] | 218 | |
| 219 | When implementing an irqchip inside a GPIO driver, these two functions should |
| 220 | typically be called in the .startup() and .shutdown() callbacks from the |
| 221 | irqchip. |
Guenter Roeck | f7d4ad9 | 2014-07-22 08:01:01 -0700 | [diff] [blame] | 222 | |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 223 | Real-Time compliance for GPIO IRQ chips |
| 224 | --------------------------------------- |
| 225 | |
| 226 | Any provider of irqchips needs to be carefully tailored to support Real Time |
| 227 | preemption. It is desireable that all irqchips in the GPIO subsystem keep this |
| 228 | in mind and does the proper testing to assure they are real time-enabled. |
| 229 | So, pay attention on above " RT_FULL:" notes, please. |
| 230 | The following is a checklist to follow when preparing a driver for real |
| 231 | time-compliance: |
| 232 | |
| 233 | - ensure spinlock_t is not used as part irq_chip implementation; |
| 234 | - ensure that sleepable APIs are not used as part irq_chip implementation. |
| 235 | If sleepable APIs have to be used, these can be done from the .irq_bus_lock() |
| 236 | and .irq_bus_unlock() callbacks; |
| 237 | - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used |
| 238 | from chained IRQ handler; |
| 239 | - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and |
| 240 | apply corresponding W/A; |
| 241 | - Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq |
| 242 | handler if possible :) |
| 243 | - regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for |
| 244 | GPIO IRQ chip implementation; |
| 245 | - Test your driver with the appropriate in-kernel real time test cases for both |
| 246 | level and edge IRQs. |
| 247 | |
Guenter Roeck | f7d4ad9 | 2014-07-22 08:01:01 -0700 | [diff] [blame] | 248 | |
| 249 | Requesting self-owned GPIO pins |
| 250 | ------------------------------- |
| 251 | |
| 252 | Sometimes it is useful to allow a GPIO chip driver to request its own GPIO |
| 253 | descriptors through the gpiolib API. Using gpio_request() for this purpose |
| 254 | does not help since it pins the module to the kernel forever (it calls |
| 255 | try_module_get()). A GPIO driver can use the following functions instead |
| 256 | to request and free descriptors without being pinned to the kernel forever. |
| 257 | |
Alexandre Courbot | abdc08a | 2014-08-19 10:06:09 -0700 | [diff] [blame] | 258 | struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, |
| 259 | const char *label) |
Guenter Roeck | f7d4ad9 | 2014-07-22 08:01:01 -0700 | [diff] [blame] | 260 | |
| 261 | void gpiochip_free_own_desc(struct gpio_desc *desc) |
| 262 | |
| 263 | Descriptors requested with gpiochip_request_own_desc() must be released with |
| 264 | gpiochip_free_own_desc(). |
| 265 | |
| 266 | These functions must be used with care since they do not affect module use |
| 267 | count. Do not use the functions to request gpio descriptors not owned by the |
| 268 | calling driver. |
Grygorii Strashko | c307b00 | 2015-10-20 17:22:15 +0300 | [diff] [blame] | 269 | |
| 270 | [1] http://www.spinics.net/lists/linux-omap/msg120425.html |
| 271 | [2] https://lkml.org/lkml/2015/9/25/494 |
| 272 | [3] https://lkml.org/lkml/2015/9/25/495 |