STRUCT GPIO_CHIP(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct gpio_chip(9) — or, like, the literal blueprint of a GPIO controller ✨

okay bestie, buckle up 🎀 this is a page from the Kernel API Manual and it's about struct gpio_chip — the struct that abstracts a GPIO controller. iykyk, this thing is iconic. it's giving main character energy in ./include/linux/gpio/driver.h. let's get into it 💖

✨ SYNOPSIS ✨

here's the whole struct, verbatim, no cap — every field exactly as it lives, line breaks and all:

struct gpio_chip {
    const char              *label;
    struct gpio_device      *gpiodev;
    struct device           *parent;
    struct fwnode_handle    *fwnode;
    struct module           *owner;
    int (*request)(struct gpio_chip *gc, unsigned int offset);
    void (*free)(struct gpio_chip *gc, unsigned int offset);
    int (*get_direction)(struct gpio_chip *gc, unsigned int offset);
    int (*direction_input)(struct gpio_chip *gc, unsigned int offset);
    int (*direction_output)(struct gpio_chip *gc, unsigned int offset,
int value);
    int (*get)(struct gpio_chip *gc, unsigned int offset);
    int (*get_multiple)(struct gpio_chip *gc, unsigned long *mask,
unsigned long *bits);
    int (*set)(struct gpio_chip *gc, unsigned int offset, int value);
    int (*set_multiple)(struct gpio_chip *gc, unsigned long *mask,
unsigned long *bits);
    int (*set_config)(struct gpio_chip *gc, unsigned int offset,
unsigned long config);
    int (*to_irq)(struct gpio_chip *gc, unsigned int offset);
    void (*dbg_show)(struct seq_file *s, struct gpio_chip *gc);
    int (*init_valid_mask)(struct gpio_chip *gc, unsigned long
*valid_mask, unsigned int ngpios);
    int (*add_pin_ranges)(struct gpio_chip *gc);
    int (*en_hw_timestamp)(struct gpio_chip *gc, u32 offset, unsigned
long flags);
    int (*dis_hw_timestamp)(struct gpio_chip *gc, u32 offset, unsigned
long flags);
    int base;
    u16 ngpio;
    u16 offset;
    const char              *const *names;
    bool can_sleep;
  #ifdef CONFIG_GPIOLIB_IRQCHIP;
    struct gpio_irq_chip irq;
  #endif ;
  #if defined(CONFIG_OF_GPIO);
    unsigned int of_gpio_n_cells;
    bool (*of_node_instance_match)(struct gpio_chip *gc, unsigned int
i);
    int (*of_xlate)(struct gpio_chip *gc, const struct of_phandle_args
*gpiospec, u32 *flags);
  #endif ;
 };

like… yes it's long. no you can't skip it. 🙈

🦋 Members 🦋

okay this is the part where we go field by field, and honestly? obsessed. 🫶

  • label — a functional name for the GPIO device, like a part number or the name of the SoC IP-block that implements it. it's the name tag at the party 💖
  • gpiodev — the internal state holder, an opaque struct. don't look at it too long, it's shy 👀
  • parent — optional parent device providing the GPIOs.
  • fwnode — optional fwnode providing this controller's properties.
  • owner — helps prevent removal of modules exporting active GPIOs. lowkey the bodyguard of the struct 💅
  • request — optional hook for chip-specific activation, such as enabling module power and clock. may sleep. must return 0 on success or a negative error number on failure.
  • free — optional hook for chip-specific deactivation, such as disabling module power and clock. may sleep.
  • get_direction — returns direction for signal "offset": 0=out, 1=in (same as GPIO_LINE_DIRECTION_OUT / GPIO_LINE_DIRECTION_IN), or a negative error. it is recommended to always implement this function, even on input-only or output-only gpio chips. yes even then. do it. 🔥
  • direction_input — configures signal "offset" as input, returns 0 on success or a negative error number. this can be omitted on input-only or output-only gpio chips.
  • direction_output — configures signal "offset" as output, returns 0 on success or a negative error number. this can be omitted on input-only or output-only gpio chips.
  • get — returns value for signal "offset": 0=low, 1=high, or a negative error. the low and high values are defined as physical low on the line in/out to the connector — such as a physical pad, pin or rail. the GPIO library has internal logic to handle lines that are active low (like, as indicated by overstrike or #name in a schematic), and the driver should not try to second-guess the logic value of a line. don't do it bestie, that's not your job 🙅‍♀️
  • get_multiple — reads values for multiple signals defined by "mask" and stores them in "bits", returns 0 on success or negative error. group chat but for signals ✨
  • set — assigns output value for signal "offset", returns 0 on success or negative error value. the output value follows the same semantic rules as for get.
  • set_multiple — assigns output values for multiple signals defined by "mask", returns 0 on success or negative error value.
  • set_config — optional hook for all kinds of settings. uses the same packed config format as generic pinconf. must return 0 on success and a negative error number on failure.
  • to_irq — optional hook supporting non-static gpiod_to_irq mappings; implementation may not sleep. like, none. zero. nope 😴🚫
  • dbg_show — optional routine to show contents in debugfs; default code will be used when this is omitted, but custom code can show extra state (such as pullup/pulldown configuration).
  • init_valid_mask — optional routine to initialize valid_mask, to be used if not all GPIOs are valid.
  • add_pin_ranges — optional routine to initialize pin ranges, to be used when [it] requires special mapping of the pins that provides GPIO functionality. it is called after adding GPIO chip and before adding IRQ chip.
  • en_hw_timestamp — dependent on GPIO chip, an optional routine to enable hardware timestamp. ⏱️✨
  • dis_hw_timestamp — dependent on GPIO chip, an optional routine to disable hardware timestamp.
  • base — identifies the first GPIO number handled by this chip; or, if negative during registration, requests dynamic ID allocation.
DEPRECATION: providing anything non-negative and nailing the base offset of GPIO chips is deprecated. please pass -1 as base to let gpiolib select the chip base in all possible cases. we want to get rid of the static GPIO number space in the long run. fr fr, stop hardcoding it 💀
  • ngpio — the number of GPIOs handled by this controller; the last GPIO handled is (base + ngpio - 1). math slay 🧮
  • offset — when multiple gpio chips belong to the same device this can be used as offset within the device so friendly names can be properly assigned.
  • names — if set, must be an array of strings to use as alternative names for the GPIOs in this chip. any entry in the array may be NULL if there is no alias for the GPIO, however the array must be ngpio entries long. length matters, periodt 👑
  • can_sleep — flag must be set iff get/set methods sleep, as they must while accessing GPIO expander chips over I2C or SPI. this implies that if the chip supports IRQs, these IRQs need to be threaded as the chip access may sleep when e.g. reading out the IRQ status registers.
  • irq — integrates interrupt chip functionality with the GPIO chip. can be used to handle IRQs for most practical cases. the 🫶 of the struct.
  • of_gpio_n_cells — number of cells used to form the GPIO specifier. the standard is 2 cells:
gpios = <gpio offset flags>;

some complex GPIO controllers instantiate more than one chip per device tree node and have 3 cells:

gpios = <gpio instance offset flags>;

legacy GPIO controllers may even have 1 cell:

gpios = <gpio offset>;
  • of_node_instance_match — determine if a chip is the right instance. must be implemented by any driver using more than one gpio_chip per device tree node. returns true if gc is the instance indicated by i (which is the first cell in the phandles for GPIO lines and gpio-ranges).
  • of_xlate — callback to translate a device tree GPIO specifier into a chip-relative GPIO number and flags.

🌈 Description 🌈

so a gpio_chip can help platforms abstract various sources of GPIOs so they can all be accessed through a common programming interface. iconic behavior, honestly. example sources would be SOC controllers, FPGAs, multifunction chips, dedicated GPIO expanders, and so on. the whole friend group 💖

each chip controls a number of signals, identified in method calls by "offset" values in the range 0..(ngpio - 1). when those signals are referenced through calls like gpio_get_value(gpio), the offset is calculated by subtracting base from the gpio number. that's the whole vibe check 🧚

🔥 SEE ALSO 🔥

and that's the page, bestie! 🎀 this gem lives in the source tree at ./include/linux/gpio and it's dated October 2026 — yes, future-dated, we stay ahead 💅 bye, go write a proper get_direction 🌸🦋

📦 where this page comes from