Synergy Software Package User's Manual
External IRQ Driver

Table of Contents

External IRQ HAL Module Introduction

The External IRQ HAL module provides an API for configuring and using external IRQ pins on Synergy MCUs. The External IRQ HAL module uses the Interrupt Controller Unit (ICU) of the Synergy MCU.

External IRQ HAL Module Features

  • Supports the external interrupt pins available on the target Synergy MCU
  • Supports multiple function options:
    • Enabling and disabling generation of an interrupt
    • Enabling and disabling the IRQ noise filter
    • Setting external pin IRQ trigger (Rising edge, falling edge or low level on the IRQ pin)
  • Supports configuring a user callback function, which will be invoked by the HAL module when an external pin interrupt is generated.
ICU_BD.png
External IRQ HAL Module Block Diagram

The following hardware features are, or are not, supported by SSP for ICU.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group Peripheral
function
interrupts 		External
pin
interrupts 		DTC and
DMAC
control 		Interrupt
sources
for NVIC 		Non-maskable
interrupts
(see notes) 		Return from
low power- mode (see notes)
S124 ✓ ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓ ✓

Notes: ⎯ The ICU module in SSP (r_icu) handles only external pin interrupts and not the other features above. ⎯ Peripheral function interrupts are controlled by BSPs for each MCU and each peripheral driver modules in SSP. ⎯ DTC or DMA control is handled by DTC or DMAC module in SSP (r_dtc or r_dmac). ⎯ Non-maskable interrupts supported in SSP are IWDT Underflow, WDT Underflow and Voltage Monitor Interrupts. Those NMIs are controlled by IWDT, WDT or LVD modules (r_iwdt, r_wdt, or r_lvd), respectively. ⎯ LVD module (r_lvd) supports the Wake Up Interrupt Enable setting. For low power mode details, see the LPM section.

MCU Group RPEST RECCST BUSSST BUSMST SPEST
S124 ⌧ N/A N/A N/A N/A
S128 ⌧ N/A N/A N/A N/A
S1JA ⌧ ⌧ ⌧ ⌧ ⌧
S3A1 ⌧ ⌧ ⌧ ⌧ ⌧
S3A3 ⌧ ⌧ ⌧ ⌧ ⌧
S3A6 ⌧ ⌧ ⌧ ⌧ ⌧
S3A7 ⌧ ⌧ ⌧ ⌧ ⌧
S5D3 ⌧ ⌧ ⌧ ⌧ ⌧
S5D5 ⌧ ⌧ ⌧ ⌧ ⌧
S5D9 ⌧ ⌧ ⌧ ⌧ ⌧
S7G2 ⌧ ⌧ ⌧ ⌧ ⌧

External IRQ HAL Module APIs Overview

The External IRQ HAL module defines APIs for opening, closing, and waiting for interrupt events from external pins. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

External IRQ HAL Module API Summary

Function Name Example API Call and Description
open g_external_irq.p_api->open(g_external_irq.p_ctrl, g_external_irq.p_cfg)
Open instance and initialize.
enable g_external_irq.p_api->enable(g_external_irq.p_ctrl)
Enable callback when IRQ occurs.
disable g_external_irq.p_api->disable(g_external_irq.p_ctrl)
Disable callback when IRQ occurs.
triggerSet g_external_irq.p_api->triggerSet(g_external_irq.p_ctrl, trigger)
Set trigger.
filterEnable g_external_irq.p_api->filterEnable(g_external_irq.p_ctrl)
Enable noise filter.
filterDisable g_external_irq.p_api->filterDisable(g_external_irq.p_ctrl)
Disable noise filter.
close g_external_irq.p_api->close(g_external_irq.p_ctrl);
Close instance.
versionGet g_external_irq.p_api->wait(&version);
Retrieve the API version with the version pointer.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS Function successful.
SSP_ERR_ASSERTION Assertion error.
SSP_ERR_INVALID_ARGUMENT Callback is not NULL but ISR is not enabled.
SSP_ERR_IN_USE Device in use.
SSP_ERR_NOT_OPEN Device unopened.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

External IRQ HAL Module Operational Overview

The External IRQ HAL module provides a set of API functions for controlling external interrupts. Interrupts can be triggered on rising edge, falling edge, both edges or low level of the input signal on the external IRQ pin. A digital-filtering function can be enabled to eliminate some noise on the input signal. A user-callback function is supported and is triggered each time an IRQ event occurs.

To trigger a transfer of data using the DMAC or DTC peripheral when the configured external IRQ event occurs, configure the DMAC or DTC transfer with the activation source set to ELC_EVENT_PORTn_IRQ (where n is the IRQ channel number.)

Other peripherals can be triggered to start from an external interrupt using the Event Link Controller (ELC.) Refer to the SSP User Manual User Guide for the ELC HAL module for more information.

External IRQ HAL Module Important Operational Notes and Limitations

External IRQ HAL Module Operational Notes

  • Refer to the datasheet for the target Synergy device to find the port pins which support the external interrupt functions and to obtain the external IRQ number for a given port pin.
  • The external IRQ number corresponds to the channel setting in the ISDE Properties window for the External IRQ HAL module.
  • The PORTn (where n is the IRQ number) interrupt must be enabled in the BSP to notify the module that the anticipated hardware event has occurred.
  • A user-callback function can be registered in the external_irq_api_t::open API. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the IRQn triggers.
    • Note
      Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can adversely affect the responsiveness of the system.

External IRQ HAL Module Limitations

  • Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the External IRQ HAL Module in an Application

This section describes how to include the External IRQ HAL Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the External IRQ Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the External IRQ Driver is g_icu0. This name can be changed in the associated Properties window.)

External IRQ HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
r_icu0 External IRQ Driver on r_icu Threads New Stack> Driver> Input> External IRQ Driver on r_icu

When the External IRQ Driver on r_icu is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

ICU_MS.png
External IRQ HAL Module Stack

Configuring the External IRQ HAL Module

The External IRQ HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the External IRQ HAL Module on r_icu

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Parameter checking setting enables or disables the addition of parameter checking code.
Name g_external_irq0 Module name.
Channel 0 Specifies the hardware IRQ channel used.
Trigger Falling, Rising, Both Edges, Low Level

Default: Rising 		Selection for trigger event mode
Digital Filtering Enabled, Disabled

Default: Disabled 		Digital filter enable/disable.
Digital Filtering Sample Clock (Only valid when Digital Filtering is Enabled) PCLK/1, PLCK/8, PLCK/32, PCLK/64

Default: PCKL/64 		Sets noise filter sampling period.
Interrupt enabled after initialization True, False

Default: True 		Determines if the interrupt is enabled immediately after initialization.
Callback NULL A user callback function can be registered in external_irq_api_t::open. If this callback function is provided, it is called from the interrupt service routine (ISR) each time the IRQn triggers.

Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Pin Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

External IRQ HAL Module Clock Configuration

The IRQ peripheral module does not require any specific clock settings.

External IRQ HAL Module Pin Configuration

The External IRQ peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the IRQ pins.

Pin Selection for the External IRQ HAL Module on r_icu

Resource ISDE Tab Pin selection Sequence
IRQ Pins Select Peripherals> Input: IRQ> IRQ0
Note
The selection sequence assumes IRQ0 is the desired hardware target for the driver.

Pin Configuration Settings for the External IRQ HAL Module on r_icu

Property Value Description
Operation Mode Disabled, Enabled

Default: Disabled 		Select Enabled to enable interrupts.
NMI None, P200

Default: None 		Non-maskable interrupt Pin.
IRQ00:14 None, Pnn, Pmm

Default: None 		Interrupt request Pin.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Using the External IRQ HAL Module in an Application

The typical steps in using the External IRQ HAL module in an application are:

  1. Initialize the External IRQ HAL module using the external_irq_api_t::open API.
  2. Enable the IRQ (if needed) with the external_irq_api_t::enable API.
  3. Enable the noise filter (if needed) with the external_irq_api_t::filterEnable API.
  4. Change the trigger condition (only if the module is closed previously to avoid any false events) with the external_irq_api_t::triggerSet API.
  5. Disable the noise filter (if enabled) with external_irq_api_t::filterDisable API.
  6. Close the module (if needed) with the external_irq_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

ICU_TA.png
Flow Diagram of a Typical External IRQ HAL Module Application