/***************************************************************************//** | |
* @file sleep.h | |
* @brief Energy Modes management driver | |
* @version 4.2.1 | |
* @details | |
* This is a energy modes management module consisting of sleep.c and sleep.h | |
* source files. The main purpose of the module is to ease energy | |
* optimization with a simple API. The module allows the system to always sleep | |
* in the lowest possible energy mode. Users could set up callbacks that are | |
* being called before and after each and every sleep. A counting semaphore is | |
* available for each low energy mode (EM1/EM2/EM3) to protect certain system | |
* states from being corrupted. This semaphore has limit set to maximum 255 locks. | |
* | |
* The module provides the following public API to the users: | |
* SLEEP_Init() | |
* SLEEP_Sleep() | |
* SLEEP_SleepBlockBegin() | |
* SLEEP_SleepBlockEnd() | |
* SLEEP_ForceSleepInEM4() | |
* | |
******************************************************************************* | |
* @section License | |
* <b>(C) Copyright 2014 Silicon Labs, http://www.silabs.com</b> | |
******************************************************************************* | |
* | |
* This file is licensed under the Silabs License Agreement. See the file | |
* "Silabs_License_Agreement.txt" for details. Before using this software for | |
* any purpose, you must agree to the terms of that agreement. | |
* | |
******************************************************************************/ | |
#ifndef __SLEEP_H | |
#define __SLEEP_H | |
#include <stdint.h> | |
#include <stdbool.h> | |
/* Device specific header file(s). */ | |
#include "em_device.h" | |
#ifdef __cplusplus | |
extern "C" { | |
#endif | |
/***************************************************************************//** | |
* @addtogroup EM_Drivers | |
* @{ | |
******************************************************************************/ | |
/***************************************************************************//** | |
* @addtogroup SLEEP | |
* @brief Energy Modes management driver. | |
* @details | |
* This is a energy modes management module consisting of sleep.c and sleep.h | |
* source files. The main purpose of the module is to ease energy | |
* optimization with a simple API. The module allows the system to always sleep | |
* in the lowest possible energy mode. Users could set up callbacks that are | |
* being called before and after each and every sleep. A counting semaphore is | |
* available for each low energy mode (EM1/EM2/EM3) to protect certain system | |
* states from being corrupted. This semaphore has limit set to maximum 255 locks. | |
* @{ | |
******************************************************************************/ | |
/******************************************************************************* | |
******************************* MACROS ************************************ | |
******************************************************************************/ | |
/******************************************************************************* | |
**************************** CONFIGURATION ******************************** | |
******************************************************************************/ | |
/** Enable/disable the HW block for protecting accidental setting of low energy | |
* modes (recommended to be set to true). */ | |
#ifndef SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED | |
#define SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED true | |
#endif | |
/** Enable/disable calling wakeup callback after EM4 reset. */ | |
#ifndef SLEEP_EM4_WAKEUP_CALLBACK_ENABLED | |
#define SLEEP_EM4_WAKEUP_CALLBACK_ENABLED true | |
#endif | |
/** Configure default lowest energy mode that the system can be set to. | |
* Possible values: | |
* @li sleepEM1 - EM1, the CPU core is turned off. | |
* @li sleepEM2 - EM2, like EM1 + all HF clocks are turned off, LF clocks are on. | |
* @li sleepEM3 - EM3, like EM2 + LF clocks are off, RAM retention, GPIO and ACMP | |
* interrupt is on. */ | |
#ifndef SLEEP_LOWEST_ENERGY_MODE_DEFAULT | |
#define SLEEP_LOWEST_ENERGY_MODE_DEFAULT sleepEM3 | |
#endif | |
/******************************************************************************* | |
****************************** TYPEDEFS *********************************** | |
******************************************************************************/ | |
/** Status value used for showing the Energy Mode the device is currently in. */ | |
typedef enum | |
{ | |
/** Status value for EM0. */ | |
sleepEM0 = 0, | |
/** Status value for EM1. */ | |
sleepEM1 = 1, | |
/** Status value for EM2. */ | |
sleepEM2 = 2, | |
/** Status value for EM3. */ | |
sleepEM3 = 3, | |
/** Status value for EM4. */ | |
sleepEM4 = 4 | |
} SLEEP_EnergyMode_t; | |
/** Callback function pointer type. */ | |
typedef void (*SLEEP_CbFuncPtr_t)(SLEEP_EnergyMode_t); | |
/******************************************************************************* | |
****************************** PROTOTYPES ********************************* | |
******************************************************************************/ | |
/***************************************************************************//** | |
* @brief | |
* Initialize the Sleep module. | |
* | |
* @details | |
* Use this function to initialize the Sleep module, should be called | |
* only once! Pointers to sleep and wake-up callback functions shall be | |
* provided when calling this function. | |
* If SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to true, this function checks | |
* for the cause of the reset that implicitly called it and calls the wakeup | |
* callback if the reset was a wakeup from EM4 (does not work on Gecko MCU). | |
* | |
* @param[in] pSleepCb | |
* Pointer to the callback function that is being called before the device is | |
* going to sleep. | |
* | |
* @param[in] pWakeUpCb | |
* Pointer to the callback function that is being called after wake up. | |
******************************************************************************/ | |
void SLEEP_Init(SLEEP_CbFuncPtr_t pSleepCb, SLEEP_CbFuncPtr_t pWakeUpCb); | |
/***************************************************************************//** | |
* @brief | |
* Gets the lowest energy mode that the system is allowed to be set to. | |
* | |
* @details | |
* This function uses the low energy mode block counters to determine the | |
* lowest possible that the system is allowed to be set to. | |
* | |
* @return | |
* Lowest energy mode that the system can be set to. Possible values: | |
* @li sleepEM0 | |
* @li sleepEM1 | |
* @li sleepEM2 | |
* @li sleepEM3 | |
******************************************************************************/ | |
SLEEP_EnergyMode_t SLEEP_LowestEnergyModeGet(void); | |
/***************************************************************************//** | |
* @brief | |
* Sets the system to sleep into the lowest possible energy mode. | |
* | |
* @details | |
* This function takes care of the system states protected by the sleep block | |
* provided by SLEEP_SleepBlockBegin() / SLEEP_SleepBlockEnd(). It allows | |
* the system to go into the lowest possible energy mode that the device can | |
* be set into at the time of the call of this function. | |
* This function will not go lower than EM3 because leaving EM4 requires | |
* resetting MCU. To enter into EM4 call SLEEP_ForceSleepInEM4(). | |
* | |
* @return | |
* Energy Mode that was entered. Possible values: | |
* @li sleepEM0 | |
* @li sleepEM1 | |
* @li sleepEM2 | |
* @li sleepEM3 | |
******************************************************************************/ | |
SLEEP_EnergyMode_t SLEEP_Sleep(void); | |
/***************************************************************************//** | |
* @brief | |
* Force the device to go to EM4 without doing any checks. | |
* | |
* @details | |
* This function unblocks the low energy sleep block then goes to EM4. | |
* | |
* @note | |
* Regular RAM is not retained in EM4 and the wake up causes a reset. | |
* If the configuration option SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to | |
* true, the SLEEP_Init() function checks for the reset cause and calls the | |
* EM4 wakeup callback. | |
******************************************************************************/ | |
void SLEEP_ForceSleepInEM4(void); | |
/***************************************************************************//** | |
* @brief | |
* Begin sleep block in the requested energy mode. | |
* | |
* @details | |
* Blocking a critical system state from a certain energy mode makes sure that | |
* the system is not set to that energy mode while the block is not being | |
* released. | |
* Every SLEEP_SleepBlockBegin() increases the corresponding counter and | |
* every SLEEP_SleepBlockEnd() decreases it. | |
* | |
* Example:\code | |
* SLEEP_SleepBlockBegin(sleepEM2); // do not allow EM2 or higher | |
* // do some stuff that requires EM1 at least, like ADC sampling | |
* SLEEP_SleepBlockEnd(sleepEM2); // remove restriction for EM2\endcode | |
* | |
* @note | |
* Be aware that there is limit of maximum blocks nesting to 255. | |
* | |
* @param[in] eMode | |
* Energy mode to begin to block. Possible values: | |
* @li sleepEM1 - Begin to block the system from being set to EM1 (and EM2..4). | |
* @li sleepEM2 - Begin to block the system from being set to EM2 (and EM3/EM4). | |
* @li sleepEM3 - Begin to block the system from being set to EM3 (and EM4). | |
******************************************************************************/ | |
void SLEEP_SleepBlockBegin(SLEEP_EnergyMode_t eMode); | |
/***************************************************************************//** | |
* @brief | |
* End sleep block in the requested energy mode. | |
* | |
* @details | |
* Release restriction for entering certain energy mode. Every call of this | |
* function reduce blocking counter by 1. Once the counter for specific energy | |
* mode is 0 and all counters for lower energy modes are 0 as well, using | |
* particular energy mode is allowed. | |
* Every SLEEP_SleepBlockBegin() increases the corresponding counter and | |
* every SLEEP_SleepBlockEnd() decreases it. | |
* | |
* Example:\code | |
* // at start all energy modes are allowed | |
* SLEEP_SleepBlockBegin(sleepEM2); // EM2, EM3, EM4 are blocked | |
* SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked | |
* SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked | |
* SLEEP_SleepBlockEnd(sleepEM2); // still EM1, EM2, EM3, EM4 are blocked | |
* SLEEP_SleepBlockEnd(sleepEM1); // still EM1, EM2, EM3, EM4 are blocked | |
* SLEEP_SleepBlockEnd(sleepEM1); // all energy modes are allowed now\endcode | |
* | |
* @param[in] eMode | |
* Energy mode to end to block. Possible values: | |
* @li sleepEM1 - End to block the system from being set to EM1 (and EM2..4). | |
* @li sleepEM2 - End to block the system from being set to EM2 (and EM3/EM4). | |
* @li sleepEM3 - End to block the system from being set to EM3 (and EM4). | |
******************************************************************************/ | |
void SLEEP_SleepBlockEnd(SLEEP_EnergyMode_t eMode); | |
/** @} (end addtogroup SLEEP) */ | |
/** @} (end addtogroup EM_Drivers) */ | |
#ifdef __cplusplus | |
} | |
#endif | |
#endif /* __SLEEP_H */ |