Low Power Callbacks

General Description

Functions
bool	Cy_SysPm_RegisterCallback (cy_stc_syspm_callback_t *handler)
	Registers a new syspm callback. More...
bool	Cy_SysPm_UnregisterCallback (cy_stc_syspm_callback_t const *handler)
	This function unregisters a callback. More...
cy_en_syspm_status_t	Cy_SysPm_ExecuteCallback (cy_en_syspm_callback_type_t type, cy_en_syspm_callback_mode_t mode)
	The function executes all registered callbacks with provided type and mode. More...
cy_stc_syspm_callback_t *	Cy_SysPm_GetFailedCallback (cy_en_syspm_callback_type_t type)
	Reads the result of the callback execution after the power mode functions execution. More...

Function Documentation

Cy_SysPm_RegisterCallback()

bool Cy_SysPm_RegisterCallback

(

cy_stc_syspm_callback_t *

handler

)

Registers a new syspm callback.

A callback is a function called after an event in the driver or middleware module has occurred. The handler callback API will be executed if the specific event occurs. SysPm callbacks are called when changing power modes. See cy_stc_syspm_callback_t.

Note

The registered callbacks are executed in two orders, based on callback mode cy_en_syspm_callback_mode_t. For modes CY_SYSPM_CHECK_READY and CY_SYSPM_BEFORE_TRANSITION, the order is same order as callbacks were registered. For modes CY_SYSPM_AFTER_TRANSITION and CY_SYSPM_CHECK_FAIL, the order is reverse as the order callbacks were registered.

Parameters

handler

The address of the syspm callback structure. See cy_stc_syspm_callback_t.

Returns

• True if a callback was registered.
• False if a callback was not registered.

Note

Do not modify the registered structure in run-time.

Warning

After being registered, the SysPm callback structures must be allocated during power mode transition.

Function Usage

/* Scenario: There is a need to have three callbacks for the CPU Deep Sleep 
*  mode. DeepSleepFunc1 and DeepSleepFunc2 callback function skip 
*  CY_SYSPM_BEFORE_TRANSITION mode.
*  DeepSleepFunc3 executes all four modes. 
*  Note that for the multi-CPU devices the another CPU must be in CPU 
*  Deep Sleep power mode. 
*/

/******************************************************************************
*  Callback prototypes
******************************************************************************/
cy_en_syspm_status_t DeepSleepFunc1(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
cy_en_syspm_status_t DeepSleepFunc2(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
cy_en_syspm_status_t DeepSleepFunc3(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);

/******************************************************************************
*  Parameter structures for callback functions
******************************************************************************/
cy_stc_syspm_callback_params_t deepSleepParam1 = 
{
    NULL,
    NULL
};

cy_stc_syspm_callback_params_t deepSleepParam2 = 
{
    &HW1_address,
    &context
};

cy_stc_syspm_callback_params_t deepSleepParam3 = 
{
    &HW2_address,
    NULL
};

/******************************************************************************
*  Callbacks structures
******************************************************************************/
cy_stc_syspm_callback_t myDeepSleep1 = 
{
    &DeepSleepFunc1, 
    CY_SYSPM_DEEPSLEEP,
    CY_SYSPM_SKIP_BEFORE_TRANSITION,
    &deepSleepParam1,
    NULL,
    NULL,
    0
};

cy_stc_syspm_callback_t myDeepSleep2 = 
{
    &DeepSleepFunc2, 
    CY_SYSPM_DEEPSLEEP,
    CY_SYSPM_SKIP_BEFORE_TRANSITION,
    &deepSleepParam2,
    NULL,
    NULL,
    0
};

cy_stc_syspm_callback_t myDeepSleep3 = 
{
    &DeepSleepFunc3, 
    CY_SYSPM_DEEPSLEEP,
    0U,
    &deepSleepParam3,
    NULL,
    NULL,
    0
};
    

/******************************************************************************
*  DeepSleepFunc1 implementation
******************************************************************************/
cy_en_syspm_status_t DeepSleepFunc1(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
{
    cy_en_syspm_status_t retVal = CY_SYSPM_FAIL;
    
    
    if (callbackParams != NULL)
    {
        /* In this use case we do not need to use HW address or context
        * So, need to add code to some switch case with callbackParams to avoid 
        * compiler warnings
        */
    }
    
    switch(mode)
    {
        /* In this case ensure that firmware/hardware is ready for CPU
        *  Deep Sleep mode */
        case CY_SYSPM_CHECK_READY:
            if(true/* system is ready */)
            {
                /* Process the "check ready" condition */
                retVal = CY_SYSPM_SUCCESS;
            }
            break;
        
        /* One of the registered callback that was executed after this callback 
        *  returned CY_SYSPM_FAIL, need to revert changes (if any) performed in 
        *  the CY_SYSPM_CHECK_READY case.
        */
        case CY_SYSPM_CHECK_FAIL:
            {
                /* Revert changes done in the CY_SYSPM_CHECK_READY case */
                retVal = CY_SYSPM_SUCCESS;
            }
            break;
            
        /* This case will be skipped during callbacks execution */
        case CY_SYSPM_BEFORE_TRANSITION:
            break;
            
        /* This case is executed after wakeup from system Deep Sleep */
        case CY_SYSPM_AFTER_TRANSITION:
            {
                /* Perform actions, if required, after wakeup from the  
                *  system Deep Sleep mode */
                retVal = CY_SYSPM_SUCCESS;
            }
            break;
        
        default:
            break;
    }
    
    return (retVal);
}


/******************************************************************************
*  DeepSleepFunc2 implementation
******************************************************************************/
cy_en_syspm_status_t DeepSleepFunc2(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
{
    CySCB_Type *hwBase = (CySCB_Type *) callbackParams->base;
    cy_stc_scb_spi_context_t *context = (cy_stc_scb_spi_context_t *) callbackParams->context;
    
    cy_en_syspm_status_t retVal = CY_SYSPM_FAIL;

    switch(mode)
    {
        /* Check is the HW1 ready to enter CPU Deep Sleep */
        case CY_SYSPM_CHECK_READY:
        {
            /* ... */
            if (0UL == (CY_SCB_SPI_TRANSFER_ACTIVE & Cy_SCB_SPI_GetTransferStatus(hwBase, context)))
            {
                /* There are no active actions so we can enter CPU Deep Sleep */
                retVal = CY_SYSPM_SUCCESS;
            }
            break;
        }

        default:
            retVal = CY_SYSPM_FAIL;
            break;
    }
    
    return (retVal);
}

    
/******************************************************************************
*  DeepSleepFunc3 implementation
******************************************************************************/
cy_en_syspm_status_t DeepSleepFunc3(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
{
    CySCB_Type *hwBase = (CySCB_Type *) callbackParams->base;

    cy_en_syspm_status_t retVal = CY_SYSPM_FAIL;

    switch(mode)
    {
        /* Check is the HW2 ready to enter into CPU Deep Sleep */
        case CY_SYSPM_CHECK_READY:
        {
            if (!Cy_SCB_SPI_IsBusBusy(hwBase))
            {
                /* Process the "check ready" condition */
                retVal = CY_SYSPM_SUCCESS;
            }
        
            break;
        }

        case CY_SYSPM_BEFORE_TRANSITION:
        {
            /* Switch - Turn off SCB SPI */
            retVal = CY_SYSPM_SUCCESS;
            break;
        }
        
        
        case CY_SYSPM_AFTER_TRANSITION:
        {
            /* Switch - Turn on SCB SPI */
            retVal = CY_SYSPM_SUCCESS;
            break;
        }

        case CY_SYSPM_CHECK_FAIL:
        {
            /* Revert changes made in CY_SYSPM_CHECK_READY switch case (if any) */
            break;
        }

        default:
            break;
    }
    
    return (retVal);
}

    /* Register myDeepSleep1 */
    if (true != Cy_SysPm_RegisterCallback(&myDeepSleep1))
    {
        /* Insert error handling */
    }
    
    /* Register myDeepSleep2 */
    if (true != Cy_SysPm_RegisterCallback(&myDeepSleep2))
    {
        /* Insert error handling */
    }
    
    /* Register myDeepSleep3 */
    if (true != Cy_SysPm_RegisterCallback(&myDeepSleep3))
    {
        /* Insert error handling */
    }

Cy_SysPm_UnregisterCallback()

bool Cy_SysPm_UnregisterCallback

(

cy_stc_syspm_callback_t const *

handler

)

This function unregisters a callback.

The registered callback can be unregistered and the function returns true. Otherwise, false is returned.

Parameters

handler

The item that should be unregistered. See cy_stc_syspm_callback_t.

Returns

• True if callback was unregistered.
• False if it was not unregistered or no callbacks are registered.

Function Usage

    /* Scenario: There is a need to unregister a previously registered callback */
    if (true != Cy_SysPm_UnregisterCallback(&myDeepSleep2))
    {
        /* Insert error handler */
    }

Cy_SysPm_ExecuteCallback()

cy_en_syspm_status_t Cy_SysPm_ExecuteCallback	(	cy_en_syspm_callback_type_t	type,
		cy_en_syspm_callback_mode_t	mode
	)

The function executes all registered callbacks with provided type and mode.

Note

This low-level function is being used by Cy_SysPm_CpuEnterSleep, Cy_SysPm_CpuEnterDeepSleep, Cy_SysPm_SystemEnterHibernate, Cy_SysPm_SystemEnterUlp and Cy_SysPm_SystemEnterLp API functions. However, it might be also useful as an independent API function in some custom applications.

The registered callbacks will be executed in order based on cy_en_syspm_callback_type_t value. There are two possible callback execution orders:

• From first registered to last registered. This order applies to callbacks with mode CY_SYSPM_CHECK_READY and CY_SYSPM_BEFORE_TRANSITION.
• Backward flow execution:
  • From last registered to the first registered. This order applies to callbacks with mode CY_SYSPM_AFTER_TRANSITION.
  • From last called to the first registered callback. This order applies to callbacks with mode CY_SYSPM_CHECK_FAIL. Note that, the last called callback function that generated the CY_SYSPM_CHECK_FAIL is skipped when mode CY_SYSPM_CHECK_FAIL. This is because the callback that returns CY_SYSPM_FAIL already knows that it failed and will not take any action that requires correction.

If no callbacks are registered, returns CY_SYSPM_SUCCESS.

Parameters

type	The callback type. See cy_en_syspm_callback_type_t.
mode	The callback mode. See cy_en_syspm_callback_mode_t.

Returns

• CY_SYSPM_SUCCESS if callback successfully completed or nor callbacks registered.
• CY_SYSPM_FAIL one of the executed callback(s) returned fail.

Function Usage

    /* Scenario: There is a need to execute all the registered callbacks for 
    *  CPU Sleep mode and Check Ready condition
    */
    if (CY_SYSPM_SUCCESS != Cy_SysPm_ExecuteCallback(CY_SYSPM_SLEEP, CY_SYSPM_CHECK_READY))
    {
        /* Insert error handling */
    }

Cy_SysPm_GetFailedCallback()

cy_stc_syspm_callback_t* Cy_SysPm_GetFailedCallback

(

cy_en_syspm_callback_type_t

type

)

Reads the result of the callback execution after the power mode functions execution.

This function reads the value of the pointer that stores the result of callback execution. It takes power mode as the parameter and returns the address of the callback configuration structure in the case of failure or NULL in the case of success. This address of the failed callback allows finding the callback that blocks entering power mode.

Parameters

type	Power mode for which a callback execution result is required.

Returns

• The address of the callback configuration structure if the callback handler function failed.
• NULL if the callback skipped or executed successfully.

Function Usage

    /* Scenario: There is a need to put the CPU into Deep Sleep mode, and in the case
    *  of failure - to trace failed callback
    */

    /* Prepare the system for Deep Sleep power mode */
    if(CY_SYSPM_SUCCESS != Cy_SysPm_CpuEnterDeepSleep(CY_SYSPM_WAIT_FOR_INTERRUPT))
    {
        /* CPU did not enter Deep Sleep mode because one of executed callback 
        *  returned a "fail" status
        */

        /* Call Cy_SysPm_GetFailedCallback to get the address of the failed callback */
        cy_stc_syspm_callback_t* failedCallbackPtr = Cy_SysPm_GetFailedCallback(CY_SYSPM_DEEPSLEEP);

        /* Find out which callback failed */
        if(failedCallbackPtr == (&myDeepSleep1))
        {
            /* myDeepSleep1 callback failed */
        }
        else if(failedCallbackPtr == (&myDeepSleep2))
        {
            /* myDeepSleep2 callback failed */
        }
        else if(failedCallbackPtr == (&myDeepSleep3))
        {
            /* myDeepSleep3 callback failed */
        }
        else 
        {
            /* In this case, the address of the failed callback was not compared
            *  with the address returned by Cy_SysPm_GetFailedCallback
            */
        }
    }
    else
    {
        /* If the program has reached here, the core is just woken up
         * from the CPU Deep Sleep mode
         */
    }