Low Power Modes Driver on r_lpmv2

Table of Contents

• LPM V2 HAL Module Introduction
  • LPM V2 HAL Module Features
  • LPMV2 Hardware support details
• LPM V2 HAL Module APIs Overview
• LPM V2 HAL Module Operational Overview
  • LPM V2 HAL Module Important Operational Notes and Limitations
    • LPM V2 HAL Module Operational Notes
    • LPM V2 HAL Module Limitations
• Including the LPM V2 HAL Module in an Application
• Configuring the LPM V2 HAL Module
  • LPM V2 HAL Module Clock Configuration
  • LPM V2 HAL Module Pin Configuration
• Using the LPM V2 HAL Module in an Application

LPM V2 HAL Module Introduction

The Low Power Modes V2 HAL module provides a high-level API for low-power mode applications and uses the low-power mode hardware peripheral on the Synergy MCU.

LPM V2 HAL Module Features

• Supports configuration of MCU operating power-control modes and MCU low-power modes
• Supports the following low power modes:
  • Deep Software Standby mode
  • Software Standby mode
  • Sleep mode
  • Snooze mode
• ​​​​​​​Supports reducing power consumption when in deep stand-by mode through internal power‑supply control and by resetting the states of I/O ports.
• Supports disabling and enabling of the MCU's other hardware peripherals.

Note

  Not all low-power V2 modes are available on all MCU Groups.

LPM V2 HAL Module Block Diagram

LPMV2 Hardware support details

The following hardware features are, or are not, supported by SSP for LPM V2:

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Sleep Low Power Mode	Software Standby Low Power Mode	Deep Standby Low Power Mode	Snooze enabled in Software Standby Low Power Mode	Snooze Linking using ELC	DTC state in Snooze Mode
S124	✓	✓	N/A	✓	⌧	✓
S128	✓	✓	N/A	✓	⌧	✓
S1JA	✓	✓	N/A	✓	⌧	✓
S3A1	✓	✓	N/A	✓	⌧	✓
S3A3	✓	✓	N/A	✓	⌧	✓
S3A6	✓	✓	N/A	✓	⌧	✓
S3A7	✓	✓	N/A	✓	⌧	✓
S5D3	✓	✓	✓	✓	⌧	✓
S5D5	✓	✓	✓	✓	⌧	✓
S5D9	✓	✓	✓	✓	⌧	✓
S7G2	✓	✓	✓	✓	⌧	✓

MCU Group	State of address bus and bus signals in Standby or Deep Standby Mode	Enter Snooze mode via RXD0 (SCI0)	IO Port state control after waking up from Deep Standby Mode	Internal Power Supply control in Deep Standby Mode (power supply to LOCO, Standby SRAM, AGTn, and USBHS/FS)
S124	⌧	✓	N/A	⌧
S128	⌧	✓	N/A	⌧
S1JA	⌧	✓	N/A	⌧
S3A1	✓	✓	N/A	⌧
S3A3	✓	✓	N/A	⌧
S3A6	✓	✓	N/A	⌧
S3A7	✓	✓	N/A	⌧
S5D3	✓	✓	✓	✓
S5D5	✓	✓	✓	✓
S5D9	✓	✓	✓	✓
S7G2	✓	✓	✓	✓

LPM V2 HAL Module APIs Overview

The Low Power Modes V2 HAL module defines APIs for configuring operations and enabling and disabling low-power operations. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Note

The Low Power Modes V2 HAL module will no longer handle operating power-control modes of the MCU; these are now handled by the CGC HAL module.

The following API examples illustrate sleep-mode use; "deep_standby" and "standby" can be substituted for "sleep" in the API examples to create examples for those modes.

LPM V2 HAL Module API Summary

Function Name	Example API Call and Description
init	g_lpmv2_sleep0.p_api->init(g_lpmv2_sleep0.p_cfg); Open the LPM driver module Initialized the LPM block according to the passed in config structure.
lowPowerCfg	g_lpmv2_sleep0.p_api->lowPowerCfg(power_mode, output_port_enable, power_supply, io_port_state); Configure a low power mode.
lowPowerModeEnter	g_lpmv2_sleep0.p_api->lowPowerModeEnter(void); Enter low power mode (sleep/standby/deep standby) using WFI macro. Function will return after waking from low power mode.
versionGet	g_lpmv2_sleep0.p_api->versionGet(&version); Get the driver version and place it at the pointer version.
clearIOKeep	g_lpmv2_sleep0.p_api->clearIOKeep(void); Clear the IOKEEP bit after deep software stand by mode exit

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_INVALID_POINTER	Pointer is NULL.
SSP_ERR_INVALID_MODE	Invalid settings for specified mode.
SSP_ERR_INVALID_HW_CONDITION	OPCMTSF and SOPCMTSF flags are not cleared within internally set timeout.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

LPM V2 HAL Module Operational Overview

LPM V2 Initialization

The LPM V2 API function lpmv2_api_t::init should be called before calling any other LPM V2 function. The init function handles initialization of internal variables and locks.

Sleep Low-Power Mode

By default, at power on, sleep mode is enabled as the low-power mode. Sleep mode is the most convenient low-power mode available, as it does not require any special configuration (other than configuring and enabling a suitable interrupt or event to wake the MCU from sleep) to return to normal program-execution mode. Any interrupt wakes the MCU device from sleep low-power mode. The states of the SRAM, the processor registers, and the hardware peripherals are all maintained in sleep mode, and the time needed to enter and wake from sleep is minimal. Any interrupt causes the MCU device to wake from sleep mode, including the Systick interrupt used by the ThreadX® thread scheduler. The LPM API function lpmv2_api_t::init should be called before any other function. The LPM API function, lpmv2_api_t::lowPowerCfg, can be used to configure the MCU to use sleep as its low‑power mode. The LPM API function lpmv2_api_t::lowPowerModeEnter should be used to directly enter sleep mode.

The following code illustrates configuring sleep as a low-power mode and entering the low-power sleep mode. In this illustration, the LPM V2 sleep module uses the name g_lpmv2_sleep0:

/* HAL-only entry function */
#include "hal_data.h"
void hal_entry(void)
{
   ssp_err_t error = SSP_SUCCESS;
   /* Initialize the LPM V2 Driver */
   error = g_lpmv2_sleep0.p_api->init();
   /* Handle error if any */
   /* Configure LPM peripheral for sleep mode */
   error = g_lpmv2_sleep0.p_api->lowPowerCfg(g_lpmv2_sleep0.p_cfg);
   /* Handle error if any */
   /* Entry sleep mode */
   error = g_lpmv2_sleep0.p_api->lowPowerModeEnter();
   /* Handle error if any */
}

Software Standby Mode for LPM V2

In software-standby mode, the CPU, as well as most of the on-chip peripheral functions and all of the internal oscillators, are stopped. Retained are the contents of the CPU internal registers and SRAM data, the states of on-chip peripheral functions, and I/O Ports. Software-standby mode allows significant reduction in power consumption, because most of the oscillators are stopped in this mode. Like Sleep mode, Standby mode requires an interrupt or event be configured and enabled to wake from Standby mode.

The possible triggers for waking from standby mode are enumerated in the Properties window for convenience; multiple triggers can be enabled.

The following code illustrates configuring standby as the low-power mode and entering the low-power standby mode. In this illustration, the LPM V2 standby module with nameg_lpmv2_standby0 is used. A version of this illustration using the Standby module with snooze enabled would be identical:

/* HAL-only entry function */
#include "hal_data.h"
void hal_entry(void)
{
   ssp_err_t error = SSP_SUCCESS;
   /* Initialize the LPM V2 Driver */
   error = g_lpmv2_standby0.p_api->init();
   /* Handle error if any */
   /* Configure LPM peripheral for standby mode */
   error = g_lpmv2_standby0.p_api->lowPowerCfg(g_lpmv2_standby0.p_cfg);
   /* Handle error if any */
   /* Entry standby mode */
   error = g_lpmv2_standby0.p_api->lowPowerModeEnter();
   /* Handle error if any */
}

Snooze Mode with Software Standby Mode for LPM V2

Snooze mode is available through the standby mode LPM V2 instance. Choose "Standby with Snooze Enabled" for "Choose the low power mode" in the Properties window. Snooze mode can be used with some MCU peripherals to execute basic tasks, while keeping the MCU in a low-power state. The snooze settings are below the standby settings in the Properties window. The ADC, DTC, and other peripherals can be enabled in snooze mode. All the settings for snooze are available through configuration properties for the standby instance Snooze is considered an advanced feature.

There are three ways to exit from Snooze mode:

1.  Select Snooze Exit Sources from the configurator (Transit from Snooze to Software Standby mode).
2. Select Standby/Snooze Exit Sources from the configurator (Transit from Snooze to Normal mode).
3. Select Additional snooze exit sources from the configurator (Transit from Snooze to Normal mode).

The Snooze Mode Settings are only used if the low-power mode choice is Standby with Snooze Enabled,"as shown in the following screen capture:

LPM V2 HAL Module Standby Mode With Snooze Setting Enabled

Snooze is a feature of Standby mode that allows some peripherals to run even though the MCU core is not executing instructions. The low-power mode peripheral options related to Snooze mode are shown in the following image. Only one snooze-entry source can be enabled; multiple snooze-exit sources can be enabled. The DTC peripheral can be enabled in snooze mode as well.

LPM V2 HAL Module Snooze Mode Settings

Deep Software Standby Mode for LPM V2

Deep Software Standby Mode is only available on some MCU devices. The MCU device always wakes from Deep Software Standby Mode by going through reset, either by the negation of the reset pin or by one of a set of wake up events displayed in the configuration Properties window for the LPM deep standby instance.

The possible triggers for waking from deep standby mode are enumerated in the Properties window for convenience. Multiple triggers can be enabled. Some triggers have an associated edge type, falling or rising. These options are enumerated also as shown above and below.

The following illustration is for configuring deep standby as the low power mode and entering low power Deep Standby mode. In this illustration, the LPM V2 Deep Standby module with nameg_lpmv2_deep_standby0 is used:

/* HAL-only entry function */
#include "hal_data.h"
void hal_entry(void)
{
   ssp_err_t error = SSP_SUCCESS;
   /* Initialize the LPM V2 Driver */
   error = g_lpmv2_deep_standby0.p_api->init();
   /* Handle error if any */
   /* Configure LPM peripheral for deep sleep mode */
   error = g_lpmv2_deep_standby0.p_api->lowPowerCfg(g_lpmv2_deep_standby0.p_cfg);
   /* Handle error if any */
   /* Entry deep sleep mode */
   error = g_lpmv2_deep_standby0.p_api->lowPowerModeEnter();
   /* Handle error if any */

LPM V2 HAL Module Important Operational Notes and Limitations

LPM V2 HAL Module Operational Notes

Using this driver to configure the LPM peripheral to wake the MCU from standby mode through interrupts requires the interrupt to be configured and enable by the peripheral driver or framework that uses that interrupt. For example, to wake from standby through AGT1 underflow, that interrupt must be enabled through the configuration of the AGT timer module.

If the main oscillator or PLL with main-oscillator source is used for the system clock, the wake time from standby mode can be affected by the Main Oscillator Wait Time Setting in the MOSCWTCR register. This register setting is available to be changed through the Main Oscillator Wait Time setting in the CGC HAL module properties. See the Wakeup Timing and Duration table in Electrical Characteristics for more information.

When a project uses ThreadX and the low-power mode standby, deep standby, or standby with snooze enabled, the call to the lpmv2_api_t::lowPowerCfg API function should occur immediately before the call to the lpmv2_api_t::lowPowerModeEnter API function. This is necessary since ThreadX also uses low-power modes in its idle loop and tx_thread_sleep function; ThreadX expects the MCU device to be configured for the low-power mode sleep.

When a project uses ThreadX and the low-power mode standby or standby with snooze enabled, the low-power mode should be reverted to sleep after the MCU device wakes from standby after returning from the lpmv2_api_t::lowPowerModeEnter function. This is necessary since ThreadX also uses low-power modes in its idle loop and tx_thread_sleep function; ThreadX expects the MCU device to be configured for the low-power mode sleep. The API function lpmv2_api_t::lowPowerCfg needs to be called again before lpmv2_api_t::lowPowerModeEnter to re-configure the low-power mode to sleep, if tx_thread_sleep() is used in the project, or if there may not always be a thread ready to run.

If the deep software standby mode is used, the configurator provides a property to select whether to reset the IO Ports or maintain the status of IO Ports while coming out of deep software standby. If the property is configured to maintain the status of IO port the status of IO Ports will be maintained, however the application code will have to clear the IOKEEP bit in the DSPBYCR register through an API call to clearIOKeep(), after coming out of the deep software standby mode, to allow the operation on IO Ports thereafter.

Detailed information about the expected power consumption of the MCU device in operating states and in Low Power Modes V2 can be found in the Operating and Standby Current section within the Electrical Characteristics section of the MCU Synergy Hardware User's Manual.

LPM V2 HAL Module Limitations

• Flash stop (code flash disable) is not supported. See the section "Flash Operation Control Register (FLSTOP)" of the S1/S3 Synergy MCU Series Hardware User's Manual.
• Reduced SRAM retention area in software standby mode is not supported. See the section "Power Save Memory Control Register (PSMCR)" of the S3 MCU Series Synergy Hardware User's Manual.
• The MCU may not enter or stay in Software Standby and Deep Software Standby modes with the debugger attached. Instead, the MCU may be woken from Software Standby and Deep Software Standby modes by the debugger. To properly test and verify Software Standby and Deep Software Standby modes, the debugger must not be attached.
• If the main oscillator or PLL with main oscillator source is used for the system clock, the wake time from standby mode can be affected by the Main Oscillator Wait Time Setting in the MOSCWTCR register. This register setting is available to be changed through the Main Oscillator Wait Time setting in the CGC HAL module properties. See the "Wakeup Timing and Duration" table in Electrical Characteristics for more information.
• Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the LPM V2 HAL Module in an Application

This section describes how to include the LPM V2 HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the LPM V2 Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the LPM V2 Driver is g_lpm2_<mode>0. This name can be changed in the associated Properties window.)

LPM V2 HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_lpmv2_deep_standby0 S7G2 Low Power Mode Sleep on r_lpmv2	Threads	New Stack> Driver> Power> Low Power Mode Deep Standby on r_lpmv2
g_lpmv2_sleep0 S7G2 Low Power Mode Sleep on r_lpmv2	Threads	New Stack> Driver> Power> Low Power Mode Sleep on r_lpmv2
g_lpmv2_standby0 S7G2 Low Power Mode Sleep on r_lpmv2	Threads	New Stack> Driver> Power> Low Power Mode Standby on r_lpmv2

When the LPM V2 Driver on r_lpm2 is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

LPM V2 HAL Module Stack

Configuring the LPM V2 HAL Module

The LPM V2 HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the LPM Deep Standby Module on r_lpm2

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables the parameter checking.
Name	g_lpmv2_deep_standby	Module name.
Output port state in standby and deep standby, applies to address output, data output, and other bus control output pins	High impedance state, No change Default: No change	Output port state selection.
Maintain or reset the IO port states on exit from deep standby mode	Maintain the IO port states, Reset the IO port states Default: Maintain the IO port states	Maintain/reset I/O port states selection.
Internal power supply control in deep standby mode	Maintain the internal power supply, Cut the power supply to standby RAM, low-speed on-chip oscillator, AGTn, and USPFS/HS resume detecting unit, Cut the power supply to LVDn, standby RAM, low-speed on-chip oscillator, AGTn, and USBFS/HS resume detecting unit Default: Maintain the internal power supply	Internal power supply control selection.
IRQ0-15	Enabled, Disabled Default: Disabled	IRQ0-15 selection.
IRQ0-15 Edge	Disabled, Rising Edge, Falling Edge Default: Disabled	IRQ0-15 Edge selection.
LVD1	Enabled, Disabled Default: Disabled	LVD1 selection.
LVD1 Edge	Disabled, Rising Edge, Falling Edge Default: Disabled	LVD1 Edge selection.
LVD2	Enabled, Disabled Default: Disabled	LVD2 selection.
LVD2 Edge	Disabled, Rising Edge, Falling Edge Default: Disabled	LVD2 Edge selection.
RTC Interval	Enabled, Disabled Default: Disabled	RTC Interval selection.
RTC Alarm	Enabled, Disabled Default: Disabled	RTC Alarm selection.
NMI	Enabled, Disabled Default: Disabled	NMI selection.
NMI Edge	Disabled, Rising Edge, Falling Edge Default: Disabled	NMI Edge selection.
USBFS	Enabled, Disabled Default: Disabled	USBFS selection.
UBSHS	Enabled, Disabled Default: Disabled	UBSHS selection.
AGT11	Enabled, Disabled Default: Disabled	AGT11 selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the LPM Sleep Module on r_lpm2

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled (Default: BSP)	Enables or disables the parameter checking.
Name	g_lpmv2_sleep0	Module name.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the LPM Standby Module on r_lpm2

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables the parameter checking.
Name	g_lpmv2_standby0	Module name.
Choose the low power mode	Standby, Standby with snooze Enabled Default: Standby	Low power mode selection.
Output port state in standby and deep standby, applies to address output, data output, and other bus control output pins	High impedance state, No change Default: No change	Output port state selection.
Select Standby/Snooze Exit Sources	Select fields below:	Transit from Standby to Normal or Snooze to Normal mode.
IRQ1-15	Enabled, Disabled Default: Disabled	IRQ1-15 selection.
IWDT	Enabled, Disabled Default: Disabled	IWDT selection.
Key Interrupt	Enabled, Disabled Default: Disabled	Key Interrupt selection.
LVD1 Interrupt	Enabled, Disabled Default: Disabled	LVD1 Interrupt selection.
LVD2 Interrupt	Enabled, Disabled Default: Disabled	LVD2 Interrupt selection.
Analog Comparator High-speed 0 Interrupt	Enabled, Disabled Default: Disabled	Analog Comparator High-speed 0 Interrupt selection.
RTC Alarm	Enabled, Disabled Default: Disabled	RTC Alarm selection.
RTC Period	Enabled, Disabled Default: Disabled	RTC Period selection.
USB High-speed	Enabled, Disabled Default: Disabled	USB High-speed selection.
USB Full-speed	Enabled, Disabled Default: Disabled	USB Full-speed selection.
AGT1 underflow	Enabled, Disabled Default: Disabled	AGT1 underflow selection.
AGT1 Compare Match A	Enabled, Disabled Default: Disabled	AGT1 Compare Match A selection.
AGT1 Compare Match B	Enabled, Disabled Default: Disabled	AGT1 Compare Match B selection.
12C 0	Enabled, Disabled Default: Disabled	12C 0 selection.
Snooze Entry Source	RXD0 falling edge, IRQ0-IRQ15, KINT, ACMPHS0, RTC Alarm, RTC Period, AGT1 Underflow, AGT1 Compare Match A, AGT1 Compare Match B Default: RXD0 falling edge	Snooze Entry Source selection.
AGT1 Underflow	Enabled, Disabled Default: Disabled	AGT1 Underflow selection.
DTC Transfer Completion	Enabled, Disabled Default: Disabled	DTC Transfer Completion selection.
DTC Transfer Completion Negated Signal	Enabled, Disabled Default: Disabled	DTC Transfer Completion Negated Signal selection.
ADC0 Compare Match	Enabled, Disabled Default: Disabled	ADC0 Compare Match selection.
ADC0 Compare Mismatch	Enabled, Disabled Default: Disabled	ADC0 Compare Mismatch selection.
ADC1 Compare Match	Enabled, Disabled Default: Disabled	ADC1 Compare Match selection.
ADC1 Compare Mismatch	Enabled, Disabled Default: Disabled	ADC1 Compare Mismatch selection.
SCI0 Address Match	Enabled, Disabled Default: Disabled	SCI0 Address Match selection.
DTC state in Snooze Mode	Enabled, Disabled Default: Disabled	DTC state in Snooze Mode selection.
Additional snooze exit sources	SCI0_RXI_OR_ERI Default: SCI0_RXI_OR_ERI	Transit from Snooze to Normal mode.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

In some cases, settings other than the defaults can be desirable. For example, it might be useful to select different states for entering or exiting low-power states.

LPM V2 HAL Module Clock Configuration

The LPM V2 peripheral module does not have any selectable clock sources.

LPM V2 HAL Module Pin Configuration

The LPM V2 peripheral module does not need pin assignments. Pin function selections are done in the properties configuration window.

Using the LPM V2 HAL Module in an Application

The typical steps in using the LPM V2 HAL module in an application are:

1. Initialize the Low Power Modes V2 HAL module using the lpmv2_api_t::init API.
2. Configure a low-power mode with the lpmv2_api_t::lowPowerCfg API.
3. Enter a low-power mode with the lpmv2_api_t::lowPowerModeEnter API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical LPM V2 HAL Module Application