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

GPT HAL Module Introduction

The General PWM Timer (GPT) HAL module provides a high-level API for timer applications and uses the GPT peripheral on the Synergy MCU. A user-defined callback can be created to respond to a timer event.

GPT HAL Module Features

The GPT HAL module configures a timer to a user-specified period. When the period elapses, any of the following events can occur:

CPU interrupt that calls a user callback function, if provided
Toggle a port pin
Data transfer using DMAC/DTC if configured with Transfer Interface
Starting of another peripheral if configured with events and peripheral definitions

General PWM Timer (GPT)

PCLKD as core clock
Two I/O pins per channel

GPT HAL Module Block Diagram

GPT Hardware support details

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

Legend:

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

MCU Group	Saw Waves	Triangle Waves	PWM waveform for controlling brushless DC motors	Compare match output for Low, High, and Toggle	Input capture function	Automatic addition of dead time
S124	✓	⌧	⌧	✓	⌧	⌧
S128	✓	⌧	⌧	✓	⌧	⌧
S1JA	✓	⌧	⌧	✓	⌧	⌧
S3A1	✓	⌧	⌧	✓	⌧	⌧
S3A3	✓	⌧	⌧	✓	⌧	⌧
S3A6	✓	⌧	⌧	✓	⌧	⌧
S3A7	✓	⌧	⌧	✓	⌧	⌧
S5D3	✓	⌧	⌧	✓	⌧	⌧
S5D5	✓	⌧	⌧	✓	⌧	⌧
S5D9	✓	⌧	⌧	✓	⌧	⌧
S7G2	✓	⌧	⌧	✓	⌧	⌧

MCU Group	PWM Mode	Phase Count Function	One-Shot Operation	Event link function through ELC HAL driver	Noise filtering function
S124	✓	⌧	✓	⌧	⌧
S128	✓	⌧	✓	⌧	⌧
S1JA	✓	⌧	✓	⌧	⌧
S3A1	✓	⌧	✓	⌧	⌧
S3A3	✓	⌧	✓	⌧	⌧
S3A6	✓	⌧	✓	⌧	⌧
S3A7	✓	⌧	✓	⌧	⌧
S5D3	✓	⌧	✓	⌧	⌧
S5D5	✓	⌧	✓	⌧	⌧
S5D9	✓	⌧	✓	⌧	⌧
S7G2	✓	⌧	✓	⌧	⌧

GPT HAL Module APIs Overview

The GPT HAL module defines APIs to open, start, stop, read status, trim and close 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.

GPT 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 has already been opened.
SSP_ERROR_NOT_OPEN	The channel is not open.
SSP_ERR_INVALID_ARGUMENT	Invalid argument provided.

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.

GPT HAL Module Operational Overview

The GPT 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:

GPT HAL Module Timer-Periodic or One-Shot Mode

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 AGT, refer to the AGT 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 following use cases describe why one timer module would be preferred over the other.

Selecting the GPT Timer Module

The GPT module uses a high-resolution 32-bit counter that can only be clocked by PCLKD. There are more GPT channels than AGT channels on Synergy devices, so using 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.

GPT HAL Module Important Operational Notes and Limitations

GPT 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 PCLKD running at 120 MHz, the maximum period is approximately 36650 seconds, which is just over 10 hours (GPT Count Clock is PCLKD/1024).
On a GPT with 16-bit resolution with PCLKD running at 32 MHz, the maximum period is approximately 2.09 seconds (GPT Count Clock is PCLKD/1024).

The GPT counter overflow interrupt must be enabled in the following situations:

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

When counter overflow interrupt is enabled, the corresponding ISR is linked in the vector table. 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 irq set to TRANSFER_IRQ_END.

GPT Output Timer Signal

If the timer output is configured (GTIOCA/B Output Enabled set to True), the output pin will start at the GTIOCA/B Stop Level and toggle 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 will toggle 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 open and periodSet.

If the specified Period Unit is different than the Raw Counts, the period is calculated using the current timer clock frequency. The current timer clock frequency is determined using the cgc_api_t::systemClockFreqGet API. This frequency will be used in the appropriate formula from the following table as clk_freq_hz.

Timer Period Calculation

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

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 will complete 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 GPT

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

Free Running Counter Mode

To use the GPT as a free running counter, set the Period to 0xFFFFFFFF for a 32-bit timer or 0xFFFF for a 16-bit timer and the Period Unit to Raw Counts in the Properties window of the Synergy Configuration tool. Stop and start the timer using the timer_api_t::stop API and the timer_api_t::start API. Check the counter value using the timer_api_t::counterGet API. Reset the timer using the timer_api_t::reset API. If the counter overflows, handle the counter overflow in the callback.

GPT PWM Mode

To use the GPT in PWM mode, set the Period and Duty cycle and select the duty cycle range.

The driver provides two options to select the duty cycle range:

Shortest duty cycle off: In this case, the lowest duty cycle obtained will be limited to 2 raw counts. But the configuration will be limited to 1 raw counts(because the hardware will add 1 extra clock cycle in ON time, hence if configured Dutycycle is 1 raw count, the user will be getting 2 raw counts in ON time).
Shortest duty cycle on: In this case, the lowest duty cycle of 1 raw count can be achieved and lowest duty cycle to configure will be limited to 1 raw counts and the longest will be (Period – 2). In this case, the 1 extra clock cycle will be added by hardware in OFF time.

GPT HAL Module Limitations

For GPT Power Down, the GPT module does not set the Module Stop bit (MSTP) for GPT in the timer_api_t::close API. This is intentional because the GPT module stop bits control the power to multiple GPT channels, and the GPT module cannot know if other GPT modules are used in the application.
Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the GPT HAL Module in an Application

This section describes how to include the GPT 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_timer0. This name can be changed in the associated Properties window.)

GPT HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_timer0 Timer Driver on r_gpt	Threads> HAL/Common	New Stack> Driver> Timers> Timer Driver on r_gpt

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

GPT HAL Module Stack

Configuring the GPT HAL Module

The GPT 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 GPT HAL Module on r_gpt

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables the parameter checking.
Name	g_timer0	Module name.
Channel	0	Channel selection.
Mode	Periodic, One Shot, PWM 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: Milliseconds	See Timer Period Calculation.
Duty Cycle Value	50	Duty cycle value selection.
Duty Cycle Unit	Unit Raw Counts, Unit Percent, Unit Percent x 1000 Default: Unit Raw Counts	Duty cycle unit selection.
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.
GTIOCA Output Enabled	True, False Default: False	Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal.
GTIOCA Stop Level	Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low	Controls output pin level when the timer is stopped.
GTIOCB Output Enabled	True, False Default: False	Set to true to output the timer signal on a port pin configured for GPT. Set to false for no output of the timer signal.
GTIOCB Stop Level	Pin Level Low, Pin Level High, Pin Level Retained Default: Pin Level Low	Controls output pin level when the timer is stopped.
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.
Overflow Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	Overflow 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.

GPT HAL Module Clock Configuration

The GPT timer is clocked based on the PCLKD frequency. You can set the PCLKD frequency using the clock configurator in the ISDE Configuring Clocks tab, or the CGC Interface at run-time.

GPT HAL Module Pin Configuration

The GPT 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 lists the method used to select pins within the SSP configuration window and the subsequent table lists an example selection for the associated pins:

Pin Selection for the GPT HAL Module on r_gpt

Resource	ISDE Tab	Pin selection Sequence
GPT	Pins	Select Peripherals> Timer: GPT> GPT0

Note: The selection sequence assumes GPT0 is the desired hardware target for the driver.

Pin Configuration Settings for GPT HAL Driver

Property	Value	Description
Pin Group Selection	Mixed, _A Only, _B Only Default: Mixed	Select pin group mapping.
Operation Mode	Disabled, GTIOCA or GTIOCB, GTIOCA and GTIOCB Default: Disabled	Select timer operation mode.
GTIOCA:	None, P300, P512 Default: P512	GTIOCA Pin.
GTIOCB:	None, P108, P511 Default: P511	GTIOCB 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 GPT HAL Module in an Application

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

Initialize the GPT HAL module using the timer_api_t::open API.
Start the GPT HAL module by calling the timer_api_t::start API if the Auto Start property is False.
Respond to the timer callback as needed (application code).

Note: The GPT period and duty cycle parameters can be reconfigured based on the application needs using the timer_api_t::periodSet() and the timer_api_t::dutyCycleSet.

In PWM mode, there will be one extra PCLK added by the hardware in ON time if Duty cycle range is selected to GPT_SHORTEST_LEVEL_OFF and in OFF time if the Duty cycle range is selected to GPT_SHORTEST_LEVEL_ON.

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

Flow Diagram of a Typical GPT HAL Module Application

Table of Contents