STRUCT GPIO_IRQ_CHIP(9)

💜 struct gpio_irq_chip(9) — like, the GPIO interrupt controller era

okay so bestie, we're in the Kernel API Manual today and this page is literally all about struct gpio_irq_chip — the GPIO interrupt controller glow-up. it's giving "the struct that makes your GPIO lines actually able to yell for attention" ✨

---

🌸 NAME 🌸

struct gpio_irq_chip — the GPIO interrupt controller, no cap 🎀

---

✨ SYNOPSIS ✨

struct gpio_irq_chip {
    struct irq_chip *chip;
    struct irq_domain *domain;
  #ifdef CONFIG_IRQ_DOMAIN_HIERARCHY;
    struct fwnode_handle *fwnode;
    struct irq_domain *parent_domain;
    int (*child_to_parent_hwirq)(struct gpio_chip *gc, unsigned int
child_hwirq, unsigned int child_type, unsigned int *parent_hwirq,
unsigned int *parent_type);
    int (*populate_parent_alloc_arg)(struct gpio_chip *gc, union
gpio_irq_fwspec *fwspec, unsigned int parent_hwirq, unsigned int
parent_type);
    unsigned int (*child_offset_to_irq)(struct gpio_chip *gc, unsigned
int pin);
    struct irq_domain_ops child_irq_domain_ops;
  #endif;
    irq_flow_handler_t handler;
    unsigned int default_type;
    struct lock_class_key *lock_key;
    struct lock_class_key *request_key;
    irq_flow_handler_t parent_handler;
    union {
      void *parent_handler_data;
      void **parent_handler_data_array;
    };
    unsigned int num_parents;
    unsigned int *parents;
    unsigned int *map;
    bool threaded;
    bool per_parent_data;
    bool initialized;
    bool domain_is_allocated_externally;
    int (*init_hw)(struct gpio_chip *gc);
    void (*init_valid_mask)(struct gpio_chip *gc, unsigned long
*valid_mask, unsigned int ngpios);
    unsigned long *valid_mask;
    unsigned int first;
    void (*irq_enable)(struct irq_data *data);
    void (*irq_disable)(struct irq_data *data);
    void (*irq_unmask)(struct irq_data *data);
    void (*irq_mask)(struct irq_data *data);
 };

---

🦋 Members 🦋 (the whole cast, main character energy only)

• chip — the GPIO IRQ chip implementation itself, and your GPIO driver is the one who provides it. 💅
• domain — the interrupt translation domain; its whole job is mapping between the GPIO hwirq number and the Linux IRQ number. matchmaker energy fr fr.
• fwnode — the firmware node corresponding to this gpiochip/irqchip. it's necessary for hierarchical irqdomain support, so don't skip it.
• parent_domain — if it's non-NULL, it gets set as the parent of this GPIO interrupt controller's IRQ domain, which establishes a hierarchical interrupt domain. and like, the mere presence of this activates the hierarchical interrupt support. iconic.
• child_to_parent_hwirq — this callback translates a child hardware IRQ offset to a parent hardware IRQ offset on a hierarchical interrupt chip. the child hardware IRQs correspond to the GPIO index 0..ngpio-1 (peep the ngpio field of struct gpio_chip) and the driver shall return the corresponding parent hardware IRQ and type (such as IRQ_TYPE_*). the driver can calculate this from an offset, or use a lookup table, or literally whatever method is best for this chip. return 0 on successful translation in the driver.

🚨 important aside bestie: if some ranges of hardware IRQs do not have a corresponding parent HWIRQ, return -EINVAL — but also make sure to fill in valid_mask and need_valid_mask to make these GPIO lines unavailable for translation. no half-jobs.

• populate_parent_alloc_arg — this optional callback allocates and populates the specific struct for the parent's IRQ domain. if this is not specified, then gpiochip_populate_parent_fwspec_twocell will be used. a four-cell variant named gpiochip_populate_parent_fwspec_fourcell is also available. options, we love to see them 🌈
• child_offset_to_irq — this optional callback translates the child's GPIO line offset on the GPIO chip to an IRQ number for the GPIO to_irq callback. if this is not specified, then a default callback will be provided that returns the line offset. free default, we stan.
• child_irq_domain_ops — the IRQ domain operations that will be used for this GPIO IRQ chip. if no operations are provided, then default callbacks will be populated to setup the IRQ hierarchy. some drivers need to supply their own translate function. iykyk.
• handler — the IRQ handler to use (often a predefined IRQ core function) for GPIO IRQs, provided by the GPIO driver.
• default_type — the default IRQ triggering type applied during GPIO driver initialization, provided by the GPIO driver.
• lock_key — per GPIO IRQ chip lockdep class for the IRQ lock.
• request_key — per GPIO IRQ chip lockdep class for the IRQ request.
• parent_handler — the interrupt handler for the GPIO chip's parent interrupts. it may be NULL if the parent interrupts are nested rather than cascaded. 💀
• {unnamed_union} — anonymous. that's it, that's the whole vibe. 🙈
• parent_handler_data — if per_parent_data is false, then parent_handler_data is a single pointer used as the data associated with every parent interrupt.
• parent_handler_data_array — if per_parent_data is true, then parent_handler_data_array is an array of num_parents pointers, and it's used to associate different data for each parent. this cannot be NULL if per_parent_data is true. periodt.
• num_parents — the number of interrupt parents of a GPIO chip.
• parents — a list of interrupt parents of a GPIO chip. this is owned by the driver, so the core will only reference this list, never modify it. hands off 🫶
• map — a list of interrupt parents for each line of a GPIO chip.
• threaded — True if set the interrupt handling uses nested threads.
• per_parent_data — True if parent_handler_data_array describes a num_parents sized array to be used as parent data.
• initialized — flag to track the GPIO chip irq member's initialization. this flag makes sure the GPIO chip irq members are not used before they are initialized. protective queen 🔥
• domain_is_allocated_externally — True it the irq_domain was allocated outside of gpiolib, in which case gpiolib won't free the irq_domain itself. (yes, the typo is canon, we're keeping it, don't come for me 😭)
• init_hw — optional routine to initialize hardware before an IRQ chip will be added. this is quite useful when a particular driver wants to clear IRQ related registers in order to avoid undesired events. very "clean your room before guests arrive" of it.
• init_valid_mask — optional routine to initialize valid_mask, to be used if not all GPIO lines are valid interrupts. sometimes some lines just cannot fire interrupts, and this routine, when defined, is passed a bitmap in "valid_mask" and it will have ngpios bits from 0..(ngpios-1) set to "1" as in valid. the callback can then directly set some bits to "0" if they cannot be used for interrupts. customise away 💅
• valid_mask — if not NULL, holds the bitmask of GPIOs which are valid to be included in the IRQ domain of the chip.
• first — required for static IRQ allocation. if set, irq_domain_create_simple will allocate and map all IRQs during initialization.
• irq_enable — stores the old irq_chip irq_enable callback. 🎀
• irq_disable — stores the old irq_chip irq_disable callback.
• irq_unmask — stores the old irq_chip irq_unmask callback.
• irq_mask — stores the old irq_chip irq_mask callback.

---

👑 SEE ALSO 👑

go peek at the Kernel file ./include/linux/gpio/driver.h plus these icons:

• struct gpio_chip(9)
• for_each_hwgpio_in_range(9)
• for_each_hwgpio(9)
• for_each_requested_gpio_in_range(9)
• gpiochip_add_data(9)
• struct gpio_pin_range(9)

---

and that's the page bestie!! 🍓 this little gem lives over in ./include/linux/gpio and the manual says October 2026 — so like, future-dated slay 💜✨ go forth and wire up those interrupts responsibly 🧚‍♀️🌸