Synergy Software Package User's Manual
External IRQ Framework

Table of Contents

External IRQ Framework Module Introduction

The External IRQ Framework provides a high-level API for applications using the external pin interrupts with the ThreadX RTOS and supports the external IRQ pins on the Synergy microcontroller. A callback function (sf_external_irq_callback) is available that will be called from the interrupt service routine (ISR) each time the IRQn triggers.

External IRQ Framework Module Features

  • Responds to external interrupt inputs
  • RTOS aware implementation using an internal semaphore for thread synchronization
    • Can signal internal threads
    • Can trigger transfers via the Event Link Controller (ELC)
  • Uses the port pins available on Synergy MCUs
    • Pins may differ between MCUs so refer to MCU User's Manuals for specifics
  • Supports several hardware features such as
    • Channel selection
    • Trigger conditions
    • Digital filtering
    • Auto-start
sf_external_irq_BD.png
External IRQ Framework Module Block Diagram

External IRQ Framework Module APIs Overview

The External IRQ framework module defines APIs for opening, waiting or closing the module. 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 Framework Module API Summary

Function Name Example API Call and Description
open g_sf_external_irq.p_api->open(g_sf_external_irq.p_ctrl, g_sf_external_irq.p_cfg);
Acquire mutex, then handle driver initialization at the HAL layer.
wait g_sf_external_irq.p_api->wait(g_sf_external_irq.p_ctrl, TX_WAIT_FOREVER);
Wait for the next external interrupt expiration, then return.
versionGet g_sf_external_irq.p_api->versionGet(&version);
Retrieve the API version and store it in the version pointer.
close g_sf_external_irq.p_api->close(g_sf_external_irq.p_ctrl);
Release channel mutex and close channel at HAL layer.
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_IN_USE Device in use.
SSP_ERR_NOT_OPEN Device unopened.
SSP_ERR_TIMEOUT Timeout error.
SSP_ERR_WAIT_ABORTED Suspension aborted.
SSP_ERR_UNSUPPORTED Function unsupported by the HAL driver.
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 Framework Module Operational Overview

The External IRQ framework is a set of ThreadX-aware framework APIs. The External IRQ Framework external inputs can signal, via an internal semaphore, threads or trigger transfers via the Event Link Controller (ELC). Both the External IRQ framework module and the External IRQ HAL module need to be configured for proper operation. The HAL configuration settings allow control over hardware options such as triggering level and digital filtering settings.

External IRQ Framework Module Important Operational Notes and Limitations

External IRQ Framework Module Operational Notes

  • Refer to the Datasheet for the Synergy device to be programmed 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 driver.

External IRQ Framework Module Limitations

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

Including the External IRQ Framework Module in an Application

This section describes how to include the External IRQ Framework 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 Framework 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 Framework is g_sf_external_irq0. This name can be changed in the associated Properties window.)

External IRQ Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_external_irq0 External IRQ Framework on sf_external_irq Threads New Stack> Framework> Input> External IRQ Framework on sf_external_irq

When the External IRQ Framework on sf_external_irq 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.

sf_external_irq_MS.png
External IRQ Framework Module Stack

Configuring the External IRQ Framework Module

The External IRQ Framework 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 Framework Module on sf_external_irq

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Controls whether to include code for API parameter checking.
Name g_sf_external_irq0 Framework name.
Event None, Semaphore Put

Default: Semaphore Put 		Event 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.

Configuration Settings for the External IRQ Framework Module Lower Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.

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 		Configures edge or level triggering.
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.
Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		An Interrupt priority can be registered in external_irq_cfg_t::irq_ipl.
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 Framework Module Clock Configuration

The External IRQ Framework does not require clock configuration.

External IRQ Framework Module Pin Configuration

The External IRQ Framework does not require pin configuration.

Using the External IRQ Framework Module in an Application

The steps in using the External IRQ Framework module in a typical application are:

  1. Open the External IRQ Framework module with the sf_external_irq_api_t::open API.
  2. Wait for an interrupt using the sf_external_irq_api_t::wait API.
  3. Process External IRQ event.
  4. Close the module using the sf_external_irq_api_t::close API.

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

sf_external_irq_TA.png
Flow Diagram of a Typical External IRQ Framework Module Application