| 1 | =====================
|
| 2 | GPIO Driver Interface
|
| 3 | =====================
|
| 4 |
|
| 5 | This document serves as a guide for writers of GPIO chip drivers.
|
| 6 |
|
| 7 | Each GPIO controller driver needs to include the following header, which defines
|
| 8 | the structures used to define a GPIO driver::
|
| 9 |
|
| 10 | #include <linux/gpio/driver.h>
|
| 11 |
|
| 12 |
|
| 13 | Internal Representation of GPIOs
|
| 14 | ================================
|
| 15 |
|
| 16 | A GPIO chip handles one or more GPIO lines. To be considered a GPIO chip, the
|
| 17 | lines must conform to the definition: General Purpose Input/Output. If the
|
| 18 | line is not general purpose, it is not GPIO and should not be handled by a
|
| 19 | GPIO chip. The use case is the indicative: certain lines in a system may be
|
| 20 | called GPIO but serve a very particular purpose thus not meeting the criteria
|
| 21 | of a general purpose I/O. On the other hand a LED driver line may be used as a
|
| 22 | GPIO and should therefore still be handled by a GPIO chip driver.
|
| 23 |
|
| 24 | Inside a GPIO driver, individual GPIO lines are identified by their hardware
|
| 25 | number, sometime also referred to as ``offset``, which is a unique number
|
| 26 | between 0 and n-1, n being the number of GPIOs managed by the chip.
|
| 27 |
|
| 28 | The hardware GPIO number should be something intuitive to the hardware, for
|
| 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
|
| 31 | use hardware offsets 0..31 for these, corresponding to bits 0..31 in the
|
| 32 | register.
|
| 33 |
|
| 34 | This number is purely internal: the hardware number of a particular GPIO
|
| 35 | line is never made visible outside of the driver.
|
| 36 |
|
| 37 | On top of this internal number, each GPIO line also needs to have a global
|
| 38 | number in the integer GPIO namespace so that it can be used with the legacy GPIO
|
| 39 | interface. Each chip must thus have a "base" number (which can be automatically
|
| 40 | assigned), and for each GPIO line the global number will be (base + hardware
|
| 41 | number). Although the integer representation is considered deprecated, it still
|
| 42 | has many users and thus needs to be maintained.
|
| 43 |
|
| 44 | So for example one platform could use global numbers 32-159 for GPIOs, with a
|
| 45 | controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
|
| 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
|
| 48 | numbers need not be contiguous; either of those platforms could also use numbers
|
| 49 | 2000-2063 to identify GPIO lines in a bank of I2C GPIO expanders.
|
| 50 |
|
| 51 |
|
| 52 | Controller Drivers: gpio_chip
|
| 53 | =============================
|
| 54 |
|
| 55 | In the gpiolib framework each GPIO controller is packaged as a "struct
|
| 56 | gpio_chip" (see <linux/gpio/driver.h> for its complete definition) with members
|
| 57 | common to each controller of that type, these should be assigned by the
|
| 58 | driver code:
|
| 59 |
|
| 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
|
| 69 |
|
| 70 | The code implementing a gpio_chip should support multiple instances of the
|
| 71 | controller, preferably using the driver model. That code will configure each
|
| 72 | gpio_chip and issue gpiochip_add_data() or devm_gpiochip_add_data(). Removing
|
| 73 | a GPIO controller should be rare; use gpiochip_remove() when it is unavoidable.
|
| 74 |
|
| 75 | Often a gpio_chip is part of an instance-specific structure with states not
|
| 76 | exposed by the GPIO interfaces, such as addressing, power management, and more.
|
| 77 | Chips such as audio codecs will have complex non-GPIO states.
|
| 78 |
|
| 79 | Any debugfs dump method should normally ignore lines which haven't been
|
| 80 | requested. They can use gpiochip_is_requested(), which returns either
|
| 81 | NULL or the label associated with that GPIO line when it was requested.
|
| 82 |
|
| 83 | Realtime considerations: the GPIO driver should not use spinlock_t or any
|
| 84 | sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set
|
| 85 | and direction control callbacks) if it is expected to call GPIO APIs from
|
| 86 | atomic context on realtime kernels (inside hard IRQ handlers and similar
|
| 87 | contexts). Normally this should not be required.
|
| 88 |
|
| 89 |
|
| 90 | GPIO level semantics
|
| 91 | --------------------
|
| 92 |
|
| 93 | The gpip_chip .get/set[_multiple]() line values are clamped to the boolean
|
| 94 | space [0, 1], low level or high level.
|
| 95 |
|
| 96 | Low and high values are defined as physical low on the line in/out to the
|
| 97 | connector such as a physical pad, pin or rail.
|
| 98 |
|
| 99 | The GPIO library has internal logic to handle lines that are active low, such
|
| 100 | as indicated by overstrike or #name in a schematic, and the driver should not
|
| 101 | try to second-guess the logic value of a line.
|
| 102 |
|
| 103 | The way GPIO values are handled by the consumers is that the library present
|
| 104 | the *logical* value to the consumer. A line is *asserted* if its *logical*
|
| 105 | value is 1, and *de-asserted* if its logical value is 0. If inversion is
|
| 106 | required, this is handled by gpiolib and configured using hardware descriptions
|
| 107 | such as device tree or ACPI that can clearly indicate if a line is active
|
| 108 | high or low.
|
| 109 |
|
| 110 | Since electronics commonly insert inverters as driving stages or protection
|
| 111 | buffers in front of a GPIO line it is necessary that this semantic is part
|
| 112 | of the hardware description, so that consumers such as kernel drivers need
|
| 113 | not worry about this, and can for example assert a RESET line tied to a GPIO
|
| 114 | pin by setting it to logic 1 even if it is physically active low.
|
| 115 |
|
| 116 |
|
| 117 | GPIO electrical configuration
|
| 118 | -----------------------------
|
| 119 |
|
| 120 | GPIO lines can be configured for several electrical modes of operation by using
|
| 121 | the .set_config() callback. Currently this API supports setting:
|
| 122 |
|
| 123 | - Debouncing
|
| 124 | - Single-ended modes (open drain/open source)
|
| 125 | - Pull up and pull down resistor enablement
|
| 126 |
|
| 127 | These settings are described below.
|
| 128 |
|
| 129 | The .set_config() callback uses the same enumerators and configuration
|
| 130 | semantics as the generic pin control drivers. This is not a coincidence: it is
|
| 131 | possible to assign the .set_config() to the function gpiochip_generic_config()
|
| 132 | which will result in pinctrl_gpio_set_config() being called and eventually
|
| 133 | ending up in the pin control back-end "behind" the GPIO controller, usually
|
| 134 | closer to the actual pins. This way the pin controller can manage the below
|
| 135 | listed GPIO configurations.
|
| 136 |
|
| 137 | If a pin controller back-end is used, the GPIO controller or hardware
|
| 138 | description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin
|
| 139 | numbers on the pin controller so they can properly cross-reference each other.
|
| 140 |
|
| 141 |
|
| 142 | GPIO lines with debounce support
|
| 143 | --------------------------------
|
| 144 |
|
| 145 | Debouncing is a configuration set to a pin indicating that it is connected to
|
| 146 | a mechanical switch or button, or similar that may bounce. Bouncing means the
|
| 147 | line is pulled high/low quickly at very short intervals for mechanical
|
| 148 | reasons. This can result in the value being unstable or irqs firing repeatedly
|
| 149 | unless the line is debounced.
|
| 150 |
|
| 151 | Debouncing in practice involves setting up a timer when something happens on
|
| 152 | the line, wait a little while and then sample the line again, so see if it
|
| 153 | still has the same value (low or high). This could also be repeated by a clever
|
| 154 | state machine, waiting for a line to become stable. In either case, it sets
|
| 155 | a certain number of milliseconds for debouncing, or just "on/off" if that time
|
| 156 | is not configurable.
|
| 157 |
|
| 158 |
|
| 159 | GPIO lines with open drain/source support
|
| 160 | -----------------------------------------
|
| 161 |
|
| 162 | Open drain (CMOS) or open collector (TTL) means the line is not actively driven
|
| 163 | high: instead you provide the drain/collector as output, so when the transistor
|
| 164 | is not open, it will present a high-impedance (tristate) to the external rail::
|
| 165 |
|
| 166 |
|
| 167 | CMOS CONFIGURATION TTL CONFIGURATION
|
| 168 |
|
| 169 | ||--- out +--- out
|
| 170 | in ----|| |/
|
| 171 | ||--+ in ----|
|
| 172 | | |\
|
| 173 | GND GND
|
| 174 |
|
| 175 | This configuration is normally used as a way to achieve one of two things:
|
| 176 |
|
| 177 | - Level-shifting: to reach a logical level higher than that of the silicon
|
| 178 | where the output resides.
|
| 179 |
|
| 180 | - Inverse wire-OR on an I/O line, for example a GPIO line, making it possible
|
| 181 | for any driving stage on the line to drive it low even if any other output
|
| 182 | to the same line is simultaneously driving it high. A special case of this
|
| 183 | is driving the SCL and SDA lines of an I2C bus, which is by definition a
|
| 184 | wire-OR bus.
|
| 185 |
|
| 186 | Both use cases require that the line be equipped with a pull-up resistor. This
|
| 187 | resistor will make the line tend to high level unless one of the transistors on
|
| 188 | the rail actively pulls it down.
|
| 189 |
|
| 190 | The level on the line will go as high as the VDD on the pull-up resistor, which
|
| 191 | may be higher than the level supported by the transistor, achieving a
|
| 192 | level-shift to the higher VDD.
|
| 193 |
|
| 194 | Integrated electronics often have an output driver stage in the form of a CMOS
|
| 195 | "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
|
| 196 | the line high and one of them drives the line low. This is called a push-pull
|
| 197 | output. The "totem-pole" looks like so::
|
| 198 |
|
| 199 | VDD
|
| 200 | |
|
| 201 | OD ||--+
|
| 202 | +--/ ---o|| P-MOS-FET
|
| 203 | | ||--+
|
| 204 | IN --+ +----- out
|
| 205 | | ||--+
|
| 206 | +--/ ----|| N-MOS-FET
|
| 207 | OS ||--+
|
| 208 | |
|
| 209 | GND
|
| 210 |
|
| 211 | The desired output signal (e.g. coming directly from some GPIO output register)
|
| 212 | arrives at IN. The switches named "OD" and "OS" are normally closed, creating
|
| 213 | a push-pull circuit.
|
| 214 |
|
| 215 | Consider the little "switches" named "OD" and "OS" that enable/disable the
|
| 216 | P-MOS or N-MOS transistor right after the split of the input. As you can see,
|
| 217 | either transistor will go totally numb if this switch is open. The totem-pole
|
| 218 | is then halved and give high impedance instead of actively driving the line
|
| 219 | high or low respectively. That is usually how software-controlled open
|
| 220 | drain/source works.
|
| 221 |
|
| 222 | Some GPIO hardware come in open drain / open source configuration. Some are
|
| 223 | hard-wired lines that will only support open drain or open source no matter
|
| 224 | what: there is only one transistor there. Some are software-configurable:
|
| 225 | by flipping a bit in a register the output can be configured as open drain
|
| 226 | or open source, in practice by flicking open the switches labeled "OD" and "OS"
|
| 227 | in the drawing above.
|
| 228 |
|
| 229 | By disabling the P-MOS transistor, the output can be driven between GND and
|
| 230 | high impedance (open drain), and by disabling the N-MOS transistor, the output
|
| 231 | can be driven between VDD and high impedance (open source). In the first case,
|
| 232 | a pull-up resistor is needed on the outgoing rail to complete the circuit, and
|
| 233 | in the second case, a pull-down resistor is needed on the rail.
|
| 234 |
|
| 235 | Hardware that supports open drain or open source or both, can implement a
|
| 236 | special callback in the gpio_chip: .set_config() that takes a generic
|
| 237 | pinconf packed value telling whether to configure the line as open drain,
|
| 238 | open source or push-pull. This will happen in response to the
|
| 239 | GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag set in the machine file, or coming
|
| 240 | from other hardware descriptions.
|
| 241 |
|
| 242 | If this state can not be configured in hardware, i.e. if the GPIO hardware does
|
| 243 | not support open drain/open source in hardware, the GPIO library will instead
|
| 244 | use a trick: when a line is set as output, if the line is flagged as open
|
| 245 | drain, and the IN output value is low, it will be driven low as usual. But
|
| 246 | if the IN output value is set to high, it will instead *NOT* be driven high,
|
| 247 | instead it will be switched to input, as input mode is an equivalent to
|
| 248 | high impedance, thus achieving an "open drain emulation" of sorts: electrically
|
| 249 | the behaviour will be identical, with the exception of possible hardware glitches
|
| 250 | when switching the mode of the line.
|
| 251 |
|
| 252 | For open source configuration the same principle is used, just that instead
|
| 253 | of actively driving the line low, it is set to input.
|
| 254 |
|
| 255 |
|
| 256 | GPIO lines with pull up/down resistor support
|
| 257 | ---------------------------------------------
|
| 258 |
|
| 259 | A GPIO line can support pull-up/down using the .set_config() callback. This
|
| 260 | means that a pull up or pull-down resistor is available on the output of the
|
| 261 | GPIO line, and this resistor is software controlled.
|
| 262 |
|
| 263 | In discrete designs, a pull-up or pull-down resistor is simply soldered on
|
| 264 | the circuit board. This is not something we deal with or model in software. The
|
| 265 | most you will think about these lines is that they will very likely be
|
| 266 | configured as open drain or open source (see the section above).
|
| 267 |
|
| 268 | The .set_config() callback can only turn pull up or down on and off, and will
|
| 269 | no have any semantic knowledge about the resistance used. It will only say
|
| 270 | switch a bit in a register enabling or disabling pull-up or pull-down.
|
| 271 |
|
| 272 | If the GPIO line supports shunting in different resistance values for the
|
| 273 | pull-up or pull-down resistor, the GPIO chip callback .set_config() will not
|
| 274 | suffice. For these complex use cases, a combined GPIO chip and pin controller
|
| 275 | need to be implemented, as the pin config interface of a pin controller
|
| 276 | supports more versatile control over electrical properties and can handle
|
| 277 | different pull-up or pull-down resistance values.
|
| 278 |
|
| 279 |
|
| 280 | GPIO drivers providing IRQs
|
| 281 | ===========================
|
| 282 |
|
| 283 | It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
|
| 284 | most often cascaded off a parent interrupt controller, and in some special
|
| 285 | cases the GPIO logic is melded with a SoC's primary interrupt controller.
|
| 286 |
|
| 287 | The IRQ portions of the GPIO block are implemented using an irq_chip, using
|
| 288 | the header <linux/irq.h>. So this combined driver is utilizing two sub-
|
| 289 | systems simultaneously: gpio and irq.
|
| 290 |
|
| 291 | It is legal for any IRQ consumer to request an IRQ from any irqchip even if it
|
| 292 | is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
|
| 293 | irq_chip are orthogonal, and offering their services independent of each
|
| 294 | other.
|
| 295 |
|
| 296 | gpiod_to_irq() is just a convenience function to figure out the IRQ for a
|
| 297 | certain GPIO line and should not be relied upon to have been called before
|
| 298 | the IRQ is used.
|
| 299 |
|
| 300 | Always prepare the hardware and make it ready for action in respective
|
| 301 | callbacks from the GPIO and irq_chip APIs. Do not rely on gpiod_to_irq() having
|
| 302 | been called first.
|
| 303 |
|
| 304 | We can divide GPIO irqchips in two broad categories:
|
| 305 |
|
| 306 | - CASCADED INTERRUPT CHIPS: this means that the GPIO chip has one common
|
| 307 | interrupt output line, which is triggered by any enabled GPIO line on that
|
| 308 | chip. The interrupt output line will then be routed to an parent interrupt
|
| 309 | controller one level up, in the most simple case the systems primary
|
| 310 | interrupt controller. This is modeled by an irqchip that will inspect bits
|
| 311 | inside the GPIO controller to figure out which line fired it. The irqchip
|
| 312 | part of the driver needs to inspect registers to figure this out and it
|
| 313 | will likely also need to acknowledge that it is handling the interrupt
|
| 314 | by clearing some bit (sometime implicitly, by just reading a status
|
| 315 | register) and it will often need to set up the configuration such as
|
| 316 | edge sensitivity (rising or falling edge, or high/low level interrupt for
|
| 317 | example).
|
| 318 |
|
| 319 | - HIERARCHICAL INTERRUPT CHIPS: this means that each GPIO line has a dedicated
|
| 320 | irq line to a parent interrupt controller one level up. There is no need
|
| 321 | to inquire the GPIO hardware to figure out which line has fired, but it
|
| 322 | may still be necessary to acknowledge the interrupt and set up configuration
|
| 323 | such as edge sensitivity.
|
| 324 |
|
| 325 | Realtime considerations: a realtime compliant GPIO driver should not use
|
| 326 | spinlock_t or any sleepable APIs (like PM runtime) as part of its irqchip
|
| 327 | implementation.
|
| 328 |
|
| 329 | - spinlock_t should be replaced with raw_spinlock_t.[1]
|
| 330 | - If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
|
| 331 | and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks
|
| 332 | on an irqchip. Create the callbacks if needed.[2]
|
| 333 |
|
| 334 |
|
| 335 | Cascaded GPIO irqchips
|
| 336 | ----------------------
|
| 337 |
|
| 338 | Cascaded GPIO irqchips usually fall in one of three categories:
|
| 339 |
|
| 340 | - CHAINED CASCADED GPIO IRQCHIPS: these are usually the type that is embedded on
|
| 341 | an SoC. This means that there is a fast IRQ flow handler for the GPIOs that
|
| 342 | gets called in a chain from the parent IRQ handler, most typically the
|
| 343 | system interrupt controller. This means that the GPIO irqchip handler will
|
| 344 | be called immediately from the parent irqchip, while holding the IRQs
|
| 345 | disabled. The GPIO irqchip will then end up calling something like this
|
| 346 | sequence in its interrupt handler::
|
| 347 |
|
| 348 | static irqreturn_t foo_gpio_irq(int irq, void *data)
|
| 349 | chained_irq_enter(...);
|
| 350 | generic_handle_irq(...);
|
| 351 | chained_irq_exit(...);
|
| 352 |
|
| 353 | Chained GPIO irqchips typically can NOT set the .can_sleep flag on
|
| 354 | struct gpio_chip, as everything happens directly in the callbacks: no
|
| 355 | slow bus traffic like I2C can be used.
|
| 356 |
|
| 357 | Realtime considerations: Note that chained IRQ handlers will not be forced
|
| 358 | threaded on -RT. As a result, spinlock_t or any sleepable APIs (like PM
|
| 359 | runtime) can't be used in a chained IRQ handler.
|
| 360 |
|
| 361 | If required (and if it can't be converted to the nested threaded GPIO irqchip,
|
| 362 | see below) a chained IRQ handler can be converted to generic irq handler and
|
| 363 | this way it will become a threaded IRQ handler on -RT and a hard IRQ handler
|
| 364 | on non-RT (for example, see [3]).
|
| 365 |
|
| 366 | The generic_handle_irq() is expected to be called with IRQ disabled,
|
| 367 | so the IRQ core will complain if it is called from an IRQ handler which is
|
| 368 | forced to a thread. The "fake?" raw lock can be used to work around this
|
| 369 | problem::
|
| 370 |
|
| 371 | raw_spinlock_t wa_lock;
|
| 372 | static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
|
| 373 | unsigned long wa_lock_flags;
|
| 374 | raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
|
| 375 | generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));
|
| 376 | raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
|
| 377 |
|
| 378 | - GENERIC CHAINED GPIO IRQCHIPS: these are the same as "CHAINED GPIO irqchips",
|
| 379 | but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
|
| 380 | performed by generic IRQ handler which is configured using request_irq().
|
| 381 | The GPIO irqchip will then end up calling something like this sequence in
|
| 382 | its interrupt handler::
|
| 383 |
|
| 384 | static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
|
| 385 | for each detected GPIO IRQ
|
| 386 | generic_handle_irq(...);
|
| 387 |
|
| 388 | Realtime considerations: this kind of handlers will be forced threaded on -RT,
|
| 389 | and as result the IRQ core will complain that generic_handle_irq() is called
|
| 390 | with IRQ enabled and the same work-around as for "CHAINED GPIO irqchips" can
|
| 391 | be applied.
|
| 392 |
|
| 393 | - NESTED THREADED GPIO IRQCHIPS: these are off-chip GPIO expanders and any
|
| 394 | other GPIO irqchip residing on the other side of a sleeping bus such as I2C
|
| 395 | or SPI.
|
| 396 |
|
| 397 | Of course such drivers that need slow bus traffic to read out IRQ status and
|
| 398 | similar, traffic which may in turn incur other IRQs to happen, cannot be
|
| 399 | handled in a quick IRQ handler with IRQs disabled. Instead they need to spawn
|
| 400 | a thread and then mask the parent IRQ line until the interrupt is handled
|
| 401 | by the driver. The hallmark of this driver is to call something like
|
| 402 | this in its interrupt handler::
|
| 403 |
|
| 404 | static irqreturn_t foo_gpio_irq(int irq, void *data)
|
| 405 | ...
|
| 406 | handle_nested_irq(irq);
|
| 407 |
|
| 408 | The hallmark of threaded GPIO irqchips is that they set the .can_sleep
|
| 409 | flag on struct gpio_chip to true, indicating that this chip may sleep
|
| 410 | when accessing the GPIOs.
|
| 411 |
|
| 412 | These kinds of irqchips are inherently realtime tolerant as they are
|
| 413 | already set up to handle sleeping contexts.
|
| 414 |
|
| 415 |
|
| 416 | Infrastructure helpers for GPIO irqchips
|
| 417 | ----------------------------------------
|
| 418 |
|
| 419 | To help out in handling the set-up and management of GPIO irqchips and the
|
| 420 | associated irqdomain and resource allocation callbacks. These are activated
|
| 421 | by selecting the Kconfig symbol GPIOLIB_IRQCHIP. If the symbol
|
| 422 | IRQ_DOMAIN_HIERARCHY is also selected, hierarchical helpers will also be
|
| 423 | provided. A big portion of overhead code will be managed by gpiolib,
|
| 424 | under the assumption that your interrupts are 1-to-1-mapped to the
|
| 425 | GPIO line index:
|
| 426 |
|
| 427 | .. csv-table::
|
| 428 | :header: GPIO line offset, Hardware IRQ
|
| 429 |
|
| 430 | 0,0
|
| 431 | 1,1
|
| 432 | 2,2
|
| 433 | ...,...
|
| 434 | ngpio-1, ngpio-1
|
| 435 |
|
| 436 |
|
| 437 | If some GPIO lines do not have corresponding IRQs, the bitmask valid_mask
|
| 438 | and the flag need_valid_mask in gpio_irq_chip can be used to mask off some
|
| 439 | lines as invalid for associating with IRQs.
|
| 440 |
|
| 441 | The preferred way to set up the helpers is to fill in the
|
| 442 | struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip.
|
| 443 | If you do this, the additional irq_chip will be set up by gpiolib at the
|
| 444 | same time as setting up the rest of the GPIO functionality. The following
|
| 445 | is a typical example of a chained cascaded interrupt handler using
|
| 446 | the gpio_irq_chip. Note how the mask/unmask (or disable/enable) functions
|
| 447 | call into the core gpiolib code:
|
| 448 |
|
| 449 | .. code-block:: c
|
| 450 |
|
| 451 | /* Typical state container */
|
| 452 | struct my_gpio {
|
| 453 | struct gpio_chip gc;
|
| 454 | };
|
| 455 |
|
| 456 | static void my_gpio_mask_irq(struct irq_data *d)
|
| 457 | {
|
| 458 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 459 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 460 |
|
| 461 | /*
|
| 462 | * Perform any necessary action to mask the interrupt,
|
| 463 | * and then call into the core code to synchronise the
|
| 464 | * state.
|
| 465 | */
|
| 466 |
|
| 467 | gpiochip_disable_irq(gc, hwirq);
|
| 468 | }
|
| 469 |
|
| 470 | static void my_gpio_unmask_irq(struct irq_data *d)
|
| 471 | {
|
| 472 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 473 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 474 |
|
| 475 | gpiochip_enable_irq(gc, hwirq);
|
| 476 |
|
| 477 | /*
|
| 478 | * Perform any necessary action to unmask the interrupt,
|
| 479 | * after having called into the core code to synchronise
|
| 480 | * the state.
|
| 481 | */
|
| 482 | }
|
| 483 |
|
| 484 | /*
|
| 485 | * Statically populate the irqchip. Note that it is made const
|
| 486 | * (further indicated by the IRQCHIP_IMMUTABLE flag), and that
|
| 487 | * the GPIOCHIP_IRQ_RESOURCE_HELPER macro adds some extra
|
| 488 | * callbacks to the structure.
|
| 489 | */
|
| 490 | static const struct irq_chip my_gpio_irq_chip = {
|
| 491 | .name = "my_gpio_irq",
|
| 492 | .irq_ack = my_gpio_ack_irq,
|
| 493 | .irq_mask = my_gpio_mask_irq,
|
| 494 | .irq_unmask = my_gpio_unmask_irq,
|
| 495 | .irq_set_type = my_gpio_set_irq_type,
|
| 496 | .flags = IRQCHIP_IMMUTABLE,
|
| 497 | /* Provide the gpio resource callbacks */
|
| 498 | GPIOCHIP_IRQ_RESOURCE_HELPERS,
|
| 499 | };
|
| 500 |
|
| 501 | int irq; /* from platform etc */
|
| 502 | struct my_gpio *g;
|
| 503 | struct gpio_irq_chip *girq;
|
| 504 |
|
| 505 | /* Get a pointer to the gpio_irq_chip */
|
| 506 | girq = &g->gc.irq;
|
| 507 | gpio_irq_chip_set_chip(girq, &my_gpio_irq_chip);
|
| 508 | girq->parent_handler = ftgpio_gpio_irq_handler;
|
| 509 | girq->num_parents = 1;
|
| 510 | girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
|
| 511 | GFP_KERNEL);
|
| 512 | if (!girq->parents)
|
| 513 | return -ENOMEM;
|
| 514 | girq->default_type = IRQ_TYPE_NONE;
|
| 515 | girq->handler = handle_bad_irq;
|
| 516 | girq->parents[0] = irq;
|
| 517 |
|
| 518 | return devm_gpiochip_add_data(dev, &g->gc, g);
|
| 519 |
|
| 520 | The helper supports using threaded interrupts as well. Then you just request
|
| 521 | the interrupt separately and go with it:
|
| 522 |
|
| 523 | .. code-block:: c
|
| 524 |
|
| 525 | /* Typical state container */
|
| 526 | struct my_gpio {
|
| 527 | struct gpio_chip gc;
|
| 528 | };
|
| 529 |
|
| 530 | static void my_gpio_mask_irq(struct irq_data *d)
|
| 531 | {
|
| 532 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 533 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 534 |
|
| 535 | /*
|
| 536 | * Perform any necessary action to mask the interrupt,
|
| 537 | * and then call into the core code to synchronise the
|
| 538 | * state.
|
| 539 | */
|
| 540 |
|
| 541 | gpiochip_disable_irq(gc, hwirq);
|
| 542 | }
|
| 543 |
|
| 544 | static void my_gpio_unmask_irq(struct irq_data *d)
|
| 545 | {
|
| 546 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 547 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 548 |
|
| 549 | gpiochip_enable_irq(gc, hwirq);
|
| 550 |
|
| 551 | /*
|
| 552 | * Perform any necessary action to unmask the interrupt,
|
| 553 | * after having called into the core code to synchronise
|
| 554 | * the state.
|
| 555 | */
|
| 556 | }
|
| 557 |
|
| 558 | /*
|
| 559 | * Statically populate the irqchip. Note that it is made const
|
| 560 | * (further indicated by the IRQCHIP_IMMUTABLE flag), and that
|
| 561 | * the GPIOCHIP_IRQ_RESOURCE_HELPER macro adds some extra
|
| 562 | * callbacks to the structure.
|
| 563 | */
|
| 564 | static const struct irq_chip my_gpio_irq_chip = {
|
| 565 | .name = "my_gpio_irq",
|
| 566 | .irq_ack = my_gpio_ack_irq,
|
| 567 | .irq_mask = my_gpio_mask_irq,
|
| 568 | .irq_unmask = my_gpio_unmask_irq,
|
| 569 | .irq_set_type = my_gpio_set_irq_type,
|
| 570 | .flags = IRQCHIP_IMMUTABLE,
|
| 571 | /* Provide the gpio resource callbacks */
|
| 572 | GPIOCHIP_IRQ_RESOURCE_HELPERS,
|
| 573 | };
|
| 574 |
|
| 575 | int irq; /* from platform etc */
|
| 576 | struct my_gpio *g;
|
| 577 | struct gpio_irq_chip *girq;
|
| 578 |
|
| 579 | ret = devm_request_threaded_irq(dev, irq, NULL, irq_thread_fn,
|
| 580 | IRQF_ONESHOT, "my-chip", g);
|
| 581 | if (ret < 0)
|
| 582 | return ret;
|
| 583 |
|
| 584 | /* Get a pointer to the gpio_irq_chip */
|
| 585 | girq = &g->gc.irq;
|
| 586 | gpio_irq_chip_set_chip(girq, &my_gpio_irq_chip);
|
| 587 | /* This will let us handle the parent IRQ in the driver */
|
| 588 | girq->parent_handler = NULL;
|
| 589 | girq->num_parents = 0;
|
| 590 | girq->parents = NULL;
|
| 591 | girq->default_type = IRQ_TYPE_NONE;
|
| 592 | girq->handler = handle_bad_irq;
|
| 593 |
|
| 594 | return devm_gpiochip_add_data(dev, &g->gc, g);
|
| 595 |
|
| 596 | The helper supports using hierarchical interrupt controllers as well.
|
| 597 | In this case the typical set-up will look like this:
|
| 598 |
|
| 599 | .. code-block:: c
|
| 600 |
|
| 601 | /* Typical state container with dynamic irqchip */
|
| 602 | struct my_gpio {
|
| 603 | struct gpio_chip gc;
|
| 604 | struct fwnode_handle *fwnode;
|
| 605 | };
|
| 606 |
|
| 607 | static void my_gpio_mask_irq(struct irq_data *d)
|
| 608 | {
|
| 609 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 610 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 611 |
|
| 612 | /*
|
| 613 | * Perform any necessary action to mask the interrupt,
|
| 614 | * and then call into the core code to synchronise the
|
| 615 | * state.
|
| 616 | */
|
| 617 |
|
| 618 | gpiochip_disable_irq(gc, hwirq);
|
| 619 | irq_mask_mask_parent(d);
|
| 620 | }
|
| 621 |
|
| 622 | static void my_gpio_unmask_irq(struct irq_data *d)
|
| 623 | {
|
| 624 | struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
|
| 625 | irq_hw_number_t hwirq = irqd_to_hwirq(d);
|
| 626 |
|
| 627 | gpiochip_enable_irq(gc, hwirq);
|
| 628 |
|
| 629 | /*
|
| 630 | * Perform any necessary action to unmask the interrupt,
|
| 631 | * after having called into the core code to synchronise
|
| 632 | * the state.
|
| 633 | */
|
| 634 |
|
| 635 | irq_mask_unmask_parent(d);
|
| 636 | }
|
| 637 |
|
| 638 | /*
|
| 639 | * Statically populate the irqchip. Note that it is made const
|
| 640 | * (further indicated by the IRQCHIP_IMMUTABLE flag), and that
|
| 641 | * the GPIOCHIP_IRQ_RESOURCE_HELPER macro adds some extra
|
| 642 | * callbacks to the structure.
|
| 643 | */
|
| 644 | static const struct irq_chip my_gpio_irq_chip = {
|
| 645 | .name = "my_gpio_irq",
|
| 646 | .irq_ack = my_gpio_ack_irq,
|
| 647 | .irq_mask = my_gpio_mask_irq,
|
| 648 | .irq_unmask = my_gpio_unmask_irq,
|
| 649 | .irq_set_type = my_gpio_set_irq_type,
|
| 650 | .flags = IRQCHIP_IMMUTABLE,
|
| 651 | /* Provide the gpio resource callbacks */
|
| 652 | GPIOCHIP_IRQ_RESOURCE_HELPERS,
|
| 653 | };
|
| 654 |
|
| 655 | struct my_gpio *g;
|
| 656 | struct gpio_irq_chip *girq;
|
| 657 |
|
| 658 | /* Get a pointer to the gpio_irq_chip */
|
| 659 | girq = &g->gc.irq;
|
| 660 | gpio_irq_chip_set_chip(girq, &my_gpio_irq_chip);
|
| 661 | girq->default_type = IRQ_TYPE_NONE;
|
| 662 | girq->handler = handle_bad_irq;
|
| 663 | girq->fwnode = g->fwnode;
|
| 664 | girq->parent_domain = parent;
|
| 665 | girq->child_to_parent_hwirq = my_gpio_child_to_parent_hwirq;
|
| 666 |
|
| 667 | return devm_gpiochip_add_data(dev, &g->gc, g);
|
| 668 |
|
| 669 | As you can see pretty similar, but you do not supply a parent handler for
|
| 670 | the IRQ, instead a parent irqdomain, an fwnode for the hardware and
|
| 671 | a function .child_to_parent_hwirq() that has the purpose of looking up
|
| 672 | the parent hardware irq from a child (i.e. this gpio chip) hardware irq.
|
| 673 | As always it is good to look at examples in the kernel tree for advice
|
| 674 | on how to find the required pieces.
|
| 675 |
|
| 676 | If there is a need to exclude certain GPIO lines from the IRQ domain handled by
|
| 677 | these helpers, we can set .irq.need_valid_mask of the gpiochip before
|
| 678 | devm_gpiochip_add_data() or gpiochip_add_data() is called. This allocates an
|
| 679 | .irq.valid_mask with as many bits set as there are GPIO lines in the chip, each
|
| 680 | bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits
|
| 681 | from this mask. The mask can be filled in the init_valid_mask() callback
|
| 682 | that is part of the struct gpio_irq_chip.
|
| 683 |
|
| 684 | To use the helpers please keep the following in mind:
|
| 685 |
|
| 686 | - Make sure to assign all relevant members of the struct gpio_chip so that
|
| 687 | the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
|
| 688 | properly.
|
| 689 |
|
| 690 | - Nominally set gpio_irq_chip.handler to handle_bad_irq. Then, if your irqchip
|
| 691 | is cascaded, set the handler to handle_level_irq() and/or handle_edge_irq()
|
| 692 | in the irqchip .set_type() callback depending on what your controller
|
| 693 | supports and what is requested by the consumer.
|
| 694 |
|
| 695 |
|
| 696 | Locking IRQ usage
|
| 697 | -----------------
|
| 698 |
|
| 699 | Since GPIO and irq_chip are orthogonal, we can get conflicts between different
|
| 700 | use cases. For example a GPIO line used for IRQs should be an input line,
|
| 701 | it does not make sense to fire interrupts on an output GPIO.
|
| 702 |
|
| 703 | If there is competition inside the subsystem which side is using the
|
| 704 | resource (a certain GPIO line and register for example) it needs to deny
|
| 705 | certain operations and keep track of usage inside of the gpiolib subsystem.
|
| 706 |
|
| 707 | Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
|
| 708 | to mark the GPIO as being used as an IRQ::
|
| 709 |
|
| 710 | int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
| 711 |
|
| 712 | This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
|
| 713 | is released::
|
| 714 |
|
| 715 | void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
|
| 716 |
|
| 717 | When implementing an irqchip inside a GPIO driver, these two functions should
|
| 718 | typically be called in the .startup() and .shutdown() callbacks from the
|
| 719 | irqchip.
|
| 720 |
|
| 721 | When using the gpiolib irqchip helpers, these callbacks are automatically
|
| 722 | assigned.
|
| 723 |
|
| 724 |
|
| 725 | Disabling and enabling IRQs
|
| 726 | ---------------------------
|
| 727 |
|
| 728 | In some (fringe) use cases, a driver may be using a GPIO line as input for IRQs,
|
| 729 | but occasionally switch that line over to drive output and then back to being
|
| 730 | an input with interrupts again. This happens on things like CEC (Consumer
|
| 731 | Electronics Control).
|
| 732 |
|
| 733 | When a GPIO is used as an IRQ signal, then gpiolib also needs to know if
|
| 734 | the IRQ is enabled or disabled. In order to inform gpiolib about this,
|
| 735 | the irqchip driver should call::
|
| 736 |
|
| 737 | void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset)
|
| 738 |
|
| 739 | This allows drivers to drive the GPIO as an output while the IRQ is
|
| 740 | disabled. When the IRQ is enabled again, a driver should call::
|
| 741 |
|
| 742 | void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset)
|
| 743 |
|
| 744 | When implementing an irqchip inside a GPIO driver, these two functions should
|
| 745 | typically be called in the .irq_disable() and .irq_enable() callbacks from the
|
| 746 | irqchip.
|
| 747 |
|
| 748 | When IRQCHIP_IMMUTABLE is not advertised by the irqchip, these callbacks
|
| 749 | are automatically assigned. This behaviour is deprecated and on its way
|
| 750 | to be removed from the kernel.
|
| 751 |
|
| 752 |
|
| 753 | Real-Time compliance for GPIO IRQ chips
|
| 754 | ---------------------------------------
|
| 755 |
|
| 756 | Any provider of irqchips needs to be carefully tailored to support Real-Time
|
| 757 | preemption. It is desirable that all irqchips in the GPIO subsystem keep this
|
| 758 | in mind and do the proper testing to assure they are real time-enabled.
|
| 759 |
|
| 760 | So, pay attention on above realtime considerations in the documentation.
|
| 761 |
|
| 762 | The following is a checklist to follow when preparing a driver for real-time
|
| 763 | compliance:
|
| 764 |
|
| 765 | - ensure spinlock_t is not used as part irq_chip implementation
|
| 766 | - ensure that sleepable APIs are not used as part irq_chip implementation
|
| 767 | If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
|
| 768 | and .irq_bus_unlock() callbacks
|
| 769 | - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
|
| 770 | from the chained IRQ handler
|
| 771 | - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
|
| 772 | apply corresponding work-around
|
| 773 | - Chained GPIO irqchips: get rid of the chained IRQ handler and use generic irq
|
| 774 | handler if possible
|
| 775 | - regmap_mmio: it is possible to disable internal locking in regmap by setting
|
| 776 | .disable_locking and handling the locking in the GPIO driver
|
| 777 | - Test your driver with the appropriate in-kernel real-time test cases for both
|
| 778 | level and edge IRQs
|
| 779 |
|
| 780 | * [1] https://lore.kernel.org/r/[email protected]/
|
| 781 | * [2] https://lore.kernel.org/r/[email protected]
|
| 782 | * [3] https://lore.kernel.org/r/[email protected]
|
| 783 |
|
| 784 |
|
| 785 | Requesting self-owned GPIO pins
|
| 786 | ===============================
|
| 787 |
|
| 788 | Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
|
| 789 | descriptors through the gpiolib API. A GPIO driver can use the following
|
| 790 | functions to request and free descriptors::
|
| 791 |
|
| 792 | struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
|
| 793 | u16 hwnum,
|
| 794 | const char *label,
|
| 795 | enum gpiod_flags flags)
|
| 796 |
|
| 797 | void gpiochip_free_own_desc(struct gpio_desc *desc)
|
| 798 |
|
| 799 | Descriptors requested with gpiochip_request_own_desc() must be released with
|
| 800 | gpiochip_free_own_desc().
|
| 801 |
|
| 802 | These functions must be used with care since they do not affect module use
|
| 803 | count. Do not use the functions to request gpio descriptors not owned by the
|
| 804 | calling driver.
|