IRQ Support in Peripheral GPIO Low-Level API

IRQ Support in Peripheral GPIO Low-Level API. More...

Detailed Description

IRQ Support in Peripheral GPIO Low-Level API.

Warning

This API is not stable yet and intended for internal use only as of now.

Note

This API can only be used, if the features periph_gpio_ll_irq is used. Not every MCU will implement the features required for this API or will have a suitable driver available.

Motivation

The IRQ related GPIO Low-Level API is very similar to the one of GPIO - however two aspects have been changed (in addition to using separate port and pin parameters): First, level triggered IRQs that many MCUs support are now exposed. (Note: They can also be trivially be emulated, see the STM32 implementation as example.) Second, the configuration of the GPIO pin and the associated IRQ have been split into two functions. This allows reconfiguring the trigger of an IRQ with less overhead. This can result in reconfiguring the IRQ trigger being less effort than filtering out unneeded events and hence consume power due to longer power saving phases.

Files
file	gpio_ll_irq.h
	IRQ Support in Peripheral GPIO Low-Level API.

Typedefs
typedef void(*	gpio_ll_cb_t) (void *arg)
	Signature of event callback function that is called on IRQs.

Enumerations
enum	gpio_irq_trig_t {   GPIO_TRIGGER_EDGE_FALLING , GPIO_TRIGGER_EDGE_RISING , GPIO_TRIGGER_EDGE_BOTH , GPIO_TRIGGER_LEVEL_HIGH ,   GPIO_TRIGGER_LEVEL_LOW }
	Definition of possible IRQ triggers. More...

Functions
int	gpio_ll_irq (gpio_port_t port, uint8_t pin, gpio_irq_trig_t trig, gpio_ll_cb_t cb, void *arg)
	Set up an IRQ for the given GPIO pin and activate it.
void	gpio_ll_irq_mask (gpio_port_t port, uint8_t pin)
	Mask IRQs on the given GPIO pin.
void	gpio_ll_irq_unmask (gpio_port_t port, uint8_t pin)
	Unmask IRQs on the given GPIO pin.
void	gpio_ll_irq_unmask_and_clear (gpio_port_t port, uint8_t pin)
	Unmask IRQs on the given GPIO pin and clear pending IRQs.
void	gpio_ll_irq_off (gpio_port_t port, uint8_t pin)
	Disable IRQs on the given GPIO pin.

Typedef Documentation

gpio_ll_cb_t

typedef void(* gpio_ll_cb_t) (void *arg)

Signature of event callback function that is called on IRQs.

Parameters

[in]

arg

optional context for the callback

Warning

This function is called in IRQ context

Definition at line 88 of file gpio_ll_irq.h.

Enumeration Type Documentation

gpio_irq_trig_t

enum gpio_irq_trig_t

Definition of possible IRQ triggers.

The following features indicate support:

Trigger	Feature provided if trigger is supported
GPIO_TRIGGER_EDGE_FALLING	Always available
GPIO_TRIGGER_EDGE_RISING	Always available
GPIO_TRIGGER_EDGE_BOTH	periph_gpio_ll_irq_edge_triggered_both
GPIO_TRIGGER_LEVEL_HIGH	periph_gpio_ll_irq_level_triggered_high
GPIO_TRIGGER_LEVEL_LOW	periph_gpio_ll_irq_level_triggered_low

Enumerator
GPIO_TRIGGER_EDGE_FALLING	edge triggered IRQ on falling flanks only
GPIO_TRIGGER_EDGE_RISING	edge triggered IRQ on rising flanks only
GPIO_TRIGGER_EDGE_BOTH	edge triggered IRQ on falling AND rising flanks
GPIO_TRIGGER_LEVEL_HIGH	level triggered IRQ on high input
GPIO_TRIGGER_LEVEL_LOW	level triggered IRQ on low input

Definition at line 72 of file gpio_ll_irq.h.

Function Documentation

gpio_ll_irq()

int gpio_ll_irq	(	gpio_port_t	port,
		uint8_t	pin,
		gpio_irq_trig_t	trig,
		gpio_ll_cb_t	cb,
		void *	arg
	)

Set up an IRQ for the given GPIO pin and activate it.

Parameters

[in]	port	port the pin belongs to
[in]	pin	number of the pin to setup IRQs on
[in]	trig	define what triggers the IRQ
[in]	cb	callback that is called from interrupt context
[in]	arg	argument to be passed to the callback

Precondition

The given GPIO pin has been initialized using gpio_ll_init prior to this call

The trigger in trig is supported by the MCU

Return values

0	Success
-ENOTSUP	No external IRQs supported for port and pin
-EBUSY	All hardware entities that monitor GPIOs and issue IRQs are busy monitoring other GPIOs. Call gpio_ll_irq_off on one of those and retry.

gpio_ll_irq_mask()

void gpio_ll_irq_mask	(	gpio_port_t	port,
		uint8_t	pin
	)

Mask IRQs on the given GPIO pin.

Parameters

[in]	port	port the pin belongs to
[in]	pin	number of the pin to disable IRQs on

Note

IRQs can be re-enabled without reconfiguration using gpio_ll_irq_unmask

If IRQs are not needed for a longer term, consider using gpio_ll_irq_off instead.

gpio_ll_irq_off()

void gpio_ll_irq_off	(	gpio_port_t	port,
		uint8_t	pin
	)

Disable IRQs on the given GPIO pin.

Postcondition

Signals on the specified pin will no longer triggers IRQs until an IRQ is reconfigured using gpio_ll_irq

Parameters

[in]	port	port the pin belongs to
[in]	pin	number of the pin disable IRQs on

Note

The implementation should consume power by disabling trigger detection on the given pin.

Unlike gpio_ll_irq_mask IRQs cannot be re-enabled with a call to gpio_ll_irq_unmask.

gpio_ll_irq_unmask()

void gpio_ll_irq_unmask	(	gpio_port_t	port,
		uint8_t	pin
	)

Unmask IRQs on the given GPIO pin.

Same as gpio_ll_irq_unmask_and_clear except that IRQs that came in while masked are not lost.

Warning

On some MCUs (most notably STM32) this is impossible to implement. The feature periph_gpio_ll_irq_unmask is provided, if this function is available.

gpio_ll_irq_unmask_and_clear is a portable alternative that might suit your use case equally well.

Parameters

[in]	port	port the pin belongs to
[in]	pin	number of the pin to unmask IRQs on

gpio_ll_irq_unmask_and_clear()

void gpio_ll_irq_unmask_and_clear	(	gpio_port_t	port,
		uint8_t	pin
	)

Unmask IRQs on the given GPIO pin and clear pending IRQs.

Precondition

IRQs on the given pin have been previously configured via gpio_ll_irq

Postcondition

IRQs will be acted upon again from now on. If one or more IRQs came in while masked, this IRQs are silently lost.

Parameters

[in]	port	port the pin belongs to
[in]	pin	number of the pin to unmask IRQs on