System Power Management

General Description

Interface for changing power states and restricting when they are allowed.

There are three supported MCU Power States:

• Active - This is the normal operating state of the MCU
• Sleep - In this state the MCU is no longer running. It can be woken up again from an interrupt. This state is reached by calling mtb_hal_syspm_sleep.
• Deep Sleep - In this state the MCU is no longer running. It can only be woken up by select interrupts. This state is reached by calling mtb_hal_syspm_deepsleep.

Some devices support multiple modes for the DeepSleep power state. The currently selected DeepSleep mode, which will be entered by mtb_hal_syspm_deepsleep, can be determined via the mtb_hal_syspm_get_deepsleep_mode function. Configuration of the DeepSleep mode can be performed via platform specific APIs (e.g. PDL).

Note

The power management functionality available depends on the availability of the features in the hardware. For detailed information about exactly what is supported on each device, refer to the Device Datasheet or Technical Reference Manual (TRM).

Any time a power state transition is requested a series of callbacks are invoked. This allows peripherals, or other parts of the application, to confirm they are not currently doing something that would not work in the requested power state. Middleware has the option to register a callback function(s) to be called on requested state transitions by callling mtb_hal_syspm_register_callback. Each callback registered can specify the exact set of states ( mtb_hal_syspm_callback_state_t ) that it should be called for. Each callback is invoked multiple times as part of the transition process as defined by mtb_hal_syspm_callback_mode_t.

At any point the code can lock the ability to enter deep sleep by calling mtb_hal_syspm_lock_deepsleep. This should be done in critical blocks that need to continue remain active. When the critical work is complete, and the lock is no longer needed, it can be released by calling mtb_hal_syspm_unlock_deepsleep. The lock is a counter with a max count of USHRT_MAX. It must be locked/unlocked an equal number of times before the device is actually able to enter deep sleep.

Features

This driver provides control over multiple different types of power management and when those transitions are allowed:

• Change CPU Power State: APIs to allow changing the current CPU state into one of the lower power CPU states (SLEEP, DEEPSLEEP)
• General Purpose Power State Transition Callback: APIs allow for registering/unregistering a callback function to be notified when various power state transitions happen. If registered, the application can do anything necessary at power transitions. It can even prevent the transition if need-be.
• Lock DeepSleep: APIs to prevent/allow the CPU from going to deep sleep. This is a convenience API rather than needing to implement a full Transition Callback handler.

Quick Start

Unlike most HAL drivers this does not require initializing an instance object. The APIs provided here can be called at anytime. See the snippets below for examples of how to use this driver.

Code Snippets

Snippet 1: Simple deep sleep locking

The following snippet shows how to use the deep sleep locking APIs to restrict when the device can enter deep sleep. In between the lock/unlock calls any attempt to change power modes will automatically be canceled.

    mtb_hal_syspm_lock_deepsleep();
 
    // Perform work that should not be interrupted by deepsleep
 
    mtb_hal_syspm_unlock_deepsleep();

Snippet 2: Calling different power state functions

The following snippet shows the different functions that exist to change power states on the device and how they can each be called.

    cy_rslt_t rslt;
 
    // Put the MCU to sleep. Peripherals will continue to operate.
    rslt = mtb_hal_syspm_sleep();
 
    // Put the MCU to deep-sleep. Many peripherals will also stop.
    rslt = mtb_hal_syspm_deepsleep();
 

Snippet 3: Using callbacks for application power management

The following snippet shows how to use the callback mechanisms to manage whether it is safe to enter low power modes.

bool syspm_app_callback(mtb_hal_syspm_callback_state_t state, mtb_hal_syspm_callback_mode_t mode,
                        void* callback_arg)
{
    (void)callback_arg;
    bool allow_transition = true;
 
    switch (mode)
    {
        case MTB_HAL_SYSPM_CHECK_READY:
            // Check to see if it is OK to change power modes.
            // If it is OK the change, make sure nothing will invalidate this and return true.
            // If it is not OK the change, return false.
 
            // Example: prevent transition if requested mode is DEEPSLEEP.
            allow_transition = (state != MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP);
            break;
 
        case MTB_HAL_SYSPM_CHECK_FAIL:
            // Undo anything done as part of CHECK_READY since it is not actually chaning.
            break;
 
        case MTB_HAL_SYSPM_BEFORE_TRANSITION:
            // Do anything necessary to shut things down.
            break;
 
        case MTB_HAL_SYSPM_AFTER_TRANSITION:
            // Undo anything done as part of CHECK_READY or BEFORE_TRANSITION since it is coming
            // back up.
            break;
 
        case MTB_HAL_SYSPM_AFTER_DS_WFI_TRANSITION:
            // Do anything necessary after deepsleep wakeup and before interrupts getting enabled.
            break;
    }
 
    return allow_transition;
}
 
 
void snippet_mtb_hal_syspm_app_callback(void)
{
    cy_rslt_t                   rslt;
    // Register the same callback to be invoked for both Sleep and DeepSleep transitions
    // The `state` argument can be used to differentiate the applicable state when
    // the callback is invoked during a transition
    mtb_hal_syspm_callback_params_t params_sleep =
    {
        .callback = syspm_app_callback,
        .state    = MTB_HAL_SYSPM_CB_CPU_SLEEP,
        .arg      = NULL,
    };
 
    mtb_hal_syspm_callback_params_t params_deepsleep =
    {
        .callback = syspm_app_callback,
        .state    = MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP,
        .arg      = NULL,
    };
 
 
    mtb_hal_syspm_callback_data_t cb_sleep;
    mtb_hal_syspm_callback_data_t cb_deepsleep;
 
    mtb_hal_syspm_register_callback(&cb_sleep, &params_sleep);
    mtb_hal_syspm_register_callback(&cb_deepsleep, &params_deepsleep);
 
    // Attempt to DeepSleep. This will be rejected by the callback.
    rslt = mtb_hal_syspm_deepsleep();
    if (CY_RSLT_SUCCESS != rslt)
    {
        // If the device couldn't go to DeepSleep, try sleep
        rslt = mtb_hal_syspm_sleep();
    }
 
    mtb_hal_syspm_unregister_callback(&cb_sleep);
    mtb_hal_syspm_unregister_callback(&cb_deepsleep);
}
 
 

API Reference
	SYSPM HAL Results
	SYSPM specific return codes.

Data Structures
struct	mtb_hal_syspm_callback_params_t
	Power management callback data object. More...

Typedefs
typedef bool(*	mtb_hal_syspm_callback_t) (mtb_hal_syspm_callback_state_t state, mtb_hal_syspm_callback_mode_t mode, void *callback_arg)
	The system wide custom action power callback type. More...

Enumerations
enum	mtb_hal_syspm_system_deep_sleep_mode_t {   MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_NONE ,   MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP ,   MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_RAM ,   MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_OFF }
	Enumeration of the system Deep Sleep modes. More...
enum	mtb_hal_syspm_callback_state_t {   MTB_HAL_SYSPM_CB_CPU_SLEEP = MTB_HAL_MAP_SYSPM_CB_SLEEP ,   MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP = MTB_HAL_MAP_SYSPM_CB_DEEPSLEEP ,   MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP_RAM = MTB_HAL_MAP_SYSPM_CB_DEEPSLEEP_RAM ,   MTB_HAL_SYSPM_CB_SYSTEM_HIBERNATE = MTB_HAL_MAP_SYSPM_CB_HIBERNATE ,   MTB_HAL_SYSPM_CB_SYSTEM_NORMAL = MTB_HAL_MAP_SYSPM_CB_NORMAL ,   MTB_HAL_SYSPM_CB_SYSTEM_LOW = MTB_HAL_MAP_SYSPM_CB_LOW ,   MTB_HAL_SYSPM_CB_SYSTEM_HIGH = MTB_HAL_MAP_SYSPM_CB_HIGH }
	Flags enum for the cpu state in a custom callback. More...
enum	mtb_hal_syspm_callback_mode_t {   MTB_HAL_SYSPM_CHECK_READY = MTB_HAL_MAP_SYSPM_CHECK_READY ,   MTB_HAL_SYSPM_CHECK_FAIL = MTB_HAL_MAP_SYSPM_CHECK_FAIL ,   MTB_HAL_SYSPM_BEFORE_TRANSITION = MTB_HAL_MAP_SYSPM_BEFORE_TRANSITION ,   MTB_HAL_SYSPM_AFTER_TRANSITION = MTB_HAL_MAP_SYSPM_AFTER_TRANSITION ,   MTB_HAL_SYSPM_AFTER_DS_WFI_TRANSITION = MTB_HAL_MAP_SYSPM_AFTER_DS_WFI_TRANSITION }
	Enumeration of the transition modes in custom callback. More...

Functions
cy_rslt_t	mtb_hal_syspm_register_callback (mtb_hal_syspm_callback_data_t *obj, mtb_hal_syspm_callback_params_t *params)
	Register the specified handler with the power manager to be notified of power state changes. More...
cy_rslt_t	mtb_hal_syspm_unregister_callback (mtb_hal_syspm_callback_data_t *obj)
	Removes the registered handler from the power manager so no future notifications are made. More...
cy_rslt_t	mtb_hal_syspm_sleep (void)
	Set CPU to sleep mode. More...
cy_rslt_t	mtb_hal_syspm_deepsleep (void)
	Set CPU to deep sleep mode. More...
void	mtb_hal_syspm_lock_deepsleep (void)
	Lock deep sleep. More...
void	mtb_hal_syspm_unlock_deepsleep (void)
	Unlock deep sleep. More...
cy_rslt_t	mtb_hal_syspm_tickless_deepsleep (mtb_hal_lptimer_t *lptimer_obj, uint32_t desired_ms, uint32_t *actual_ms)
	Timed deep-sleep without system timer. More...
cy_rslt_t	mtb_hal_syspm_tickless_sleep (mtb_hal_lptimer_t *lptimer_obj, uint32_t desired_ms, uint32_t *actual_ms)
	Timed sleep without system timer. More...
mtb_hal_syspm_system_deep_sleep_mode_t	mtb_hal_syspm_get_deepsleep_mode (void)
	Get current deep sleep mode. More...

---

Data Structure Documentation

mtb_hal_syspm_callback_params_t

struct mtb_hal_syspm_callback_params_t

Data Fields
mtb_hal_syspm_callback_t	callback	Callback to run on power state change.
mtb_hal_syspm_callback_state_t	state	Power states that should trigger calling the callback.
mtb_hal_syspm_callback_mode_t	ignore_modes	Modes to ignore invoking the callback for. Multiple mtb_hal_syspm_callback_mode_t values can be ored together.
void *	arg	Argument value to provide to the callback.

Typedef Documentation

mtb_hal_syspm_callback_t

typedef bool(* mtb_hal_syspm_callback_t) (mtb_hal_syspm_callback_state_t state, mtb_hal_syspm_callback_mode_t mode, void *callback_arg)

The system wide custom action power callback type.

Parameters

[in]	state	State the system or CPU is being transitioned into.
[in]	mode	Callback mode.
[in]	callback_arg	User argument passed as part of registering callback.

Returns

If mode is MTB_HAL_SYSPM_CHECK_READY, then this indicates whether the low power mode should be allowed (true) or not (false). Otherwise the return value is ignored.

Enumeration Type Documentation

mtb_hal_syspm_system_deep_sleep_mode_t

enum mtb_hal_syspm_system_deep_sleep_mode_t

Enumeration of the system Deep Sleep modes.

These modes are device specifc and may not be supported on all devices. Refer to the device specific documentation or the Data Sheet to determine what is allowed.

Enumerator
MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_NONE	Not Deep Sleep Mode.
MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP	Deep Sleep Mode.
MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_RAM	Deep Sleep RAM Mode.
MTB_HAL_SYSPM_SYSTEM_DEEPSLEEP_OFF	Deep Sleep OFF Mode.

mtb_hal_syspm_callback_state_t

enum mtb_hal_syspm_callback_state_t

Flags enum for the cpu state in a custom callback.

This is used to indicate what states a callback should be called in. When a callback is called, only one of these will be set at a time.

Enumerator
MTB_HAL_SYSPM_CB_CPU_SLEEP	Flag for MCU sleep callback.
MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP	Flag for MCU deep sleep callback.
MTB_HAL_SYSPM_CB_CPU_DEEPSLEEP_RAM	Flag for MCU deep sleep ram callback.
MTB_HAL_SYSPM_CB_SYSTEM_HIBERNATE	Flag for Hibernate callback.
MTB_HAL_SYSPM_CB_SYSTEM_NORMAL	Flag for Normal mode callback.
MTB_HAL_SYSPM_CB_SYSTEM_LOW	Flag for Low power mode callback.
MTB_HAL_SYSPM_CB_SYSTEM_HIGH	Flag for High Performance mode callback.

mtb_hal_syspm_callback_mode_t

enum mtb_hal_syspm_callback_mode_t

Enumeration of the transition modes in custom callback.

The general sequence is: CHECK_READY, BEFORE_TRANSITION, AFTER_TRANSITION. If any callback indicates that it is not able to change state as part of CHECK_READY, CHECK_FAIL will be run instead of the BEFORE/AFTER_TRANSITION.

Enumerator
MTB_HAL_SYSPM_CHECK_READY	Callbacks with this mode are executed before entering into the low power mode. The purpose of this transition state is to check if the device is ready to enter the low power mode. The application must not perform any actions that would prevent transition after returning true for this mode.
MTB_HAL_SYSPM_CHECK_FAIL	Callbacks with this mode are only executed if the callback returned true for MTB_HAL_SYSPM_CHECK_READY and a later callback returns false for MTB_HAL_SYSPM_CHECK_READY. This mode should roll back any changes made to avoid blocking transition made in MTB_HAL_SYSPM_CHECK_READY mode
MTB_HAL_SYSPM_BEFORE_TRANSITION	Callbacks with this mode are executed after the MTB_HAL_SYSPM_CHECK_READY callbacks' execution returns true. In this mode, the callback must perform the actions to be done before entering into the low power mode.
MTB_HAL_SYSPM_AFTER_TRANSITION	In this mode, the application must perform the actions to be done after exiting the low power mode.
MTB_HAL_SYSPM_AFTER_DS_WFI_TRANSITION	Performs the actions to be done after exiting the Deepsleep low power mode if entered and before the interrupts are enabled. This mode is not invoked on all devices, see the implementation specific documentation for details.

Function Documentation

mtb_hal_syspm_register_callback()

cy_rslt_t mtb_hal_syspm_register_callback	(	mtb_hal_syspm_callback_data_t *	obj,
		mtb_hal_syspm_callback_params_t *	params
	)

Register the specified handler with the power manager to be notified of power state changes.

This callback will be called before any of the peripheral callbacks for MTB_HAL_SYSPM_CHECK_READY and MTB_HAL_SYSPM_BEFORE_TRANSITION.

Note

The callback will be executed from a critical section

Parameters

[out]	obj	The callback object. The caller must allocate the memory for this object, but the HAL will populate its
[in]	params	The paramers for the callback to register

Returns

CY_RSLT_SUCCESS if the callback was successfully registered, otherwise an error

mtb_hal_syspm_unregister_callback()

cy_rslt_t mtb_hal_syspm_unregister_callback

(

mtb_hal_syspm_callback_data_t *

obj

)

Removes the registered handler from the power manager so no future notifications are made.

Parameters

[in]

obj

The callback object to unregister.

Returns

CY_RSLT_SUCCESS if the callback was successfully unregistered, otherwise an error

mtb_hal_syspm_sleep()

cy_rslt_t mtb_hal_syspm_sleep

(

void

)

Set CPU to sleep mode.

Returns

Returns CY_RSLT_SUCCESS if the processor successfully entered the sleep mode , otherwise error.

mtb_hal_syspm_deepsleep()

cy_rslt_t mtb_hal_syspm_deepsleep

(

void

)

Set CPU to deep sleep mode.

Returns

Returns CY_RSLT_SUCCESS if the processor successfully entered the deep sleep mode, otherwise error.

mtb_hal_syspm_lock_deepsleep()

void mtb_hal_syspm_lock_deepsleep

(

void

)

Lock deep sleep.

This function prevents the CPU from going to deep sleep. The lock is implemented as a counter from 0 to USHRT_MAX. Each call to this function increments the counter by 1. mtb_hal_syspm_unlock_deepsleep must be called an equal number of times to fully unlock. Deepsleep will only be allowed when the counter is equal to 0.

mtb_hal_syspm_unlock_deepsleep()

void mtb_hal_syspm_unlock_deepsleep

(

void

)

Unlock deep sleep.

This function decrements the lock counter by 1 and must be called an equal number of times as mtb_hal_syspm_lock_deepsleep is called to fully unlock. Deepsleep will only be allowed when the counter is equal to 0.

mtb_hal_syspm_tickless_deepsleep()

cy_rslt_t mtb_hal_syspm_tickless_deepsleep	(	mtb_hal_lptimer_t *	lptimer_obj,
		uint32_t	desired_ms,
		uint32_t *	actual_ms
	)

Timed deep-sleep without system timer.

Provides a way to deep-sleep for a desired number of milliseconds(ms) with the system timer disabled. The system timer is disabled before sleeping and a low power timer is setup to wake the device from deep-sleep after the desired number of ms have elapsed.

Note

The actual ms in the best case will be 1 ms less than the desired time to prevent the device from over-sleeping due to low clock accuracy.

Parameters

[in]	lptimer_obj	Pre-Initialized LPTimer object.
[in]	desired_ms	Desired number of ms to deep-sleep.
[out]	actual_ms	Actual number of ms in which systick timer was disabled. This value can range from 0 to desired_ms - 1 depending on how long the device was able to deep-sleep.

Returns

The status of the deep-sleep request.

mtb_hal_syspm_tickless_sleep()

cy_rslt_t mtb_hal_syspm_tickless_sleep	(	mtb_hal_lptimer_t *	lptimer_obj,
		uint32_t	desired_ms,
		uint32_t *	actual_ms
	)

Timed sleep without system timer.

Provides a way to sleep for a desired number of milliseconds(ms) with the system timer disabled. The system timer is disabled before sleeping and a low power timer is setup to wake the device from sleep after the desired number of ms have elapsed.

Note

The actual ms in the best case will be 1 ms less than the desired time to prevent the device from over-sleeping due to low clock accuracy.

Parameters

[in]	lptimer_obj	Pre-Initialized LPTimer object.
[in]	desired_ms	Desired number of ms to sleep.
[out]	actual_ms	Actual number of ms that was spent in sleep. This value can range from 0 to desired_ms - 1 depending on how long the device was able to sleep.

Returns

The status of the sleep request.

mtb_hal_syspm_get_deepsleep_mode()

mtb_hal_syspm_system_deep_sleep_mode_t mtb_hal_syspm_get_deepsleep_mode

(

void

)

Get current deep sleep mode.

Provides a way to get the current deep sleep mode.

Returns

The current deep sleep mode.