General Purpose Input/Output (GPIO)¶

Core¶

struct gpio_chip¶: abstract a GPIO controller

Definition

struct gpio_chip {
  const char * label;
  struct gpio_device * gpiodev;
  struct device * parent;
  struct module * owner;
  int (* request) (struct gpio_chip *chip, unsigned offset);
  void (* free) (struct gpio_chip *chip, unsigned offset);
  int (* get_direction) (struct gpio_chip *chip, unsigned offset);
  int (* direction_input) (struct gpio_chip *chip, unsigned offset);
  int (* direction_output) (struct gpio_chip *chip, unsigned offset, int value);
  int (* get) (struct gpio_chip *chip, unsigned offset);
  void (* set) (struct gpio_chip *chip, unsigned offset, int value);
  void (* set_multiple) (struct gpio_chip *chip,unsigned long *mask, unsigned long *bits);
  int (* set_config) (struct gpio_chip *chip,unsigned offset, unsigned long config);
  int (* to_irq) (struct gpio_chip *chip, unsigned offset);
  void (* dbg_show) (struct seq_file *s, struct gpio_chip *chip);
  int base;
  u16 ngpio;
  const char *const * names;
  bool can_sleep;
#if IS_ENABLED(CONFIG_GPIO_GENERIC
  unsigned long (* read_reg) (void __iomem *reg);
  void (* write_reg) (void __iomem *reg, unsigned long data);
  unsigned long (* pin2mask) (struct gpio_chip *gc, unsigned int pin);
  void __iomem * reg_dat;
  void __iomem * reg_set;
  void __iomem * reg_clr;
  void __iomem * reg_dir;
  int bgpio_bits;
  spinlock_t bgpio_lock;
  unsigned long bgpio_data;
  unsigned long bgpio_dir;
#endif
#ifdef CONFIG_GPIOLIB_IRQCHIP
  struct irq_chip * irqchip;
  struct irq_domain * irqdomain;
  unsigned int irq_base;
  irq_flow_handler_t irq_handler;
  unsigned int irq_default_type;
  unsigned int irq_chained_parent;
  bool irq_nested;
  bool irq_need_valid_mask;
  unsigned long * irq_valid_mask;
  struct lock_class_key * lock_key;
#endif
#if defined(CONFIG_OF_GPIO
  struct device_node * of_node;
  unsigned int of_gpio_n_cells;
  int (* of_xlate) (struct gpio_chip *gc, const struct of_phandle_args *gpiospec, u32 *flags);
#endif
};

Members

label: a functional name for the GPIO device, such as a part number or the name of the SoC IP-block implementing it.
gpiodev: the internal state holder, opaque struct
parent: optional parent device providing the GPIOs
owner: helps prevent removal of modules exporting active GPIOs
request: optional hook for chip-specific activation, such as enabling module power and clock; may sleep
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 GPIOF_DIR_XXX), or negative error
direction_input: configures signal “offset” as input, or returns error
direction_output: configures signal “offset” as output, or returns error
get: returns value for signal “offset”, 0=low, 1=high, or negative error
set: assigns output value for signal “offset”
set_multiple: assigns output values for multiple signals defined by “mask”
set_config: optional hook for all kinds of settings. Uses the same packed config format as generic pinconf.
to_irq: optional hook supporting non-static gpio_to_irq() mappings; implementation may not sleep
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).
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.
ngpio: the number of GPIOs handled by this controller; the last GPIO handled is (base + ngpio - 1).
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. A name can include a single printk format specifier for an unsigned int. It is substituted by the actual number of the gpio.
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.
read_reg: reader function for generic GPIO
write_reg: writer function for generic GPIO
pin2mask: some generic GPIO controllers work with the big-endian bits notation, e.g. in a 8-bits register, GPIO7 is the least significant bit. This callback assigns the right bit mask.
reg_dat: data (in) register for generic GPIO
reg_set: output set register (out=high) for generic GPIO
reg_clr: output clear register (out=low) for generic GPIO
reg_dir: direction setting register for generic GPIO
bgpio_bits: number of register bits used for a generic GPIO i.e. <register width> * 8
bgpio_lock: used to lock chip->bgpio_data. Also, this is needed to keep shadowed and real data registers writes together.
bgpio_data: shadowed data register for generic GPIO to clear/set bits safely.
bgpio_dir: shadowed direction register for generic GPIO to clear/set direction safely.
irqchip: GPIO IRQ chip impl, provided by GPIO driver
irqdomain: Interrupt translation domain; responsible for mapping between GPIO hwirq number and linux irq number
irq_base: first linux IRQ number assigned to GPIO IRQ chip (deprecated)
irq_handler: the irq handler to use (often a predefined irq core function) for GPIO IRQs, provided by GPIO driver
irq_default_type: default IRQ triggering type applied during GPIO driver initialization, provided by GPIO driver
irq_chained_parent: GPIO IRQ chip parent/bank linux irq number, provided by GPIO driver for chained interrupt (not for nested interrupts).
irq_nested: True if set the interrupt handling is nested.
irq_need_valid_mask: If set core allocates irq_valid_mask with all bits set to one
irq_valid_mask: If not NULL holds bitmask of GPIOs which are valid to be included in IRQ domain of the chip
lock_key: per GPIO IRQ chip lockdep class
of_node: Pointer to a device tree node representing this GPIO controller.
of_gpio_n_cells: Number of cells used to form the GPIO specifier.
of_xlate: Callback to translate a device tree GPIO specifier into a chip- relative GPIO number and flags.

Description

A gpio_chip can help platforms abstract various sources of GPIOs so they can all be accessed through a common programing interface. Example sources would be SOC controllers, FPGAs, multifunction chips, dedicated GPIO expanders, and so on.

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.

struct gpio_pin_range¶: pin range controlled by a gpio chip

Definition

struct gpio_pin_range {
  struct list_head node;
  struct pinctrl_dev * pctldev;
  struct pinctrl_gpio_range range;
};

Members

node: list for maintaining set of pin ranges, used internally
pctldev: pinctrl device which handles corresponding pins
range: actual range of pins controlled by a gpio controller

struct gpio_desc * gpio_to_desc(unsigned gpio)¶: Convert a GPIO number to its descriptor

Parameters

unsigned gpio: global GPIO number

Return

The GPIO descriptor associated with the given GPIO, or NULL if no GPIO with the given number exists in the system.

int desc_to_gpio(const struct gpio_desc * desc)¶: convert a GPIO descriptor to the integer namespace

Parameters

const struct gpio_desc * desc: GPIO descriptor

Description

This should disappear in the future but is needed since we still use GPIO numbers for error messages and sysfs nodes.

Return

The global GPIO number for the GPIO specified by its descriptor.

struct gpio_chip * gpiod_to_chip(const struct gpio_desc * desc)¶: Return the GPIO chip to which a GPIO descriptor belongs

Parameters

const struct gpio_desc * desc: descriptor to return the chip of

int gpiod_get_direction(struct gpio_desc * desc)¶: return the current direction of a GPIO

Parameters

struct gpio_desc * desc: GPIO to get the direction of

Description

Return GPIOF_DIR_IN or GPIOF_DIR_OUT, or an error code in case of error.

This function may sleep if gpiod_cansleep() is true.

int gpiochip_add_data(struct gpio_chip * chip, void * data)¶: register a gpio_chip

Parameters

struct gpio_chip * chip: the chip to register, with chip->base initialized
void * data: driver-private data associated with this chip

Context

potentially before irqs will work

Description

When gpiochip_add_data() is called very early during boot, so that GPIOs can be freely used, the chip->parent device must be registered before the gpio framework’s arch_initcall(). Otherwise sysfs initialization for GPIOs will fail rudely.

gpiochip_add_data() must only be called after gpiolib initialization, ie after core_initcall().

If chip->base is negative, this requests dynamic assignment of a range of valid GPIOs.

Return

A negative errno if the chip can’t be registered, such as because the chip->base is invalid or already associated with a different chip. Otherwise it returns zero as a success code.

void * gpiochip_get_data(struct gpio_chip * chip)¶: get per-subdriver data for the chip

Parameters

struct gpio_chip * chip: GPIO chip

Return

The per-subdriver data for the chip.

void gpiochip_remove(struct gpio_chip * chip)¶: unregister a gpio_chip

Parameters

struct gpio_chip * chip: the chip to unregister

Description

A gpio_chip with any GPIOs still requested may not be removed.

int devm_gpiochip_add_data(struct device * dev, struct gpio_chip * chip, void * data)¶: Resource manager piochip_add_data()

Parameters

struct device * dev: the device pointer on which irq_chip belongs to.
struct gpio_chip * chip: the chip to register, with chip->base initialized
void * data: driver-private data associated with this chip

Context

potentially before irqs will work

Description

The gpio chip automatically be released when the device is unbound.

Return

A negative errno if the chip can’t be registered, such as because the chip->base is invalid or already associated with a different chip. Otherwise it returns zero as a success code.

void devm_gpiochip_remove(struct device * dev, struct gpio_chip * chip)¶: Resource manager of gpiochip_remove()

Parameters

struct device * dev: device for which which resource was allocated
struct gpio_chip * chip: the chip to remove

Description

A gpio_chip with any GPIOs still requested may not be removed.

struct gpio_chip * gpiochip_find(void * data, int (*match) (struct gpio_chip *chip, void *data)¶: iterator for locating a specific gpio_chip

Parameters

void * data: data to pass to match function
int (*)(struct gpio_chip *chip, void *data) match: Callback function to check gpio_chip

Description

Similar to bus_find_device. It returns a reference to a gpio_chip as determined by a user supplied match callback. The callback should return 0 if the device doesn’t match and non-zero if it does. If the callback is non-zero, this function will return to the caller and not iterate over any more gpio_chips.

void gpiochip_set_chained_irqchip(struct gpio_chip * gpiochip, struct irq_chip * irqchip, unsigned int parent_irq, irq_flow_handler_t parent_handler)¶: connects a chained irqchip to a gpiochip

Parameters

struct gpio_chip * gpiochip: the gpiochip to set the irqchip chain to
struct irq_chip * irqchip: the irqchip to chain to the gpiochip
unsigned int parent_irq: the irq number corresponding to the parent IRQ for this chained irqchip
irq_flow_handler_t parent_handler: the parent interrupt handler for the accumulated IRQ coming out of the gpiochip. If the interrupt is nested rather than cascaded, pass NULL in this handler argument

void gpiochip_set_nested_irqchip(struct gpio_chip * gpiochip, struct irq_chip * irqchip, unsigned int parent_irq)¶: connects a nested irqchip to a gpiochip

Parameters

struct gpio_chip * gpiochip: the gpiochip to set the irqchip nested handler to
struct irq_chip * irqchip: the irqchip to nest to the gpiochip
unsigned int parent_irq: the irq number corresponding to the parent IRQ for this nested irqchip

int gpiochip_irqchip_add_key(struct gpio_chip * gpiochip, struct irq_chip * irqchip, unsigned int first_irq, irq_flow_handler_t handler, unsigned int type, bool nested, struct lock_class_key * lock_key)¶: adds an irqchip to a gpiochip

Parameters

struct gpio_chip * gpiochip: the gpiochip to add the irqchip to
struct irq_chip * irqchip: the irqchip to add to the gpiochip
unsigned int first_irq: if not dynamically assigned, the base (first) IRQ to allocate gpiochip irqs from
irq_flow_handler_t handler: the irq handler to use (often a predefined irq core function)
unsigned int type: the default type for IRQs on this irqchip, pass IRQ_TYPE_NONE to have the core avoid setting up any default type in the hardware.
bool nested: whether this is a nested irqchip calling handle_nested_irq() in its IRQ handler
struct lock_class_key * lock_key: lockdep class

Description

This function closely associates a certain irqchip with a certain gpiochip, providing an irq domain to translate the local IRQs to global irqs in the gpiolib core, and making sure that the gpiochip is passed as chip data to all related functions. Driver callbacks need to use gpiochip_get_data() to get their local state containers back from the gpiochip passed as chip data. An irqdomain will be stored in the gpiochip that shall be used by the driver to handle IRQ number translation. The gpiochip will need to be initialized and registered before calling this function.

This function will handle two cell:ed simple IRQs and assumes all the pins on the gpiochip can generate a unique IRQ. Everything else need to be open coded.

int gpiochip_generic_request(struct gpio_chip * chip, unsigned offset)¶: request the gpio function for a pin

Parameters

struct gpio_chip * chip: the gpiochip owning the GPIO
unsigned offset: the offset of the GPIO to request for GPIO function

void gpiochip_generic_free(struct gpio_chip * chip, unsigned offset)¶: free the gpio function from a pin

Parameters

struct gpio_chip * chip: the gpiochip to request the gpio function for
unsigned offset: the offset of the GPIO to free from GPIO function

int gpiochip_generic_config(struct gpio_chip * chip, unsigned offset, unsigned long config)¶: apply configuration for a pin

Parameters

struct gpio_chip * chip: the gpiochip owning the GPIO
unsigned offset: the offset of the GPIO to apply the configuration
unsigned long config: the configuration to be applied

int gpiochip_add_pingroup_range(struct gpio_chip * chip, struct pinctrl_dev * pctldev, unsigned int gpio_offset, const char * pin_group)¶: add a range for GPIO <-> pin mapping

Parameters

struct gpio_chip * chip: the gpiochip to add the range for
struct pinctrl_dev * pctldev: the pin controller to map to
unsigned int gpio_offset: the start offset in the current gpio_chip number space
const char * pin_group: name of the pin group inside the pin controller

int gpiochip_add_pin_range(struct gpio_chip * chip, const char * pinctl_name, unsigned int gpio_offset, unsigned int pin_offset, unsigned int npins)¶: add a range for GPIO <-> pin mapping

Parameters

struct gpio_chip * chip: the gpiochip to add the range for
const char * pinctl_name: the dev_name() of the pin controller to map to
unsigned int gpio_offset: the start offset in the current gpio_chip number space
unsigned int pin_offset: the start offset in the pin controller number space
unsigned int npins: the number of pins from the offset of each pin space (GPIO and pin controller) to accumulate in this range

Return

0 on success, or a negative error-code on failure.

void gpiochip_remove_pin_ranges(struct gpio_chip * chip)¶: remove all the GPIO <-> pin mappings

Parameters

struct gpio_chip * chip: the chip to remove all the mappings for

const char * gpiochip_is_requested(struct gpio_chip * chip, unsigned offset)¶: return string iff signal was requested

Parameters

struct gpio_chip * chip: controller managing the signal
unsigned offset: of signal within controller’s 0..(ngpio - 1) range

Description

Returns NULL if the GPIO is not currently requested, else a string. The string returned is the label passed to gpio_request(); if none has been passed it is a meaningless, non-NULL constant.

This function is for use by GPIO controller drivers. The label can help with diagnostics, and knowing that the signal is used as a GPIO can help avoid accidentally multiplexing it to another controller.

struct gpio_desc * gpiochip_request_own_desc(struct gpio_chip * chip, u16 hwnum, const char * label)¶: Allow GPIO chip to request its own descriptor

Parameters

struct gpio_chip * chip: GPIO chip
u16 hwnum: hardware number of the GPIO for which to request the descriptor
const char * label: label for the GPIO

Description

Function allows GPIO chip drivers to request and use their own GPIO descriptors via gpiolib API. Difference to gpiod_request() is that this function will not increase reference count of the GPIO chip module. This allows the GPIO chip module to be unloaded as needed (we assume that the GPIO chip driver handles freeing the GPIOs it has requested).

Return

A pointer to the GPIO descriptor, or an ERR_PTR()-encoded negative error code on failure.

void gpiochip_free_own_desc(struct gpio_desc * desc)¶: Free GPIO requested by the chip driver

Parameters

struct gpio_desc * desc: GPIO descriptor to free

Description

Function frees the given GPIO requested previously with gpiochip_request_own_desc().

int gpiod_direction_input(struct gpio_desc * desc)¶: set the GPIO direction to input

Parameters

struct gpio_desc * desc: GPIO to set to input

Description

Set the direction of the passed GPIO to input, such as gpiod_get_value() can be called safely on it.

Return 0 in case of success, else an error code.

int gpiod_direction_output_raw(struct gpio_desc * desc, int value)¶: set the GPIO direction to output

Parameters

struct gpio_desc * desc: GPIO to set to output
int value: initial output value of the GPIO

Description

Set the direction of the passed GPIO to output, such as gpiod_set_value() can be called safely on it. The initial value of the output must be specified as raw value on the physical line without regard for the ACTIVE_LOW status.

Return 0 in case of success, else an error code.

int gpiod_direction_output(struct gpio_desc * desc, int value)¶: set the GPIO direction to output

Parameters

struct gpio_desc * desc: GPIO to set to output
int value: initial output value of the GPIO

Description

Set the direction of the passed GPIO to output, such as gpiod_set_value() can be called safely on it. The initial value of the output must be specified as the logical value of the GPIO, i.e. taking its ACTIVE_LOW status into account.

Return 0 in case of success, else an error code.

int gpiod_set_debounce(struct gpio_desc * desc, unsigned debounce)¶: sets debounce time for a GPIO

Parameters

struct gpio_desc * desc: descriptor of the GPIO for which to set debounce time
unsigned debounce: debounce time in microseconds

Return

0 on success, -ENOTSUPP if the controller doesn’t support setting the debounce time.

int gpiod_is_active_low(const struct gpio_desc * desc)¶: test whether a GPIO is active-low or not

Parameters

const struct gpio_desc * desc: the gpio descriptor to test

Description

Returns 1 if the GPIO is active-low, 0 otherwise.

int gpiod_get_raw_value(const struct gpio_desc * desc)¶: return a gpio’s raw value

Parameters

const struct gpio_desc * desc: gpio whose value will be returned

Description

Return the GPIO’s raw value, i.e. the value of the physical line disregarding its ACTIVE_LOW status, or negative errno on failure.

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

int gpiod_get_value(const struct gpio_desc * desc)¶: return a gpio’s value

Parameters

const struct gpio_desc * desc: gpio whose value will be returned

Description

Return the GPIO’s logical value, i.e. taking the ACTIVE_LOW status into account, or negative errno on failure.

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

void gpiod_set_raw_value(struct gpio_desc * desc, int value)¶: assign a gpio’s raw value

Parameters

struct gpio_desc * desc: gpio whose value will be assigned
int value: value to assign

Description

Set the raw value of the GPIO, i.e. the value of its physical line without regard for its ACTIVE_LOW status.

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

void gpiod_set_value(struct gpio_desc * desc, int value)¶: assign a gpio’s value

Parameters

struct gpio_desc * desc: gpio whose value will be assigned
int value: value to assign

Description

Set the logical value of the GPIO, i.e. taking its ACTIVE_LOW status into account

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

void gpiod_set_raw_array_value(unsigned int array_size, struct gpio_desc ** desc_array, int * value_array)¶: assign values to an array of GPIOs

Parameters

unsigned int array_size: number of elements in the descriptor / value arrays
struct gpio_desc ** desc_array: array of GPIO descriptors whose values will be assigned
int * value_array: array of values to assign

Description

Set the raw values of the GPIOs, i.e. the values of the physical lines without regard for their ACTIVE_LOW status.

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

void gpiod_set_array_value(unsigned int array_size, struct gpio_desc ** desc_array, int * value_array)¶: assign values to an array of GPIOs

Parameters

unsigned int array_size: number of elements in the descriptor / value arrays
struct gpio_desc ** desc_array: array of GPIO descriptors whose values will be assigned
int * value_array: array of values to assign

Description

Set the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status into account.

This function should be called from contexts where we cannot sleep, and will complain if the GPIO chip functions potentially sleep.

int gpiod_cansleep(const struct gpio_desc * desc)¶: report whether gpio value access may sleep

Parameters

const struct gpio_desc * desc: gpio to check

int gpiod_to_irq(const struct gpio_desc * desc)¶: return the IRQ corresponding to a GPIO

Parameters

const struct gpio_desc * desc: gpio whose IRQ will be returned (already requested)

Description

Return the IRQ corresponding to the passed GPIO, or an error code in case of error.

int gpiochip_lock_as_irq(struct gpio_chip * chip, unsigned int offset)¶: lock a GPIO to be used as IRQ

Parameters

struct gpio_chip * chip: the chip the GPIO to lock belongs to
unsigned int offset: the offset of the GPIO to lock as IRQ

Description

This is used directly by GPIO drivers that want to lock down a certain GPIO line to be used for IRQs.

void gpiochip_unlock_as_irq(struct gpio_chip * chip, unsigned int offset)¶: unlock a GPIO used as IRQ

Parameters

struct gpio_chip * chip: the chip the GPIO to lock belongs to
unsigned int offset: the offset of the GPIO to lock as IRQ

Description

This is used directly by GPIO drivers that want to indicate that a certain GPIO is no longer used exclusively for IRQ.

int gpiod_get_raw_value_cansleep(const struct gpio_desc * desc)¶: return a gpio’s raw value

Parameters

const struct gpio_desc * desc: gpio whose value will be returned

Description

Return the GPIO’s raw value, i.e. the value of the physical line disregarding its ACTIVE_LOW status, or negative errno on failure.