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.

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:

ELC Example

Features

The ELC HAL module can perform the following functions:

• Initialize the ELC to a pre-defined set of links
• Create an event link between two blocks
• Break an event link between two blocks
• Generate one of two software events that interrupt the CPU
• Globally enable or disable event links

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

• General-purpose timer (GPT) control
• ADC and DAC conversion start
• Synchronized I/O port output (ports 1-4 only)
• Capacitive touch unit (CTSU) measurement activation

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:

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

Configurations for System > Event Link Controller (r_elc)

This module can be added to the Stacks tab via New Stack > System > Event Link Controller (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.

Configuration	Options	Default	Description
Name	ELC instance name must be g_elc to match elc_cfg_t data structure created in elc_data.c	g_elc	Module name. Fixed to g_elc.

Usage Notes

Limitations

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

• To link events it is necessary for the ELC and the related modules to be enabled. The ELC cannot operate if the related modules are in the module stop state or the MCU is in a low power consumption mode for which the module is stopped.
• If two modules are linked across clock domains there may be a 1 to 2 cycle delay between event signaling and reception. The delay timing is based on the frequency of the slowest clock.

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. */
    err = R_ELC_SoftwareEventGenerate(&g_elc_ctrl, ELC_SOFTWARE_EVENT_0);
    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_SUCCESS	Initialization was successful
FSP_ERR_ASSERTION	p_ctrl or p_cfg was NULL
FSP_ERR_ALREADY_OPEN	The 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_SUCCESS	The ELC was successfully disabled
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The 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. */
    err = R_ELC_SoftwareEventGenerate(&g_elc_ctrl, ELC_SOFTWARE_EVENT_0);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Initialization was successful
FSP_ERR_ASSERTION	Invalid event number or p_ctrl was NULL
FSP_ERR_NOT_OPEN	The 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_SUCCESS	Initialization was successful
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The 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_SUCCESS	Event link broken
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The 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_SUCCESS	ELC enabled.
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The 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_SUCCESS	ELC disabled.
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The module has not been opened