Loading...
Searching...
No Matches
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]argoptional 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

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]portport the pin belongs to
[in]pinnumber of the pin to setup IRQs on
[in]trigdefine what triggers the IRQ
[in]cbcallback that is called from interrupt context
[in]argargument 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
0Success
-ENOTSUPNo external IRQs supported for port and pin
-EBUSYAll 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]portport the pin belongs to
[in]pinnumber 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]portport the pin belongs to
[in]pinnumber 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]portport the pin belongs to
[in]pinnumber 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]portport the pin belongs to
[in]pinnumber of the pin to unmask IRQs on