Compare Match Timer W (r_cmtw)

Functions
fsp_err_t	R_CMTW_Close (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_PeriodSet (timer_ctrl_t *const p_ctrl, uint32_t const period_counts)
fsp_err_t	R_CMTW_DutyCycleSet (timer_ctrl_t *const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin)
fsp_err_t	R_CMTW_Reset (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_Start (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_Enable (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_Disable (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_InfoGet (timer_ctrl_t *const p_ctrl, timer_info_t *const p_info)
fsp_err_t	R_CMTW_StatusGet (timer_ctrl_t *const p_ctrl, timer_status_t *const p_status)
fsp_err_t	R_CMTW_Stop (timer_ctrl_t *const p_ctrl)
fsp_err_t	R_CMTW_Open (timer_ctrl_t *const p_ctrl, timer_cfg_t const *const p_cfg)
fsp_err_t	R_CMTW_OutputEnable (timer_ctrl_t *const p_ctrl, cmtw_io_pin_t pin)
fsp_err_t	R_CMTW_OutputDisable (timer_ctrl_t *const p_ctrl, cmtw_io_pin_t pin)
fsp_err_t	R_CMTW_CallbackSet (timer_ctrl_t *const p_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 CMTW peripheral on RZ microprocessor. This module implements the Timer Interface.

Overview

Features

The CMTW module has the following features:

• Supports periodic mode and one-shot mode.
• Supports count source of PCLKL.
• Supports Input capture function, Output compare function, and Compare match function.
• Signal can be output to a pin.
• Configurable period (counts per timer cycle).
• Supports runtime reconfiguration of 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.

Configuration

Build Time Configurations for r_cmtw

The following build time configurations are defined in fsp_cfg/r_cmtw_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.
Multiplex Interrupt	Enabled Disabled	Disabled	Enable multiplex interrupt for a single driver.

Configurations for Timers > Timer, Compare Match W (r_cmtw)

This module can be added to the Stacks tab via New Stack > Timers > Timer, Compare Match W (r_cmtw).

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 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	0x10000	Specify the timer period based on the selected unit.
General > Period Unit	Raw Counts Nanoseconds Microseconds Milliseconds Seconds Hertz Kilohertz	Raw Counts	Unit of the period specified above
General > Counter Size	32-bit 16-bit	32-bit	Size of the timer counter
General > Counter Clear Source	Compare Match Disabled Input Capture0 Input Capture1 Output Compare0 Output Compare1	Compare Match	Select the Counter Clear Source.
Output > TOC0 Output	Disabled Start Level Low and Toggle Output Start Level High and Toggle Output	Disabled	Configure TOC0 output.
Output > TOC1 Output	Disabled Start Level Low and Toggle Output Start Level High and Toggle Output	Disabled	Configure TOC1 output.
Output > TOC0 Output Enable	Output Disable Output Enable	Output Disable	Configure TOC0 output enable.
Output > TOC1 Output Enable	Output Disable Output Enable	Output Disable	Configure TOC1 output enable.
Input > TIC0 Capture Trigger	Rising Edge Falling Edge Both Edge	Rising Edge	Select the trigger edge.
Input > TIC1 Capture Trigger	Rising Edge Falling Edge Both Edge	Rising Edge	Select the trigger edge.
Input > TIC0 Input Enable	Input Disable Input Enable	Input Disable	Configure TIC0 output enable.
Input > TIC1 Input Enable	Input Disable Input Enable	Input Disable	Configure TIC1 output enable.
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 > Compare Match Interrupt Priority	MCU Specific Options		Compare match interrupt priority.
Interrupts > Input Capture 0 Interrupt Priority	MCU Specific Options		Input capture 0 interrupt priority.
Interrupts > Input Capture 1 Interrupt Priority	MCU Specific Options		Input capture 1 interrupt priority.
Interrupts > Output Compare 0 Interrupt Priority	MCU Specific Options		Output capture 0 interrupt priority.
Interrupts > Output Compare 1 Interrupt Priority	MCU Specific Options		Output capture 1 interrupt priority.

Clock Configuration

The CMTW clock is based on the PCLKL. You can set the clock frequency using the Clocks tab of the FSP Configuration editor or by using the CGC Interface at run-time.

Pin Configuration

This module can use the TOC0 and TOC1 pins as output pins for output compare or one-shot signals.

For input capture, the input signal must be applied to the TIC0 or TIC1 pin.

Timer Period

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

Clock source	Maximum period (counts)
PCLKL	0x10000(16-bit counter) / 0x100000000(32-bit counter)

Note

Because the period interrupt occurs when the counter overflows, 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

One-Shot Mode

The CMTW 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 Direct Memory Access Controller (r_dmac).

One-Shot Mode Output

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

CMTW One-Shot Output

Output Compare

The TOC0 or TOC1 pin toggles each time the timer expires in output compare mode.

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

CMTW Periodic Output

Examples

CMTW Basic Example

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

void cmtw_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


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

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);



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

}

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

CMTW Free Running Counter Example

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

void cmtw_counter_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

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

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);

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


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



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

}

CMTW Input Capture Example

This is an example of using the CMTW 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_CMTW_InfoGet(&g_timer0_ctrl, &info);
        uint32_t period = info.period_counts;


        /* Process capture from  CMTWm_TIC0/CMTWm_TIC1. */
        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 cmtw_capture_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

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

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);


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



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

}

CMTW Period Update Example

This an example of updating the period.

#define CMTW_EXAMPLE_MSEC_PER_SEC           (1000)
#define CMTW_EXAMPLE_DESIRED_PERIOD_MSEC    (20)

/* This example shows how to calculate a new period value at runtime. */
void cmtw_period_calculation_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

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

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);

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


    /* Get the source clock frequency (in Hz). There are several ways to do this in FSP:
     *  - Use the R_CMTW_InfoGet function (it accounts for the clock source and divider).
     *  - Calculate the current PCLKL frequency using R_FSP_SystemClockHzGet(FSP_PRIV_CLOCK_PCLKL) 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_PCLKL) >> 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 / pclkl_freq_hz. A cast to uint64_t is used to prevent this. */
    uint32_t period_counts =
        (uint32_t) (((uint64_t) timer_freq_hz * CMTW_EXAMPLE_DESIRED_PERIOD_MSEC) / CMTW_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 when the count value is 16-bit wide. */
    err = R_CMTW_PeriodSet(&g_timer0_ctrl, period_counts);
    handle_error(err);

}

Data Structures
struct	cmtw_instance_ctrl_t
struct	cmtw_extended_cfg_t

Enumerations
enum	cmtw_source_edge_t
enum	cmtw_output_pin_t
enum	cmtw_clear_source_t
enum	cmtw_io_pin_t
enum	cmtw_output_control_t
enum	cmtw_input_control_t

---

Data Structure Documentation

cmtw_instance_ctrl_t

struct cmtw_instance_ctrl_t

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

cmtw_extended_cfg_t

struct cmtw_extended_cfg_t

Optional CMTW extension data structure.

Data Fields
cmtw_output_pin_t	toc0	Configure TOC0 pin.
cmtw_output_pin_t	toc1	Configure TOC1 pin.
cmtw_output_control_t	toc0_control	OutputCompare0 enable setting.
cmtw_output_control_t	toc1_control	OutputCompare1 enable setting.
cmtw_source_edge_t	capture_ic0_source	Event sources that trigger capture of TIC0.
cmtw_source_edge_t	capture_ic1_source	Event sources that trigger capture of TIC1.
cmtw_input_control_t	ic0_control	InputCapture0 enable setting.
cmtw_input_control_t	ic1_control	InputCapture1 enable setting.
cmtw_clear_source_t	clear_source	Counter clear source.
timer_variant_t	counter_size	Timer counter size.
uint8_t	capture_ic0_ipl	InputCapture 0 interrupt priority.
uint8_t	capture_ic1_ipl	InputCapture 1 interrupt priority.
IRQn_Type	capture_ic0_irq	InputCapture 0 interrupt.
IRQn_Type	capture_ic1_irq	InputCapture 1 interrupt.
uint8_t	compare_oc0_ipl	OutputCompare 0 interrupt priority.
uint8_t	compare_oc1_ipl	OutputCompare 1 interrupt priority.
IRQn_Type	compare_oc0_irq	OutputCompare 0 interrupt.
IRQn_Type	compare_oc1_irq	OutputCompare 1 interrupt.

Enumeration Type Documentation

cmtw_source_edge_t

enum cmtw_source_edge_t

Trigger edge for Input capture function.

Enumerator
CMTW_SOURCE_EDGE_RISING	Input capture trigger on rising edge.
CMTW_SOURCE_EDGE_FALLING	Input capture trigger on falling edge.
CMTW_SOURCE_EDGE_BOTH	Input capture trigger on both edge.

cmtw_output_pin_t

enum cmtw_output_pin_t

Level of CMTW pin

Enumerator
CMTW_OUTPUT_PIN_RETAIN	Retain output value.
CMTW_OUTPUT_PIN_START_LEVEL_LOW	Pin level low.
CMTW_OUTPUT_PIN_START_LEVEL_HIGH	Pin level high.

cmtw_clear_source_t

enum cmtw_clear_source_t

Clear source of CMWCNT

Enumerator
CMTW_CLEAR_SOURCE_COMPARE_MATCH_CMWCOR	Counter is cleared by CMWCOR compare match.
CMTW_CLEAR_SOURCE_DISABLED	Counter is not cleared.
CMTW_CLEAR_SOURCE_INPUT_CAPTURE_CMWICR0	Counter is cleared by CMWICR0 input capture.
CMTW_CLEAR_SOURCE_INPUT_CAPTURE_CMWICR1	Counter is cleared by CMWICR1 input capture.
CMTW_CLEAR_SOURCE_COMPARE_MATCH_CMWOCR0	Counter is cleared by CMWOCR0 output compare.
CMTW_CLEAR_SOURCE_COMPARE_MATCH_CMWOCR1	Counter is cleared by CMWOCR1 output compare.

cmtw_io_pin_t

enum cmtw_io_pin_t

Output pins, used to select

Enumerator
CMTW_IO_PIN_TOC0	TOC0.
CMTW_IO_PIN_TOC1	TOC1.
CMTW_IO_PIN_TOC0_AND_TOC1	TOC0 and TOC1.

cmtw_output_control_t

enum cmtw_output_control_t

Enumerator
CMTW_OUTPUT_CONTROL_DISABLED	OutputCompare disabled.
CMTW_OUTPUT_CONTROL_ENABLED	OutputCompare enabled.

cmtw_input_control_t

enum cmtw_input_control_t

Enumerator
CMTW_INPUT_CONTROL_DISABLED	InputCapture disabled.
CMTW_INPUT_CONTROL_ENABLED	InputCapture enabled.

Function Documentation

R_CMTW_Close()

fsp_err_t R_CMTW_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_CMTW_PeriodSet()

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

Updates period. The new period is updated immediately. Implements timer_api_t::periodSet.

Warning

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 in 16bit counter or 1 to 0xFFFFFFFF in 32bit counter.
FSP_ERR_NOT_OPEN	The instance control structure is not opened.

R_CMTW_DutyCycleSet()

fsp_err_t R_CMTW_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

CMTW duty cycle set is not supported.

R_CMTW_Reset()

fsp_err_t R_CMTW_Reset

(

timer_ctrl_t *const

p_ctrl

)

Resets the counter value to 0. 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_CMTW_Start()

fsp_err_t R_CMTW_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_CMTW_Enable()

fsp_err_t R_CMTW_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_SUCCESS	External events successfully enabled.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_CMTW_Disable()

fsp_err_t R_CMTW_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_SUCCESS	External events successfully disabled.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_CMTW_InfoGet()

fsp_err_t R_CMTW_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_CMTW_StatusGet()

fsp_err_t R_CMTW_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_CMTW_Stop()

fsp_err_t R_CMTW_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_CMTW_Open()

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

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

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

The CMTW implementation of the general timer can accept an optional cmtw_extended_cfg_t extension parameter.

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 in 16bit counter or 1 to 0xFFFFFFFF in 32bit counter.
FSP_ERR_ALREADY_OPEN	R_CMTW_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 CMTW.

R_CMTW_OutputEnable()

fsp_err_t R_CMTW_OutputEnable	(	timer_ctrl_t *const	p_ctrl,
		cmtw_io_pin_t	pin
	)

Enable output for TOC0 and/or TOC1.

Return values

FSP_SUCCESS	Output is enabled.
FSP_ERR_ASSERTION	p_ctrl or p_status was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_CMTW_OutputDisable()

fsp_err_t R_CMTW_OutputDisable	(	timer_ctrl_t *const	p_ctrl,
		cmtw_io_pin_t	pin
	)

Disable output for TOC0 and/or TOC1.

Return values

FSP_SUCCESS	Output is disabled.
FSP_ERR_ASSERTION	p_ctrl or p_status was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_CMTW_CallbackSet()

fsp_err_t R_CMTW_CallbackSet	(	timer_ctrl_t *const	p_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.