Timer (Timer/Counter)

General Description

High level interface for interacting with the Timer/Counter hardware resource.

The timer block is commonly used to measure the time of occurrence of an event, to measure the time difference between two events or perform an action after a specified period of time. The driver also allows the user to invoke a callback function when a particular event occurs.

Some use case scenarios of timer -

• Creating a periodic interrupt for executing periodic tasks
• Measuring time between two events
• Triggering other system resources after a certain number of events
• Capturing time stamps when events occur

Features

• Runtime configurable parameters like period and compare value - cyhal_timer_cfg_t
• Configurable counting direction - cyhal_timer_direction_t
• Interrupt on various events - cyhal_timer_event_t
• Continuous or One Shot run modes

Quick Start

cyhal_timer_init can be used for timer initialization by providing the timer object - cyhal_timer_t, and shared clock source - clk (optional). The timer parameters needs to be populated in cyhal_timer_cfg_t structure. The timer then needs to be configured by using the cyhal_timer_configure function.

Note

A default frequency is set when an existing clock divider - clk is not provided to cyhal_timer_init which is defined by the macro - CYHAL_TIMER_DEFAULT_FREQ.

Warning

Currently there is no support for pin connections to Timer using this driver. So, the pin should be assigned as NC while using the cyhal_timer_init to initialize the timer.

See Snippet 1: Measuring time of an operation.

Code Snippets

Snippet 1: Measuring time of an operation

The following snippet initializes a Timer and measures the time between two events. The clk need not be provided, in which case a clock resource is assigned.

    cy_rslt_t rslt;
    uint32_t  read_val;

    // Timer object used
    cyhal_timer_t timer_obj;

    const cyhal_timer_cfg_t timer_cfg =
    {
        .compare_value = 0,                  // Timer compare value, not used
        .period        = 20000,              // Timer period set to a large enough value
                                             //   compared to event being measured
        .direction     = CYHAL_TIMER_DIR_UP, // Timer counts up
        .is_compare    = false,              // Don't use compare mode
        .is_continuous = false,              // Do not run timer indefinitely
        .value         = 0                   // Initial value of counter
    };

    // Initialize the timer object. Does not use pin output ('pin' is NC) and does not use a
    // pre-configured clock source ('clk' is NULL).
    rslt = cyhal_timer_init(&timer_obj, NC, NULL);

    // Apply timer configuration such as period, count direction, run mode, etc.
    cyhal_timer_configure(&timer_obj, &timer_cfg);

    // Set the frequency of timer to 10000 counts in a second or 10000 Hz
    cyhal_timer_set_frequency(&timer_obj, 10000);

    // Start the timer with the configured settings
    cyhal_timer_start(&timer_obj);

    // Delay Function simulates the time between two events
    cyhal_system_delay_ms(500);

    // Read the current timer value, which should be close to the amount of delay in ms * 10 (5000)
    read_val = cyhal_timer_read(&timer_obj);

Snippet 2: Handling an event in a callback function

The following snippet initializes a Timer and triggers an event after every one second. The clk need not be provided (NULL), in which case a clock resource is assigned.

bool timer_interrupt_flag = false;

// Timer object used
cyhal_timer_t timer_obj;

static void isr_timer(void* callback_arg, cyhal_timer_event_t event)
{
    (void)callback_arg;
    (void)event;

    // Set the interrupt flag and process it from the application
    timer_interrupt_flag = true;
}


cy_rslt_t snippet_cyhal_timer_event_interrupt()
{
    cy_rslt_t rslt;

    const cyhal_timer_cfg_t timer_cfg =
    {
        .compare_value = 0,                  // Timer compare value, not used
        .period        = 9999,               // Defines the timer period
        .direction     = CYHAL_TIMER_DIR_UP, // Timer counts up
        .is_compare    = false,              // Don't use compare mode
        .is_continuous = true,               // Run the timer indefinitely
        .value         = 0                   // Initial value of counter
    };

    // Initialize the timer object. Does not use pin output ('pin' is NC) and does not use a
    // pre-configured clock source ('clk' is NULL).
    rslt = cyhal_timer_init(&timer_obj, NC, NULL);

    // Apply timer configuration such as period, count direction, run mode, etc.
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_timer_configure(&timer_obj, &timer_cfg);
    }

    // Set the frequency of timer to 10000 Hz
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_timer_set_frequency(&timer_obj, 10000);
    }

    if (CY_RSLT_SUCCESS == rslt)
    {
        // Assign the ISR to execute on timer interrupt
        cyhal_timer_register_callback(&timer_obj, isr_timer, NULL);

        // Set the event on which timer interrupt occurs and enable it
        cyhal_timer_enable_event(&timer_obj, CYHAL_TIMER_IRQ_TERMINAL_COUNT, 3, true);

        // Start the timer with the configured settings
        rslt = cyhal_timer_start(&timer_obj);
    }

    return rslt;
}

API Reference
	Timer HAL Results
	Timer specific return codes.

Data Structures
struct	cyhal_timer_cfg_t
	Describes the current configuration of a timer/counter. More...

Macros
#define	CYHAL_TIMER_DEFAULT_FREQ   (1000000u)
	Default timer frequency, used when an existing clock divider is not provided to cyhal_timer_init()

Typedefs
typedef void(*	cyhal_timer_event_callback_t) (void *callback_arg, cyhal_timer_event_t event)
	Handler for timer events.

Enumerations
enum	cyhal_timer_direction_t {   CYHAL_TIMER_DIR_UP,   CYHAL_TIMER_DIR_DOWN,   CYHAL_TIMER_DIR_UP_DOWN }
	Timer directions. More...
enum	cyhal_timer_event_t {   CYHAL_TIMER_IRQ_NONE = 0,   CYHAL_TIMER_IRQ_TERMINAL_COUNT = 1 << 0,   CYHAL_TIMER_IRQ_CAPTURE_COMPARE = 1 << 1,   CYHAL_TIMER_IRQ_ALL = (1 << 2) - 1 }
	Timer/counter interrupt triggers. More...
enum	cyhal_timer_input_t {   CYHAL_TIMER_INPUT_START,   CYHAL_TIMER_INPUT_STOP,   CYHAL_TIMER_INPUT_RELOAD,   CYHAL_TIMER_INPUT_COUNT,   CYHAL_TIMER_INPUT_CAPTURE }
	Timer/counter input signal. More...
enum	cyhal_timer_output_t {   CYHAL_TIMER_OUTPUT_OVERFLOW,   CYHAL_TIMER_OUTPUT_UNDERFLOW,   CYHAL_TIMER_OUTPUT_COMPARE_MATCH,   CYHAL_TIMER_OUTPUT_TERMINAL_COUNT }
	Timer/counter output signal. More...

Functions
cy_rslt_t	cyhal_timer_init (cyhal_timer_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk)
	Initialize the timer/counter peripheral and configure the pin. More...
cy_rslt_t	cyhal_timer_init_cfg (cyhal_timer_t *obj, const cyhal_timer_configurator_t *cfg)
	Initialize the Timer peripheral using a configurator generated configuration struct. More...
void	cyhal_timer_free (cyhal_timer_t *obj)
	Deinitialize the timer/counter object. More...
cy_rslt_t	cyhal_timer_configure (cyhal_timer_t *obj, const cyhal_timer_cfg_t *cfg)
	Updates the configuration and counter value of the timer/counter object. More...
cy_rslt_t	cyhal_timer_set_frequency (cyhal_timer_t *obj, uint32_t hz)
	Configures the timer frequency. More...
cy_rslt_t	cyhal_timer_start (cyhal_timer_t *obj)
	Starts the timer/counter with the pre-set configuration from cyhal_timer_configure. More...
cy_rslt_t	cyhal_timer_stop (cyhal_timer_t *obj)
	Stops the timer/counter. More...
cy_rslt_t	cyhal_timer_reset (cyhal_timer_t *obj)
	Reset the timer/counter value to the default value set from cyhal_timer_configure. More...
uint32_t	cyhal_timer_read (const cyhal_timer_t *obj)
	Reads the current value from the timer/counter See Snippet 1: Measuring time of an operation. More...
void	cyhal_timer_register_callback (cyhal_timer_t *obj, cyhal_timer_event_callback_t callback, void *callback_arg)
	Register a timer/counter callback handler More...
void	cyhal_timer_enable_event (cyhal_timer_t *obj, cyhal_timer_event_t event, uint8_t intr_priority, bool enable)
	Configure timer/counter event enablement More...
cy_rslt_t	cyhal_timer_connect_digital (cyhal_timer_t *obj, cyhal_source_t source, cyhal_timer_input_t signal)
	Connects a source signal and configures and enables a timer event to be triggered from that signal. More...
cy_rslt_t	cyhal_timer_enable_output (cyhal_timer_t *obj, cyhal_timer_output_t signal, cyhal_source_t *source)
	Enables the specified output signal from a tcpwm that will be triggered when the corresponding event occurs. More...
cy_rslt_t	cyhal_timer_disconnect_digital (cyhal_timer_t *obj, cyhal_source_t source, cyhal_timer_input_t signal)
	Disconnects a source signal and disables the timer event. More...
cy_rslt_t	cyhal_timer_disable_output (cyhal_timer_t *obj, cyhal_timer_output_t signal)
	Disables the specified output signal from a timer. More...

---

Data Structure Documentation

cyhal_timer_cfg_t

struct cyhal_timer_cfg_t

Data Fields
bool	is_continuous	Whether the timer is set to continuously run. If true, the timer will run forever. Otherwise, the timer will run once and stop (one shot).Whether the timer/counter operates continuous (true) or one shot (false)
cyhal_timer_direction_t	direction	Direction the timer/counter is running.
bool	is_compare	Is it in compare (true) or capture (false) mode.
uint32_t	period	Timer/counter period.
uint32_t	compare_value	Timer/counter comparison value.
uint32_t	value	Default value of the timer/counter. cyhal_timer_reset() will also change counter to this value when called.

Enumeration Type Documentation

cyhal_timer_direction_t

enum cyhal_timer_direction_t

Timer directions.

Enumerator
CYHAL_TIMER_DIR_UP	Counts up.
CYHAL_TIMER_DIR_DOWN	Counts down.
CYHAL_TIMER_DIR_UP_DOWN	Counts up and down, terminal count occurs on both overflow and underflow.

cyhal_timer_event_t

enum cyhal_timer_event_t

Timer/counter interrupt triggers.

Enumerator
CYHAL_TIMER_IRQ_NONE	No interrupt handled.
CYHAL_TIMER_IRQ_TERMINAL_COUNT	Interrupt when terminal count is reached.
CYHAL_TIMER_IRQ_CAPTURE_COMPARE	Interrupt when Compare/Capture value is reached.
CYHAL_TIMER_IRQ_ALL	Interrupt on terminal count and Compare/Capture values.

cyhal_timer_input_t

enum cyhal_timer_input_t

Timer/counter input signal.

Enumerator
CYHAL_TIMER_INPUT_START	Start signal.
CYHAL_TIMER_INPUT_STOP	Stop signal.
CYHAL_TIMER_INPUT_RELOAD	Reload signal.
CYHAL_TIMER_INPUT_COUNT	Count signal.
CYHAL_TIMER_INPUT_CAPTURE	Capture signal.

cyhal_timer_output_t

enum cyhal_timer_output_t

Timer/counter output signal.

Enumerator
CYHAL_TIMER_OUTPUT_OVERFLOW	Overflow signal.
CYHAL_TIMER_OUTPUT_UNDERFLOW	Underflow signal.
CYHAL_TIMER_OUTPUT_COMPARE_MATCH	Compare Match signal.
CYHAL_TIMER_OUTPUT_TERMINAL_COUNT	Terminal count signal (logical OR of overflow and underflow signal)

Function Documentation

cyhal_timer_init()

cy_rslt_t cyhal_timer_init	(	cyhal_timer_t *	obj,
		cyhal_gpio_t	pin,
		const cyhal_clock_t *	clk
	)

Initialize the timer/counter peripheral and configure the pin.

See Snippet 1: Measuring time of an operation.

Parameters

[out]	obj	Pointer to a timer/counter object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	pin	optional - The timer/counter compare/capture pin to initialize
[in]	clk	optional - The shared clock to use, if not provided a new clock will be allocated and the timer frequency will be set to CYHAL_TIMER_DEFAULT_FREQ

Returns

The status of the init request

cyhal_timer_init_cfg()

cy_rslt_t cyhal_timer_init_cfg	(	cyhal_timer_t *	obj,
		const cyhal_timer_configurator_t *	cfg
	)

Initialize the Timer peripheral using a configurator generated configuration struct.

Parameters

[out]	obj	Pointer to a Timer object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the init request

cyhal_timer_free()

void cyhal_timer_free

(

cyhal_timer_t *

obj

)

Deinitialize the timer/counter object.

Parameters

[in,out]

obj

The timer/counter object

cyhal_timer_configure()

cy_rslt_t cyhal_timer_configure	(	cyhal_timer_t *	obj,
		const cyhal_timer_cfg_t *	cfg
	)

Updates the configuration and counter value of the timer/counter object.

This function may temporary stop the timer if it is currently running. See Snippet 1: Measuring time of an operation.

Parameters

[in]	obj	The timer/counter object
[in]	cfg	The configuration of the timer/counter

Returns

The status of the configure request

cyhal_timer_set_frequency()

cy_rslt_t cyhal_timer_set_frequency	(	cyhal_timer_t *	obj,
		uint32_t	hz
	)

Configures the timer frequency.

Note

This is only valid to call if a null clock divider was provided to cyhal_timer_init. If a custom clock was provided its frequency should be adjusted directly.

See Snippet 1: Measuring time of an operation.

Parameters

[in]	obj	The timer/counter object
[in]	hz	The frequency rate in Hz

Returns

The status of the set_frequency request

cyhal_timer_start()

cy_rslt_t cyhal_timer_start

(

cyhal_timer_t *

obj

)

Starts the timer/counter with the pre-set configuration from cyhal_timer_configure.

This does not reset the counter. The count value will start from the value that was set by the last operation to modify it. See cyhal_timer_configure, and cyhal_timer_reset for how the value can be changed. If none of these functions have been called, it will start from 0.
See Snippet 1: Measuring time of an operation.

Parameters

[in]

obj

The timer/counter object

Returns

The status of the start request

cyhal_timer_stop()

cy_rslt_t cyhal_timer_stop

(

cyhal_timer_t *

obj

)

Stops the timer/counter.

Does not reset counter value.

Parameters

[in]

obj

The timer/counter object

Returns

The status of the stop request

cyhal_timer_reset()

cy_rslt_t cyhal_timer_reset

(

cyhal_timer_t *

obj

)

Reset the timer/counter value to the default value set from cyhal_timer_configure.

If cyhal_timer_configure was never called, this will reset timer/counter value to 0. This function may temporary stop the timer.

Parameters

[in]

obj

The timer/counter object

Returns

The status of the reset request

cyhal_timer_read()

uint32_t cyhal_timer_read

(

const cyhal_timer_t *

obj

)

Reads the current value from the timer/counter
See Snippet 1: Measuring time of an operation.

Parameters

[in]

obj

The timer/counter object

Returns

The current value of the timer/counter

cyhal_timer_register_callback()

void cyhal_timer_register_callback	(	cyhal_timer_t *	obj,
		cyhal_timer_event_callback_t	callback,
		void *	callback_arg
	)

Register a timer/counter callback handler

This function will be called when one of the events enabled by cyhal_timer_enable_event occurs.

See Snippet 2: Handling an event in a callback function.

Parameters

[in]	obj	The timer/counter object
[in]	callback	The callback handler which will be invoked when the event occurs
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_timer_enable_event()

void cyhal_timer_enable_event	(	cyhal_timer_t *	obj,
		cyhal_timer_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure timer/counter event enablement

When an enabled event occurs, the function specified by cyhal_timer_register_callback will be called.

See Snippet 2: Handling an event in a callback function.

Parameters

[in]	obj	The timer/counter object
[in]	event	The timer/counter event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off

cyhal_timer_connect_digital()

cy_rslt_t cyhal_timer_connect_digital	(	cyhal_timer_t *	obj,
		cyhal_source_t	source,
		cyhal_timer_input_t	signal
	)

Connects a source signal and configures and enables a timer event to be triggered from that signal.

These timer events can be configured independently and connect to the same or different source signals.

Parameters

[in]	obj	Timer obj
[in]	source	Source signal obtained from another driver's cyhal_<PERIPH>_enable_output
[in]	signal	The timer input signal

Returns

The current status of the connection

cyhal_timer_enable_output()

cy_rslt_t cyhal_timer_enable_output	(	cyhal_timer_t *	obj,
		cyhal_timer_output_t	signal,
		cyhal_source_t *	source
	)

Enables the specified output signal from a tcpwm that will be triggered when the corresponding event occurs.

Multiple output signals can be configured simultaneously.

Parameters

[in]	obj	Timer obj
[in]	signal	The timer output signal
[out]	source	Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

Returns

The current status of the output enable

cyhal_timer_disconnect_digital()

cy_rslt_t cyhal_timer_disconnect_digital	(	cyhal_timer_t *	obj,
		cyhal_source_t	source,
		cyhal_timer_input_t	signal
	)

Disconnects a source signal and disables the timer event.

Parameters

[in]	obj	Timer obj
[in]	source	Source signal from cyhal_<PERIPH>_enable_output to disable
[in]	signal	The timer input signal

Returns

The status of the disconnection

cyhal_timer_disable_output()

cy_rslt_t cyhal_timer_disable_output	(	cyhal_timer_t *	obj,
		cyhal_timer_output_t	signal
	)

Disables the specified output signal from a timer.

Parameters

[in]	obj	Timer obj
[in]	signal	The timer output signal

Returns

The status of the output disable