RA Flexible Software Package Documentation  Release v3.1.0

 
Interrupt Controller Unit (r_icu)

Functions

fsp_err_t R_ICU_ExternalIrqOpen (external_irq_ctrl_t *const p_api_ctrl, external_irq_cfg_t const *const p_cfg)
 
fsp_err_t R_ICU_ExternalIrqEnable (external_irq_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_ICU_ExternalIrqDisable (external_irq_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_ICU_ExternalIrqCallbackSet (external_irq_ctrl_t *const p_api_ctrl, void(*p_callback)(external_irq_callback_args_t *), void const *const p_context, external_irq_callback_args_t *const p_callback_memory)
 
fsp_err_t R_ICU_ExternalIrqClose (external_irq_ctrl_t *const p_api_ctrl)
 

Detailed Description

Driver for the ICU peripheral on RA MCUs. This module implements the External IRQ Interface.

Overview

The Interrupt Controller Unit (ICU) controls which event signals are linked to the NVIC, DTC, and DMAC modules. The R_ICU software module only implements the External IRQ Interface. The external_irq interface is for configuring interrupts to fire when a trigger condition is detected on an external IRQ pin.

Note
Multiple instances are used when more than one external interrupt is needed. Configure each instance with different channels and properties as needed for the specific interrupt.

Features

Configuration

Build Time Configurations for r_icu

The following build time configurations are defined in fsp_cfg/r_icu_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.

Configurations for Driver > Input > External IRQ Driver on r_icu

This module can be added to the Stacks tab via New Stack > Driver > Input > External IRQ Driver on r_icu. Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_external_irq0 Module name.
ChannelValue must be an integer between 0 and 150 Specify the hardware channel.
Trigger
  • Falling
  • Rising
  • Both Edges
  • Low Level
Rising Select the signal edge or state that triggers an interrupt.
Digital Filtering
  • Enabled
  • Disabled
Disabled Select if the digital noise filter should be enabled.
Digital Filtering Sample Clock (Only valid when Digital Filtering is Enabled)
  • PCLK / 1
  • PCLK / 8
  • PCLK / 32
  • PCLK / 64
PCLK / 64 Select the clock divider for the digital noise filter.
CallbackName must be a valid C symbolNULL A user callback function can be provided here. If this callback function is provided, it is called from the interrupt service routine (ISR) each time the IRQn triggers
Pin Interrupt PriorityMCU Specific OptionsSelect the PIN interrupt priority.

Clock Configuration

The ICU peripheral module doesn't require any specific clock settings.

Note
The digital filter uses PCLKB as the clock source for sampling the IRQ pin.

Pin Configuration

The pin for the external interrupt channel must be configured as an input with IRQ Input Enabled.

Usage Notes

Digital Filter

The digital filter is used to reject trigger conditions that are too short. The trigger condition must be longer than three periods of the filter clock. The filter clock frequency is determined by PCLKB and the external_irq_pclk_div_t setting.

MIN_PULSE_WIDTH = EXTERNAL_IRQ_PCLKB_DIV / PCLKB_FREQUENCY * 3

DMAC/DTC

When using an External IRQ pin to trigger a DMAC/DTC transfer, the External IRQ pin must be opened before the transfer instance is opened.

Examples

Basic Example

This is a basic example of minimal use of the ICU in an application.

#define ICU_IRQN_PIN BSP_IO_PORT_02_PIN_06
#define ICU_IRQN 6
/* Called from icu_irq_isr */
void external_irq_callback (external_irq_callback_args_t * p_args)
{
(void) p_args;
g_external_irq_complete = 1;
}
void simple_example ()
{
/* Example Configuration */
{
.channel = ICU_IRQN,
.filter_enable = false,
.p_callback = external_irq_callback,
.p_context = 0,
.ipl = 0,
.irq = (IRQn_Type) 0,
};
/* Configure the external interrupt. */
fsp_err_t err = R_ICU_ExternalIrqOpen(&g_icu_ctrl, &icu_cfg);
assert(FSP_SUCCESS == err);
/* Enable the external interrupt. */
/* Enable not required when used with ELC or DMAC. */
err = R_ICU_ExternalIrqEnable(&g_icu_ctrl);
assert(FSP_SUCCESS == err);
while (0 == g_external_irq_complete)
{
/* Wait for interrupt. */
}
}

Data Structures

struct  icu_instance_ctrl_t
 

Data Structure Documentation

◆ icu_instance_ctrl_t

struct icu_instance_ctrl_t

ICU private control block. DO NOT MODIFY. Initialization occurs when R_ICU_ExternalIrqOpen is called.

Data Fields

uint32_t open
 Used to determine if channel control block is in use.
 
IRQn_Type irq
 NVIC interrupt number.
 
uint8_t channel
 Channel.
 
void const * p_context
 

Field Documentation

◆ p_context

void const* icu_instance_ctrl_t::p_context

Placeholder for user data. Passed to the user callback in external_irq_callback_args_t.

Function Documentation

◆ R_ICU_ExternalIrqOpen()

fsp_err_t R_ICU_ExternalIrqOpen ( external_irq_ctrl_t *const  p_api_ctrl,
external_irq_cfg_t const *const  p_cfg 
)

Configure an IRQ input pin for use with the external interrupt interface. Implements external_irq_api_t::open.

The Open function is responsible for preparing an external IRQ pin for operation.

Return values
FSP_SUCCESSOpen successful.
FSP_ERR_ASSERTIONOne of the following is invalid:
  • p_ctrl or p_cfg is NULL
FSP_ERR_ALREADY_OPENThe channel specified has already been opened. No configurations were changed. Call the associated Close function to reconfigure the channel.
FSP_ERR_IP_CHANNEL_NOT_PRESENTThe channel requested in p_cfg is not available on the device selected in r_bsp_cfg.h.
FSP_ERR_INVALID_ARGUMENTp_cfg->p_callback is not NULL, but ISR is not enabled. ISR must be enabled to use callback function.
Note
This function is reentrant for different channels. It is not reentrant for the same channel.

◆ R_ICU_ExternalIrqEnable()

fsp_err_t R_ICU_ExternalIrqEnable ( external_irq_ctrl_t *const  p_api_ctrl)

Enable external interrupt for specified channel at NVIC. Implements external_irq_api_t::enable.

Return values
FSP_SUCCESSInterrupt Enabled successfully.
FSP_ERR_ASSERTIONThe p_ctrl parameter was null.
FSP_ERR_NOT_OPENThe channel is not opened.
FSP_ERR_IRQ_BSP_DISABLEDRequested IRQ is not defined in this system

◆ R_ICU_ExternalIrqDisable()

fsp_err_t R_ICU_ExternalIrqDisable ( external_irq_ctrl_t *const  p_api_ctrl)

Disable external interrupt for specified channel at NVIC. Implements external_irq_api_t::disable.

Return values
FSP_SUCCESSInterrupt disabled successfully.
FSP_ERR_ASSERTIONThe p_ctrl parameter was null.
FSP_ERR_NOT_OPENThe channel is not opened.
FSP_ERR_IRQ_BSP_DISABLEDRequested IRQ is not defined in this system

◆ R_ICU_ExternalIrqCallbackSet()

fsp_err_t R_ICU_ExternalIrqCallbackSet ( external_irq_ctrl_t *const  p_api_ctrl,
void(*)(external_irq_callback_args_t *)  p_callback,
void const *const  p_context,
external_irq_callback_args_t *const  p_callback_memory 
)

Updates the user callback and has option of providing memory for callback structure. Implements external_irq_api_t::callbackSet

Return values
FSP_SUCCESSCallback updated successfully.
FSP_ERR_ASSERTIONA required pointer is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORYp_callback is non-secure and p_callback_memory is either secure or NULL.

◆ R_ICU_ExternalIrqClose()

fsp_err_t R_ICU_ExternalIrqClose ( external_irq_ctrl_t *const  p_api_ctrl)

Close the external interrupt channel. Implements external_irq_api_t::close.

Return values
FSP_SUCCESSSuccessfully closed.
FSP_ERR_ASSERTIONThe parameter p_ctrl is NULL.
FSP_ERR_NOT_OPENThe channel is not opened.