PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Typedefs | Enumerations | Functions
LPTimer (Low-Power Timer)
HAL API Reference » HAL Drivers

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

- Wake the device up from deepsleep
- Configurable to create a free-running timer or generate periodic interrupts.
- Configurable to update the match value of an already configured LPTimer set up to generate an interrupt on match.
- Used for measuring time between events in free-running mode.

# Quick Start

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;
uint32_t lptimer_value;
// Initialize the LPTIMER with configurator-generated structures
rslt = mtb_hal_lptimer_setup(&lptimer_obj, &lptimer_hal_config);
if (CY_RSLT_SUCCESS == rslt)
{
// Init and enable functions calls are for illustration purpose only
// and the user needs to set up the hardware according to the low power
// timer hadware block that is actually used.
// Initialize hardware via PDL call
rslt = (cy_rslt_t)_LPTimer_Init_IP_Specific(lptimer_obj.base, &lptimer_config);
// Enable hardware via PDL call
_LPTimer_Enable_IP_Specific(lptimer_obj.base);
}
// Read the LPTIMER count value
lptimer_value = mtb_hal_lptimer_read(&lptimer_obj);
mtb_hal_lptimer_read
uint32_t mtb_hal_lptimer_read(const mtb_hal_lptimer_t *obj)
Read the current tick.
Definition: mtb_hal_lptimer.c:119
mtb_hal_lptimer_setup
cy_rslt_t mtb_hal_lptimer_setup(mtb_hal_lptimer_t *obj, const mtb_hal_lptimer_configurator_t *config)
Sets up a HAL instance to use the specified hardware resource.
Definition: mtb_hal_lptimer.c:45
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486

## Snippet 2: LPTimer interrupts

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

#define LPTIMER_MATCH_VALUE (8192u)
//Only MCWDT_B still defines this value so in case we don't have it defined we use the old presets
#if !defined _MTB_HAL_LPTIMER_RESET_TIME_US
#if defined (CY_IP_M0S8WCO)
#define _MTB_HAL_LPTIMER_RESET_TIME_US (180)
#else
#define _MTB_HAL_LPTIMER_RESET_TIME_US (62)
#endif
mtb_hal_lptimer_t lptimer_obj;
// Structures generated by configurator:
const mtb_hal_lptimer_configurator_t lptimer_hal_config;
#if defined(CY_IP_MXS22SRSS) && (CY_IP_MXS22SRSS_VERSION >= 2) && defined(SRSS_NUM_WDT_A) && (SRSS_NUM_WDT_A > 1)
const cy_stc_wdt_config_t lptimer_config;
#else
const cy_stc_mcwdt_config_t lptimer_config;
#endif
cy_rslt_t snippet_lptimer_init(void)
{
cy_rslt_t rslt;
// Initialize the LPTIMER
rslt = mtb_hal_lptimer_setup(&lptimer_obj, &lptimer_hal_config);
if (CY_RSLT_SUCCESS == rslt)
{
// Init and enable functions calls are for illustration purpose only
// and the user needs to set up the hardware according to the low power
// timer hadware block that is actually used.
// Initialize hardware via PDL call
rslt = (cy_rslt_t)_LPTimer_Init_IP_Specific(lptimer_obj.base, &lptimer_config);
// Enable hardware via PDL call
_LPTimer_Enable_IP_Specific(lptimer_obj.base);
}
if (CY_RSLT_SUCCESS == rslt)
{
// Register the callback handler which will be invoked when the interrupt triggers
mtb_hal_lptimer_register_callback(&lptimer_obj, lptimer_interrupt_handler, NULL);
// Configure and Enable the LPTIMER events
mtb_hal_lptimer_enable_event(&lptimer_obj, MTB_HAL_LPTIMER_COMPARE_MATCH, true);
}
return rslt;
}
void lptimer_interrupt_handler(void* handler_arg, mtb_hal_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
mtb_hal_lptimer_set_delay(&lptimer_obj, LPTIMER_MATCH_VALUE);
mtb_hal_lptimer_process_interrupt(&lptimer_obj);
}
mtb_hal_lptimer_event_t
mtb_hal_lptimer_event_t
LPTimer interrupt triggers.
Definition: mtb_hal_lptimer.h:105
mtb_hal_lptimer_enable_event
void mtb_hal_lptimer_enable_event(mtb_hal_lptimer_t *obj, mtb_hal_lptimer_event_t event, bool enable)
Configure and Enable/Disable the LPTimer events.
Definition: mtb_hal_lptimer.c:84
mtb_hal_lptimer_process_interrupt
cy_rslt_t mtb_hal_lptimer_process_interrupt(mtb_hal_lptimer_t *obj)
Process interrupts related related to an LPTimer instance.
Definition: mtb_hal_lptimer_mcwdt.c:63
mtb_hal_lptimer_register_callback
void mtb_hal_lptimer_register_callback(mtb_hal_lptimer_t *obj, mtb_hal_lptimer_event_callback_t callback, void *callback_arg)
Register a LPTimer match event handler.
Definition: mtb_hal_lptimer.c:68
mtb_hal_lptimer_set_delay
cy_rslt_t mtb_hal_lptimer_set_delay(mtb_hal_lptimer_t *obj, uint32_t delay)
Update the match/compare value.
Definition: mtb_hal_lptimer_common.c:50
cy_stc_mcwdt_config_t
The MCWDT component configuration structure.
Definition: cy_mcwdt.h:260

## API Reference
| LPTimer HAL Results
| LPTimer specific return codes.

## Typedefs
typedef void(* | mtb_hal_lptimer_event_callback_t) (void *callback_arg, mtb_hal_lptimer_event_t event)
| Handler for LPTimer interrupts.

## Enumerations
enum | mtb_hal_lptimer_event_t { MTB_HAL_LPTIMER_COMPARE_MATCH }
| LPTimer interrupt triggers.

## Functions
cy_rslt_t | mtb_hal_lptimer_setup (mtb_hal_lptimer_t *obj, const mtb_hal_lptimer_configurator_t *config)
| Sets up a HAL instance to use the specified hardware resource. More...
cy_rslt_t | mtb_hal_lptimer_set_delay (mtb_hal_lptimer_t *obj, uint32_t delay)
| Update the match/compare value. More...
uint32_t | mtb_hal_lptimer_read (const mtb_hal_lptimer_t *obj)
| Read the current tick. More...
void | mtb_hal_lptimer_register_callback (mtb_hal_lptimer_t *obj, mtb_hal_lptimer_event_callback_t callback, void *callback_arg)
| Register a LPTimer match event handler. More...
void | mtb_hal_lptimer_enable_event (mtb_hal_lptimer_t *obj, mtb_hal_lptimer_event_t event, bool enable)
| Configure and Enable/Disable the LPTimer events. More...
cy_rslt_t | mtb_hal_lptimer_process_interrupt (mtb_hal_lptimer_t *obj)
| Process interrupts related related to an LPTimer instance. More...

## Function Documentation

## ◆ mtb_hal_lptimer_setup()

cy_rslt_t mtb_hal_lptimer_setup | ( | mtb_hal_lptimer_t * | obj,
|  | const mtb_hal_lptimer_configurator_t * | config
| ) |  |

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

  [out] | obj | The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
  [in] | config | The configurator-generated HAL config structure for this peripheral instance

Returns
  the status of the HAL setup

## ◆ mtb_hal_lptimer_set_delay()

cy_rslt_t mtb_hal_lptimer_set_delay | ( | mtb_hal_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.

Parameters

  [in] | obj | The LPTimer object
  [in] | delay | The ticks to wait. The minimum permitted delay value can be found in the implementation specific documentation.

Returns
  The status of the set_delay request. On success it returns CY_RSLT_SUCCESS.

- 16 bit Counter0 (C0) & Counter1 (C1) are cascaded to generated a 32 bit counter.
- Counter2 (C2) is a free running counter.
- C0 continues counting after reaching its match value.
- An interrupt is generated when C1 increments past the match value.

EXAMPLE: Supposed T=C0=C1=0, and we need to trigger an interrupt at T=0x18000. We set C0_match to 0x8000 and C1 match to 1. At T = 0x8000, C0_value matches C0_match so C1 get incremented. C1/C0=0x18000. At T = 0x18000, C0_value matches C0_match again so C1 get incremented from 1 to 2. When C1 get incremented from 1 to 2 the interrupt is generated. At T = 0x18000, C1/C0 = 0x28000.

## ◆ mtb_hal_lptimer_read()

uint32_t mtb_hal_lptimer_read | ( | const mtb_hal_lptimer_t * | obj | ) |

Read the current tick.

If no rollover has occurred, the seconds passed since mtb_hal_lptimer_init() or mtb_hal_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] | obj | The LPTimer object

Returns
  The timer's timer value in ticks

## ◆ mtb_hal_lptimer_register_callback()

void mtb_hal_lptimer_register_callback | ( | mtb_hal_lptimer_t * | obj,
|  | mtb_hal_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 mtb_hal_lptimer_enable_event occurs.

Parameters

  [in] | obj | The LPTimer object
  [in] | callback | The callback handler which will be invoked when the interrupt triggers
  [in] | callback_arg | Generic argument that will be provided to the handler when called

## ◆ mtb_hal_lptimer_enable_event()

void mtb_hal_lptimer_enable_event | ( | mtb_hal_lptimer_t * | obj,
|  | mtb_hal_lptimer_event_t | event,
|  | bool | enable
| ) |  |

Configure and Enable/Disable the LPTimer events.

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

Parameters

  [in] | obj | The LPTimer object
  [in] | event | The LPTimer event type
  [in] | enable | True to turn on event, False to turn off

## ◆ mtb_hal_lptimer_process_interrupt()

cy_rslt_t mtb_hal_lptimer_process_interrupt | ( | mtb_hal_lptimer_t * | obj | ) |

Process interrupts related related to an LPTimer instance.

Parameters

  [in] | obj | HAL object for which the interrupt should be processed

Returns
  CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error