RA Flexible Software Package Documentation  Release v3.3.0

 
Event Link Controller (r_elc)

Functions

fsp_err_t R_ELC_Open (elc_ctrl_t *const p_ctrl, elc_cfg_t const *const p_cfg)
 
fsp_err_t R_ELC_Close (elc_ctrl_t *const p_ctrl)
 
fsp_err_t R_ELC_SoftwareEventGenerate (elc_ctrl_t *const p_ctrl, elc_software_event_t event_number)
 
fsp_err_t R_ELC_LinkSet (elc_ctrl_t *const p_ctrl, elc_peripheral_t peripheral, elc_event_t signal)
 
fsp_err_t R_ELC_LinkBreak (elc_ctrl_t *const p_ctrl, elc_peripheral_t peripheral)
 
fsp_err_t R_ELC_Enable (elc_ctrl_t *const p_ctrl)
 
fsp_err_t R_ELC_Disable (elc_ctrl_t *const p_ctrl)
 

Detailed Description

Driver for the ELC peripheral on RA MCUs. This module implements the ELC Interface.

Overview

The event link controller (ELC) uses the event requests generated by various peripheral modules as source signals to connect (link) them to different modules, allowing direct cooperation between the modules without central processing unit (CPU) intervention. The conceptual diagram below illustrates a potential setup where a pin interrupt triggers a timer which later triggers an ADC conversion and CTSU scan, while at the same time a serial communication interrupt automatically starts a data transfer. These tasks would be automatically handled without the need for polling or interrupt management.

r_elc_concept.svg
Event Link Controller Conceptual Diagram

In essence, the ELC is an array of multiplexers to route a wide variety of interrupt signals to a subset of peripheral functions. Events are linked by setting the multiplexer for the desired function to the desired signal (through R_ELC_LinkSet). The diagram below illustrates one peripheral output of the ELC. In this example, a conversion start is triggered for ADC0 Group A when the GPT0 counter overflows:

r_elc_eventset.svg
ELC Example

Features

The ELC HAL module can perform the following functions:

A variety of functions can be activated via events, including:

Note
The available sources and peripherals may differ between devices. A full list of selectable peripherals and events is available in the User's Manual for your device.
Some peripherals have specific settings related to ELC event generation and/or reception. Details on how to enable event functionality for each peripheral are located in the usage notes for the related module(s) as well as in the User's Manual for your device.

Configuration

Note
Event links will be automatically generated based on the selections made in module properties. To view the currently linked events check the Event Links tab in the RA Configuration editor.
Calling R_ELC_Open followed by R_ELC_Enable will automatically link all events shown in the Event Links tab.

To manually link an event to a peripheral at runtime perform the following steps:

  1. Configure the operation of the destination peripheral (including any configuration necessary to receive events)
  2. Use R_ELC_LinkSet to set the desired event link to the peripheral
  3. Use R_ELC_Enable to enable transmission of event signals
  4. Configure the signaling module to output the desired event (typically an interrupt)

To disable the event, either use R_ELC_LinkBreak to clear the link for a specific event or R_ELC_Disable to globally disable event linking.

Note
The ELC module needs no pin, clocking or interrupt configuration; it is merely a mechanism to connect signals between peripherals. However, when linking I/O Ports via the ELC the relevant I/O pins need to be configured as inputs or outputs.

Build Time Configurations for r_elc

The following build time configurations are defined in fsp_cfg/r_elc_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 > System > ELC Driver on r_elc

This module can be added to the Stacks tab via New Stack > Driver > System > ELC Driver on r_elc. 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
NameELC instance name must be g_elc to match elc_cfg_t data structure created in elc_data.cg_elc Module name. Fixed to g_elc.

Usage Notes

Limitations

Developers should be aware of the following limitations when using the ELC:

Examples

Basic Example

Below is a basic example of minimal use of event linking in an application.

/* This struct is automatically generated based on the events configured by peripherals in the RA Configuration editor. */
static const elc_cfg_t g_elc_cfg =
{
.link[ELC_PERIPHERAL_GPT_A] = ELC_EVENT_ICU_IRQ0,
.link[ELC_PERIPHERAL_IOPORT1] = ELC_EVENT_GPT4_COUNTER_OVERFLOW
};
void elc_basic_example (void)
{
fsp_err_t err = FSP_SUCCESS;
/* Initializes the software and sets the links defined in the control structure. */
err = R_ELC_Open(&g_elc_ctrl, &g_elc_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Create or modify a link between a peripheral function and an event source. */
err = R_ELC_LinkSet(&g_elc_ctrl, ELC_PERIPHERAL_ADC0, ELC_EVENT_GPT4_COUNTER_OVERFLOW);
assert(FSP_SUCCESS == err);
/* Globally enable event linking in the ELC. */
err = R_ELC_Enable(&g_elc_ctrl);
assert(FSP_SUCCESS == err);
}

Software-Generated Events

This example demonstrates how to use a software-generated event to signal a peripheral. This can be useful when the desired event source is not supported by the ELC hardware.

/* Interrupt handler for peripheral event not supported by the ELC */
void peripheral_isr (void)
{
fsp_err_t err;
/* Generate an event signal through software to the linked peripheral. */
assert(FSP_SUCCESS == err);
}
void elc_software_event (void)
{
fsp_err_t err = FSP_SUCCESS;
/* Open the module. */
err = R_ELC_Open(&g_elc_ctrl, &g_elc_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Link ADC0 conversion start to software event 0. */
err = R_ELC_LinkSet(&g_elc_ctrl, ELC_PERIPHERAL_ADC0, ELC_EVENT_ELC_SOFTWARE_EVENT_0);
assert(FSP_SUCCESS == err);
while (true)
{
/* Application code here. */
}
}

Data Structures

struct  elc_instance_ctrl_t
 

Data Structure Documentation

◆ elc_instance_ctrl_t

struct elc_instance_ctrl_t

ELC private control block. DO NOT MODIFY. Initialization occurs when R_ELC_Open() is called.

Function Documentation

◆ R_ELC_Open()

fsp_err_t R_ELC_Open ( elc_ctrl_t *const  p_ctrl,
elc_cfg_t const *const  p_cfg 
)

Initialize all the links in the Event Link Controller. Implements elc_api_t::open

The configuration structure passed in to this function includes links for every event source included in the ELC and sets them all at once. To set or clear an individual link use R_ELC_LinkSet and R_ELC_LinkBreak respectively.

Example:

/* Initializes the software and sets the links defined in the control structure. */
err = R_ELC_Open(&g_elc_ctrl, &g_elc_cfg);
Return values
FSP_SUCCESSInitialization was successful
FSP_ERR_ASSERTIONp_ctrl or p_cfg was NULL
FSP_ERR_ALREADY_OPENThe module is currently open

◆ R_ELC_Close()

fsp_err_t R_ELC_Close ( elc_ctrl_t *const  p_ctrl)

Globally disable ELC linking. Implements elc_api_t::close

Return values
FSP_SUCCESSThe ELC was successfully disabled
FSP_ERR_ASSERTIONp_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened

◆ R_ELC_SoftwareEventGenerate()

fsp_err_t R_ELC_SoftwareEventGenerate ( elc_ctrl_t *const  p_ctrl,
elc_software_event_t  event_number 
)

Generate a software event in the Event Link Controller. Implements elc_api_t::softwareEventGenerate

Example:

/* Generate an event signal through software to the linked peripheral. */
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSInitialization was successful
FSP_ERR_ASSERTIONInvalid event number or p_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened

◆ R_ELC_LinkSet()

fsp_err_t R_ELC_LinkSet ( elc_ctrl_t *const  p_ctrl,
elc_peripheral_t  peripheral,
elc_event_t  signal 
)

Create a single event link. Implements elc_api_t::linkSet

Example:

/* Create or modify a link between a peripheral function and an event source. */
err = R_ELC_LinkSet(&g_elc_ctrl, ELC_PERIPHERAL_ADC0, ELC_EVENT_GPT4_COUNTER_OVERFLOW);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSInitialization was successful
FSP_ERR_ASSERTIONp_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened

◆ R_ELC_LinkBreak()

fsp_err_t R_ELC_LinkBreak ( elc_ctrl_t *const  p_ctrl,
elc_peripheral_t  peripheral 
)

Break an event link. Implements elc_api_t::linkBreak

Return values
FSP_SUCCESSEvent link broken
FSP_ERR_ASSERTIONp_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened

◆ R_ELC_Enable()

fsp_err_t R_ELC_Enable ( elc_ctrl_t *const  p_ctrl)

Enable the operation of the Event Link Controller. Implements elc_api_t::enable

Return values
FSP_SUCCESSELC enabled.
FSP_ERR_ASSERTIONp_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened

◆ R_ELC_Disable()

fsp_err_t R_ELC_Disable ( elc_ctrl_t *const  p_ctrl)

Disable the operation of the Event Link Controller. Implements elc_api_t::disable

Return values
FSP_SUCCESSELC disabled.
FSP_ERR_ASSERTIONp_ctrl was NULL
FSP_ERR_NOT_OPENThe module has not been opened