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;
}
void 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);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);
    /* Apply timer configuration such as period, count direction, run mode, etc. */
    rslt = cyhal_timer_configure(&timer_obj, &timer_cfg);
    /* Set the frequency of timer to 10000 Hz */
    rslt = cyhal_timer_set_frequency(&timer_obj, 10000);
    /* 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);
}

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

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

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

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.

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_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

General Description

Features

Quick Start

Code Snippets

Snippet 1: Measuring time of an operation

Snippet 2: Handling an event in a callback function

API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ cyhal_timer_cfg_t

Enumeration Type Documentation

◆ cyhal_timer_direction_t

◆ cyhal_timer_event_t

Function Documentation

◆ cyhal_timer_init()

◆ cyhal_timer_free()

◆ cyhal_timer_configure()

◆ cyhal_timer_set_frequency()

◆ cyhal_timer_start()

◆ cyhal_timer_stop()

◆ cyhal_timer_reset()

◆ cyhal_timer_read()

◆ cyhal_timer_register_callback()

◆ cyhal_timer_enable_event()