General Purpose Input/Output (GPIO)¶
Contents:
Core¶
-
struct
gpio_irq_chip
¶ GPIO interrupt controller
Definition
struct gpio_irq_chip {
struct irq_chip *chip;
struct irq_domain *domain;
const struct irq_domain_ops *domain_ops;
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;
void *parent_handler_data;
unsigned int num_parents;
unsigned int parent_irq;
unsigned int *parents;
unsigned int *map;
bool threaded;
bool need_valid_mask;
unsigned long *valid_mask;
unsigned int first;
void (*irq_enable)(struct irq_data *data);
void (*irq_disable)(struct irq_data *data);
};
Members
chip
- GPIO IRQ chip implementation, provided by GPIO driver.
domain
- Interrupt translation domain; responsible for mapping between GPIO hwirq number and Linux IRQ number.
domain_ops
- Table of interrupt domain operations for this IRQ chip.
handler
- The IRQ handler to use (often a predefined IRQ core function) for GPIO IRQs, provided by GPIO driver.
default_type
- Default IRQ triggering type applied during GPIO driver initialization, provided by GPIO driver.
lock_key
- Per GPIO IRQ chip lockdep class for IRQ lock.
request_key
- Per GPIO IRQ chip lockdep class for IRQ request.
parent_handler
- The interrupt handler for the GPIO chip’s parent interrupts, may be NULL if the parent interrupts are nested rather than cascaded.
parent_handler_data
- Data associated, and passed to, the handler for the parent interrupt.
num_parents
- The number of interrupt parents of a GPIO chip.
parent_irq
- For use by
gpiochip_set_cascaded_irqchip()
parents
- A list of interrupt parents of a GPIO chip. This is owned by the driver, so the core will only reference this list, not modify it.
map
- A list of interrupt parents for each line of a GPIO chip.
threaded
- True if set the interrupt handling uses nested threads.
need_valid_mask
- If set core allocates valid_mask with all bits set to one.
valid_mask
- If not
NULL
holds bitmask of GPIOs which are valid to be included in IRQ domain of the chip. first
- Required for static IRQ allocation. If set,
irq_domain_add_simple()
will allocate and map all IRQs during initialization. irq_enable
- Store old irq_chip irq_enable callback
irq_disable
- Store old irq_chip irq_disable callback
-
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);
int (*get_multiple)(struct gpio_chip *chip,unsigned long *mask, unsigned long *bits);
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 (*init_valid_mask)(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);
bool be_bits;
void __iomem *reg_dat;
void __iomem *reg_set;
void __iomem *reg_clr;
void __iomem *reg_dir;
bool bgpio_dir_inverted;
int bgpio_bits;
spinlock_t bgpio_lock;
unsigned long bgpio_data;
unsigned long bgpio_dir;
#endif;
#ifdef CONFIG_GPIOLIB_IRQCHIP;
struct gpio_irq_chip irq;
#endif;
bool need_valid_mask;
unsigned long *valid_mask;
#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. It is recommended to always implement this function, even on input-only or output-only gpio chips.
direction_input
- configures signal “offset” as input, or returns error This can be omitted on input-only or output-only gpio chips.
direction_output
- configures signal “offset” as output, or returns error This can be omitted on input-only or output-only gpio chips.
get
- returns value for signal “offset”, 0=low, 1=high, or negative error
get_multiple
- reads values for multiple signals defined by “mask” and stores them in “bits”, returns 0 on success 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
be_bits
- if the generic GPIO has big endian bit order (bit 31 is representing line 0, bit 30 is line 1 ... bit 0 is line 31) this is set to true by the generic GPIO core. It is for internal housekeeping only.
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_dir_inverted
- indicates that the direction register is inverted (gpiolib private state variable)
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.
irq
- Integrates interrupt chip functionality with the GPIO chip. Can be used to handle IRQs for most practical cases.
need_valid_mask
- If set core allocates valid_mask with all its values initialized
with
init_valid_mask()
or set to one ifinit_valid_mask()
is not defined valid_mask
- If not
NULL
holds bitmask of GPIOs which are valid to be used from the chip. 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.
-
gpiochip_add_data
(chip, data)¶ register a gpio_chip
Parameters
chip
- the chip to register, with chip->base initialized
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.
-
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
Returns 0 for output, 1 for input, or an error code in case of error.
This function may sleep if gpiod_cansleep()
is true.
Parameters
struct gpio_chip * chip
- GPIO chip
Return
The per-subdriver data for the 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
gpiochip_add_data()
Parameters
struct device * dev
- pointer to the device that gpio_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.
-
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_irq_map
(struct irq_domain * d, unsigned int irq, irq_hw_number_t hwirq)¶ maps an IRQ into a GPIO irqchip
Parameters
struct irq_domain * d
- the irqdomain used by this irqchip
unsigned int irq
- the global irq number used by this GPIO irqchip irq
irq_hw_number_t hwirq
- the local IRQ/GPIO line offset on this gpiochip
Description
This function will set up the mapping for a certain IRQ line on a gpiochip by assigning the gpiochip as chip data, and using the irqchip stored inside the gpiochip.
-
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 threaded, struct lock_class_key * lock_key, struct lock_class_key * request_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 threaded
- whether this irqchip uses a nested thread handler
struct lock_class_key * lock_key
- lockdep class for IRQ lock
struct lock_class_key * request_key
- lockdep class for IRQ request
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
Description
Calling this function directly from a DeviceTree-supported pinctrl driver is DEPRECATED. Please see Section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind pinctrl and gpio drivers via the “gpio-ranges” property.
-
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.
Calling this function directly from a DeviceTree-supported pinctrl driver is DEPRECATED. Please see Section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind pinctrl and gpio drivers via the “gpio-ranges” property.
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_set_transitory
(struct gpio_desc * desc, bool transitory)¶ Lose or retain GPIO state on suspend or reset
Parameters
struct gpio_desc * desc
- descriptor of the GPIO for which to configure persistence
bool transitory
- True to lose state on suspend or reset, false for persistence
Return
0 on success, otherwise a negative error code.
-
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.
-
int
gpiod_get_raw_array_value
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ read raw values from an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be read
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap to store the read values
Description
Read the raw values of the GPIOs, i.e. the values of the physical lines without regard for their ACTIVE_LOW status. Return 0 in case of success, else an error code.
This function should be called from contexts where we cannot sleep, and it will complain if the GPIO chip functions potentially sleep.
-
int
gpiod_get_array_value
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ read values from an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be read
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap to store the read values
Description
Read the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status into account. Return 0 in case of success, else an error code.
This function should be called from contexts where we cannot sleep, and it 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, OPEN_DRAIN and OPEN_SOURCE flags 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_set_raw_array_value
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ assign values to an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be assigned
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap 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.
-
int
gpiod_set_array_value
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ assign values to an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be assigned
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap 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
-
void
gpiod_set_consumer_name
(struct gpio_desc * desc, const char * name)¶ set the consumer name for the descriptor
Parameters
struct gpio_desc * desc
- gpio to set the consumer name on
const char * name
- the new consumer name
-
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.
This function is to be called from contexts that can sleep.
-
int
gpiod_get_value_cansleep
(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 is to be called from contexts that can sleep.
-
int
gpiod_get_raw_array_value_cansleep
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ read raw values from an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be read
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap to store the read values
Description
Read the raw values of the GPIOs, i.e. the values of the physical lines without regard for their ACTIVE_LOW status. Return 0 in case of success, else an error code.
This function is to be called from contexts that can sleep.
-
int
gpiod_get_array_value_cansleep
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ read values from an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be read
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap to store the read values
Description
Read the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status into account. Return 0 in case of success, else an error code.
This function is to be called from contexts that can sleep.
-
void
gpiod_set_raw_value_cansleep
(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 is to be called from contexts that can sleep.
-
void
gpiod_set_value_cansleep
(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 is to be called from contexts that can sleep.
-
int
gpiod_set_raw_array_value_cansleep
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ assign values to an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be assigned
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap 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 is to be called from contexts that can sleep.
-
int
gpiod_set_array_value_cansleep
(unsigned int array_size, struct gpio_desc ** desc_array, struct gpio_array * array_info, unsigned long * value_bitmap)¶ assign values to an array of GPIOs
Parameters
unsigned int array_size
- number of elements in the descriptor array / value bitmap
struct gpio_desc ** desc_array
- array of GPIO descriptors whose values will be assigned
struct gpio_array * array_info
- information on applicability of fast bitmap processing path
unsigned long * value_bitmap
- bitmap of values to assign
Description
Set the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status into account.
This function is to be called from contexts that can sleep.
-
void
gpiod_add_lookup_table
(struct gpiod_lookup_table * table)¶ register GPIO device consumers
Parameters
struct gpiod_lookup_table * table
- table of consumers to register
-
void
gpiod_remove_lookup_table
(struct gpiod_lookup_table * table)¶ unregister GPIO device consumers
Parameters
struct gpiod_lookup_table * table
- table of consumers to unregister
-
void
gpiod_add_hogs
(struct gpiod_hog * hogs)¶ register a set of GPIO hogs from machine code
Parameters
struct gpiod_hog * hogs
- table of gpio hog entries with a zeroed sentinel at the end
-
int
gpiod_count
(struct device * dev, const char * con_id)¶ return the number of GPIOs associated with a device / function or -ENOENT if no GPIO has been assigned to the requested function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
-
struct gpio_desc *
gpiod_get
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ obtain a GPIO for a given GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Return the GPIO descriptor corresponding to the function con_id of device
dev, -ENOENT if no GPIO has been assigned to the requested function, or
another IS_ERR()
code if an error occurred while trying to acquire the GPIO.
-
struct gpio_desc *
gpiod_get_optional
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ obtain an optional GPIO for a given GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
This is equivalent to gpiod_get()
, except that when no GPIO was assigned to
the requested function it will return NULL. This is convenient for drivers
that need to handle optional GPIOs.
-
struct gpio_desc *
gpiod_get_index
(struct device * dev, const char * con_id, unsigned int idx, enum gpiod_flags flags)¶ obtain a GPIO from a multi-index GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
unsigned int idx
- index of the GPIO to obtain in the consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
This variant of gpiod_get()
allows to access GPIOs other than the first
defined one for functions that define several GPIOs.
Return a valid GPIO descriptor, -ENOENT if no GPIO has been assigned to the
requested function and/or index, or another IS_ERR()
code if an error
occurred while trying to acquire the GPIO.
-
struct gpio_desc *
gpiod_get_from_of_node
(struct device_node * node, const char * propname, int index, enum gpiod_flags dflags, const char * label)¶ obtain a GPIO from an OF node
Parameters
struct device_node * node
- handle of the OF node
const char * propname
- name of the DT property representing the GPIO
int index
- index of the GPIO to obtain for the consumer
enum gpiod_flags dflags
- GPIO initialization flags
const char * label
- label to attach to the requested GPIO
Return
On successful request the GPIO pin is configured in accordance with provided dflags. If the node does not have the requested GPIO property, NULL is returned.
In case of error an ERR_PTR()
is returned.
-
struct gpio_desc *
fwnode_get_named_gpiod
(struct fwnode_handle * fwnode, const char * propname, int index, enum gpiod_flags dflags, const char * label)¶ obtain a GPIO from firmware node
Parameters
struct fwnode_handle * fwnode
- handle of the firmware node
const char * propname
- name of the firmware property representing the GPIO
int index
- index of the GPIO to obtain for the consumer
enum gpiod_flags dflags
- GPIO initialization flags
const char * label
- label to attach to the requested GPIO
Description
This function can be used for drivers that get their configuration from opaque firmware.
The function properly finds the corresponding GPIO using whatever is the underlying firmware interface and then makes sure that the GPIO descriptor is requested before it is returned to the caller.
Return
On successful request the GPIO pin is configured in accordance with provided dflags.
In case of error an ERR_PTR()
is returned.
-
struct gpio_desc *
gpiod_get_index_optional
(struct device * dev, const char * con_id, unsigned int index, enum gpiod_flags flags)¶ obtain an optional GPIO from a multi-index GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
unsigned int index
- index of the GPIO to obtain in the consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
This is equivalent to gpiod_get_index()
, except that when no GPIO with the
specified index was assigned to the requested function it will return NULL.
This is convenient for drivers that need to handle optional GPIOs.
-
struct gpio_descs *
gpiod_get_array
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ obtain multiple GPIOs from a multi-index GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
This function acquires all the GPIOs defined under a given function.
Return a struct gpio_descs containing an array of descriptors, -ENOENT if
no GPIO has been assigned to the requested function, or another IS_ERR()
code if an error occurred while trying to acquire the GPIOs.
-
struct gpio_descs *
gpiod_get_array_optional
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ obtain multiple GPIOs from a multi-index GPIO function
Parameters
struct device * dev
- GPIO consumer, can be NULL for system-global GPIOs
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
This is equivalent to gpiod_get_array()
, except that when no GPIO was
assigned to the requested function it will return NULL.
-
void
gpiod_put
(struct gpio_desc * desc)¶ dispose of a GPIO descriptor
Parameters
struct gpio_desc * desc
- GPIO descriptor to dispose of
Description
No descriptor can be used after gpiod_put()
has been called on it.
-
void
gpiod_put_array
(struct gpio_descs * descs)¶ dispose of multiple GPIO descriptors
Parameters
struct gpio_descs * descs
- struct gpio_descs containing an array of descriptors
ACPI support¶
-
void
acpi_gpiochip_request_interrupts
(struct gpio_chip * chip)¶ Register isr for gpio chip ACPI events
Parameters
struct gpio_chip * chip
- GPIO chip
Description
ACPI5 platforms can use GPIO signaled ACPI events. These GPIO interrupts are handled by ACPI event methods which need to be called from the GPIO chip’s interrupt handler. acpi_gpiochip_request_interrupts finds out which gpio pins have acpi event methods and assigns interrupt handlers that calls the acpi event methods for those pins.
Parameters
struct gpio_chip * chip
- GPIO chip
Description
Free interrupts associated with GPIO ACPI event method for the given GPIO chip.
-
int
acpi_dev_gpio_irq_get
(struct acpi_device * adev, int index)¶ Find GpioInt and translate it to Linux IRQ number
Parameters
struct acpi_device * adev
- pointer to a ACPI device to get IRQ from
int index
- index of GpioInt resource (starting from
0
)
Description
If the device has one or more GpioInt resources, this function can be used to translate from the GPIO offset in the resource to the Linux IRQ number.
The function is idempotent, though each time it runs it will configure GPIO pin direction according to the flags in GpioInt resource.
Return
Linux IRQ number (> 0
) on success, negative errno on failure.
Device tree support¶
-
int
of_gpio_simple_xlate
(struct gpio_chip * gc, const struct of_phandle_args * gpiospec, u32 * flags)¶ translate gpiospec to the GPIO number and flags
Parameters
struct gpio_chip * gc
- pointer to the gpio_chip structure
const struct of_phandle_args * gpiospec
- GPIO specifier as found in the device tree
u32 * flags
- a flags pointer to fill in
Description
This is simple translation function, suitable for the most 1:1 mapped GPIO chips. This function performs only one sanity check: whether GPIO is less than ngpios (that is specified in the gpio_chip).
-
int
of_mm_gpiochip_add_data
(struct device_node * np, struct of_mm_gpio_chip * mm_gc, void * data)¶ Add memory mapped GPIO chip (bank)
Parameters
struct device_node * np
- device node of the GPIO chip
struct of_mm_gpio_chip * mm_gc
- pointer to the of_mm_gpio_chip allocated structure
void * data
- driver data to store in the struct gpio_chip
Description
To use this function you should allocate and fill mm_gc with:
- In the gpio_chip structure: - all the callbacks - of_gpio_n_cells - of_xlate callback (optional)
- In the of_mm_gpio_chip structure: - save_regs callback (optional)
If succeeded, this function will map bank’s memory and will do all necessary work for you. Then you’ll able to use .regs to manage GPIOs from the callbacks.
-
void
of_mm_gpiochip_remove
(struct of_mm_gpio_chip * mm_gc)¶ Remove memory mapped GPIO chip (bank)
Parameters
struct of_mm_gpio_chip * mm_gc
- pointer to the of_mm_gpio_chip allocated structure
Device-managed API¶
-
struct gpio_desc *
devm_gpiod_get
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ Resource-managed
gpiod_get()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get()
. GPIO descriptors returned from this function are
automatically disposed on driver detach. See gpiod_get()
for detailed
information about behavior and return values.
-
struct gpio_desc *
devm_gpiod_get_optional
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ Resource-managed
gpiod_get_optional()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get_optional()
. GPIO descriptors returned from this function
are automatically disposed on driver detach. See gpiod_get_optional()
for
detailed information about behavior and return values.
-
struct gpio_desc *
devm_gpiod_get_index
(struct device * dev, const char * con_id, unsigned int idx, enum gpiod_flags flags)¶ Resource-managed
gpiod_get_index()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
unsigned int idx
- index of the GPIO to obtain in the consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get_index()
. GPIO descriptors returned from this function are
automatically disposed on driver detach. See gpiod_get_index()
for detailed
information about behavior and return values.
-
struct gpio_desc *
devm_gpiod_get_from_of_node
(struct device * dev, struct device_node * node, const char * propname, int index, enum gpiod_flags dflags, const char * label)¶ obtain a GPIO from an OF node
Parameters
struct device * dev
- device for lifecycle management
struct device_node * node
- handle of the OF node
const char * propname
- name of the DT property representing the GPIO
int index
- index of the GPIO to obtain for the consumer
enum gpiod_flags dflags
- GPIO initialization flags
const char * label
- label to attach to the requested GPIO
Return
On successful request the GPIO pin is configured in accordance with provided dflags.
In case of error an ERR_PTR()
is returned.
-
struct gpio_desc *
devm_fwnode_get_index_gpiod_from_child
(struct device * dev, const char * con_id, int index, struct fwnode_handle * child, enum gpiod_flags flags, const char * label)¶ get a GPIO descriptor from a device’s child node
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
int index
- index of the GPIO to obtain in the consumer
struct fwnode_handle * child
- firmware node (child of dev)
enum gpiod_flags flags
- GPIO initialization flags
const char * label
- label to attach to the requested GPIO
Description
GPIO descriptors returned from this function are automatically disposed on driver detach.
On successful request the GPIO pin is configured in accordance with provided flags.
-
struct gpio_desc *
devm_gpiod_get_index_optional
(struct device * dev, const char * con_id, unsigned int index, enum gpiod_flags flags)¶ Resource-managed
gpiod_get_index_optional()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
unsigned int index
- index of the GPIO to obtain in the consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get_index_optional()
. GPIO descriptors returned from this
function are automatically disposed on driver detach. See
gpiod_get_index_optional()
for detailed information about behavior and
return values.
-
struct gpio_descs *
devm_gpiod_get_array
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ Resource-managed
gpiod_get_array()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get_array()
. GPIO descriptors returned from this function are
automatically disposed on driver detach. See gpiod_get_array()
for detailed
information about behavior and return values.
-
struct gpio_descs *
devm_gpiod_get_array_optional
(struct device * dev, const char * con_id, enum gpiod_flags flags)¶ Resource-managed
gpiod_get_array_optional()
Parameters
struct device * dev
- GPIO consumer
const char * con_id
- function within the GPIO consumer
enum gpiod_flags flags
- optional GPIO initialization flags
Description
Managed gpiod_get_array_optional()
. GPIO descriptors returned from this
function are automatically disposed on driver detach.
See gpiod_get_array_optional()
for detailed information about behavior and
return values.
-
void
devm_gpiod_put
(struct device * dev, struct gpio_desc * desc)¶ Resource-managed
gpiod_put()
Parameters
struct device * dev
- GPIO consumer
struct gpio_desc * desc
- GPIO descriptor to dispose of
Description
Dispose of a GPIO descriptor obtained with devm_gpiod_get()
or
devm_gpiod_get_index()
. Normally this function will not be called as the GPIO
will be disposed of by the resource management code.
-
void
devm_gpiod_put_array
(struct device * dev, struct gpio_descs * descs)¶ Resource-managed
gpiod_put_array()
Parameters
struct device * dev
- GPIO consumer
struct gpio_descs * descs
- GPIO descriptor array to dispose of
Description
Dispose of an array of GPIO descriptors obtained with devm_gpiod_get_array()
.
Normally this function will not be called as the GPIOs will be disposed of
by the resource management code.
-
int
devm_gpio_request
(struct device * dev, unsigned gpio, const char * label)¶ request a GPIO for a managed device
Parameters
struct device * dev
- device to request the GPIO for
unsigned gpio
- GPIO to allocate
const char * label
- the name of the requested GPIO
Description
Except for the extra dev argument, this function takes the same arguments and performs the same function as
gpio_request()
. GPIOs requested with this function will be automatically freed on driver detach.If an GPIO allocated with this function needs to be freed separately,
devm_gpio_free()
must be used.
-
int
devm_gpio_request_one
(struct device * dev, unsigned gpio, unsigned long flags, const char * label)¶ request a single GPIO with initial setup
Parameters
struct device * dev
- device to request for
unsigned gpio
- the GPIO number
unsigned long flags
- GPIO configuration as specified by GPIOF_*
const char * label
- a literal description string of this GPIO
Parameters
struct device * dev
- device to free GPIO for
unsigned int gpio
- GPIO to free
Description
Except for the extra dev argument, this function takes the same arguments and performs the same function asgpio_free()
. This function instead ofgpio_free()
should be used to manually free GPIOs allocated withdevm_gpio_request()
.
sysfs helpers¶
-
int
gpiod_export
(struct gpio_desc * desc, bool direction_may_change)¶ export a GPIO through sysfs
Parameters
struct gpio_desc * desc
- GPIO to make available, already requested
bool direction_may_change
- true if userspace may change GPIO direction
Context
arch_initcall or later
Description
When drivers want to make a GPIO accessible to userspace after they have requested it – perhaps while debugging, or as part of their public interface – they may use this routine. If the GPIO can change direction (some can’t) and the caller allows it, userspace will see “direction” sysfs attribute which may be used to change the gpio’s direction. A “value” attribute will always be provided.
Returns zero on success, else an error.
-
int
gpiod_export_link
(struct device * dev, const char * name, struct gpio_desc * desc)¶ create a sysfs link to an exported GPIO node
Parameters
struct device * dev
- device under which to create symlink
const char * name
- name of the symlink
struct gpio_desc * desc
- GPIO to create symlink to, already exported
Description
Set up a symlink from /sys/.../dev/name to /sys/class/gpio/gpioN node. Caller is responsible for unlinking.
Returns zero on success, else an error.
-
void
gpiod_unexport
(struct gpio_desc * desc)¶ reverse effect of
gpiod_export()
Parameters
struct gpio_desc * desc
- GPIO to make unavailable
Description
This is implicit on gpiod_free()
.