Hardware Abstraction Layer (HAL)
LPTimer (Low-Power Timer)

General Description

High level interface for interacting with the low-power timer (LPTimer).

LPTimer can operate in all possible low power modes. It can be used either to measure timing between events, or to perform some action after a specified interval of time.

Features

Quick Start

cyhal_lptimer_init can be used for a LPTimer initialization which resets all the clocking and prescaler registers, along with disabling the compare interrupt.

See Snippet 2: LPTimer interrupts.

Code snippets

Snippet 1: LPTimer initialization with Default configuration

The following snippet initializes a LPTimer in free running mode.

cy_rslt_t rslt;
cyhal_lptimer_t lptimer;
uint32_t lptimer_value;
// Initialize the LPTIMER with default configuration
rslt = cyhal_lptimer_init(&lptimer);
// Read the LPTIMER count value
lptimer_value = cyhal_lptimer_read(&lptimer);
LPTIMER object.
Definition: cyhal_hw_types.h:911
cy_rslt_t cyhal_lptimer_init(cyhal_lptimer_t *obj)
Initialize the LPTimer.
uint32_t cyhal_lptimer_read(const cyhal_lptimer_t *obj)
Read the current tick.
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

Snippet 2: LPTimer interrupts

The following snippet initializes a LPTimer and uses cyhal_lptimer_set_match() to trigger an interrupt on match. Subsequent interrupts can be triggered at required times using cyhal_lptimer_set_delay() called from the ISR.

#define LPTIMER_MATCH_VALUE (8192u)
#define LPTIMER_INTR_PRIORITY (3u)
cyhal_lptimer_t lptimer_obj;
cy_rslt_t snippet_lptimer_init()
{
cy_rslt_t rslt;
// Initialize the LPTIMER
rslt = cyhal_lptimer_init(&lptimer_obj);
// Set a match value of 8192 counts (~0.25 seconds for a clock source of 32768 Hz)
if (CY_RSLT_SUCCESS == rslt)
{
rslt = cyhal_lptimer_set_match(&lptimer_obj, LPTIMER_MATCH_VALUE);
}
if (CY_RSLT_SUCCESS == rslt)
{
// Register the callback handler which will be invoked when the interrupt triggers
cyhal_lptimer_register_callback(&lptimer_obj, lptimer_interrupt_handler, NULL);
// Configure and Enable the LPTIMER events
cyhal_lptimer_enable_event(&lptimer_obj, CYHAL_LPTIMER_COMPARE_MATCH, LPTIMER_INTR_PRIORITY,
true);
// Reload/Reset the Low-Power timer to start counting from this instant
rslt = cyhal_lptimer_reload(&lptimer_obj);
}
return rslt;
}
void lptimer_interrupt_handler(void* handler_arg, cyhal_lptimer_event_t event)
{
CY_UNUSED_PARAMETER(handler_arg);
CY_UNUSED_PARAMETER(event);
// Reload/Reset the Low-Power timer to start counting from this instant
cyhal_lptimer_set_delay(&lptimer_obj, LPTIMER_MATCH_VALUE);
}
cy_rslt_t cyhal_lptimer_reload(cyhal_lptimer_t *obj)
Reload/Reset the Low-Power timer.
cyhal_lptimer_event_t
LPTimer interrupt triggers.
Definition: cyhal_lptimer.h:107
cy_rslt_t cyhal_lptimer_set_match(cyhal_lptimer_t *obj, uint32_t ticks)
Update the match/compare value.
void cyhal_lptimer_enable_event(cyhal_lptimer_t *obj, cyhal_lptimer_event_t event, uint8_t intr_priority, bool enable)
Configure and Enable/Disable the LPTimer events.
void cyhal_lptimer_register_callback(cyhal_lptimer_t *obj, cyhal_lptimer_event_callback_t callback, void *callback_arg)
Register a LPTimer match event handler.
cy_rslt_t cyhal_lptimer_set_delay(cyhal_lptimer_t *obj, uint32_t delay)
Update the match/compare value.
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

API Reference

 LPTimer HAL Results
 LPTimer specific return codes.
 

Data Structures

struct  cyhal_lptimer_info_t
 LPTimer Information. More...
 

Macros

#define cyhal_lptimer_set_time   cyhal_lptimer_set_match
 Deprecated. More...
 

Typedefs

typedef void(* cyhal_lptimer_event_callback_t) (void *callback_arg, cyhal_lptimer_event_t event)
 Handler for LPTimer interrupts.
 

Enumerations

enum  cyhal_lptimer_event_t { CYHAL_LPTIMER_COMPARE_MATCH }
 LPTimer interrupt triggers.
 

Functions

cy_rslt_t cyhal_lptimer_init (cyhal_lptimer_t *obj)
 Initialize the LPTimer. More...
 
void cyhal_lptimer_free (cyhal_lptimer_t *obj)
 Deinitialize the LPTimer. More...
 
cy_rslt_t cyhal_lptimer_reload (cyhal_lptimer_t *obj)
 Reload/Reset the Low-Power timer. More...
 
cy_rslt_t cyhal_lptimer_set_match (cyhal_lptimer_t *obj, uint32_t ticks)
 Update the match/compare value. More...
 
cy_rslt_t cyhal_lptimer_set_delay (cyhal_lptimer_t *obj, uint32_t delay)
 Update the match/compare value. More...
 
uint32_t cyhal_lptimer_read (const cyhal_lptimer_t *obj)
 Read the current tick. More...
 
void cyhal_lptimer_register_callback (cyhal_lptimer_t *obj, cyhal_lptimer_event_callback_t callback, void *callback_arg)
 Register a LPTimer match event handler. More...
 
void cyhal_lptimer_enable_event (cyhal_lptimer_t *obj, cyhal_lptimer_event_t event, uint8_t intr_priority, bool enable)
 Configure and Enable/Disable the LPTimer events. More...
 
void cyhal_lptimer_irq_trigger (cyhal_lptimer_t *obj)
 Manually trigger the LPTimer interrupt. More...
 
void cyhal_lptimer_get_info (cyhal_lptimer_t *obj, cyhal_lptimer_info_t *info)
 Get information about the LPTimer. More...
 

Data Structure Documentation

◆ cyhal_lptimer_info_t

struct cyhal_lptimer_info_t
Data Fields
uint32_t frequency_hz Operating clock frequency the LPTimer is running on.
uint8_t min_set_delay Minimum permitted value for the delay parameter in cyhal_lptimer_set_delay.
uint32_t max_counter_value Maximum value of the counter.

Macro Definition Documentation

◆ cyhal_lptimer_set_time

#define cyhal_lptimer_set_time   cyhal_lptimer_set_match

Deprecated.

Call cyhal_lptimer_set_match instead.

Function Documentation

◆ cyhal_lptimer_init()

cy_rslt_t cyhal_lptimer_init ( cyhal_lptimer_t obj)

Initialize the LPTimer.

Initialize or re-initialize the LPTimer. This resets all the clocking and prescaler registers, along with disabling the compare interrupt. Refer to the BSP for the clock source for the LPTimer.

Parameters
[out]objPointer to an LPTimer object. The caller must allocate the memory for this object but the init function will initialize its contents.
Returns
The status of the init request. On success it returns CY_RSLT_SUCCESS.

◆ cyhal_lptimer_free()

void cyhal_lptimer_free ( cyhal_lptimer_t obj)

Deinitialize the LPTimer.

Powers down the LPTimer. After calling this function no other LPTimer functions should be called except cyhal_lptimer_init(). Calling any function other than init after freeing is undefined.

Parameters
[in,out]objThe LPTimer object

◆ cyhal_lptimer_reload()

cy_rslt_t cyhal_lptimer_reload ( cyhal_lptimer_t obj)

Reload/Reset the Low-Power timer.

Parameters
[in]objThe LPTimer object
Returns
The status of the reload request. On success it returns CY_RSLT_SUCCESS.

◆ cyhal_lptimer_set_match()

cy_rslt_t cyhal_lptimer_set_match ( cyhal_lptimer_t obj,
uint32_t  ticks 
)

Update the match/compare value.

Update the match value of an already configured LPTimer set up to generate an interrupt on match. Note that this function does not reinitialize the counter or the associated peripheral initialization sequence.

Note
This does not reset the counter.
Parameters
[in]objThe LPTimer object
[in]ticksThe tick value to match
Returns
The status of the set_match request. On success it returns CY_RSLT_SUCCESS.

◆ cyhal_lptimer_set_delay()

cy_rslt_t cyhal_lptimer_set_delay ( cyhal_lptimer_t obj,
uint32_t  delay 
)

Update the match/compare value.

Update the match value of an already configured LPTimer set up to generate an interrupt on match delay from the current counter value. Note that this function does not reinitialize the counter or the associated peripheral initialization sequence.

Note
This does not reset the counter.
Parameters
[in]objThe LPTimer object
[in]delayThe ticks to wait. The minimum permitted delay value can be queried using cyhal_lptimer_get_info
Returns
The status of the set_match request. On success it returns CY_RSLT_SUCCESS.

◆ cyhal_lptimer_read()

uint32_t cyhal_lptimer_read ( const cyhal_lptimer_t obj)

Read the current tick.

If no rollover has occurred, the seconds passed since cyhal_lptimer_init() or cyhal_lptimer_set_time() was called can be found by dividing the ticks returned by this function by the frequency of the source clock (Refer to BSP Settings section in the kit's BSP API Reference Manual for details on the clock source for LPTimer).

Parameters
[in]objThe LPTimer object
Returns
The timer's timer value in ticks

◆ cyhal_lptimer_register_callback()

void cyhal_lptimer_register_callback ( cyhal_lptimer_t obj,
cyhal_lptimer_event_callback_t  callback,
void *  callback_arg 
)

Register a LPTimer match event handler.

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

Parameters
[in]objThe LPTimer object
[in]callbackThe callback handler which will be invoked when the interrupt triggers
[in]callback_argGeneric argument that will be provided to the handler when called

◆ cyhal_lptimer_enable_event()

void cyhal_lptimer_enable_event ( cyhal_lptimer_t obj,
cyhal_lptimer_event_t  event,
uint8_t  intr_priority,
bool  enable 
)

Configure and Enable/Disable the LPTimer events.

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

Parameters
[in]objThe LPTimer object
[in]eventThe LPTimer event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on event, False to turn off

◆ cyhal_lptimer_irq_trigger()

void cyhal_lptimer_irq_trigger ( cyhal_lptimer_t obj)

Manually trigger the LPTimer interrupt.

Parameters
[in]objThe LPTimer object

◆ cyhal_lptimer_get_info()

void cyhal_lptimer_get_info ( cyhal_lptimer_t obj,
cyhal_lptimer_info_t info 
)

Get information about the LPTimer.

Provides information such as operating frequency, etc.

Parameters
[in]objThe LPTimer object.
[out]infoInformation about the LPtimer.