Driver for the GTM peripherals on RZ MPUs. This module implements the Timer Interface.
Overview
The GTM module can be used to count events, generate a periodic interrupt.
Features
The General timer has the following features:
- Supports periodic mode, one-shot mode as Timer API.
- Configurable period (counts per timer cycle).
- Supports runtime reconfiguration of period.
- Supports counting based on P0 clock.
- APIs are provided to start, stop the counter.
- APIs are provided to get the current period, source clock frequency, and count direction.
- APIs are provided to get the current timer status and counter value.
- Supports two operating modes as GTM API.
- Interval timer mode
- Free-running comparison mode
Selecting a Timer
RZ MPUs have two timer peripherals: the General PWM Timer (GPT) and the General Timer (GTM). When selecting between them, consider these factors:
| GPT | GTM |
Available Channels | The number of GPT channels is device specific. All currently supported MPUs have at least 6 GPT channels. | All MPUs have 3 GTM channels. |
Timer Resolution | All MPUs have 32-bit GPT timer. | The GTM timers are 32-bit timers. |
Clock Source | The GPT runs off P0 clock with a configurable divider up to 1024. | The GTM runs off P0 clock. |
Configuration
Build Time Configurations for r_gtm
The following build time configurations are defined in fsp_cfg/r_gtm_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 Driver > Timers > Timer Driver on r_gtm
This module can be added to the Stacks tab via New Stack > Driver > Timers > Timer Driver on r_gtm.
Configuration | Options | Default | Description |
General > Name | Name must be a valid C symbol | g_timer0 | Module name. |
General > Channel | Channel number does not exist | 0 | Physical hardware channel. |
General > Mode |
| Periodic | Mode selection. Note: One-shot mode is implemented in software. ISR's must be enabled for one shot even if callback is unused. |
General > Period | Value must be non-negative | 1 | Specify the timer period based on the selected unit.
When the unit is set to 'Raw Counts', setting the period to 0x10000 results in the maximum period at the lowest divisor (fastest timer tick). Set the period to 0x10000 for a free running timer, pulse width measurement or pulse period measurement. Setting the period higher will automatically select a higher divider; the period can be set up to 0x80000 when counting from PCLKB or 0x800000 when counting from LOCO/subclock, which will use a divider of 8 or 128 respectively with the maximum period. |
General > Period Unit |
-
Raw Counts
-
Nanoseconds
-
Microseconds
-
Milliseconds
-
Seconds
-
Hertz
-
Kilohertz
| Milliseconds | Unit of the period specified above |
General > Count Source | P0CLK | P0CLK | GTM counter clock source. NOTE: The divisor is calculated automatically based on the selected period. See agt_count_source_t documentation for details. |
Interrupts > Callback | Name must be a valid C symbol | NULL | A user callback function. If this callback function is provided, it is called from the interrupt service routine (ISR) each time the timer period elapses. |
Interrupts > Underflow Interrupt Priority | Illegal interrupt priority level | 5 | Timer interrupt priority. |
Interrupts > Generate at Start |
| Disable | Controls enabling or disabling of generates OSTMnTINT interrupt at starts |
Extra Features > GTM Mode |
-
Interval timer mode
-
Free-running comparison mode
| Interval timer mode | GTM Count Mode (Interval timer mode or Free-running comparison mode) |
Timer Period
The Configuration editor will automatically calculate the period count value based on the selected period time, units.
When the selected unit is "Raw counts", the maximum allowed period setting varies depending on the selected clock source:
Clock source | Maximum period (counts) |
P0 clock | 0x100000000 |
- Note
- Though the GTM is a 32-bit timer, because the period interrupt occurs when the counter underflows, setting the period register to 0 results in an effective period of 1 count. For this reason all user-provided raw count values reflect the actual number of period counts (not the raw register values).
Usage Notes
Interval Timer Mode
In this mode, the timer counts down from the value specified in the compare match register. An interrupt request is generated when the counter reaches 0x0000_0000.
Free-Running Comparison Mode
In this mode, the counter counts up from 0x0000_0000 to 0xFFFF_FFFF. An interrupt request is output when the current value of the counter matches the value of the compare match register.
Updating Period
The period is updated after the next counter overflow or underflow after calling R_GTM_PeriodSet().
One-Shot Mode
The GTM timer does not support one-shot mode natively. One-shot mode is achieved by stopping the timer in the interrupt service routine before the callback is called. If the interrupt is not serviced before the timer period expires again, the timer generates more than one event. The callback is only called once in this case.
Examples of periodic signals that can be generated by this module are shown below:
Examples
GTM Basic Example
This is a basic example of minimal use of the GTM in an application.
void gtm_basic_example (void)
{
assert(FSP_SUCCESS == err);
}
GTM Callback Example
This is an example of a timer callback.
GTM Free Running Counter Example
To use the GTM as a free running counter, select Free-Running Comparison Mode.
void gtm_counter_example (void)
{
assert(FSP_SUCCESS == err);
}
GTM Period Update Example
This is an example of updating the period.
#define GTM_EXAMPLE_MSEC_PER_SEC (1000)
#define GTM_EXAMPLE_DESIRED_PERIOD_MSEC (20)
void gtm_period_calculation_example (void)
{
assert(FSP_SUCCESS == err);
uint32_t period_counts =
(uint32_t) (((uint64_t) timer_freq_hz * gtm_EXAMPLE_DESIRED_PERIOD_MSEC) / gtm_EXAMPLE_MSEC_PER_SEC);
assert(FSP_SUCCESS == err);
}
◆ gtm_instance_ctrl_t
struct gtm_instance_ctrl_t |
Channel control block. DO NOT INITIALIZE. Initialization occurs when timer_api_t::open is called.
◆ gtm_extended_cfg_t
struct gtm_extended_cfg_t |
Optional GTM extension data structure.
◆ gtm_giws_type_t
Optional GTM interrupt setting
Enumerator |
---|
GTM_GIWS_TYPE_DISABLED | Do not generate interrupt when timer started.
|
GTM_GIWS_TYPE_ENABLED | Generates interrupt when timer started.
|
◆ gtm_timer_mode_t
Optional GTM timer mode setting
Enumerator |
---|
GTM_TIMER_MODE_INTERVAL | Use interval timer mode.
|
GTM_TIMER_MODE_FREERUN | Use free-running comparison mode.
|
◆ R_GTM_Close()
Stops counter, disables interrupts, disables output pins, and clears internal driver data. Implements timer_api_t::close.
- Return values
-
FSP_SUCCESS | Timer closed. |
FSP_ERR_ASSERTION | p_ctrl is NULL. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_PeriodSet()
Updates period. The new period is updated immediately and the counter is reset to the maximum value. Implements timer_api_t::periodSet.
- Warning
- If periodic output is used, the duty cycle buffer registers are updated after the period buffer register. If this function is called while the timer is running and an GTM underflow occurs during processing, the duty cycle will not be the desired 50% duty cycle until the counter underflow after processing completes.
-
Stop the timer before calling this function if one-shot output is used.
- Return values
-
FSP_SUCCESS | Period value updated. |
FSP_ERR_ASSERTION | A required pointer was NULL, or the period was not in the valid range of 1 to 0xFFFF. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_DutyCycleSet()
fsp_err_t R_GTM_DutyCycleSet |
( |
timer_ctrl_t *const |
p_ctrl, |
|
|
uint32_t const |
duty_cycle_counts, |
|
|
uint32_t const |
pin |
|
) |
| |
Updates duty cycle. If the timer is counting, the new duty cycle is reflected after the next counter underflow. Implements timer_api_t::dutyCycleSet.
- Return values
-
◆ R_GTM_Reset()
Resets the counter value to the period minus one. Implements timer_api_t::reset.
- Return values
-
FSP_ERR_UNSUPPORTED | Selected function not supported by this module. |
◆ R_GTM_Start()
Starts timer. Implements timer_api_t::start.
- Return values
-
FSP_SUCCESS | Timer started. |
FSP_ERR_ASSERTION | p_ctrl is null. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_Enable()
Enables external event triggers that start, stop, clear, or capture the counter. Implements timer_api_t::enable.
- Return values
-
FSP_ERR_UNSUPPORTED | Selected function not supported by this module. |
◆ R_GTM_Disable()
Disables external event triggers that start, stop, clear, or capture the counter. Implements timer_api_t::disable.
- Return values
-
FSP_ERR_UNSUPPORTED | Selected function not supported by this module. |
◆ R_GTM_InfoGet()
Gets timer information and store it in provided pointer p_info. Implements timer_api_t::infoGet.
- Return values
-
FSP_SUCCESS | Period, count direction, and frequency stored in p_info. |
FSP_ERR_ASSERTION | A required pointer is NULL. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_StatusGet()
Retrieves the current state and counter value stores them in p_status. Implements timer_api_t::statusGet.
- Return values
-
FSP_SUCCESS | Current status and counter value provided in p_status. |
FSP_ERR_ASSERTION | A required pointer is NULL. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_Stop()
Stops the timer. Implements timer_api_t::stop.
- Return values
-
FSP_SUCCESS | Timer stopped. |
FSP_ERR_ASSERTION | p_ctrl was NULL. |
FSP_ERR_NOT_OPEN | The instance control structure is not opened. |
◆ R_GTM_Open()
Initializes the GTM module instance. Implements timer_api_t::open.
The GTM hardware does not support one-shot functionality natively. The one-shot feature is therefore implemented in the GTM HAL layer. For a timer configured as a one-shot timer, the timer is stopped upon the first timer expiration.
The GTM implementation of the general timer can accept an optional gtm_extended_cfg_t extension parameter. For GTM, the extension specifies the clock to be used as timer source and the output pin configurations. If the extension parameter is not specified (NULL), the default clock P0CLK is used and the output pins are disabled.
- Return values
-
FSP_SUCCESS | Initialization was successful and timer has started. |
FSP_ERR_ASSERTION | A required input pointer is NULL or the period is not in the valid range of 1 to 0xFFFF. |
FSP_ERR_ALREADY_OPEN | R_GTM_Open has already been called for this p_ctrl. |
FSP_ERR_IRQ_BSP_DISABLED | A required interrupt has not been enabled in the vector table. |
FSP_ERR_IP_CHANNEL_NOT_PRESENT | Requested channel number is not available on GTM. |
◆ R_GTM_CallbackSet()
Updates the user callback with the option to provide memory for the callback argument structure. Implements timer_api_t::callbackSet.
- Return values
-
FSP_SUCCESS | Callback updated successfully. |
FSP_ERR_ASSERTION | A required pointer is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_NO_CALLBACK_MEMORY | p_callback is non-secure and p_callback_memory is either secure or NULL. |