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 -
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.
See 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.
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.
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... | |
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. |
enum cyhal_timer_event_t |
Timer/counter interrupt triggers.
enum cyhal_timer_input_t |
enum cyhal_timer_output_t |
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.
[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 |
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.
[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. |
void cyhal_timer_free | ( | cyhal_timer_t * | obj | ) |
Deinitialize the timer/counter object.
[in,out] | 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.
[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.
See Snippet 1: Measuring time of an operation.
[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.
[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.
[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.
[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.
[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.
[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.
[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 | ||
) |
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.
[in] | obj | Timer obj |
[in] | source | Source signal obtained from another driver's cyhal_<PERIPH>_enable_output |
[in] | signal | The timer input signal |
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.
[in] | obj | Timer obj |
[in] | source | Source signal obtained from another driver's cyhal_<PERIPH>_enable_output |
[in] | signal | The timer input signal |
[in] | edge_type | The 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. |
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.
[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.
[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.
[in] | obj | Timer obj |
[in] | signal | The timer output signal |