Timer Driver on r_agt

Table of Contents

• AGT HAL Module Introduction
  • AGT HAL Module Features
  • AGT Hardware support details
• AGT HAL Module APIs Overview
• AGT HAL Module Operational Overview
  • AGT HAL Module Important Operational Notes and Limitations
    • AGT HAL Module Operational Notes
    • AGT HAL Module Limitations
• Including the AGT HAL Module in an Application
• Configuring the AGT HAL Module
  • AGT HAL Module Clock Configuration
  • AGT HAL Module Pin Configuration
• Using the AGT HAL Module in an Application

AGT HAL Module Introduction

The AGT HAL module implements a high-level API for timing applications and uses the AGT peripheral on a Synergy MCU. A user-defined callback can be created to respond to a timer event.

AGT HAL Module Features

• Configures a timer for a set period and generates one of the following events when the period expires:
  • Interrupt the CPU, which calls a user-callback function (if provided)
  • Toggle a port pin
  • Transfer data using DMAC/DTC (if configured with transfer interface)
  • Start another peripheral (if configured with events and peripheral definitions)
• Multiple Channels: 16-bit x 2 channels
  • Channel 1 can be clocked by the channel 0 underflow, creating a cascaded 32-bit timer
• Core Clock: Can be clocked using PCLKB, LOCO, or Fsub. When clocked by LOCO or Fsub, it can be used to wake up the MCU from sleep modes

AGT HAL Module Block Diagram

AGT Hardware support details

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

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Timer Mode	Pulse Output Mode	Event Counter Mode	Pulse width measurement mode
S124	✓	✓	⌧	⌧
S128	✓	✓	⌧	⌧
S1JA	✓	✓	⌧	⌧
S3A1	✓	✓	⌧	⌧
S3A3	✓	✓	⌧	⌧
S3A6	✓	✓	⌧	⌧
S3A7	✓	✓	⌧	⌧
S5D3	✓	✓	⌧	⌧
S5D5	✓	✓	⌧	⌧
S5D9	✓	✓	⌧	⌧
S7G2	✓	✓	⌧	⌧

MCU Group	Pulse period measurement mode	Event link function through ELC HAL driver	Compare/Match Function
S124	⌧	⌧	✓
S128	⌧	⌧	✓
S1JA	⌧	⌧	✓
S3A1	⌧	⌧	✓
S3A3	⌧	⌧	✓
S3A6	⌧	⌧	✓
S3A7	⌧	⌧	✓
S5D3	⌧	⌧	✓
S5D5	⌧	⌧	✓
S5D9	⌧	⌧	✓
S7G2	⌧	⌧	✓

AGT HAL Module APIs Overview

The AGT HAL module defines APIs for opening, closing, starting and stopping timers. 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.

AGT HAL Module API Summary

Function Name	Example API Call and Description
open	g_timer0.p_api->open(g_timer0.p_ctrl, g_timer0.p_cfg) Initial configuration.
stop	g_timer0.p_api->stop(g_timer0.p_ctrl) Stop the counter.
start	g_timer0.p_api->start(g_timer0.p_ctrl) Start the counter.
reset	g_timer0.p_api->reset(g_timer0.p_ctrl) Reset the counter initial value.
counterGet	g_timer0.p_api->counterGet(&value) Get current counter value and store it in the provided pointer, value.
periodSet	g_timer0.p_api->periodSet(g_timer0.p_ctrl, period, unit) Set the time until the timer expires.
dutyCycleSet	g_timer0.p_api->dutyCycleSet(g_timer0.p_ctrl, period, unit, pin) Sets the time until the duty cycle expires.
infoGet	g_timer0.p_api->infoGet(&info) Get the time until the timer expires in clock counts and store it in provided pointer, info.
close	g_timer0.p_api->close(g_timer0.p_ctrl) Allows driver to be reconfigured and may reduce power consumption.
versionGet	g_timer0.p_api->versionGet(g_timer0.p_ctrl, &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	Operation is successful.
SSP_ERR_ASSERTION	Parameter is NULL or configuration setting is not allowed.
SSP_ERR_IN_USE	The channel specified is already open.
SSP_ERR_IRQ_BSP_DISABLED	A required interrupt is not enabled in the BSP.
SSP_ERROR_NOT_OPEN	The channel is not open.
SSP_ERR_INVALID_ARG	Invalid argument provided.
SSP_ERR_INVALID_HW_CONDITION	Invalid hardware setting detected.
SSP_ERR_INVALID_PTR	A pointer parameter was NULL, but needed a non-NULL value.

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.

AGT HAL Module Operational Overview

The AGT HAL module configures a timer to a user-specified period. When the period elapses, the CPU can be interrupted, a port pin can be toggled, a transfer of data using the DMAC or DTC can be initiated, or another peripheral can be triggered to begin operation.

The following figure shows a flowchart for toggling a port pin or generating a CPU interrupt after a specified period. This flowchart is appropriate for both AGT and GPT counters. (Replace the GPT references with AGT references for AGT operation.  AGT is a down counter so change overflow to underflow.)

AGT HAL Module Flow Chart

Two different timer modules, the GPT and the AGT, are supported in the SSP. The following sections provide information on both modules so that the developer can compare and contrast the capabilities of each module for a particular application. For additional information on the GPT, refer to the GPT User's Guide.

The GPT module is recommended for most generic timer applications, but either module can be used for a basic timer functionality. The use cases in which one timer module would be preferred over the other are described as follows:

Selecting the GPT Timer Module

The GPT module uses a high-resolution 32-bit counter that can only be clocked by PCLKA. There are more GPT channels than AGT channels on Synergy devices, so using the GPT is less likely to cause a resource conflict.

Selecting the AGT Timer Module

The AGT module uses a 16-bit counter that can be clocked by PCLKB, LOCO or Fsub. If clocked by LOCO or Fsub, the AGT interrupt can be used to wake the MCU from sleep modes. There are two channels, and channel 1 can be clocked by channel 0 underflow, effectively creating a 32-bit cascaded timer.

AGT HAL Module Important Operational Notes and Limitations

AGT HAL Module Operational Notes

The maximum time period depends on the timer type and the input clock frequency.

• On a GPT with 32-bit resolution with PCLKA running at 120 MHz, the maximum period is approximately 36650 seconds, which is just over 10 hours.
• On a GPT with 16-bit resolution with PCLKA running at 32 MHz, the maximum period is approximately 2.09 seconds.
• On an AGT with 16-bit resolution with PCLKB running at 60 MHz, the maximum period is approximately 8.7 ms.
• On an AGT with 16-bit resolution with Fsub or LOCO at 32 kHz as its count source, the maximum period is approximately 262 seconds using pre-scalar up to 128.

The AGT counter underflow interrupt for the selected channel used must be enabled in the BSP in the following situations:

• To get a software interrupt when the timer period has elapsed.
• To use one-shot mode.

When the count source selected as AGTO Fsub or AGTO LOCO, turn on the count source using call cgc_api_t::clockStart API before calling timer_api_t::open.

When the AGTn AGTI interrupt is enabled in the BSP, the corresponding ISR is defined in the timer driver. The ISR calls a user-callback function if one was registered in open.

Note

Interrupts may be skipped when used with the DTC peripheral with the IRQ set to TRANSFER_IRQ_END.

AGT Output Timer Signal

If the timer output is configured, (AGTO Output Enabled set to true) the output pin starts at a high level if the output inverted is configured to True and a low level if it is configured to False. The output pin toggles every time the period elapses, beginning with the first time the period elapses after the timer is started.

In one-shot mode, the output is also configured to toggle when the timer starts counting. This generates a pulse - the timer toggles from the stop level when counting begins and toggles back to the stop level when counting ends.

Timer Period Calculation

The timer period is defined as the time until the timer expires. When output compare is used, the output pin toggles once per period, so the traditional period (from rising edge to rising edge) is twice the period specified in the software.

Runtime period calculation based on the current clock settings is available from timer_api_t::open and timer_api_t::periodSet.

If the specified timer period is different than the raw counts, the period is calculated using the current timer clock frequency (see Configuring the GPT Clocks or Configuring the AGT Clocks). The current timer clock frequency is determined using systemClockFreqGet. This frequency is used in the appropriate formula from the following table as clk_freq_hz.

Timer Period Calculation

Timer Units	Description
TIMER_UNIT_PERIOD_NSEC	Counts = (period * clk_freq_hz)/ (1000000000 * channel_0_period)
TIMER_UNIT_PERIOD_USEC	Counts = (period * clk_freq_hz)/ (1000000 * channel_0_period)
TIMER_UNIT_PERIOD_MSEC	Counts = (period * clk_freq_hz)/ (1000 * channel_0_period)
TIMER_UNIT_PERIOD_SEC	Counts = (period * clk_freq_hz) / (channel_0_period)
TIMER_UNIT_FREQUENCY_HZ	Counts = (clk_freq_hz)/ (period * channel_0_period)
TIMER_UNIT_FREQUENCY_KHZ	Counts = (clk_freq_hz)/ (1000 * period * channel_0_period)

Note

  In normal mode channel_0_period value will be 1 and in cascade mode channel_0_period value will be the timer T0 count value.

Timer Period Calculation

If the requested period is larger than the counter size (32-bit or 16-bit), the driver selects the smallest divisor that allows the result to fit in the counter size. If the counter value is larger than the counter size with the largest divisor (1024), an error code (SSP_ERR_INVALID_ARGUMENT) is returned.

Triggering DMAC/DTC with GPT

To trigger a transfer of data using the DMAC or DTC peripheral when the timer period elapses, configure the DMAC/DTC transfer with activation_source set to ELC_EVENT_GPTn_COUNTER_OVERFLOW (where n is the GPT channel number). See the DMAC or DTC guides for further information.

Note

If you use the timer in one-shot mode with the DTC, the entire transfer completes before the interrupt stops the timer if the IRQ is set to TRANSFER_IRQ_END. To generate only one transfer after the timer period elapses, set the IRQ to TRANSFER_IRQ_EACH or use the DMAC for the transfer.

Triggering ELC Events with GPT

The GPT timer can trigger the start of other peripherals. The ELC guide provides a list of all available peripherals.

Triggering DMAC/DTC with AGT

To trigger a transfer of data using the DMAC or DTC peripheral when the timer period elapses, configure the DMAC/DTC transfer with activation_source set to ELC_EVENT_AGTn_AGTI (where n is the AGT channel number). See the Transfer Interface for further information.

Note

If you use the timer in one-shot mode with the DTC, the entire transfer completes before the interrupt stops the timer if irq is set to TRANSFER_IRQ_END. To generate only one transfer after the timer period elapses, set irq to TRANSFER_IRQ_EACH, or use the DMAC for the transfer.

Triggering ELC Events with AGT

The AGT timer can trigger the start of other peripherals. The ELC guide provides a list of all available peripherals listed in elc_peripheral_t. (See events and peripheral definitions for further information.)

Cascading AGT Timers to Create a 32-bit timer

AGT Channel 1 can be clocked by the AGT Channel 0 underflow, creating a cascaded 32-bit timer. In this mode, the AGT Channel 0 output frequency will be the input frequency of AGT Channel 1. With cascaded operation, longer time periods are achievable:

• On a cascaded AGT with PCLKB running at 60 MHz, the maximum possible period is approximately 574.1 seconds.
• On a cascaded AGT with LOCO running at 32 kHz, the maximum possible period is approximately 1048560 seconds.

Cascaded Timer Period Calculation

AGT Channel 0 period calculation will be the same as normal timer period calculation as shown in the preceding table. If the requested period is larger than the counter size (32-bit or 16-bit), the driver selects the smallest divisor that allows the result to fit in the counter size.

AGT Channel 1 period calculation will be same as shown in the preceding table, except the "channel_0_period" value will be equal to AGT Channel 0's output period value (that is, after divisor selection).

Note

The cascaded timer output will have the granularity error of 1 / (clock source).

AGT HAL Module Limitations

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

Including the AGT HAL Module in an Application

This section describes how to include the AGT 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 Timer 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 Timer Driver is g_agt0. This name can be changed in the associated Properties window.)

AGT HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
r_agt0 Timer Driver on r_agt	Threads	New Stack> Driver> Timers> Timer Driver on r_agt

When the Timer Driver on r_agt 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.

AGT HAL Module Stack

Configuring the AGT HAL Module

The AGT 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 AGT HAL Module on r_agt

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables parameter checking.
Name	g_timer0	Module name.
Channel	0	Physical hardware channel.
Mode	Periodic, One Shot Default: Periodic	Warning: One Shot functionality is not available in the GPT hardware, so it is implemented in software by stopping the timer in the ISR called when the period expires. For this reason, ISR's must be enabled for one-shot mode even if the callback is unused.
Period Value	10	See Timer Period Calculation.
Period Unit	Raw Counts, Nanoseconds, Microseconds, Milliseconds, Seconds, Hertz, Kilohertz Default: Microseconds	See Timer Period Calculation.
Auto Start	True, False Default: True	Set to true to start the timer after configuring or false to leave the timer stopped until timer_api_t::start is called.
Count Source	PCLKB, PCLKB/8, PCLKB/2, LOCO, AGT0 Underflow, AGT0 fSub Default: PCLKB	The clock source for the AGT counter.
AGTO Output Enabled	True, False Default: False	Set to true to output the timer signal on a port pin configured for AGT (AGTO pin). Set to false for no output of the timer signal.
AGTIO Output Enabled	True, False Default: False	Set to true to output the timer signal on a port pin configured for AGT (AGTIO pin). Set to false for no output of the timer signal.
Output Inverted	True, False Default: False	Set to false to start the output signal low. Set to true to start the output signal high.
Enable comparator A output pin	True, False Default: False	Enable comparator A output pin selection.
Enable comparator B output pin	True, False Default: False	Enable comparator B output pin selection.
Callback	NULL	A user callback function can be registered in timer_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the timer period elapses. 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: Disabled	Timer interrupt priority. 0 is the highest priority.

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.

AGT HAL Module Clock Configuration

The AGT timer is clocked based on the PCLKB, LOCO, Fsub or AGT Underflow frequency. The AGT clock is selectable in the Properties window in e² studio. You can set the clock frequencies using the clock configurator in e² studio or the CGC Interface at run-time.

AGT HAL Module Pin Configuration

The AGT 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 associated pins.

Note

The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection for the AGT HAL Module on r_agt

Resource	ISDE Tab	Pin selection Sequence
AGT	Pins	Select Peripherals> Timer: AGT> AGT0

Note

The selection sequence assumes AGT0 is the desired hardware target for the driver.

Pin Configuration Settings for the AGT HAL Module on r_agt

Property	Value	Description
Operation Mode	Disabled, Custom, Timer Output, Compare Match, Count Measurement, Gated Count Default: Disabled	Select timer operation mode.
AGTIO	None Default: None	AGTIO Pin.
AGTO	None, P102 Default: P102	AGTO Pin.
AGTOA	None Default: None	AGTOA Pin.
AGTOB	None Default: None	AGTOB Pin.
AGTEE	None, P101 Default: P101	AGTEE 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 AGT HAL Module in an Application

The typical steps in using the AGT HAL Module in an application are:

1. Initialize the AGT HAL module using the timer_api_t::open API.
2. Start the AGT HAL module by calling the timer_api_t::start API.
3. Read the counter value by calling the timer_api_t::counterGet API.
4. Set the period value by using thetimer_api_t::periodSet API
5. Set the duty cycle by using timer_api_t::dutyCycleSet API
6. Get the timer information using timer_api_t::infoGet API
7. Respond to the AGT HAL module callback as needed.
8. Resets the counter value using the timer_api_t::reset API
9. Stop the AGT channel using timer_api_t::stop API
10. Use the timer_api_t::close call to power down the peripheral.

Note

The timer-period and duty-cycle parameters can be reconfigured based on the application's needs.

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

Flow Diagram of a Typical AGT HAL Module Application