Functions
fsp_err_t	R_AGT_Open (timer_ctrl_t const p_ctrl, timer_cfg_t const const p_cfg)

fsp_err_t	R_AGT_Start (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_AGT_Stop (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_AGT_Reset (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_AGT_Enable (timer_ctrl_t *const p_ctrl)

fsp_err_t	R_AGT_Disable (timer_ctrl_t *const p_ctrl)

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

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

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

fsp_err_t	R_AGT_InfoGet (timer_ctrl_t const p_ctrl, timer_info_t const p_info)

fsp_err_t	R_AGT_StatusGet (timer_ctrl_t const p_ctrl, timer_status_t const p_status)

fsp_err_t	R_AGT_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)

fsp_err_t	R_AGT_Close (timer_ctrl_t *const p_ctrl)

Detailed Description

Driver for the AGT and AGTW peripheral on RA MCUs. This module implements the Timer Interface.

Overview

Features

The AGT module has the following features:

Supports 16- and 32-bit timers via the AGT and AGTW peripherals, respectively.
Supports periodic mode, one-shot mode, and PWM mode.
Signal can be output to a pin.
Configurable period (counts per timer cycle).
Configurable duty cycle in PWM mode.
Configurable clock source, including PCLKB, LOCO, SUBCLK, and external sources input to AGTIO.
Supports runtime reconfiguration of period.
Supports runtime reconfiguration of duty cycle in PWM mode.
Supports counting based on an external clock input to AGTIO.
Supports debounce filter on AGTIO pins.
Supports measuring pulse width or pulse period.
APIs are provided to start, stop, and reset 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.

Selecting a Timer

RA MCUs have two timer peripherals: the General PWM Timer (GPT) and the Asynchronous General Purpose Timer (AGT). When selecting between them, consider these factors:

	GPT	AGT
Low Power Modes	The GPT can operate in sleep mode.	The AGT can operate in all low power modes (when count source is LOCO or subclock).
Available Channels	The number of GPT channels is device specific. All currently supported MCUs have at least 7 GPT channels.	All MCUs have at least 2 AGT channels.
Timer Resolution	All MCUs have at least one 32-bit GPT timer.	The AGT timers can be 16-bit or 32-bit timers.
Clock Source	The GPT runs off PCLKD with a configurable divider up to 1024. It can also be configured to count ELC events or external pulses.	The AGT runs off PCLKB, LOCO, or subclock with a configurable divider up to 8 for PCLKB or up to 128 for LOCO or subclock.

Configuration

Build Time Configurations for r_agt

The following build time configurations are defined in fsp_cfg/r_agt_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.
Pin Output Support	Disabled Enabled	Disabled	If selected code for outputting a waveform to a pin is included in the build.
Pin Input Support	Disabled Enabled	Disabled	Enable input support to use pulse width measurement mode, pulse period measurement mode, or input from P402, P403, P404, or AGTIO.

Configurations for Timers > Timer, Low-Power (r_agt)

This module can be added to the Stacks tab via New Stack > Timers > Timer, Low-Power (r_agt). 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
General
Name	Name must be a valid C symbol	g_timer0	Module name.
Counter Bit Width	MCU Specific Options		Counter register bit width (16-bit or 32-bit))
Channel	Channel number must be a non-negative integer	0	Physical hardware channel.
Mode	Periodic One-Shot PWM	Periodic	Mode selection. Note: One-shot mode is implemented in software. ISR's must be enabled for one shot even if callback is unused.
Period	Value must be non-negative	0x10000	Specify the timer period based on the selected unit. When the unit is set to 'Raw Counts', setting the period to 0x100000000 (32-bit) or 0x10000 (16-bit) results in the maximum period at the lowest divisor (fastest timer tick). Set the period to 0x100000000 (32-bit) or 0x10000 (16-bit) 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 0x800000000 (32-bit) or 0x80000 (16-bit) when counting from PCLKB or 0x8000000000 (32-bit) or 0x800000 (16-bit) when counting from LOCO/subclock, which will use a divider of 8 or 128 respectively with the maximum period. If the requested period cannot be achieved, the settings with the largest possible period that is less than or equal to the requested period are used. The theoretical calculated period is printed in a comment in the timer_cfg_t structure.
Period Unit	Raw Counts Nanoseconds Microseconds Milliseconds Seconds Hertz Kilohertz	Raw Counts	Unit of the period specified above
Count Source	MCU Specific Options		AGT counter clock source. NOTE: The divisor is calculated automatically based on the selected period. See agt_clock_t documentation for details.
Output
Duty Cycle Percent (only applicable in PWM mode)	Value must be between 0 and 100	50	Specify the timer duty cycle percent. Only used in PWM mode.
AGTOA Output	Disabled Start Level Low Start Level High	Disabled	Configure AGTOA output.
AGTOB Output	Disabled Start Level Low Start Level High	Disabled	Configure AGTOB output.
AGTO Output	Disabled Start Level Low Start Level High	Disabled	Configure AGTO output.
Input
Measurement Mode	Measure Disabled Measure Low Level Pulse Width Measure High Level Pulse Width Measure Pulse Period	Measure Disabled	Select if the AGT should be used to measure pulse width or pulse period. In high level pulse width measurement mode, the AGT counts when AGTIO is high and starts counting immediately in the middle of a pulse if AGTIO is high when R_AGT_Start() is called. In low level pulse width measurement mode, the AGT counts when AGTIO is low and could start counting in the middle of a pulse if AGTIO is low when R_AGT_Start() is called.
Input Filter	No Filter Filter sampled at PCLKB Filter sampled at PCLKB / 8 Filter sampled at PCLKB / 32	No Filter	Input filter, applies AGTIO in pulse period measurement, pulse width measurement, or event counter mode. The filter requires the signal to be at the same level for 3 successive reads at the specified filter frequency.
Enable Pin	Enable Pin Not Used Enable Pin Active Low Enable Pin Active High	Enable Pin Not Used	Select active edge for the AGTEE pin if used. Only applies if the count source is P402, P403 or AGTIO.
Trigger Edge	Trigger Edge Rising Trigger Edge Falling Trigger Edge Both	Trigger Edge Rising	Select the trigger edge. Applies if measurement mode is pulse period, or if the count source is P402, P403, or AGTIO. Do not select Trigger Edge Both with pulse period measurement.
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.
Underflow Interrupt Priority	MCU Specific Options		Timer interrupt priority.

When using the AGT module on devices with both AGT and AGTW peripherals, the channel numbers used with the AGT driver are combined between both peripherals; AGTW channels are listed first followed by AGT. For example, on the RA2A2 there are 2 AGTW channels and 8 AGT channels. These correspond to channels 0-1 for AGTW0-AGTW1 and 2-9 for AGT0-AGT7.

Clock Configuration

The AGT clock is based on the PCLKB, LOCO, or Subclock frequency. You can set the clock frequency using the Clocks tab of the RA Configuration editor or by using the CGC Interface at run-time.

Pin Configuration

This module can use the AGTOA and AGTOB pins as output pins for periodic, one-shot, or PWM signals.

For input capture, the input signal must be applied to the AGTIOn pin.

For event counting, the AGTEEn enable pin is optional.

Timer Period

The RA Configuration editor will automatically calculate the period count value and source clock divider based on the selected period time, units, and clock speed.

When the selected unit is "Raw counts", the maximum allowed period setting varies depending on the selected clock source:

Clock source	16-bit Timer Maximum period (counts)	32-bit Timer Maximum period (counts)
LOCO/Subclock	0x800000	0x8000000000
PCLKB	0x80000	0x800000000
All other sources	0x10000	0x100000000

Note: 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).; When using a 32-bit channel (AGTW), a special period count value of 0 is used to obtain an actual period register value of 0xFFFFFFFF.

Usage Notes

Starting and Stopping the AGT

After starting or stopping the timer, AGT registers cannot be accessed until the AGT state is updated after 3 AGTCLK cycles. If another AGT function is called before the 3 AGTCLK period elapses, the function spins waiting for the AGT state to update. The required wait time after starting or stopping the timer can be determined using the frequency of AGTCLK, which is derived from timer_cfg_t::source_div and agt_extended_cfg_t::count_source.

The application is responsible for ensuring required clocks are started and stable before accessing MCU peripheral registers.

Warning: The subclock can take seconds to stabilize. The RA startup code does not wait for subclock stabilization unless the subclock is the main clock source. When running AGT or RTC off the subclock, the application must ensure the subclock is stable before starting operation.

Low Power Modes

The AGT1 (channel 1 only) can be used to enter snooze mode or to wake the MCU from snooze, software standby, or deep software standby modes when a counter underflow occurs. The compare match A and B events can also be used to wake from software standby or snooze modes.

One-Shot Mode

The AGT 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, but multiple events may be generated if the timer is linked to the Transfer (r_dtc).

One-Shot Mode Output

The output waveform in one-shot mode is one AGT clock cycle less than the configured period. The configured period must be at least 2 counts to generate an output pulse.

Examples of one-shot signals that can be generated by this module are shown below:

AGT One-Shot Output

Periodic Output

The AGTOA or AGTOB pin toggles twice each time the timer expires in periodic mode. This is achieved by defining a PWM wave at a 50 percent duty cycle so that the period of the resulting square (from rising edge to rising edge) matches the period of the AGT timer. Since the periodic output is actually a PWM output, the time at the stop level is one cycle shorter than the time opposite the stop level for odd period values.

Examples of periodic signals that can be generated by this module are shown below:

AGT Periodic Output

PWM Output

This module does not support in phase PWM output. The PWM output signal is low at the beginning of the cycle and high at the end of the cycle.

Examples of PWM signals that can be generated by this module are shown below:

AGT PWM Output

Triggering ELC Events with AGT

The AGT timer can trigger the start of other peripherals. The Event Link Controller (r_elc) guide provides a list of all available peripherals.

Examples

AGT Basic Example

This is a basic example of minimal use of the AGT in an application.

void agt_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_AGT_Start(&g_timer0_ctrl);
}

AGT 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. */
    }
}

AGT Free Running Counter Example

To use the AGT as a free running counter, select periodic mode and set the the Period to 0xFFFFFFFF for a 32-bit timer or 0xFFFF for a 16-bit timer.

void agt_counter_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_AGT_Start(&g_timer0_ctrl);
    /* (Optional) Stop the timer. */
    (void) R_AGT_Stop(&g_timer0_ctrl);
    /* Read the current counter value. Counter value is in status.counter. */
    timer_status_t status;
    (void) R_AGT_StatusGet(&g_timer0_ctrl, &status);
}

AGT Input Capture Example

This is an example of using the AGT to capture pulse width or pulse period measurements.

/* Example callback called when a capture occurs. */
uint64_t g_captured_time     = 0U;
uint32_t g_capture_overflows = 0U;
void timer_capture_callback (timer_callback_args_t * p_args)
{
    if (TIMER_EVENT_CAPTURE_A == p_args->event)
    {
        /* (Optional) Get the current period if not known. */
        timer_info_t info;
        (void) R_AGT_InfoGet(&g_timer0_ctrl, &info);
        uint32_t period = info.period_counts;
        /* Process capture from AGTIO. */
        g_captured_time     = ((uint64_t) period * g_capture_overflows) + p_args->capture;
        g_capture_overflows = 0U;
    }
    if (TIMER_EVENT_CYCLE_END == p_args->event)
    {
        /* An overflow occurred during capture. This must be accounted for at the application layer. */
        g_capture_overflows++;
    }
}
void agt_capture_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Enable captures. Captured values arrive in the interrupt. */
    (void) R_AGT_Enable(&g_timer0_ctrl);
    /* (Optional) Disable captures. */
    (void) R_AGT_Disable(&g_timer0_ctrl);
}

AGT Period Update Example

This an example of updating the period.

#define AGT_EXAMPLE_MSEC_PER_SEC           (1000)
#define AGT_EXAMPLE_DESIRED_PERIOD_MSEC    (20)
/* This example shows how to calculate a new period value at runtime. */
void agt_period_calculation_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_AGT_Start(&g_timer0_ctrl);
    /* Get the source clock frequency (in Hz). There are several ways to do this in FSP:
     *  - If LOCO or subclock is chosen in agt_extended_cfg_t::clock_source
     *      - The source clock frequency is BSP_LOCO_HZ >> timer_cfg_t::source_div
     *  - If PCLKB is chosen in agt_extended_cfg_t::clock_source and the PCLKB frequency has not changed since reset,
     *      - The source clock frequency is BSP_STARTUP_PCLKB_HZ >> timer_cfg_t::source_div
     *  - Use the R_AGT_InfoGet function (it accounts for the clock source and divider).
     *  - Calculate the current PCLKB frequency using R_FSP_SystemClockHzGet(FSP_PRIV_CLOCK_PCLKB) and right shift
     *    by timer_cfg_t::source_div.
     *
     * This example uses the last option (R_FSP_SystemClockHzGet).
     */
    uint32_t timer_freq_hz = R_FSP_SystemClockHzGet(FSP_PRIV_CLOCK_PCLKB) >> g_timer0_cfg.source_div;
    /* 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 * AGT_EXAMPLE_DESIRED_PERIOD_MSEC) / AGT_EXAMPLE_MSEC_PER_SEC);
    /* Set the calculated period. This will return an error if parameter checking is enabled and the calculated
     * period is larger than UINT16_MAX. */
    err = R_AGT_PeriodSet(&g_timer0_ctrl, period_counts);
    assert(FSP_SUCCESS == err);
}

AGT Duty Cycle Update Example

This an example of updating the duty cycle.

#define AGT_EXAMPLE_DESIRED_DUTY_CYCLE_PERCENT    (25)
#define AGT_EXAMPLE_MAX_PERCENT                   (100)
/* This example shows how to calculate a new duty cycle value at runtime. */
void agt_duty_cycle_calculation_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Start the timer. */
    (void) R_AGT_Start(&g_timer0_ctrl);
    /* Get the current period setting. */
    timer_info_t info;
    (void) R_AGT_InfoGet(&g_timer0_ctrl, &info);
    uint32_t current_period_counts = info.period_counts;
    /* Calculate the desired duty cycle based on the current period. */
    uint32_t duty_cycle_counts = (current_period_counts * AGT_EXAMPLE_DESIRED_DUTY_CYCLE_PERCENT) /
                                 AGT_EXAMPLE_MAX_PERCENT;
    /* Set the calculated duty cycle. */
    err = R_AGT_DutyCycleSet(&g_timer0_ctrl, duty_cycle_counts, AGT_OUTPUT_PIN_AGTOA);
    assert(FSP_SUCCESS == err);
}

AGT Cascaded Timers Example

This an example of using underflow from an even AGT channel as the count source for the next channel (in this case, AGT0 and AGT1).

/* This example shows how use cascaded timers. The count source for AGT channel 1 is set to AGT0 underflow. */
void agt_cascaded_timers_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Initialize the timers in any order. */
    err = R_AGT_Open(&g_timer_channel0_ctrl, &g_timer_channel0_cfg);
    assert(FSP_SUCCESS == err);
    err = R_AGT_Open(&g_timer_channel1_ctrl, &g_timer_channel1_cfg);
    assert(FSP_SUCCESS == err);
    /* Start AGT channel 1 first. */
    (void) R_AGT_Start(&g_timer_channel1_ctrl);
    (void) R_AGT_Start(&g_timer_channel0_ctrl);
    /* (Optional) Stop AGT channel 0 first. */
    (void) R_AGT_Stop(&g_timer_channel0_ctrl);
    (void) R_AGT_Stop(&g_timer_channel1_ctrl);
    /* Read the current counter value. Counter value is in status.counter. */
    timer_status_t status;
    (void) R_AGT_StatusGet(&g_timer_channel1_ctrl, &status);
}

Data Structures
struct	agt_instance_ctrl_t

struct	agt_extended_cfg_t

Enumerations
enum	agt_clock_t

enum	agt_measure_t

enum	agt_agtio_filter_t

enum	agt_enable_pin_t

enum	agt_trigger_edge_t

enum	agt_output_pin_t

enum	agt_pin_cfg_t

enum	agt_counter_bit_width_t

Data Structure Documentation

◆ agt_instance_ctrl_t

struct agt_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when timer_api_t::open is called.

◆ agt_extended_cfg_t

struct agt_extended_cfg_t

Optional AGT extension data structure.

Data Fields
agt_clock_t	count_source	AGT channel clock source. Valid values are: AGT_CLOCK_PCLKB, AGT_CLOCK_LOCO, AGT_CLOCK_FSUB.
union agt_extended_cfg_t	__unnamed__
agt_pin_cfg_t	agto: 3	Configure AGTO pin. Note AGTIO polarity is opposite AGTO
agt_measure_t	measurement_mode	Measurement mode.
agt_agtio_filter_t	agtio_filter	Input filter for AGTIO.
agt_enable_pin_t	enable_pin	Enable pin (event counting only)
agt_trigger_edge_t	trigger_edge	Trigger edge to start pulse period measurement or count external event.
agt_counter_bit_width_t	counter_bit_width	Counter bit width.

Enumeration Type Documentation

◆ agt_clock_t

enum agt_clock_t

Count source

Enumerator
AGT_CLOCK_PCLKB	PCLKB count source, division by 1, 2, or 8 allowed.
AGT_CLOCK_LOCO	LOCO count source, division by 1, 2, 4, 8, 16, 32, 64, or 128 allowed.
AGT_CLOCK_AGT_UNDERFLOW	Underflow event signal from next lowest AGT channel, division must be 1.
AGT_CLOCK_SUBCLOCK	Subclock count source, division by 1, 2, 4, 8, 16, 32, 64, or 128 allowed.
AGT_CLOCK_P402	Counts events on P402, events are counted in deep software standby mode.
AGT_CLOCK_P403	Counts events on P403, events are counted in deep software standby mode.
AGT_CLOCK_P404	Counts events on P404, events are counted in deep software standby mode.
AGT_CLOCK_AGTIO	Counts events on AGTIOn, events are not counted in software standby modes.

◆ agt_measure_t

enum agt_measure_t

Enable pin for event counting mode.

Enumerator
AGT_MEASURE_DISABLED	AGT used as a counter.
AGT_MEASURE_PULSE_WIDTH_LOW_LEVEL	AGT used to measure low level pulse width.
AGT_MEASURE_PULSE_WIDTH_HIGH_LEVEL	AGT used to measure high level pulse width.
AGT_MEASURE_PULSE_PERIOD	AGT used to measure pulse period.

◆ agt_agtio_filter_t

enum agt_agtio_filter_t

Input filter, applies AGTIO in pulse period measurement, pulse width measurement, or event counter mode. The filter requires the signal to be at the same level for 3 successive reads at the specified filter frequency.

Enumerator
AGT_AGTIO_FILTER_NONE	No filter.
AGT_AGTIO_FILTER_PCLKB	Filter at PCLKB.
AGT_AGTIO_FILTER_PCLKB_DIV_8	Filter at PCLKB / 8.
AGT_AGTIO_FILTER_PCLKB_DIV_32	Filter at PCLKB / 32.

◆ agt_enable_pin_t

enum agt_enable_pin_t

Enable pin for event counting mode.

Enumerator
AGT_ENABLE_PIN_NOT_USED	AGTEE/AGTWEE is not used.
AGT_ENABLE_PIN_ACTIVE_LOW	Events are only counted when AGTEE/AGTWEE is low.
AGT_ENABLE_PIN_ACTIVE_HIGH	Events are only counted when AGTEE/AGTWEE is high.

◆ agt_trigger_edge_t

enum agt_trigger_edge_t

Trigger edge for pulse period measurement mode and event counting mode.

Enumerator
AGT_TRIGGER_EDGE_RISING	Measurement starts or events are counted on rising edge.
AGT_TRIGGER_EDGE_FALLING	Measurement starts or events are counted on falling edge.
AGT_TRIGGER_EDGE_BOTH	Events are counted on both edges (n/a for pulse period mode)

◆ agt_output_pin_t

enum agt_output_pin_t

Output pins, used to select which duty cycle to update in R_AGT_DutyCycleSet().

Enumerator
AGT_OUTPUT_PIN_AGTOA	AGTOA.
AGT_OUTPUT_PIN_AGTOB	AGTOB.

◆ agt_pin_cfg_t

enum agt_pin_cfg_t

Level of AGT pin

Enumerator
AGT_PIN_CFG_DISABLED	Not used as output pin.
AGT_PIN_CFG_START_LEVEL_LOW	Pin level low.
AGT_PIN_CFG_START_LEVEL_HIGH	Pin level high.

◆ agt_counter_bit_width_t

enum agt_counter_bit_width_t

Counter type to determine regsiter size

Enumerator
AGT_COUNTER_BIT_WIDTH_DEFAULT	Legacy.
AGT_COUNTER_BIT_WIDTH_16	AGT.
AGT_COUNTER_BIT_WIDTH_32	AGTW.

Function Documentation

◆ R_AGT_Open()

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

Initializes the AGT module instance. Implements timer_api_t::open.

The AGT hardware does not support one-shot functionality natively. The one-shot feature is therefore implemented in the AGT HAL layer. For a timer configured as a one-shot timer, the timer is stopped upon the first timer expiration.

The AGT implementation of the general timer can accept an optional agt_extended_cfg_t extension parameter. For AGT, 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 PCLKB is used and the output pins are disabled.

Example:

    /* Initializes the module. */
    err = R_AGT_Open(&g_timer0_ctrl, &g_timer0_cfg);

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_AGT_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 AGT.

◆ R_AGT_Start()

fsp_err_t R_AGT_Start ( timer_ctrl_t *const p_ctrl )

Starts timer. Implements timer_api_t::start.

Example:

    /* Start the timer. */
    (void) R_AGT_Start(&g_timer0_ctrl);

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

fsp_err_t R_AGT_Stop ( timer_ctrl_t *const p_ctrl )

Stops the timer. Implements timer_api_t::stop.

Example:

    /* (Optional) Stop the timer. */
    (void) R_AGT_Stop(&g_timer0_ctrl);

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

fsp_err_t R_AGT_Reset ( timer_ctrl_t *const p_ctrl )

Resets the counter value to the period minus one. Implements timer_api_t::reset.

Return values

FSP_SUCCESS	Counter reset.
FSP_ERR_ASSERTION	p_ctrl is NULL
FSP_ERR_NOT_OPEN	The instance control structure is not opened.

◆ R_AGT_Enable()

fsp_err_t R_AGT_Enable ( timer_ctrl_t *const p_ctrl )

Enables external event triggers that start, stop, clear, or capture the counter. Implements timer_api_t::enable.

Example:

    /* Enable captures. Captured values arrive in the interrupt. */
    (void) R_AGT_Enable(&g_timer0_ctrl);

Return values

FSP_SUCCESS	External events successfully enabled.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

◆ R_AGT_Disable()

fsp_err_t R_AGT_Disable ( timer_ctrl_t *const p_ctrl )

Disables external event triggers that start, stop, clear, or capture the counter. Implements timer_api_t::disable.

Example:

    /* (Optional) Disable captures. */
    (void) R_AGT_Disable(&g_timer0_ctrl);

Return values

FSP_SUCCESS	External events successfully disabled.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

◆ R_AGT_PeriodSet()

fsp_err_t R_AGT_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 AGT 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.

Example:

    /* Get the source clock frequency (in Hz). There are several ways to do this in FSP:
     *  - If LOCO or subclock is chosen in agt_extended_cfg_t::clock_source
     *      - The source clock frequency is BSP_LOCO_HZ >> timer_cfg_t::source_div
     *  - If PCLKB is chosen in agt_extended_cfg_t::clock_source and the PCLKB frequency has not changed since reset,
     *      - The source clock frequency is BSP_STARTUP_PCLKB_HZ >> timer_cfg_t::source_div
     *  - Use the R_AGT_InfoGet function (it accounts for the clock source and divider).
     *  - Calculate the current PCLKB frequency using R_FSP_SystemClockHzGet(FSP_PRIV_CLOCK_PCLKB) and right shift
     *    by timer_cfg_t::source_div.
     *
     * This example uses the last option (R_FSP_SystemClockHzGet).
     */
    uint32_t timer_freq_hz = R_FSP_SystemClockHzGet(FSP_PRIV_CLOCK_PCLKB) >> g_timer0_cfg.source_div;
    /* 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 * AGT_EXAMPLE_DESIRED_PERIOD_MSEC) / AGT_EXAMPLE_MSEC_PER_SEC);
    /* Set the calculated period. This will return an error if parameter checking is enabled and the calculated
     * period is larger than UINT16_MAX. */
    err = R_AGT_PeriodSet(&g_timer0_ctrl, period_counts);
    assert(FSP_SUCCESS == err);

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

fsp_err_t R_AGT_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.

Example:

    /* Get the current period setting. */
    timer_info_t info;
    (void) R_AGT_InfoGet(&g_timer0_ctrl, &info);
    uint32_t current_period_counts = info.period_counts;
    /* Calculate the desired duty cycle based on the current period. */
    uint32_t duty_cycle_counts = (current_period_counts * AGT_EXAMPLE_DESIRED_DUTY_CYCLE_PERCENT) /
                                 AGT_EXAMPLE_MAX_PERCENT;
    /* Set the calculated duty cycle. */
    err = R_AGT_DutyCycleSet(&g_timer0_ctrl, duty_cycle_counts, AGT_OUTPUT_PIN_AGTOA);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Duty cycle updated.
FSP_ERR_ASSERTION	A required pointer was NULL, or the pin was not AGT_AGTO_AGTOA or AGT_AGTO_AGTOB.
FSP_ERR_INVALID_ARGUMENT	Duty cycle was not in the valid range of 0 to period (counts) - 1
FSP_ERR_NOT_OPEN	The instance control structure is not opened.
FSP_ERR_UNSUPPORTED	AGT_CFG_OUTPUT_SUPPORT_ENABLE is 0.

◆ R_AGT_CompareMatchSet()

fsp_err_t R_AGT_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 AGT compare match is not supported.

◆ R_AGT_InfoGet()

fsp_err_t R_AGT_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.

Example:

        /* (Optional) Get the current period if not known. */
        timer_info_t info;
        (void) R_AGT_InfoGet(&g_timer0_ctrl, &info);
        uint32_t period = info.period_counts;

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

fsp_err_t R_AGT_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.

Example:

    /* Read the current counter value. Counter value is in status.counter. */
    timer_status_t status;
    (void) R_AGT_StatusGet(&g_timer0_ctrl, &status);

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

fsp_err_t R_AGT_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.

◆ R_AGT_Close()

fsp_err_t R_AGT_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.

Functions

Detailed Description

Overview

Features

Selecting a Timer

Configuration

Build Time Configurations for r_agt

Configurations for Timers > Timer, Low-Power (r_agt)

Clock Configuration

Pin Configuration

Timer Period

Usage Notes

Starting and Stopping the AGT

Low Power Modes

One-Shot Mode

One-Shot Mode Output

Periodic Output

PWM Output

Triggering ELC Events with AGT

Examples

AGT Basic Example

AGT Callback Example

AGT Free Running Counter Example

AGT Input Capture Example

AGT Period Update Example

AGT Duty Cycle Update Example

AGT Cascaded Timers Example

Data Structures

Enumerations

Data Structure Documentation

◆ agt_instance_ctrl_t

◆ agt_extended_cfg_t

Enumeration Type Documentation

◆ agt_clock_t

◆ agt_measure_t

◆ agt_agtio_filter_t

◆ agt_enable_pin_t

◆ agt_trigger_edge_t

◆ agt_output_pin_t

◆ agt_pin_cfg_t

◆ agt_counter_bit_width_t

Function Documentation

◆ R_AGT_Open()

◆ R_AGT_Start()

◆ R_AGT_Stop()

◆ R_AGT_Reset()

◆ R_AGT_Enable()

◆ R_AGT_Disable()

◆ R_AGT_PeriodSet()

◆ R_AGT_DutyCycleSet()

◆ R_AGT_CompareMatchSet()

◆ R_AGT_InfoGet()

◆ R_AGT_StatusGet()

◆ R_AGT_CallbackSet()

◆ R_AGT_Close()