Hardware Abstraction Layer (HAL)
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 -

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
// 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);
Timer object.
Definition: cyhal_hw_types.h:1478
@ NC
No Connect/Invalid Pin.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:53
cy_rslt_t cyhal_system_delay_ms(uint32_t milliseconds)
Requests that the current operation delays for at least the specified length of time.
uint32_t compare_value
Timer/counter comparison value.
Definition: cyhal_timer.h:178
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.
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.
cy_rslt_t cyhal_timer_set_frequency(cyhal_timer_t *obj, uint32_t hz)
Configures the timer frequency.
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.
cy_rslt_t cyhal_timer_start(cyhal_timer_t *obj)
Starts the timer/counter with the pre-set configuration from cyhal_timer_configure.
@ CYHAL_TIMER_DIR_UP
Counts up.
Definition: cyhal_timer.h:130
Describes the current configuration of a timer/counter.
Definition: cyhal_timer.h:168
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

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
// Start the timer with the configured settings
rslt = cyhal_timer_start(&timer_obj);
}
return rslt;
}
cyhal_timer_event_t
Timer/counter interrupt triggers.
Definition: cyhal_timer.h:136
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
void cyhal_timer_register_callback(cyhal_timer_t *obj, cyhal_timer_event_callback_t callback, void *callback_arg)
Register a timer/counter callback handler
@ CYHAL_TIMER_IRQ_TERMINAL_COUNT
Interrupt when terminal count is reached.
Definition: cyhal_timer.h:138
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

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_connect_digital2 (cyhal_timer_t *obj, cyhal_source_t source, cyhal_timer_input_t signal, cyhal_edge_type_t edge_type)
 Connects a source signal and configures and enables a timer event to be triggered from that signal with a configurable edge type. 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

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

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

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

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]objPointer to a timer/counter object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]pinoptional - The timer/counter compare/capture pin to initialize
[in]clkoptional - 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]objPointer to a Timer object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]cfgConfiguration 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]objThe 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]objThe timer/counter object
[in]cfgThe 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]objThe timer/counter object
[in]hzThe 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]objThe 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]objThe 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]objThe 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]objThe 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]objThe timer/counter object
[in]callbackThe callback handler which will be invoked when the event occurs
[in]callback_argGeneric 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]objThe timer/counter object
[in]eventThe timer/counter event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue 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.

Note
For "edge" signals, this function will default to rising edge. To control the edge type, use cyhal_timer_connect_digital2
Parameters
[in]objTimer obj
[in]sourceSource signal obtained from another driver's cyhal_<PERIPH>_enable_output
[in]signalThe timer input signal
Returns
The current status of the connection

◆ cyhal_timer_connect_digital2()

cy_rslt_t cyhal_timer_connect_digital2 ( cyhal_timer_t obj,
cyhal_source_t  source,
cyhal_timer_input_t  signal,
cyhal_edge_type_t  edge_type 
)

Connects a source signal and configures and enables a timer event to be triggered from that signal with a configurable edge type.

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

Parameters
[in]objTimer obj
[in]sourceSource signal obtained from another driver's cyhal_<PERIPH>_enable_output
[in]signalThe timer input signal
[in]edge_typeThe edge type that should trigger the event. This must be consistent with the edge type of source. If source produces a "level" signal, the only valid value is CYHAL_EDGE_TYPE_LEVEL. If source produces an "edge" signal, then CYHAL_EDGE_TYPE_LEVEL is not a valid value.
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]objTimer obj
[in]signalThe timer output signal
[out]sourcePointer 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]objTimer obj
[in]sourceSource signal from cyhal_<PERIPH>_enable_output to disable
[in]signalThe 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]objTimer obj
[in]signalThe timer output signal
Returns
The status of the output disable