Timer (Timer/Counter)

group group_hal_timer

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

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);
}

Defines

CYHAL_TIMER_DEFAULT_FREQ

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.

Enums

enum cyhal_timer_direction_t

cyhal_timer_direction_t: Timer directions.

Values:

enumerator CYHAL_TIMER_DIR_UP

Counts up.

enumerator CYHAL_TIMER_DIR_DOWN

Counts down.

enumerator CYHAL_TIMER_DIR_UP_DOWN

Counts up and down, terminal count occurs on both overflow and underflow.

enum cyhal_timer_event_t

cyhal_timer_event_t: Timer/counter interrupt triggers.

Values:

enumerator CYHAL_TIMER_IRQ_NONE

No interrupt handled.

enumerator CYHAL_TIMER_IRQ_TERMINAL_COUNT

Interrupt when terminal count is reached.

enumerator CYHAL_TIMER_IRQ_CAPTURE_COMPARE

Interrupt when Compare/Capture value is reached.

enumerator CYHAL_TIMER_IRQ_ALL

Interrupt on terminal count and Compare/Capture values.

enum cyhal_timer_input_t

cyhal_timer_input_t: Timer/counter input signal.

Values:

enumerator CYHAL_TIMER_INPUT_START

Start signal.

enumerator CYHAL_TIMER_INPUT_STOP

Stop signal.

enumerator CYHAL_TIMER_INPUT_RELOAD

Reload signal.

enumerator CYHAL_TIMER_INPUT_COUNT

Count signal.

enumerator CYHAL_TIMER_INPUT_CAPTURE

Capture signal.

enum cyhal_timer_output_t

cyhal_timer_output_t: Timer/counter output signal.

Values:

enumerator CYHAL_TIMER_OUTPUT_OVERFLOW

Overflow signal.

enumerator CYHAL_TIMER_OUTPUT_UNDERFLOW

Underflow signal.

enumerator CYHAL_TIMER_OUTPUT_COMPARE_MATCH

Compare Match signal.

enumerator CYHAL_TIMER_OUTPUT_TERMINAL_COUNT

Terminal count signal (logical OR of overflow and underflow signal)

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.

See

Snippet 1: Measuring time of an operation.

Return

The status of the init request

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

void cyhal_timer_free(cyhal_timer_t *obj)

Deinitialize the timer/counter object.

Parameters
  • [inout] obj: The timer/counter object

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

The status of the configure request

Parameters
  • [in] obj: The timer/counter object

  • [in] cfg: The configuration of the timer/counter

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

The status of the set_frequency request

Parameters
  • [in] obj: The timer/counter object

  • [in] hz: The frequency rate in Hz

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.

Return

The status of the start request

Parameters
  • [in] obj: The timer/counter object

cy_rslt_t cyhal_timer_stop(cyhal_timer_t *obj)

Stops the timer/counter.

Does not reset counter value.

Return

The status of the stop request

Parameters
  • [in] obj: The timer/counter object

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.

Return

The status of the reset request

Parameters
  • [in] obj: The timer/counter object

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.

Return

The current value of the timer/counter

Parameters
  • [in] obj: The timer/counter object

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

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

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

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.

Return

The current status of the connection

Parameters
  • [in] obj: Timer obj

  • [in] source: Source signal obtained from another driver’s cyhal_<PERIPH>_enable_output

  • [in] signal: The timer input signal

  • [in] type: The timer input signal edge type

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.

Return

The current status of the output enable

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.

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.

Return

The status of the disconnection

Parameters
  • [in] obj: Timer obj

  • [in] source: Source signal from cyhal_<PERIPH>_enable_output to disable

  • [in] signal: The timer input signal

cy_rslt_t cyhal_timer_disable_output(cyhal_timer_t *obj, cyhal_timer_output_t signal)

Disables the specified output signal from a timer.

Return

The status of the output disable

Parameters
  • [in] obj: Timer obj

  • [in] signal: The timer output signal

struct cyhal_timer_cfg_t
#include <cyhal_timer.h>

Describes the current configuration of a timer/counter.

Public Members

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.