PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
Low Power Callbacks
PDL API Reference » SysPm (System Power Management) » Functions

## 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);
  cy_en_syspm_status_t
  cy_en_syspm_status_t
  The SysPm function return value status definitions.
  Definition: cy_syspm.h:1352
  cy_en_syspm_callback_mode_t
  cy_en_syspm_callback_mode_t
  This enumeration specifies the associated callback mode.
  Definition: cy_syspm.h:1959
  cy_stc_syspm_callback_params_t
  The structure contains syspm callback parameters.
  Definition: cy_syspm.h:2054
  /******************************************************************************
  * 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
  };
  CY_SYSPM_DEEPSLEEP
  @ CY_SYSPM_DEEPSLEEP
  The Deep Sleep enum callback type.
  Definition: cy_syspm.h:1519
  cy_stc_syspm_callback_t
  Structure with syspm callback configuration elements.
  Definition: cy_syspm.h:2068
  CY_SYSPM_SKIP_BEFORE_TRANSITION
  #define CY_SYSPM_SKIP_BEFORE_TRANSITION
  Define to skip before transition mode in the syspm callback.
  Definition: cy_syspm.h:2042
  /******************************************************************************
  * 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 *spiContext = (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, spiContext)))
  {
  /* 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);
  }
  cy_stc_scb_spi_context_t
  SPI context structure.
  Definition: cy_scb_spi.h:608
  Cy_SCB_SPI_IsBusBusy
  __STATIC_INLINE bool Cy_SCB_SPI_IsBusBusy(CySCB_Type const *base)
  Returns whether the SPI bus is busy or not.
  Definition: cy_scb_spi.h:983
  Cy_SCB_SPI_GetTransferStatus
  uint32_t Cy_SCB_SPI_GetTransferStatus(CySCB_Type const *base, cy_stc_scb_spi_context_t const *context)
  Returns the status of the transfer operation started by Cy_SCB_SPI_Transfer.
  Definition: cy_scb_spi.c:1007
  CY_SCB_SPI_TRANSFER_ACTIVE
  #define CY_SCB_SPI_TRANSFER_ACTIVE
  Transfer operation started by Cy_SCB_SPI_Transfer is in progress.
  Definition: cy_scb_spi.h:820
  CY_SYSPM_FAIL
  @ CY_SYSPM_FAIL
  Unknown failure.
  Definition: cy_syspm.h:1360
  CY_SYSPM_SUCCESS
  @ CY_SYSPM_SUCCESS
  Successful.
  Definition: cy_syspm.h:1353
  CY_SYSPM_BEFORE_TRANSITION
  @ CY_SYSPM_BEFORE_TRANSITION
  Callbacks with this mode are executed after the CY_SYSPM_CHECK_READY callbacks execution returns CY_S...
  Definition: cy_syspm.h:1968
  CY_SYSPM_CHECK_FAIL
  @ CY_SYSPM_CHECK_FAIL
  Callbacks with this mode are executed after the CY_SYSPM_CHECK_READY callbacks execution returns CY_S...
  Definition: cy_syspm.h:1963
  CY_SYSPM_AFTER_TRANSITION
  @ CY_SYSPM_AFTER_TRANSITION
  Performs the actions to be done after exiting the low power mode if entered.
  Definition: cy_syspm.h:1972
  CY_SYSPM_CHECK_READY
  @ CY_SYSPM_CHECK_READY
  Callbacks with this mode are executed before entering into the low power mode.
  Definition: cy_syspm.h:1960
  cy_stc_syspm_callback_params_t::base
  void * base
  Base address of a HW instance, matches name of the driver in the API for the base address.
  Definition: cy_syspm.h:2055
  cy_stc_syspm_callback_params_t::context
  void * context
  Context for the handler function.
  Definition: cy_syspm.h:2058
  CySCB_Type
  Serial Communications Block (SPI/UART/I2C) (CySCB)
  Definition: cyip_scb.h:38
  /* 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_RegisterCallback
  bool Cy_SysPm_RegisterCallback(cy_stc_syspm_callback_t *handler)
  Registers a new syspm callback.
  Definition: cy_syspm_v4.c:2063

## ◆ 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_UnregisterCallback
  bool Cy_SysPm_UnregisterCallback(cy_stc_syspm_callback_t const *handler)
  This function unregisters a callback.
  Definition: cy_syspm_v4.c:2130

## ◆ 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_SLEEP
  @ CY_SYSPM_SLEEP
  The Sleep enum callback type.
  Definition: cy_syspm.h:1518
  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.
  Definition: cy_syspm_v4.c:2186

## ◆ 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
  */
  }
  CY_SYSPM_WAIT_FOR_INTERRUPT
  @ CY_SYSPM_WAIT_FOR_INTERRUPT
  Wait for an interrupt.
  Definition: cy_syspm.h:1369
  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.
  Definition: cy_syspm_v4.c:2288
  Cy_SysPm_CpuEnterDeepSleep
  cy_en_syspm_status_t Cy_SysPm_CpuEnterDeepSleep(cy_en_syspm_waitfor_t waitFor)
  Sets executing CPU to the Deep Sleep mode.
  Definition: cy_syspm_v4.c:1333