1===================== 2GPIO Driver Interface 3===================== 4 5This document serves as a guide for writers of GPIO chip drivers. 6 7Each GPIO controller driver needs to include the following header, which defines 8the structures used to define a GPIO driver:: 9 10 #include <linux/gpio/driver.h> 11 12 13Internal Representation of GPIOs 14================================ 15 16A GPIO chip handles one or more GPIO lines. To be considered a GPIO chip, the 17lines must conform to the definition: General Purpose Input/Output. If the 18line is not general purpose, it is not GPIO and should not be handled by a 19GPIO chip. The use case is the indicative: certain lines in a system may be 20called GPIO but serve a very particular purpose thus not meeting the criteria 21of a general purpose I/O. On the other hand a LED driver line may be used as a 22GPIO and should therefore still be handled by a GPIO chip driver. 23 24Inside a GPIO driver, individual GPIO lines are identified by their hardware 25number, sometime also referred to as ``offset``, which is a unique number 26between 0 and n-1, n being the number of GPIOs managed by the chip. 27 28The hardware GPIO number should be something intuitive to the hardware, for 29example if a system uses a memory-mapped set of I/O-registers where 32 GPIO 30lines are handled by one bit per line in a 32-bit register, it makes sense to 31use hardware offsets 0..31 for these, corresponding to bits 0..31 in the 32register. 33 34This number is purely internal: the hardware number of a particular GPIO 35line is never made visible outside of the driver. 36 37On top of this internal number, each GPIO line also needs to have a global 38number in the integer GPIO namespace so that it can be used with the legacy GPIO 39interface. Each chip must thus have a "base" number (which can be automatically 40assigned), and for each GPIO line the global number will be (base + hardware 41number). Although the integer representation is considered deprecated, it still 42has many users and thus needs to be maintained. 43 44So for example one platform could use global numbers 32-159 for GPIOs, with a 45controller defining 128 GPIOs at a "base" of 32 ; while another platform uses 46global numbers 0..63 with one set of GPIO controllers, 64-79 with another type 47of GPIO controller, and on one particular board 80-95 with an FPGA. The legacy 48numbers need not be contiguous; either of those platforms could also use numbers 492000-2063 to identify GPIO lines in a bank of I2C GPIO expanders. 50 51 52Controller Drivers: gpio_chip 53============================= 54 55In the gpiolib framework each GPIO controller is packaged as a "struct 56gpio_chip" (see <linux/gpio/driver.h> for its complete definition) with members 57common to each controller of that type, these should be assigned by the 58driver 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 70The code implementing a gpio_chip should support multiple instances of the 71controller, preferably using the driver model. That code will configure each 72gpio_chip and issue gpiochip_add_data() or devm_gpiochip_add_data(). Removing 73a GPIO controller should be rare; use gpiochip_remove() when it is unavoidable. 74 75Often a gpio_chip is part of an instance-specific structure with states not 76exposed by the GPIO interfaces, such as addressing, power management, and more. 77Chips such as audio codecs will have complex non-GPIO states. 78 79Any debugfs dump method should normally ignore lines which haven't been 80requested. They can use gpiochip_is_requested(), which returns either 81NULL or the label associated with that GPIO line when it was requested. 82 83Realtime considerations: the GPIO driver should not use spinlock_t or any 84sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set 85and direction control callbacks) if it is expected to call GPIO APIs from 86atomic context on realtime kernels (inside hard IRQ handlers and similar 87contexts). Normally this should not be required. 88 89 90GPIO level semantics 91-------------------- 92 93The gpip_chip .get/set[_multiple]() line values are clamped to the boolean 94space [0, 1], low level or high level. 95 96Low and high values are defined as physical low on the line in/out to the 97connector such as a physical pad, pin or rail. 98 99The GPIO library has internal logic to handle lines that are active low, such 100as indicated by overstrike or #name in a schematic, and the driver should not 101try to second-guess the logic value of a line. 102 103The way GPIO values are handled by the consumers is that the library present 104the *logical* value to the consumer. A line is *asserted* if its *logical* 105value is 1, and *de-asserted* if its logical value is 0. If inversion is 106required, this is handled by gpiolib and configured using hardware descriptions 107such as device tree or ACPI that can clearly indicate if a line is active 108high or low. 109 110Since electronics commonly insert inverters as driving stages or protection 111buffers in front of a GPIO line it is necessary that this semantic is part 112of the hardware description, so that consumers such as kernel drivers need 113not worry about this, and can for example assert a RESET line tied to a GPIO 114pin by setting it to logic 1 even if it is physically active low. 115 116 117GPIO electrical configuration 118----------------------------- 119 120GPIO lines can be configured for several electrical modes of operation by using 121the .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 127These settings are described below. 128 129The .set_config() callback uses the same enumerators and configuration 130semantics as the generic pin control drivers. This is not a coincidence: it is 131possible to assign the .set_config() to the function gpiochip_generic_config() 132which will result in pinctrl_gpio_set_config() being called and eventually 133ending up in the pin control back-end "behind" the GPIO controller, usually 134closer to the actual pins. This way the pin controller can manage the below 135listed GPIO configurations. 136 137If a pin controller back-end is used, the GPIO controller or hardware 138description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin 139numbers on the pin controller so they can properly cross-reference each other. 140 141 142GPIO lines with debounce support 143-------------------------------- 144 145Debouncing is a configuration set to a pin indicating that it is connected to 146a mechanical switch or button, or similar that may bounce. Bouncing means the 147line is pulled high/low quickly at very short intervals for mechanical 148reasons. This can result in the value being unstable or irqs firing repeatedly 149unless the line is debounced. 150 151Debouncing in practice involves setting up a timer when something happens on 152the line, wait a little while and then sample the line again, so see if it 153still has the same value (low or high). This could also be repeated by a clever 154state machine, waiting for a line to become stable. In either case, it sets 155a certain number of milliseconds for debouncing, or just "on/off" if that time 156is not configurable. 157 158 159GPIO lines with open drain/source support 160----------------------------------------- 161 162Open drain (CMOS) or open collector (TTL) means the line is not actively driven 163high: instead you provide the drain/collector as output, so when the transistor 164is 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 175This 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 186Both use cases require that the line be equipped with a pull-up resistor. This 187resistor will make the line tend to high level unless one of the transistors on 188the rail actively pulls it down. 189 190The level on the line will go as high as the VDD on the pull-up resistor, which 191may be higher than the level supported by the transistor, achieving a 192level-shift to the higher VDD. 193 194Integrated 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 196the line high and one of them drives the line low. This is called a push-pull 197output. 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 211The desired output signal (e.g. coming directly from some GPIO output register) 212arrives at IN. The switches named "OD" and "OS" are normally closed, creating 213a push-pull circuit. 214 215Consider the little "switches" named "OD" and "OS" that enable/disable the 216P-MOS or N-MOS transistor right after the split of the input. As you can see, 217either transistor will go totally numb if this switch is open. The totem-pole 218is then halved and give high impedance instead of actively driving the line 219high or low respectively. That is usually how software-controlled open 220drain/source works. 221 222Some GPIO hardware come in open drain / open source configuration. Some are 223hard-wired lines that will only support open drain or open source no matter 224what: there is only one transistor there. Some are software-configurable: 225by flipping a bit in a register the output can be configured as open drain 226or open source, in practice by flicking open the switches labeled "OD" and "OS" 227in the drawing above. 228 229By disabling the P-MOS transistor, the output can be driven between GND and 230high impedance (open drain), and by disabling the N-MOS transistor, the output 231can be driven between VDD and high impedance (open source). In the first case, 232a pull-up resistor is needed on the outgoing rail to complete the circuit, and 233in the second case, a pull-down resistor is needed on the rail. 234 235Hardware that supports open drain or open source or both, can implement a 236special callback in the gpio_chip: .set_config() that takes a generic 237pinconf packed value telling whether to configure the line as open drain, 238open source or push-pull. This will happen in response to the 239GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag set in the machine file, or coming 240from other hardware descriptions. 241 242If this state can not be configured in hardware, i.e. if the GPIO hardware does 243not support open drain/open source in hardware, the GPIO library will instead 244use a trick: when a line is set as output, if the line is flagged as open 245drain, and the IN output value is low, it will be driven low as usual. But 246if the IN output value is set to high, it will instead *NOT* be driven high, 247instead it will be switched to input, as input mode is an equivalent to 248high impedance, thus achieving an "open drain emulation" of sorts: electrically 249the behaviour will be identical, with the exception of possible hardware glitches 250when switching the mode of the line. 251 252For open source configuration the same principle is used, just that instead 253of actively driving the line low, it is set to input. 254 255 256GPIO lines with pull up/down resistor support 257--------------------------------------------- 258 259A GPIO line can support pull-up/down using the .set_config() callback. This 260means that a pull up or pull-down resistor is available on the output of the 261GPIO line, and this resistor is software controlled. 262 263In discrete designs, a pull-up or pull-down resistor is simply soldered on 264the circuit board. This is not something we deal with or model in software. The 265most you will think about these lines is that they will very likely be 266configured as open drain or open source (see the section above). 267 268The .set_config() callback can only turn pull up or down on and off, and will 269no have any semantic knowledge about the resistance used. It will only say 270switch a bit in a register enabling or disabling pull-up or pull-down. 271 272If the GPIO line supports shunting in different resistance values for the 273pull-up or pull-down resistor, the GPIO chip callback .set_config() will not 274suffice. For these complex use cases, a combined GPIO chip and pin controller 275need to be implemented, as the pin config interface of a pin controller 276supports more versatile control over electrical properties and can handle 277different pull-up or pull-down resistance values. 278 279 280GPIO drivers providing IRQs 281=========================== 282 283It is custom that GPIO drivers (GPIO chips) are also providing interrupts, 284most often cascaded off a parent interrupt controller, and in some special 285cases the GPIO logic is melded with a SoC's primary interrupt controller. 286 287The IRQ portions of the GPIO block are implemented using an irq_chip, using 288the header <linux/irq.h>. So this combined driver is utilizing two sub- 289systems simultaneously: gpio and irq. 290 291It is legal for any IRQ consumer to request an IRQ from any irqchip even if it 292is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and 293irq_chip are orthogonal, and offering their services independent of each 294other. 295 296gpiod_to_irq() is just a convenience function to figure out the IRQ for a 297certain GPIO line and should not be relied upon to have been called before 298the IRQ is used. 299 300Always prepare the hardware and make it ready for action in respective 301callbacks from the GPIO and irq_chip APIs. Do not rely on gpiod_to_irq() having 302been called first. 303 304We 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 325Realtime considerations: a realtime compliant GPIO driver should not use 326spinlock_t or any sleepable APIs (like PM runtime) as part of its irqchip 327implementation. 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 335Cascaded GPIO irqchips 336---------------------- 337 338Cascaded 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 416Infrastructure helpers for GPIO irqchips 417---------------------------------------- 418 419To help out in handling the set-up and management of GPIO irqchips and the 420associated irqdomain and resource allocation callbacks. These are activated 421by selecting the Kconfig symbol GPIOLIB_IRQCHIP. If the symbol 422IRQ_DOMAIN_HIERARCHY is also selected, hierarchical helpers will also be 423provided. A big portion of overhead code will be managed by gpiolib, 424under the assumption that your interrupts are 1-to-1-mapped to the 425GPIO 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 437If some GPIO lines do not have corresponding IRQs, the bitmask valid_mask 438and the flag need_valid_mask in gpio_irq_chip can be used to mask off some 439lines as invalid for associating with IRQs. 440 441The preferred way to set up the helpers is to fill in the 442struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip. 443If you do this, the additional irq_chip will be set up by gpiolib at the 444same time as setting up the rest of the GPIO functionality. The following 445is a typical example of a chained cascaded interrupt handler using 446the gpio_irq_chip. Note how the mask/unmask (or disable/enable) functions 447call 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 520The helper supports using threaded interrupts as well. Then you just request 521the 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 596The helper supports using hierarchical interrupt controllers as well. 597In 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 669As you can see pretty similar, but you do not supply a parent handler for 670the IRQ, instead a parent irqdomain, an fwnode for the hardware and 671a function .child_to_parent_hwirq() that has the purpose of looking up 672the parent hardware irq from a child (i.e. this gpio chip) hardware irq. 673As always it is good to look at examples in the kernel tree for advice 674on how to find the required pieces. 675 676If there is a need to exclude certain GPIO lines from the IRQ domain handled by 677these helpers, we can set .irq.need_valid_mask of the gpiochip before 678devm_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 680bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits 681from this mask. The mask can be filled in the init_valid_mask() callback 682that is part of the struct gpio_irq_chip. 683 684To 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 696Locking IRQ usage 697----------------- 698 699Since GPIO and irq_chip are orthogonal, we can get conflicts between different 700use cases. For example a GPIO line used for IRQs should be an input line, 701it does not make sense to fire interrupts on an output GPIO. 702 703If there is competition inside the subsystem which side is using the 704resource (a certain GPIO line and register for example) it needs to deny 705certain operations and keep track of usage inside of the gpiolib subsystem. 706 707Input GPIOs can be used as IRQ signals. When this happens, a driver is requested 708to mark the GPIO as being used as an IRQ:: 709 710 int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) 711 712This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock 713is released:: 714 715 void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) 716 717When implementing an irqchip inside a GPIO driver, these two functions should 718typically be called in the .startup() and .shutdown() callbacks from the 719irqchip. 720 721When using the gpiolib irqchip helpers, these callbacks are automatically 722assigned. 723 724 725Disabling and enabling IRQs 726--------------------------- 727 728In some (fringe) use cases, a driver may be using a GPIO line as input for IRQs, 729but occasionally switch that line over to drive output and then back to being 730an input with interrupts again. This happens on things like CEC (Consumer 731Electronics Control). 732 733When a GPIO is used as an IRQ signal, then gpiolib also needs to know if 734the IRQ is enabled or disabled. In order to inform gpiolib about this, 735the irqchip driver should call:: 736 737 void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset) 738 739This allows drivers to drive the GPIO as an output while the IRQ is 740disabled. When the IRQ is enabled again, a driver should call:: 741 742 void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset) 743 744When implementing an irqchip inside a GPIO driver, these two functions should 745typically be called in the .irq_disable() and .irq_enable() callbacks from the 746irqchip. 747 748When IRQCHIP_IMMUTABLE is not advertised by the irqchip, these callbacks 749are automatically assigned. This behaviour is deprecated and on its way 750to be removed from the kernel. 751 752 753Real-Time compliance for GPIO IRQ chips 754--------------------------------------- 755 756Any provider of irqchips needs to be carefully tailored to support Real-Time 757preemption. It is desirable that all irqchips in the GPIO subsystem keep this 758in mind and do the proper testing to assure they are real time-enabled. 759 760So, pay attention on above realtime considerations in the documentation. 761 762The following is a checklist to follow when preparing a driver for real-time 763compliance: 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/1437496011-11486-1-git-send-email-bigeasy@linutronix.de/ 781* [2] https://lore.kernel.org/r/1443209283-20781-2-git-send-email-grygorii.strashko@ti.com 782* [3] https://lore.kernel.org/r/1443209283-20781-3-git-send-email-grygorii.strashko@ti.com 783 784 785Requesting self-owned GPIO pins 786=============================== 787 788Sometimes it is useful to allow a GPIO chip driver to request its own GPIO 789descriptors through the gpiolib API. A GPIO driver can use the following 790functions 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 799Descriptors requested with gpiochip_request_own_desc() must be released with 800gpiochip_free_own_desc(). 801 802These functions must be used with care since they do not affect module use 803count. Do not use the functions to request gpio descriptors not owned by the 804calling driver. 805