Functions
fsp_err_t	R_GTM_Close (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_PeriodSet (timer_ctrl_t *const p_ctrl, uint32_t const period_counts)

fsp_err_t	R_GTM_DutyCycleSet (timer_ctrl_t *const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin)

fsp_err_t	R_GTM_Reset (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_Start (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_Enable (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_Disable (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_InfoGet (timer_ctrl_t const p_ctrl, timer_info_t const p_info)

fsp_err_t	R_GTM_StatusGet (timer_ctrl_t const p_ctrl, timer_status_t const p_status)

fsp_err_t	R_GTM_Stop (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_GTM_Open (timer_ctrl_t const p_ctrl, timer_cfg_t const const p_cfg)

fsp_err_t	R_GTM_CompareMatchSet (timer_ctrl_t *const p_ctrl, uint32_t const compare_match_value, timer_compare_match_t const match_channel)

fsp_err_t	R_GTM_CallbackSet (timer_ctrl_t const p_api_ctrl, void(p_callback)(timer_callback_args_t ), void const const p_context, timer_callback_args_t *const p_callback_memory)

Detailed Description

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 Timers > Timer (r_gtm)

This module can be added to the Stacks tab via New Stack > Timers > Timer (r_gtm).

Configuration	Options	Default	Description
General > Name	Name must be a valid C symbol	g_timer0	Module name.
General > Channel	MCU Specific Options		Physical hardware channel.
General > Mode	Periodic One-Shot	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. Valid input value range: - When 'Raw Counts' is selected in 'Period Unit', set the value to 0x00000001~0x100000000 - When other item is selected in 'Period Unit', set the value to (1 / count clock) ~ (0x100000000 / count clock) If the input value is exceeded valid range, the ERROR will be shown in hal_data.c.
General > Period Unit	Raw Counts Nanoseconds Microseconds Milliseconds Seconds Hertz Kilohertz	Milliseconds	Unit of the period specified above
General > Count Source	MCU Specific Options		GTM counter clock source.
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 Enable	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)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_GTM_Open(&g_timer_ctrl, &g_timer_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_GTM_Start(&g_timer_ctrl);
}

GTM Callback Example

This is an example of a timer callback.

/* Example callback called when timer expires. */
void timer_callback (timer_callback_args_t * p_args)
{
    if (TIMER_EVENT_CYCLE_END == p_args->event)
    {
        /* Add application code to be called periodically here. */
    }
}

GTM Free Running Counter Example

To use the GTM as a free running counter, select Free-Running Comparison Mode.

void gtm_counter_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_GTM_Open(&g_timer_ctrl, &g_timer_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_GTM_Start(&g_timer_ctrl);
    /* (Optional) Stop the timer. */
    (void) R_GTM_Stop(&g_timer_ctrl);
    /* Read the current counter value. Counter value is in status.counter. */
    timer_status_t status;
    (void) R_GTM_StatusGet(&g_timer_ctrl, &status);
}

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)
/* This example shows how to calculate a new period value at runtime. */
void gtm_period_calculation_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_GTM_Open(&g_timer_ctrl, &g_timer_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_GTM_Start(&g_timer_ctrl);
    /* Get the source clock frequency (in Hz). There are several ways to do this in FSP:
     *  - Use the R_GTM_InfoGet function (it accounts for the clock source and divider).
     *  - Calculate the current count clock frequency using R_FSP_SystemClockHzGet(BSP_FEATURE_GTM_SOURCE_CLOCK).
     *
     * This example uses the last option (R_FSP_SystemClockHzGet).
     */
    uint32_t timer_freq_hz = R_FSP_SystemClockHzGet(BSP_FEATURE_GTM_SOURCE_CLOCK);
    /* Calculate the desired period based on the current clock. Note that this calculation could overflow if the
     * desired period is larger than UINT32_MAX / pclkb_freq_hz. A cast to uint64_t is used to prevent this. */
    uint32_t period_counts =
        (uint32_t) (((uint64_t) timer_freq_hz * GTM_EXAMPLE_DESIRED_PERIOD_MSEC) / GTM_EXAMPLE_MSEC_PER_SEC);
    /* Set the calculated period. */
    err = R_GTM_PeriodSet(&g_timer_ctrl, period_counts);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	gtm_instance_ctrl_t

struct	gtm_extended_cfg_t

Enumerations
enum	gtm_giws_type_t

enum	gtm_timer_mode_t

Data Structure Documentation

◆ 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.

Enumeration Type Documentation

◆ gtm_giws_type_t

enum 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

enum 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.

Function Documentation

◆ R_GTM_Close()

fsp_err_t R_GTM_Close ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_PeriodSet	(	timer_ctrl_t *const	p_ctrl,
		uint32_t const	period_counts
	)

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

FSP_ERR_UNSUPPORTED

◆ R_GTM_Reset()

fsp_err_t R_GTM_Reset ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_Start ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_Enable ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_Disable ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_InfoGet	(	timer_ctrl_t *const	p_ctrl,
		timer_info_t *const	p_info
	)

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()

fsp_err_t R_GTM_StatusGet	(	timer_ctrl_t *const	p_ctrl,
		timer_status_t *const	p_status
	)

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()

fsp_err_t R_GTM_Stop ( timer_ctrl_t *const p_ctrl )

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()

fsp_err_t R_GTM_Open	(	timer_ctrl_t *const	p_ctrl,
		timer_cfg_t const *const	p_cfg
	)

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_CompareMatchSet()

fsp_err_t R_GTM_CompareMatchSet	(	timer_ctrl_t *const	p_ctrl,
		uint32_t const	compare_match_value,
		timer_compare_match_t const	match_channel
	)

Placeholder for unsupported compareMatch function. Implements timer_api_t::compareMatchSet.

Return values

FSP_ERR_UNSUPPORTED GTM compare match is not supported.

◆ R_GTM_CallbackSet()

fsp_err_t R_GTM_CallbackSet	(	timer_ctrl_t *const	p_api_ctrl,
		void()(timer_callback_args_t )	p_callback,
		void const *const	p_context,
		timer_callback_args_t *const	p_callback_memory
	)

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.

Functions

Detailed Description

Overview

Features

Selecting a Timer

Configuration

Build Time Configurations for r_gtm

Configurations for Timers > Timer (r_gtm)

Timer Period

Usage Notes

Interval Timer Mode

Free-Running Comparison Mode

Updating Period

One-Shot Mode

Examples

GTM Basic Example

GTM Callback Example

GTM Free Running Counter Example

GTM Period Update Example

Data Structures

Enumerations

Data Structure Documentation

◆ gtm_instance_ctrl_t

◆ gtm_extended_cfg_t

Enumeration Type Documentation

◆ gtm_giws_type_t

◆ gtm_timer_mode_t

Function Documentation

◆ R_GTM_Close()

◆ R_GTM_PeriodSet()

◆ R_GTM_DutyCycleSet()

◆ R_GTM_Reset()

◆ R_GTM_Start()

◆ R_GTM_Enable()

◆ R_GTM_Disable()

◆ R_GTM_InfoGet()

◆ R_GTM_StatusGet()

◆ R_GTM_Stop()

◆ R_GTM_Open()

◆ R_GTM_CompareMatchSet()

◆ R_GTM_CallbackSet()